Skip to main content

esp_hal/i2c/master/low_level/
mod.rs

1use super::*;
2use crate::{
3    asynch::{wait_until, wake_at},
4    rtc_cntl::WakeLock,
5    soc::clocks::ClockTree,
6};
7
8#[cfg_attr(i2c_master_version = "1", path = "v1.rs")]
9#[cfg_attr(i2c_master_version = "2", path = "v2.rs")]
10#[cfg_attr(
11    any(i2c_master_version = "3", i2c_master_version = "4"),
12    path = "v3.rs"
13)]
14mod version;
15
16#[must_use = "futures do nothing unless you `.await` or poll them"]
17pub(super) struct I2cFuture<'a> {
18    events: EnumSet<Event>,
19    driver: Driver<'a>,
20    deadline: Option<Instant>,
21    /// True if the Future has been polled to completion.
22    finished: bool,
23    _wake_lock: WakeLock,
24}
25
26impl<'a> I2cFuture<'a> {
27    pub fn new(events: EnumSet<Event>, driver: Driver<'a>, deadline: Option<Instant>) -> Self {
28        driver.regs().int_ena().modify(|_, w| {
29            for event in events {
30                match event {
31                    Event::EndDetect => w.end_detect().set_bit(),
32                    Event::TxComplete => w.trans_complete().set_bit(),
33                    #[cfg(i2c_master_has_tx_fifo_watermark)]
34                    Event::TxFifoWatermark => w.txfifo_wm().set_bit(),
35                };
36            }
37
38            w.arbitration_lost().set_bit();
39            w.time_out().set_bit();
40            w.nack().set_bit();
41            #[cfg(i2c_master_has_fsm_timeouts)]
42            {
43                w.scl_main_st_to().set_bit();
44                w.scl_st_to().set_bit();
45            }
46
47            w
48        });
49
50        Self::new_blocking(events, driver, deadline)
51    }
52
53    pub fn new_blocking(
54        events: EnumSet<Event>,
55        driver: Driver<'a>,
56        deadline: Option<Instant>,
57    ) -> Self {
58        Self {
59            events,
60            driver,
61            deadline,
62            finished: false,
63            _wake_lock: WakeLock::new(),
64        }
65    }
66
67    fn is_done(&self) -> bool {
68        !self.driver.info.interrupts().is_disjoint(self.events)
69    }
70
71    fn poll_completion(&mut self) -> Poll<Result<(), Error>> {
72        // Grab the current time before doing anything. This will ensure that a long
73        // interruption still allows the peripheral sufficient time to complete the
74        // operation (i.e. it ensures that the deadline is "at least", not "at most").
75        let now = if self.deadline.is_some() {
76            Instant::now()
77        } else {
78            Instant::EPOCH
79        };
80        let error = self.driver.check_errors();
81
82        let result = if self.is_done() {
83            // Even though we are done, we have to check for NACK and arbitration loss.
84            let result = if error == Err(Error::Timeout) {
85                // We are both done, and timed out. Likely the transaction has completed, but we
86                // checked too late?
87                Ok(())
88            } else {
89                error
90            };
91            Poll::Ready(result)
92        } else if error.is_err() {
93            Poll::Ready(error)
94        } else if let Some(deadline) = self.deadline
95            && now > deadline
96        {
97            // If the deadline is reached, we return an error.
98            Poll::Ready(Err(Error::Timeout))
99        } else {
100            Poll::Pending
101        };
102
103        if result.is_ready() {
104            self.finished = true;
105        }
106
107        result
108    }
109}
110
111impl core::future::Future for I2cFuture<'_> {
112    type Output = Result<(), Error>;
113
114    fn poll(mut self: Pin<&mut Self>, ctx: &mut Context<'_>) -> Poll<Self::Output> {
115        self.driver.state.waker.register(ctx.waker());
116
117        let result = self.poll_completion();
118
119        if result.is_pending()
120            && let Some(deadline) = self.deadline
121        {
122            wake_at(deadline, ctx);
123        }
124
125        result
126    }
127}
128
129impl Drop for I2cFuture<'_> {
130    fn drop(&mut self) {
131        if !self.finished {
132            let result = self.poll_completion();
133            if result.is_pending() || result == Poll::Ready(Err(Error::Timeout)) {
134                self.driver.reset_fsm(true);
135            }
136        }
137    }
138}
139
140#[ram]
141pub(super) fn async_handler(info: &Info, state: &State) {
142    // Disable all interrupts. The I2C Future will check events based on the
143    // interrupt status bits.
144    info.regs().int_ena().write(|w| unsafe { w.bits(0) });
145
146    state.waker.wake();
147}
148
149/// Sets the filter with a supplied threshold in clock cycles for which a
150/// pulse must be present to pass the filter.
151fn set_filter(
152    register_block: &RegisterBlock,
153    sda_threshold: Option<u8>,
154    scl_threshold: Option<u8>,
155) {
156    cfg_select! {
157        i2c_master_separate_filter_config_registers => {
158            register_block.sda_filter_cfg().modify(|_, w| {
159                if let Some(threshold) = sda_threshold {
160                    unsafe { w.sda_filter_thres().bits(threshold) };
161                }
162                w.sda_filter_en().bit(sda_threshold.is_some())
163            });
164            register_block.scl_filter_cfg().modify(|_, w| {
165                if let Some(threshold) = scl_threshold {
166                    unsafe { w.scl_filter_thres().bits(threshold) };
167                }
168                w.scl_filter_en().bit(scl_threshold.is_some())
169            });
170        }
171        _ => {
172            register_block.filter_cfg().modify(|_, w| {
173                if let Some(threshold) = sda_threshold {
174                    unsafe { w.sda_filter_thres().bits(threshold) };
175                }
176                if let Some(threshold) = scl_threshold {
177                    unsafe { w.scl_filter_thres().bits(threshold) };
178                }
179                w.sda_filter_en().bit(sda_threshold.is_some());
180                w.scl_filter_en().bit(scl_threshold.is_some())
181            });
182        }
183    }
184}
185
186#[expect(clippy::too_many_arguments)]
187#[allow(unused)]
188/// Configures the timing parameters for the I2C peripheral.
189///
190/// Clock source selection is handled separately via the clock tree.
191fn configure_clock(
192    info: &Info,
193    scl_low_period: u32,
194    scl_high_period: u32,
195    scl_wait_high_period: u32,
196    sda_hold_time: u32,
197    sda_sample_time: u32,
198    scl_rstart_setup_time: u32,
199    scl_stop_setup_time: u32,
200    scl_start_hold_time: u32,
201    scl_stop_hold_time: u32,
202    timeout: Option<u32>,
203) -> Result<(), ConfigError> {
204    unsafe {
205        // scl period
206        info.regs()
207            .scl_low_period()
208            .write(|w| w.scl_low_period().bits(scl_low_period as u16));
209
210        #[cfg(not(i2c_master_version = "1"))]
211        let scl_wait_high_period = scl_wait_high_period
212            .try_into()
213            .map_err(|_| ConfigError::FrequencyOutOfRange)?;
214
215        info.regs().scl_high_period().write(|w| {
216            #[cfg(not(i2c_master_version = "1"))] // ESP32 does not have a wait_high field
217            w.scl_wait_high_period().bits(scl_wait_high_period);
218            w.scl_high_period().bits(scl_high_period as u16)
219        });
220
221        // sda sample
222        info.regs()
223            .sda_hold()
224            .write(|w| w.time().bits(sda_hold_time as u16));
225        info.regs()
226            .sda_sample()
227            .write(|w| w.time().bits(sda_sample_time as u16));
228
229        // setup
230        info.regs()
231            .scl_rstart_setup()
232            .write(|w| w.time().bits(scl_rstart_setup_time as u16));
233        info.regs()
234            .scl_stop_setup()
235            .write(|w| w.time().bits(scl_stop_setup_time as u16));
236
237        // hold
238        info.regs()
239            .scl_start_hold()
240            .write(|w| w.time().bits(scl_start_hold_time as u16));
241        info.regs()
242            .scl_stop_hold()
243            .write(|w| w.time().bits(scl_stop_hold_time as u16));
244
245        cfg_select! {
246            i2c_master_has_bus_timeout_enable => {
247                info.regs().to().write(|w| {
248                    w.time_out_en().bit(timeout.is_some());
249                    w.time_out_value().bits(timeout.unwrap_or(1) as _)
250                });
251            }
252            _ => {
253                info.regs()
254                    .to()
255                    .write(|w| w.time_out().bits(timeout.unwrap_or(1)));
256            }
257        }
258    }
259    Ok(())
260}
261
262/// Peripheral data describing a particular I2C instance.
263#[doc(hidden)]
264#[derive(Debug)]
265#[non_exhaustive]
266#[allow(private_interfaces, reason = "Unstable details")]
267pub struct Info {
268    /// Numeric instance id (0 = I2C0, 1 = I2C1, ...)
269    #[cfg(soc_has_i2c1)]
270    pub id: u8,
271
272    /// Pointer to the register block for this I2C instance.
273    ///
274    /// Used with [`Self::register_block`] to access the register block.
275    pub register_block: *const RegisterBlock,
276
277    /// System peripheral marker.
278    pub peripheral: crate::system::Peripheral,
279
280    /// Interrupt handler for the asynchronous operations of this I2C instance.
281    pub async_handler: InterruptHandler,
282
283    /// SCL output signal.
284    pub scl_output: OutputSignal,
285
286    /// SCL input signal.
287    pub scl_input: InputSignal,
288
289    /// SDA output signal.
290    pub sda_output: OutputSignal,
291
292    /// SDA input signal.
293    pub sda_input: InputSignal,
294
295    /// I2C clock group instance.
296    pub clock_instance: crate::soc::clocks::I2cInstance,
297}
298
299impl Info {
300    /// Returns the register block for this I2C instance.
301    pub fn regs(&self) -> &RegisterBlock {
302        unsafe { &*self.register_block }
303    }
304
305    /// Listens for the given interrupts.
306    pub(super) fn enable_listen(&self, interrupts: EnumSet<Event>, enable: bool) {
307        let reg_block = self.regs();
308
309        reg_block.int_ena().modify(|_, w| {
310            for interrupt in interrupts {
311                match interrupt {
312                    Event::EndDetect => w.end_detect().bit(enable),
313                    Event::TxComplete => w.trans_complete().bit(enable),
314                    #[cfg(i2c_master_has_tx_fifo_watermark)]
315                    Event::TxFifoWatermark => w.txfifo_wm().bit(enable),
316                };
317            }
318            w
319        });
320    }
321
322    pub(super) fn interrupts(&self) -> EnumSet<Event> {
323        let mut res = EnumSet::new();
324        let reg_block = self.regs();
325
326        let ints = reg_block.int_raw().read();
327
328        if ints.end_detect().bit_is_set() {
329            res.insert(Event::EndDetect);
330        }
331        if ints.trans_complete().bit_is_set() {
332            res.insert(Event::TxComplete);
333        }
334        #[cfg(i2c_master_has_tx_fifo_watermark)]
335        if ints.txfifo_wm().bit_is_set() {
336            res.insert(Event::TxFifoWatermark);
337        }
338
339        res
340    }
341
342    pub(super) fn clear_interrupts(&self, interrupts: EnumSet<Event>) {
343        let reg_block = self.regs();
344
345        reg_block.int_clr().write(|w| {
346            for interrupt in interrupts {
347                match interrupt {
348                    Event::EndDetect => w.end_detect().clear_bit_by_one(),
349                    Event::TxComplete => w.trans_complete().clear_bit_by_one(),
350                    #[cfg(i2c_master_has_tx_fifo_watermark)]
351                    Event::TxFifoWatermark => w.txfifo_wm().clear_bit_by_one(),
352                };
353            }
354            w
355        });
356    }
357}
358
359impl PartialEq for Info {
360    fn eq(&self, other: &Self) -> bool {
361        core::ptr::eq(self.register_block, other.register_block)
362    }
363}
364
365unsafe impl Sync for Info {}
366
367pub(super) struct I2cClockGuard {
368    clock: crate::clock::ll::I2cInstance,
369}
370
371impl I2cClockGuard {
372    pub(super) fn new(i2c: AnyI2c<'_>) -> Self {
373        let clock = i2c.info().clock_instance;
374        ClockTree::with(|clocks| clock.request_function_clock(clocks));
375        Self { clock }
376    }
377}
378
379impl Drop for I2cClockGuard {
380    fn drop(&mut self) {
381        ClockTree::with(|clocks| self.clock.release_function_clock(clocks));
382    }
383}
384
385#[derive(Clone, Copy)]
386enum Deadline {
387    None,
388    Fixed(Instant),
389    PerByte(Duration),
390}
391
392impl Deadline {
393    fn start(self, data_len: usize) -> Option<Instant> {
394        match self {
395            Deadline::None => None,
396            Deadline::Fixed(deadline) => Some(deadline),
397            Deadline::PerByte(duration) => Some(Instant::now() + duration * data_len as u32),
398        }
399    }
400}
401
402#[allow(dead_code)] // Some versions don't need `state`
403#[derive(Clone, Copy)]
404pub(super) struct Driver<'a> {
405    pub(super) info: &'a Info,
406    pub(super) state: &'a State,
407    pub(super) config: &'a DriverConfig,
408}
409
410impl Driver<'_> {
411    fn regs(&self) -> &RegisterBlock {
412        self.info.regs()
413    }
414
415    pub(super) fn connect_pin(
416        pin: crate::gpio::interconnect::OutputSignal<'_>,
417        input: InputSignal,
418        output: OutputSignal,
419        guard: &mut PinGuard,
420    ) {
421        // avoid the pin going low during configuration
422        pin.set_output_high(true);
423
424        pin.apply_output_config(
425            &OutputConfig::default()
426                .with_drive_mode(DriveMode::OpenDrain)
427                .with_pull(Pull::Up),
428        );
429        pin.set_output_enable(true);
430        pin.set_input_enable(true);
431
432        input.connect_to(&pin);
433
434        *guard = interconnect::OutputSignal::connect_with_guard(pin, output);
435    }
436
437    fn init_master(&self, config: &Config) {
438        self.regs().ctr().write(|w| {
439            // Set I2C controller to master mode
440            w.ms_mode().set_bit();
441            w.sda_force_out().open_drain();
442            w.scl_force_out().open_drain();
443            // Use Most Significant Bit first for sending and receiving data
444            w.tx_lsb_first().clear_bit();
445            w.rx_lsb_first().clear_bit();
446
447            w.sample_scl_level()
448                .bit(config.scl_sample_level == Level::Low);
449
450            #[cfg(i2c_master_has_arbitration_en)]
451            w.arbitration_en().bit(config.bus_arbitration);
452
453            #[cfg(i2c_master_version = "2")]
454            w.ref_always_on().set_bit();
455
456            // Ensure that clock is enabled
457            w.clk_en().set_bit()
458        });
459    }
460
461    /// Configures the I2C peripheral with the specified frequency, clocks, and
462    /// optional timeout.
463    pub(super) fn setup(&self, config: &Config) -> Result<(), ConfigError> {
464        self.init_master(config);
465
466        // Configure filter
467        // FIXME if we ever change this we need to adapt `set_frequency` for ESP32
468        set_filter(self.regs(), Some(7), Some(7));
469
470        // Configure frequency
471        self.set_frequency(config)?;
472
473        // Configure additional timeouts
474        #[cfg(i2c_master_has_fsm_timeouts)]
475        {
476            self.regs()
477                .scl_st_time_out()
478                .write(|w| unsafe { w.scl_st_to().bits(config.scl_st_timeout.value()) });
479            self.regs()
480                .scl_main_st_time_out()
481                .write(|w| unsafe { w.scl_main_st_to().bits(config.scl_main_st_timeout.value()) });
482        }
483
484        self.update_registers();
485
486        Ok(())
487    }
488
489    fn do_fsm_reset(&self) {
490        cfg_select! {
491            i2c_master_has_reliable_fsm_reset => {
492                // Device has a working FSM reset mechanism
493                self.regs().ctr().modify(|_, w| w.fsm_rst().set_bit());
494            }
495            _ => {
496                // Even though C2 and C3 have a FSM reset bit, esp-idf does not
497                // define I2C_LL_SUPPORT_HW_FSM_RST for them, so include them in the fallback impl.
498
499                crate::system::PeripheralClockControl::reset(self.info.peripheral);
500
501                // Restore configuration. This operation has succeeded once, so we can
502                // assume that the config is valid and we can ignore the result.
503                self.setup(&self.config.config).ok();
504            }
505        }
506    }
507
508    /// Resets the I2C controller (FIFO + FSM + command list).
509    // This function implements esp-idf's `s_i2c_hw_fsm_reset`
510    // https://github.com/espressif/esp-idf/blob/27d68f57e6bdd3842cd263585c2c352698a9eda2/components/esp_driver_i2c/i2c_master.c#L115
511    //
512    // Make sure you don't call this function in the middle of a transaction. If the
513    // first command in the command list is not a START, the hardware will hang
514    // with no timeouts.
515    pub(super) fn reset_fsm(&self, clear_bus: bool) {
516        if clear_bus {
517            self.clear_bus_blocking(true);
518        } else {
519            self.do_fsm_reset();
520        }
521    }
522
523    fn bus_busy(&self) -> bool {
524        self.regs().sr().read().bus_busy().bit_is_set()
525    }
526
527    fn ensure_idle_blocking(&self) {
528        if self.bus_busy() {
529            // If the bus is busy, we need to clear it.
530            self.clear_bus_blocking(false);
531        }
532    }
533
534    async fn ensure_idle(&self) {
535        if self.bus_busy() {
536            // If the bus is busy, we need to clear it.
537            self.clear_bus().await;
538        }
539    }
540
541    fn reset_before_transmission(&self) {
542        // Clear all I2C interrupts
543        self.clear_all_interrupts();
544
545        // Reset fifo
546        self.reset_fifo();
547
548        // Reset the command list
549        self.reset_command_list();
550    }
551
552    /// Implements s_i2c_master_clear_bus.
553    ///
554    /// If a transaction ended incorrectly for some reason, the slave may drive SDA
555    /// indefinitely. Forces the slave to release the bus by sending 9 clock pulses.
556    fn clear_bus_blocking(&self, reset_fsm: bool) {
557        let mut future = ClearBusFuture::new(*self, reset_fsm);
558        let start = Instant::now();
559        while future.poll_completion().is_pending() {
560            if start.elapsed() > CLEAR_BUS_TIMEOUT_MS {
561                break;
562            }
563        }
564    }
565
566    async fn clear_bus(&self) {
567        let clear_bus = ClearBusFuture::new(*self, true);
568        let deadline = Instant::now() + CLEAR_BUS_TIMEOUT_MS;
569
570        embassy_futures::select::select(clear_bus, wait_until(deadline)).await;
571    }
572
573    pub(super) fn force_scl_low(&self, low: bool) {
574        cfg_select! {
575            i2c_master_has_pd_en => self.set_scl_pd(low),
576            _ => self.force_pin_low(low, self.config.scl_pin.pin_number(), &self.info.scl_output),
577        }
578    }
579
580    pub(super) fn force_sda_low(&self, low: bool) {
581        cfg_select! {
582            i2c_master_has_pd_en => self.set_sda_pd(low),
583            _ => self.force_pin_low(low, self.config.sda_pin.pin_number(), &self.info.sda_output),
584        }
585    }
586
587    /// Restores force_out to open-drain mode for both lines.
588    #[cfg(i2c_master_has_pd_en)]
589    fn restore_force_out(&self) {
590        self.regs().ctr().modify(|_, w| {
591            w.scl_force_out().open_drain();
592            w.sda_force_out().open_drain()
593        });
594        self.update_registers();
595    }
596
597    #[cfg(not(i2c_master_has_pd_en))]
598    fn force_pin_low(
599        &self,
600        low: bool,
601        pin_number: Option<u8>,
602        output_signal: &crate::gpio::OutputSignal,
603    ) {
604        use crate::gpio::AnyPin;
605        let Some(n) = pin_number else { return };
606        let pin = unsafe { AnyPin::steal(n) };
607        if low {
608            pin.set_output_high(false);
609            output_signal.disconnect_from(&pin);
610        } else {
611            output_signal.connect_to(&pin);
612        }
613    }
614
615    /// Sets or clears `scl_pd_en`. Switches `scl_force_out` to direct-output while
616    /// pd_en is active (required on all chips), restoring OD mode when both pd_en
617    /// bits clear.
618    #[cfg(i2c_master_has_pd_en)]
619    fn set_scl_pd(&self, low: bool) {
620        if low {
621            self.regs()
622                .ctr()
623                .modify(|_, w| w.scl_force_out().direct_output());
624        }
625        self.regs()
626            .scl_sp_conf()
627            .modify(|_, w| w.scl_pd_en().bit(low));
628        if !low {
629            let sp = self.regs().scl_sp_conf().read();
630            if sp.scl_pd_en().bit_is_clear() && sp.sda_pd_en().bit_is_clear() {
631                self.restore_force_out();
632                return;
633            }
634        }
635        self.update_registers();
636    }
637
638    /// Sets or clears `sda_pd_en`. Switches `sda_force_out` to direct-output while
639    /// pd_en is active (required on all chips), restoring OD mode when both pd_en
640    /// bits clear.
641    #[cfg(i2c_master_has_pd_en)]
642    fn set_sda_pd(&self, low: bool) {
643        if low {
644            self.regs()
645                .ctr()
646                .modify(|_, w| w.sda_force_out().direct_output());
647        }
648        self.regs()
649            .scl_sp_conf()
650            .modify(|_, w| w.sda_pd_en().bit(low));
651        if !low {
652            let sp = self.regs().scl_sp_conf().read();
653            if sp.scl_pd_en().bit_is_clear() && sp.sda_pd_en().bit_is_clear() {
654                self.restore_force_out();
655                return;
656            }
657        }
658        self.update_registers();
659    }
660
661    /// Resets the I2C peripheral's command registers.
662    fn reset_command_list(&self) {
663        for cmd in self.regs().comd_iter() {
664            cmd.reset();
665        }
666    }
667
668    /// Configures the I2C peripheral for a write operation.
669    /// - `addr` is the address of the slave device.
670    /// - `bytes` is the data to be sent
671    /// - `start` indicates whether the operation should start by a START condition and sending the
672    ///   address.
673    /// - `stop` indicates whether the operation will end with a STOP condition.
674    /// - `cmd_iterator` is an iterator over the command registers.
675    fn setup_write<'a, I>(
676        &self,
677        addr: I2cAddress,
678        bytes: &[u8],
679        start: bool,
680        stop: bool,
681        cmd_iterator: &mut I,
682    ) -> Result<(), Error>
683    where
684        I: Iterator<Item = &'a COMD>,
685    {
686        // If start is true we need to send the address, too, which takes up a data
687        // byte.
688        let max_len = if start {
689            I2C_CHUNK_SIZE
690        } else {
691            I2C_CHUNK_SIZE + 1
692        };
693        if bytes.len() > max_len {
694            return Err(Error::FifoExceeded);
695        }
696
697        if start {
698            add_cmd(cmd_iterator, Command::Start)?;
699        }
700
701        let write_len = if start { bytes.len() + 1 } else { bytes.len() };
702        // don't issue write if there is no data to write
703        if write_len > 0 {
704            // ESP32 can't alter the position of END, so we need to split the chunk always into
705            // 3-command sequences. Chunking makes sure not to place a 1-byte
706            // command at the end, which would cause an arithmetic underflow.
707            // The sequences we can generate are:
708            // - START-WRITE-STOP
709            // - START-WRITE-END-WRITE-STOP
710            // - START-WRITE-END-(WRITE-WRITE-END)*-WRITE-STOP sequence.
711            if cfg!(i2c_master_version = "1") && !(start || stop) {
712                // Chunks that do not have a START or STOP command need to be split into multiple
713                // commands.
714                add_cmd(
715                    cmd_iterator,
716                    Command::Write {
717                        ack_exp: Ack::Ack,
718                        ack_check_en: true,
719                        length: (write_len as u8) - 1,
720                    },
721                )?;
722                add_cmd(
723                    cmd_iterator,
724                    Command::Write {
725                        ack_exp: Ack::Ack,
726                        ack_check_en: true,
727                        length: 1,
728                    },
729                )?;
730            } else {
731                add_cmd(
732                    cmd_iterator,
733                    Command::Write {
734                        ack_exp: Ack::Ack,
735                        ack_check_en: true,
736                        length: write_len as u8,
737                    },
738                )?;
739            }
740        }
741
742        if start {
743            // Load address and R/W bit into FIFO
744            match addr {
745                I2cAddress::SevenBit(addr) => {
746                    self.write_fifo((addr << 1) | OperationType::Write as u8);
747                }
748            }
749        }
750        for b in bytes {
751            self.write_fifo(*b);
752        }
753
754        Ok(())
755    }
756
757    /// Configures the I2C peripheral for a read operation.
758    /// - `addr` is the address of the slave device.
759    /// - `buffer` is the buffer to store the read data.
760    /// - `start` indicates whether the operation should start by a START condition and sending the
761    ///   address.
762    /// - `stop` indicates whether the operation will end with a STOP condition.
763    /// - `will_continue` indicates whether there is another read operation following this one and
764    ///   the last byte must not be nacked.
765    /// - `cmd_iterator` is an iterator over the command registers.
766    fn setup_read<'a, I>(
767        &self,
768        addr: I2cAddress,
769        buffer: &mut [u8],
770        start: bool,
771        stop: bool,
772        will_continue: bool,
773        cmd_iterator: &mut I,
774    ) -> Result<(), Error>
775    where
776        I: Iterator<Item = &'a COMD>,
777    {
778        if buffer.is_empty() {
779            return Err(Error::ZeroLengthInvalid);
780        }
781        let (max_len, initial_len) = if will_continue {
782            (I2C_CHUNK_SIZE + 1, buffer.len())
783        } else {
784            (I2C_CHUNK_SIZE, buffer.len() - 1)
785        };
786        if buffer.len() > max_len {
787            return Err(Error::FifoExceeded);
788        }
789
790        if start {
791            add_cmd(cmd_iterator, Command::Start)?;
792            // WRITE 7-bit address
793            add_cmd(
794                cmd_iterator,
795                Command::Write {
796                    ack_exp: Ack::Ack,
797                    ack_check_en: true,
798                    length: 1,
799                },
800            )?;
801        }
802
803        if initial_len > 0 {
804            let extra_commands = if cfg!(i2c_master_version = "1") {
805                match (start, will_continue) {
806                    // No chunking (START-WRITE-READ-STOP) or first chunk (START-WRITE-READ-END)
807                    (true, _) => 0,
808                    // Middle chunk - (READ-READ-READ-END)
809                    (false, true) => 2,
810                    // Last chunk - (READ-READ-STOP-END)
811                    (false, false) => 1 - stop as u8,
812                }
813            } else {
814                0
815            };
816
817            add_cmd(
818                cmd_iterator,
819                Command::Read {
820                    ack_value: Ack::Ack,
821                    length: initial_len as u8 - extra_commands,
822                },
823            )?;
824            for _ in 0..extra_commands {
825                add_cmd(
826                    cmd_iterator,
827                    Command::Read {
828                        ack_value: Ack::Ack,
829                        length: 1,
830                    },
831                )?;
832            }
833        }
834
835        if !will_continue {
836            // this is the last read so we need to nack the last byte
837            // READ w/o ACK
838            add_cmd(
839                cmd_iterator,
840                Command::Read {
841                    ack_value: Ack::Nack,
842                    length: 1,
843                },
844            )?;
845        }
846
847        self.update_registers();
848
849        if start {
850            // Load address and R/W bit into FIFO
851            match addr {
852                I2cAddress::SevenBit(addr) => {
853                    self.write_fifo((addr << 1) | OperationType::Read as u8);
854                }
855            }
856        }
857        Ok(())
858    }
859
860    /// Reads from RX FIFO into the given buffer.
861    fn read_all_from_fifo(&self, buffer: &mut [u8]) -> Result<(), Error> {
862        if self.regs().sr().read().rxfifo_cnt().bits() < buffer.len() as u8 {
863            return Err(Error::ExecutionIncomplete);
864        }
865
866        // Read bytes from FIFO
867        for byte in buffer.iter_mut() {
868            *byte = self.read_fifo();
869        }
870
871        // The RX FIFO should be empty now. If it is not, it means we queued up reading
872        // more data than we read, which is an error.
873        debug_assert!(self.regs().sr().read().rxfifo_cnt().bits() == 0);
874
875        Ok(())
876    }
877
878    /// Clears all pending interrupts for the I2C peripheral.
879    fn clear_all_interrupts(&self) {
880        self.regs()
881            .int_clr()
882            .write(|w| unsafe { w.bits(property!("i2c_master.ll_intr_mask")) });
883    }
884
885    async fn wait_for_completion(&self, deadline: Option<Instant>) -> Result<(), Error> {
886        I2cFuture::new(Event::TxComplete | Event::EndDetect, *self, deadline).await?;
887        self.check_all_commands_done(deadline).await
888    }
889
890    /// Waits for the completion of an I2C transaction.
891    fn wait_for_completion_blocking(&self, deadline: Option<Instant>) -> Result<(), Error> {
892        let mut future =
893            I2cFuture::new_blocking(Event::TxComplete | Event::EndDetect, *self, deadline);
894        loop {
895            if let Poll::Ready(result) = future.poll_completion() {
896                result?;
897                return self.check_all_commands_done_blocking(deadline);
898            }
899        }
900    }
901
902    fn all_commands_done(&self, deadline: Option<Instant>) -> Result<bool, Error> {
903        // NOTE: on esp32 executing the end command generates the end_detect interrupt
904        //       but does not seem to clear the done bit! So we don't check the done
905        //       status of an end command
906        let now = if deadline.is_some() {
907            Instant::now()
908        } else {
909            Instant::EPOCH
910        };
911
912        self.check_errors()?;
913
914        for cmd_reg in self.regs().comd_iter() {
915            let cmd = cmd_reg.read();
916
917            // if there is a valid command which is not END, check if it's marked as done
918            if cmd.bits() != 0x0 && !cmd.opcode().is_end() && !cmd.command_done().bit_is_set() {
919                // Let's retry
920                if let Some(deadline) = deadline
921                    && now > deadline
922                {
923                    return Err(Error::ExecutionIncomplete);
924                }
925
926                return Ok(false);
927            }
928
929            // once we hit END or STOP we can break the loop
930            if cmd.opcode().is_end() {
931                break;
932            }
933            if cmd.opcode().is_stop() {
934                #[cfg(i2c_master_version = "1")]
935                // wait for STOP - apparently on ESP32 we otherwise miss the ACK error for an
936                // empty write
937                if self.regs().sr().read().scl_state_last() == 6 {
938                    self.check_errors()?;
939                } else {
940                    continue;
941                }
942                break;
943            }
944        }
945        Ok(true)
946    }
947
948    /// Returns whether all I2C commands have completed execution.
949    fn check_all_commands_done_blocking(&self, deadline: Option<Instant>) -> Result<(), Error> {
950        // loop until commands are actually done
951        while !self.all_commands_done(deadline)? {}
952        self.check_errors()?;
953
954        Ok(())
955    }
956
957    /// Returns whether all I2C commands have completed execution.
958    async fn check_all_commands_done(&self, deadline: Option<Instant>) -> Result<(), Error> {
959        // loop until commands are actually done
960        while !self.all_commands_done(deadline)? {
961            embassy_futures::yield_now().await;
962        }
963        self.check_errors()?;
964
965        Ok(())
966    }
967
968    /// Checks for I2C transmission errors and handles them.
969    ///
970    /// Inspects specific I2C-related interrupts to detect errors during
971    /// communication, such as timeouts, failed acknowledgments, or arbitration loss.
972    /// If an error is detected, resets the I2C peripheral to clear the error condition
973    /// and returns an appropriate error.
974    fn check_errors(&self) -> Result<(), Error> {
975        let r = self.regs().int_raw().read();
976
977        // Handle error cases
978        if r.nack().bit_is_set() {
979            return Err(Error::AcknowledgeCheckFailed(estimate_ack_failed_reason(
980                self.regs(),
981            )));
982        }
983        if r.arbitration_lost().bit_is_set() {
984            return Err(Error::ArbitrationLost);
985        }
986
987        #[cfg(not(i2c_master_version = "1"))]
988        if r.trans_complete().bit_is_set() && self.regs().sr().read().resp_rec().bit_is_clear() {
989            return Err(Error::AcknowledgeCheckFailed(
990                AcknowledgeCheckFailedReason::Data,
991            ));
992        }
993
994        #[cfg(i2c_master_has_fsm_timeouts)]
995        {
996            if r.scl_st_to().bit_is_set() {
997                return Err(Error::Timeout);
998            }
999            if r.scl_main_st_to().bit_is_set() {
1000                return Err(Error::Timeout);
1001            }
1002        }
1003        if r.time_out().bit_is_set() {
1004            return Err(Error::Timeout);
1005        }
1006
1007        Ok(())
1008    }
1009
1010    /// Updates the configuration of the I2C peripheral.
1011    ///
1012    /// Ensures that configuration values, such as clock settings, SDA/SCL filtering,
1013    /// timeouts, and other operational parameters configured in other methods, are
1014    /// propagated to the I2C hardware. This step synchronizes the software-configured
1015    /// settings with the peripheral's internal registers.
1016    fn update_registers(&self) {
1017        // Ensure that the configuration of the peripheral is correctly propagated
1018        // (only necessary for C2, C3, C6, H2 and S3 variant)
1019        #[cfg(i2c_master_has_conf_update)]
1020        self.regs().ctr().modify(|_, w| w.conf_upgate().set_bit());
1021    }
1022
1023    fn set_frequency(&self, config: &Config) -> Result<(), ConfigError> {
1024        version::set_frequency(self, config)
1025    }
1026
1027    fn reset_fifo(&self) {
1028        version::reset_fifo(self);
1029    }
1030
1031    fn read_fifo(&self) -> u8 {
1032        version::read_fifo(self.regs())
1033    }
1034
1035    fn write_fifo(&self, data: u8) {
1036        version::write_fifo(self.regs(), data);
1037    }
1038
1039    /// Starts an I2C transmission.
1040    fn start_transmission(&self) {
1041        // Start transmission
1042        self.regs().ctr().modify(|_, w| w.trans_start().set_bit());
1043    }
1044
1045    fn start_write_operation(
1046        &self,
1047        address: I2cAddress,
1048        buffer: &[u8],
1049        start: bool,
1050        stop: bool,
1051        deadline: Deadline,
1052    ) -> Result<Option<Instant>, Error> {
1053        let cmd_iterator = &mut self.regs().comd_iter();
1054
1055        self.setup_write(address, buffer, start, stop, cmd_iterator)?;
1056
1057        if stop {
1058            add_cmd(cmd_iterator, Command::Stop)?;
1059        }
1060        if !(start && stop) {
1061            // Multi-chunk write, terminate with END. ESP32 TRM suggests a write should work with
1062            // only a STOP at the end, but STOP does not seem to generate a TX_COMPLETE interrupt
1063            // without END.
1064            add_cmd(cmd_iterator, Command::End)?;
1065        }
1066
1067        self.start_transmission();
1068
1069        Ok(deadline.start(buffer.len() + address.bytes()))
1070    }
1071
1072    /// Executes an I2C read operation.
1073    /// - `addr` is the address of the slave device.
1074    /// - `buffer` is the buffer to store the read data.
1075    /// - `start` indicates whether the operation should start by a START condition and sending the
1076    ///   address.
1077    /// - `stop` indicates whether the operation should end with a STOP condition.
1078    /// - `will_continue` indicates whether there is another read operation following this one and
1079    ///   the last byte must not be nacked.
1080    /// - `cmd_iterator` is an iterator over the command registers.
1081    fn start_read_operation(
1082        &self,
1083        address: I2cAddress,
1084        buffer: &mut [u8],
1085        start: bool,
1086        will_continue: bool,
1087        stop: bool,
1088        deadline: Deadline,
1089    ) -> Result<Option<Instant>, Error> {
1090        // We don't support single I2C reads larger than the FIFO. This should be
1091        // enforced by `VariableChunkIterMut` used in `Driver::read` and
1092        // `Driver::read_async`.
1093        debug_assert!(buffer.len() <= I2C_FIFO_SIZE);
1094
1095        let cmd_iterator = &mut self.regs().comd_iter();
1096
1097        self.setup_read(address, buffer, start, stop, will_continue, cmd_iterator)?;
1098
1099        if stop {
1100            add_cmd(cmd_iterator, Command::Stop)?;
1101        }
1102        if !(start && stop) {
1103            // Multi-chunk read, terminate with END. On ESP32, assume same limitation as writes.
1104            add_cmd(cmd_iterator, Command::End)?;
1105        }
1106
1107        self.start_transmission();
1108
1109        Ok(deadline.start(buffer.len() + address.bytes()))
1110    }
1111
1112    /// Executes an I2C write operation.
1113    /// - `addr` is the address of the slave device.
1114    /// - `bytes` is the data to be sent
1115    /// - `start` indicates whether the operation should start by a START condition and sending the
1116    ///   address.
1117    /// - `stop` indicates whether the operation should end with a STOP condition.
1118    /// - `cmd_iterator` is an iterator over the command registers.
1119    fn write_operation_blocking(
1120        &self,
1121        address: I2cAddress,
1122        bytes: &[u8],
1123        start: bool,
1124        stop: bool,
1125        deadline: Deadline,
1126    ) -> Result<(), Error> {
1127        address.validate()?;
1128
1129        self.reset_before_transmission();
1130
1131        // Short circuit for zero length writes without start or end as that would be an
1132        // invalid operation write lengths in the TRM (at least for ESP32-S3) are 1-255
1133        if bytes.is_empty() && !start && !stop {
1134            return Ok(());
1135        }
1136
1137        let deadline = self.start_write_operation(address, bytes, start, stop, deadline)?;
1138        self.wait_for_completion_blocking(deadline)?;
1139
1140        Ok(())
1141    }
1142
1143    /// Executes an I2C read operation.
1144    /// - `addr` is the address of the slave device.
1145    /// - `buffer` is the buffer to store the read data.
1146    /// - `start` indicates whether the operation should start by a START condition and sending the
1147    ///   address.
1148    /// - `stop` indicates whether the operation should end with a STOP condition.
1149    /// - `will_continue` indicates whether there is another read operation following this one and
1150    ///   the last byte must not be nacked.
1151    /// - `cmd_iterator` is an iterator over the command registers.
1152    fn read_operation_blocking(
1153        &self,
1154        address: I2cAddress,
1155        buffer: &mut [u8],
1156        start: bool,
1157        stop: bool,
1158        will_continue: bool,
1159        deadline: Deadline,
1160    ) -> Result<(), Error> {
1161        address.validate()?;
1162        self.reset_before_transmission();
1163
1164        // Short circuit for zero length reads as that would be an invalid operation
1165        // read lengths in the TRM (at least for ESP32-S3) are 1-255
1166        if buffer.is_empty() {
1167            return Ok(());
1168        }
1169
1170        let deadline =
1171            self.start_read_operation(address, buffer, start, will_continue, stop, deadline)?;
1172        self.wait_for_completion_blocking(deadline)?;
1173        self.read_all_from_fifo(buffer)?;
1174
1175        Ok(())
1176    }
1177
1178    /// Executes an async I2C write operation.
1179    /// - `addr` is the address of the slave device.
1180    /// - `bytes` is the data to be sent
1181    /// - `start` indicates whether the operation should start by a START condition and sending the
1182    ///   address.
1183    /// - `stop` indicates whether the operation should end with a STOP condition.
1184    /// - `cmd_iterator` is an iterator over the command registers.
1185    async fn write_operation(
1186        &self,
1187        address: I2cAddress,
1188        bytes: &[u8],
1189        start: bool,
1190        stop: bool,
1191        deadline: Deadline,
1192    ) -> Result<(), Error> {
1193        address.validate()?;
1194        self.reset_before_transmission();
1195
1196        // Short circuit for zero length writes without start or end as that would be an
1197        // invalid operation write lengths in the TRM (at least for ESP32-S3) are 1-255
1198        if bytes.is_empty() && !start && !stop {
1199            return Ok(());
1200        }
1201
1202        let deadline = self.start_write_operation(address, bytes, start, stop, deadline)?;
1203        self.wait_for_completion(deadline).await?;
1204
1205        Ok(())
1206    }
1207
1208    /// Executes an async I2C read operation.
1209    /// - `addr` is the address of the slave device.
1210    /// - `buffer` is the buffer to store the read data.
1211    /// - `start` indicates whether the operation should start by a START condition and sending the
1212    ///   address.
1213    /// - `stop` indicates whether the operation should end with a STOP condition.
1214    /// - `will_continue` indicates whether there is another read operation following this one and
1215    ///   the last byte must not be nacked.
1216    /// - `cmd_iterator` is an iterator over the command registers.
1217    async fn read_operation(
1218        &self,
1219        address: I2cAddress,
1220        buffer: &mut [u8],
1221        start: bool,
1222        stop: bool,
1223        will_continue: bool,
1224        deadline: Deadline,
1225    ) -> Result<(), Error> {
1226        address.validate()?;
1227        self.reset_before_transmission();
1228
1229        // Short circuit for zero length reads as that would be an invalid operation
1230        // read lengths in the TRM (at least for ESP32-S3) are 1-255
1231        if buffer.is_empty() {
1232            return Ok(());
1233        }
1234
1235        let deadline =
1236            self.start_read_operation(address, buffer, start, will_continue, stop, deadline)?;
1237        self.wait_for_completion(deadline).await?;
1238        self.read_all_from_fifo(buffer)?;
1239
1240        Ok(())
1241    }
1242
1243    fn read_blocking(
1244        &self,
1245        address: I2cAddress,
1246        buffer: &mut [u8],
1247        start: bool,
1248        stop: bool,
1249        will_continue: bool,
1250        deadline: Deadline,
1251    ) -> Result<(), Error> {
1252        let chunk_count = VariableChunkIterMut::new(buffer).count();
1253        for (idx, chunk) in VariableChunkIterMut::new(buffer).enumerate() {
1254            self.read_operation_blocking(
1255                address,
1256                chunk,
1257                start && idx == 0,
1258                stop && idx == chunk_count - 1,
1259                will_continue || idx < chunk_count - 1,
1260                deadline,
1261            )?;
1262        }
1263
1264        Ok(())
1265    }
1266
1267    fn write_blocking(
1268        &self,
1269        address: I2cAddress,
1270        buffer: &[u8],
1271        start: bool,
1272        stop: bool,
1273        deadline: Deadline,
1274    ) -> Result<(), Error> {
1275        if buffer.is_empty() {
1276            return self.write_operation_blocking(address, &[], start, stop, deadline);
1277        }
1278
1279        let chunk_count = VariableChunkIter::new(buffer).count();
1280        for (idx, chunk) in VariableChunkIter::new(buffer).enumerate() {
1281            self.write_operation_blocking(
1282                address,
1283                chunk,
1284                start && idx == 0,
1285                stop && idx == chunk_count - 1,
1286                deadline,
1287            )?;
1288        }
1289
1290        Ok(())
1291    }
1292
1293    async fn read(
1294        &self,
1295        address: I2cAddress,
1296        buffer: &mut [u8],
1297        start: bool,
1298        stop: bool,
1299        will_continue: bool,
1300        deadline: Deadline,
1301    ) -> Result<(), Error> {
1302        let chunk_count = VariableChunkIterMut::new(buffer).count();
1303        for (idx, chunk) in VariableChunkIterMut::new(buffer).enumerate() {
1304            self.read_operation(
1305                address,
1306                chunk,
1307                start && idx == 0,
1308                stop && idx == chunk_count - 1,
1309                will_continue || idx < chunk_count - 1,
1310                deadline,
1311            )
1312            .await?;
1313        }
1314
1315        Ok(())
1316    }
1317
1318    async fn write(
1319        &self,
1320        address: I2cAddress,
1321        buffer: &[u8],
1322        start: bool,
1323        stop: bool,
1324        deadline: Deadline,
1325    ) -> Result<(), Error> {
1326        if buffer.is_empty() {
1327            return self
1328                .write_operation(address, &[], start, stop, deadline)
1329                .await;
1330        }
1331
1332        let chunk_count = VariableChunkIter::new(buffer).count();
1333        for (idx, chunk) in VariableChunkIter::new(buffer).enumerate() {
1334            self.write_operation(
1335                address,
1336                chunk,
1337                start && idx == 0,
1338                stop && idx == chunk_count - 1,
1339                deadline,
1340            )
1341            .await?;
1342        }
1343
1344        Ok(())
1345    }
1346
1347    pub(super) fn transaction_impl<'a>(
1348        &self,
1349        address: I2cAddress,
1350        operations: impl Iterator<Item = Operation<'a>>,
1351    ) -> Result<(), Error> {
1352        address.validate()?;
1353        self.ensure_idle_blocking();
1354
1355        let mut deadline = Deadline::None;
1356
1357        if let SoftwareTimeout::Transaction(timeout) = self.config.config.software_timeout {
1358            deadline = Deadline::Fixed(Instant::now() + timeout);
1359        }
1360
1361        let mut last_op: Option<OpKind> = None;
1362        // filter out 0 length read operations
1363        let mut op_iter = operations
1364            .filter(|op| op.is_write() || !op.is_empty())
1365            .peekable();
1366
1367        while let Some(op) = op_iter.next() {
1368            let next_op = op_iter.peek().map(|v| v.kind());
1369            let kind = op.kind();
1370            match op {
1371                Operation::Write(buffer) => {
1372                    // execute a write operation:
1373                    // - issue START/RSTART if op is different from previous
1374                    // - issue STOP if op is the last one
1375                    if let SoftwareTimeout::PerByte(timeout) = self.config.config.software_timeout {
1376                        deadline = Deadline::PerByte(timeout);
1377                    }
1378                    self.write_blocking(
1379                        address,
1380                        buffer,
1381                        !matches!(last_op, Some(OpKind::Write)),
1382                        next_op.is_none(),
1383                        deadline,
1384                    )?;
1385                }
1386                Operation::Read(buffer) => {
1387                    if let SoftwareTimeout::PerByte(timeout) = self.config.config.software_timeout {
1388                        deadline = Deadline::PerByte(timeout);
1389                    }
1390                    // execute a read operation:
1391                    // - issue START/RSTART if op is different from previous
1392                    // - issue STOP if op is the last one
1393                    // - will_continue is true if there is another read operation next
1394                    self.read_blocking(
1395                        address,
1396                        buffer,
1397                        !matches!(last_op, Some(OpKind::Read)),
1398                        next_op.is_none(),
1399                        matches!(next_op, Some(OpKind::Read)),
1400                        deadline,
1401                    )?;
1402                }
1403            }
1404
1405            last_op = Some(kind);
1406        }
1407
1408        Ok(())
1409    }
1410
1411    pub(super) async fn transaction_impl_async<'a>(
1412        &self,
1413        address: I2cAddress,
1414        operations: impl Iterator<Item = Operation<'a>>,
1415    ) -> Result<(), Error> {
1416        address.validate()?;
1417        self.ensure_idle().await;
1418
1419        let mut deadline = Deadline::None;
1420
1421        if let SoftwareTimeout::Transaction(timeout) = self.config.config.software_timeout {
1422            deadline = Deadline::Fixed(Instant::now() + timeout);
1423        }
1424
1425        let mut last_op: Option<OpKind> = None;
1426        // filter out 0 length read operations
1427        let mut op_iter = operations
1428            .filter(|op| op.is_write() || !op.is_empty())
1429            .peekable();
1430
1431        while let Some(op) = op_iter.next() {
1432            let next_op = op_iter.peek().map(|v| v.kind());
1433            let kind = op.kind();
1434            match op {
1435                Operation::Write(buffer) => {
1436                    if let SoftwareTimeout::PerByte(timeout) = self.config.config.software_timeout {
1437                        deadline = Deadline::PerByte(timeout);
1438                    }
1439                    // execute a write operation:
1440                    // - issue START/RSTART if op is different from previous
1441                    // - issue STOP if op is the last one
1442                    self.write(
1443                        address,
1444                        buffer,
1445                        !matches!(last_op, Some(OpKind::Write)),
1446                        next_op.is_none(),
1447                        deadline,
1448                    )
1449                    .await?;
1450                }
1451                Operation::Read(buffer) => {
1452                    if let SoftwareTimeout::PerByte(timeout) = self.config.config.software_timeout {
1453                        deadline = Deadline::PerByte(timeout);
1454                    }
1455                    // execute a read operation:
1456                    // - issue START/RSTART if op is different from previous
1457                    // - issue STOP if op is the last one
1458                    // - will_continue is true if there is another read operation next
1459                    self.read(
1460                        address,
1461                        buffer,
1462                        !matches!(last_op, Some(OpKind::Read)),
1463                        next_op.is_none(),
1464                        matches!(next_op, Some(OpKind::Read)),
1465                        deadline,
1466                    )
1467                    .await?;
1468                }
1469            }
1470
1471            last_op = Some(kind);
1472        }
1473
1474        Ok(())
1475    }
1476}
1477
1478/// Chunks a slice by I2C_CHUNK_SIZE in a way to avoid the last chunk being
1479/// sized smaller than 2
1480struct VariableChunkIterMut<'a, T> {
1481    buffer: &'a mut [T],
1482}
1483
1484impl<'a, T> VariableChunkIterMut<'a, T> {
1485    fn new(buffer: &'a mut [T]) -> Self {
1486        Self { buffer }
1487    }
1488}
1489
1490impl<'a, T> Iterator for VariableChunkIterMut<'a, T> {
1491    type Item = &'a mut [T];
1492
1493    fn next(&mut self) -> Option<Self::Item> {
1494        if self.buffer.is_empty() {
1495            return None;
1496        }
1497
1498        let s = calculate_chunk_size(self.buffer.len());
1499        let (chunk, remaining) = core::mem::take(&mut self.buffer).split_at_mut(s);
1500        self.buffer = remaining;
1501        Some(chunk)
1502    }
1503}
1504
1505/// Chunks a slice by I2C_CHUNK_SIZE in a way to avoid the last chunk being
1506/// sized smaller than 2
1507struct VariableChunkIter<'a, T> {
1508    buffer: &'a [T],
1509}
1510
1511impl<'a, T> VariableChunkIter<'a, T> {
1512    fn new(buffer: &'a [T]) -> Self {
1513        Self { buffer }
1514    }
1515}
1516
1517impl<'a, T> Iterator for VariableChunkIter<'a, T> {
1518    type Item = &'a [T];
1519
1520    fn next(&mut self) -> Option<Self::Item> {
1521        if self.buffer.is_empty() {
1522            return None;
1523        }
1524
1525        let s = calculate_chunk_size(self.buffer.len());
1526        let (chunk, remaining) = core::mem::take(&mut self.buffer).split_at(s);
1527        self.buffer = remaining;
1528        Some(chunk)
1529    }
1530}
1531
1532fn calculate_chunk_size(remaining: usize) -> usize {
1533    if remaining <= I2C_CHUNK_SIZE {
1534        remaining
1535    } else if remaining > I2C_CHUNK_SIZE + 2 {
1536        I2C_CHUNK_SIZE
1537    } else {
1538        I2C_CHUNK_SIZE - 2
1539    }
1540}
1541
1542#[cfg(i2c_master_has_hw_bus_clear)]
1543mod bus_clear {
1544    use esp_rom_sys::rom::ets_delay_us;
1545
1546    use super::*;
1547
1548    #[must_use = "futures do nothing unless you `.await` or poll them"]
1549    pub struct ClearBusFuture<'a> {
1550        driver: Driver<'a>,
1551    }
1552
1553    impl<'a> ClearBusFuture<'a> {
1554        // Number of SCL pulses to clear the bus
1555        const BUS_CLEAR_BITS: u8 = 9;
1556        const DELAY_US: u32 = 5; // 5us -> 100kHz
1557
1558        pub fn new(driver: Driver<'a>, reset_fsm: bool) -> Self {
1559            // If we have a HW implementation, reset FSM to make sure it's not trying to transmit
1560            // while we clear the bus.
1561            if reset_fsm {
1562                // Resetting the FSM may still generate a short SCL pulse, but I don't know how to
1563                // work around it - just waiting doesn't solve anything if the hardware is running.
1564                driver.do_fsm_reset();
1565            }
1566
1567            let mut this = Self { driver };
1568
1569            // Prevent SCL from going low immediately after FSM reset/previous operation has set
1570            // it high
1571            ets_delay_us(Self::DELAY_US);
1572
1573            this.configure(Self::BUS_CLEAR_BITS);
1574            this
1575        }
1576
1577        fn configure(&mut self, bits: u8) {
1578            self.driver.regs().scl_sp_conf().modify(|_, w| {
1579                unsafe { w.scl_rst_slv_num().bits(bits) };
1580                w.scl_rst_slv_en().bit(bits > 0)
1581            });
1582            self.driver.update_registers();
1583        }
1584
1585        fn is_done(&self) -> bool {
1586            self.driver
1587                .regs()
1588                .scl_sp_conf()
1589                .read()
1590                .scl_rst_slv_en()
1591                .bit_is_clear()
1592        }
1593
1594        pub fn poll_completion(&mut self) -> Poll<()> {
1595            if self.is_done() {
1596                Poll::Ready(())
1597            } else {
1598                Poll::Pending
1599            }
1600        }
1601    }
1602
1603    impl Drop for ClearBusFuture<'_> {
1604        fn drop(&mut self) {
1605            use crate::gpio::AnyPin;
1606            if !self.is_done() {
1607                self.configure(0);
1608            }
1609
1610            // Generate a stop condition
1611            let sda = self
1612                .driver
1613                .config
1614                .sda_pin
1615                .pin_number()
1616                .map(|n| unsafe { AnyPin::steal(n) });
1617            let scl = self
1618                .driver
1619                .config
1620                .scl_pin
1621                .pin_number()
1622                .map(|n| unsafe { AnyPin::steal(n) });
1623
1624            if let (Some(sda), Some(scl)) = (sda, scl) {
1625                // Prevent short SCL pulse right after HW clearing completes
1626                ets_delay_us(Self::DELAY_US);
1627
1628                sda.set_output_high(true);
1629                scl.set_output_high(false);
1630
1631                self.driver.info.scl_output.disconnect_from(&scl);
1632                self.driver.info.sda_output.disconnect_from(&sda);
1633
1634                // Set SDA low - whatever state it was in, we need a low -> high transition.
1635                sda.set_output_high(false);
1636                ets_delay_us(Self::DELAY_US);
1637
1638                // Set SCL high to prepare for STOP condition
1639                scl.set_output_high(true);
1640                ets_delay_us(Self::DELAY_US);
1641
1642                // STOP
1643                sda.set_output_high(true);
1644                ets_delay_us(Self::DELAY_US);
1645
1646                self.driver.info.sda_output.connect_to(&sda);
1647                self.driver.info.scl_output.connect_to(&scl);
1648            }
1649
1650            // We don't care about errors during bus clearing
1651            self.driver.clear_all_interrupts();
1652        }
1653    }
1654}
1655
1656#[cfg(not(i2c_master_has_hw_bus_clear))]
1657mod bus_clear {
1658    use super::*;
1659    use crate::gpio::AnyPin;
1660
1661    /// State of the bus clearing operation.
1662    ///
1663    /// Pins are changed on the start of the state, and a wait is scheduled
1664    /// for the end of the state. At the end of the wait, the state is
1665    /// updated to the next state.
1666    enum State {
1667        Idle,
1668        SendStop,
1669
1670        // Number of SCL pulses left to send, and the last SCL level.
1671        //
1672        // Our job is to send 9 high->low SCL transitions, followed by a STOP condition.
1673        SendClock(u8, bool),
1674    }
1675
1676    #[must_use = "futures do nothing unless you `.await` or poll them"]
1677    pub struct ClearBusFuture<'a> {
1678        driver: Driver<'a>,
1679        wait: Instant,
1680        state: State,
1681        reset_fsm: bool,
1682        pins: Option<(AnyPin<'static>, AnyPin<'static>)>,
1683    }
1684
1685    impl<'a> ClearBusFuture<'a> {
1686        // Number of SCL pulses to clear the bus (max 8 data bits sent by the device, + NACK)
1687        const BUS_CLEAR_BITS: u8 = 9;
1688        // use standard 100kHz data rate
1689        const SCL_DELAY: Duration = Duration::from_micros(5);
1690
1691        pub fn new(driver: Driver<'a>, reset_fsm: bool) -> Self {
1692            let sda = driver
1693                .config
1694                .sda_pin
1695                .pin_number()
1696                .map(|n| unsafe { AnyPin::steal(n) });
1697            let scl = driver
1698                .config
1699                .scl_pin
1700                .pin_number()
1701                .map(|n| unsafe { AnyPin::steal(n) });
1702
1703            let (Some(sda), Some(scl)) = (sda, scl) else {
1704                // If we don't have the pins, we can't clear the bus.
1705                if reset_fsm {
1706                    driver.do_fsm_reset();
1707                }
1708                return Self {
1709                    driver,
1710                    wait: Instant::now(),
1711                    state: State::Idle,
1712                    reset_fsm: false,
1713                    pins: None,
1714                };
1715            };
1716
1717            sda.set_output_high(true);
1718            scl.set_output_high(false);
1719
1720            driver.info.scl_output.disconnect_from(&scl);
1721            driver.info.sda_output.disconnect_from(&sda);
1722
1723            // Starting from (9, false), because:
1724            // - we start with SCL low
1725            // - a complete SCL cycle consists of a high period and a low period
1726            // - we decrement the remaining counter at the beginning of a cycle, which gives us 9
1727            //   complete SCL cycles.
1728            let state = State::SendClock(Self::BUS_CLEAR_BITS, false);
1729
1730            Self {
1731                driver,
1732                wait: Instant::now() + Self::SCL_DELAY,
1733                state,
1734                reset_fsm,
1735                pins: Some((sda, scl)),
1736            }
1737        }
1738    }
1739
1740    impl ClearBusFuture<'_> {
1741        pub fn poll_completion(&mut self) -> Poll<()> {
1742            let now = Instant::now();
1743
1744            match self.state {
1745                State::Idle => {
1746                    if let Some((sda, _scl)) = self.pins.as_ref() {
1747                        // Pins are disconnected from the peripheral, we can't use `bus_busy`.
1748                        if !sda.is_input_high() {
1749                            return Poll::Pending;
1750                        }
1751                    }
1752                    return Poll::Ready(());
1753                }
1754                _ if now < self.wait => {
1755                    // Still waiting for the end of the SCL pulse
1756                    return Poll::Pending;
1757                }
1758                State::SendStop => {
1759                    if let Some((sda, _scl)) = self.pins.as_ref() {
1760                        sda.set_output_high(true); // STOP, SDA low -> high while SCL is HIGH
1761                    }
1762                    self.state = State::Idle;
1763                    return Poll::Pending;
1764                }
1765                State::SendClock(0, false) => {
1766                    if let Some((sda, scl)) = self.pins.as_ref() {
1767                        // Set up for STOP condition
1768                        sda.set_output_high(false);
1769                        scl.set_output_high(true);
1770                    }
1771                    self.state = State::SendStop;
1772                }
1773                State::SendClock(n, false) => {
1774                    if let Some((sda, scl)) = self.pins.as_ref() {
1775                        scl.set_output_high(true);
1776                        if sda.is_input_high() {
1777                            sda.set_output_high(false);
1778                            // The device has released SDA, we can move on to generating a STOP
1779                            // condition
1780                            self.wait = Instant::now() + Self::SCL_DELAY;
1781                            self.state = State::SendStop;
1782                            return Poll::Pending;
1783                        }
1784                    }
1785                    self.state = State::SendClock(n - 1, true);
1786                }
1787                State::SendClock(n, true) => {
1788                    if let Some((_sda, scl)) = self.pins.as_ref() {
1789                        scl.set_output_high(false);
1790                    }
1791                    self.state = State::SendClock(n, false);
1792                }
1793            }
1794            self.wait = Instant::now() + Self::SCL_DELAY;
1795
1796            Poll::Pending
1797        }
1798    }
1799
1800    impl Drop for ClearBusFuture<'_> {
1801        fn drop(&mut self) {
1802            if let Some((sda, scl)) = self.pins.take() {
1803                // Make sure _we_ release the bus.
1804                scl.set_output_high(true);
1805                sda.set_output_high(true);
1806
1807                // If we don't have a HW implementation, reset the peripheral after clearing the
1808                // bus, but before we reconnect the pins in Drop. This should prevent glitches.
1809                if self.reset_fsm {
1810                    self.driver.do_fsm_reset();
1811                }
1812
1813                self.driver.info.sda_output.connect_to(&sda);
1814                self.driver.info.scl_output.connect_to(&scl);
1815
1816                // We don't care about errors during bus clearing. There shouldn't be any,
1817                // anyway.
1818                self.driver.clear_all_interrupts();
1819            }
1820        }
1821    }
1822}
1823
1824use bus_clear::ClearBusFuture;
1825
1826impl Future for ClearBusFuture<'_> {
1827    type Output = ();
1828
1829    fn poll(mut self: Pin<&mut Self>, ctx: &mut Context<'_>) -> Poll<Self::Output> {
1830        let pending = self.poll_completion();
1831        if pending.is_pending() {
1832            ctx.waker().wake_by_ref();
1833        }
1834        pending
1835    }
1836}
1837
1838/// Peripheral state for an I2C instance.
1839#[doc(hidden)]
1840#[non_exhaustive]
1841pub struct State {
1842    /// Waker for the asynchronous operations.
1843    pub waker: AtomicWaker,
1844}
1845
1846/// A peripheral singleton compatible with the I2C master driver.
1847pub trait Instance: crate::private::Sealed + any::Degrade {
1848    #[doc(hidden)]
1849    /// Returns the peripheral data and state describing this instance.
1850    fn parts(&self) -> (&Info, &State);
1851
1852    /// Returns the peripheral data describing this instance.
1853    #[doc(hidden)]
1854    #[inline(always)]
1855    fn info(&self) -> &Info {
1856        self.parts().0
1857    }
1858
1859    /// Returns the peripheral state for this instance.
1860    #[doc(hidden)]
1861    #[inline(always)]
1862    fn state(&self) -> &State {
1863        self.parts().1
1864    }
1865}
1866
1867/// Adds a command to the I2C command sequence.
1868///
1869/// The first command after a FSM reset must be a START, otherwise
1870/// the hardware will hang with no timeouts.
1871fn add_cmd<'a, I>(cmd_iterator: &mut I, command: Command) -> Result<(), Error>
1872where
1873    I: Iterator<Item = &'a COMD>,
1874{
1875    let cmd = cmd_iterator.next().ok_or(Error::CommandNumberExceeded)?;
1876
1877    cmd.write(|w| match command {
1878        Command::Start => w.opcode().rstart(),
1879        Command::Stop => w.opcode().stop(),
1880        Command::End => w.opcode().end(),
1881        Command::Write {
1882            ack_exp,
1883            ack_check_en,
1884            length,
1885        } => unsafe {
1886            w.opcode().write();
1887            w.ack_exp().bit(ack_exp == Ack::Nack);
1888            w.ack_check_en().bit(ack_check_en);
1889            w.byte_num().bits(length);
1890            w
1891        },
1892        Command::Read { ack_value, length } => unsafe {
1893            w.opcode().read();
1894            w.ack_value().bit(ack_value == Ack::Nack);
1895            w.byte_num().bits(length);
1896            w
1897        },
1898    });
1899
1900    Ok(())
1901}
1902
1903// Estimate the reason for an acknowledge check failure on a best effort basis.
1904// When in doubt it's better to return `Unknown` than to return a wrong reason.
1905fn estimate_ack_failed_reason(_register_block: &RegisterBlock) -> AcknowledgeCheckFailedReason {
1906    cfg_select! {
1907        i2c_master_can_estimate_nack_reason => {
1908            // this is based on observations rather than documented behavior
1909            if _register_block.fifo_st().read().txfifo_raddr().bits() <= 1 {
1910                AcknowledgeCheckFailedReason::Address
1911            } else {
1912                AcknowledgeCheckFailedReason::Data
1913            }
1914        }
1915        _ => AcknowledgeCheckFailedReason::Unknown,
1916    }
1917}
1918
1919for_each_i2c_master!(
1920    ($id:literal, $inst:ident, $peri:ident, $scl:ident, $sda:ident) => {
1921        impl Instance for crate::peripherals::$inst<'_> {
1922            fn parts(&self) -> (&Info, &State) {
1923                #[handler]
1924                #[ram]
1925                pub(super) fn irq_handler() {
1926                    async_handler(&PERIPHERAL, &STATE);
1927                }
1928
1929                static STATE: State = State {
1930                    waker: AtomicWaker::new(),
1931                };
1932
1933                static PERIPHERAL: Info = Info {
1934                    #[cfg(soc_has_i2c1)]
1935                    id: $id,
1936                    register_block: crate::peripherals::$inst::ptr(),
1937                    peripheral: crate::system::Peripheral::$peri,
1938                    async_handler: irq_handler,
1939                    scl_output: OutputSignal::$scl,
1940                    scl_input: InputSignal::$scl,
1941                    sda_output: OutputSignal::$sda,
1942                    sda_input: InputSignal::$sda,
1943                    clock_instance: paste::paste! { crate::soc::clocks::I2cInstance::[<I2c $id>] },
1944                };
1945                (&PERIPHERAL, &STATE)
1946            }
1947        }
1948    };
1949);
1950
1951crate::any_peripheral! {
1952    /// Any I2C peripheral.
1953    pub peripheral AnyI2c<'d> {
1954        #[cfg(i2c_master_i2c0)]
1955        I2c0(crate::peripherals::I2C0<'d>),
1956        #[cfg(i2c_master_i2c1)]
1957        I2c1(crate::peripherals::I2C1<'d>),
1958    }
1959}
1960
1961impl Instance for AnyI2c<'_> {
1962    fn parts(&self) -> (&Info, &State) {
1963        any::delegate!(self, i2c => { i2c.parts() })
1964    }
1965}
1966
1967impl AnyI2c<'_> {
1968    fn bind_peri_interrupt(&self, handler: InterruptHandler) {
1969        any::delegate!(self, i2c => { i2c.bind_peri_interrupt(handler) })
1970    }
1971
1972    pub(super) fn disable_peri_interrupt_on_all_cores(&self) {
1973        any::delegate!(self, i2c => { i2c.disable_peri_interrupt_on_all_cores() })
1974    }
1975
1976    pub(super) fn set_interrupt_handler(&self, handler: InterruptHandler) {
1977        self.disable_peri_interrupt_on_all_cores();
1978
1979        self.info().enable_listen(EnumSet::all(), false);
1980        self.info().clear_interrupts(EnumSet::all());
1981
1982        self.bind_peri_interrupt(handler);
1983    }
1984}