4. Peripherals

4.1. USB

4.1.1. Overview

Prerequisite Knowledge Required

This section requires knowledge of the USB protocol. We recommend USB Made Simple if you are unclear on the terminology used in this section.

RP2040 contains a USB 2.0 controller that can operate as either:

• • a Full Speed device (12Mbps)
• • a host that can communicate with both Low Speed (1.5Mbps) and Full Speed devices. This includes multiple downstream devices connected to a USB hub.

There is an integrated USB 1.1 PHY which interfaces the USB controller with the DP and DM pins of the chip.

4.1.1.1. Features

The USB controller hardware handles the low level USB protocol, meaning the main job of the programmer is to configure the controller and then provide / consume data buffers in response to events on the bus. The controller interrupts the processor when it needs attention. The USB controller has 4kB of DPSRAM which is used for configuration and data buffers.

4.1.1.1.1. Device Mode

• • USB 2.0-compatible Full Speed device (12Mbps)
• • Supports up to 32 endpoints (Endpoints 0 → 15 in both in and out directions)
• • Supports Control , Isochronous , Bulk , and Interrupt endpoint types
• • Supports double buffering
• • 3840 bytes of usable buffer space in DPSRAM. This is equivalent to 60 × 64-byte buffers.

4.1.1.1.2. Host Mode

• • Can communicate with Full Speed (12Mbps) devices and Low Speed devices (1.5Mbps)
• • Can communicate with multiple devices via a USB hub, including Low Speed devices connected to a Full Speed hub
• • Can poll up to 15 interrupt endpoints in hardware. (Interrupt endpoints are used by hubs to notify the host of connect/disconnect events, mice to notify the host of movement etc.)

4.1.2. Architecture

4.1.2.1. Clock speed

This controller requires clk_usb to be running at 48MHz.

NOTE

clk_sys must also be running at > 48MHz. See RP2040-E16 .

4.1.2.2. Overview

Figure 57. A simplified overview of the USB controller architecture.

The USB controller is an area efficient design that muxes a device controller or host controller onto a common set of components. Each component is detailed below.

4.1.2.3. USB PHY

The USB PHY provides the electrical interface between the USB DP and DM pins and the digital logic of the controller. The DP and DM pins are a differential pair, meaning the values are always the inverse of each other, except to encode a specific line state ( SE0 , etc). The USB PHY drives the DP and DM pins to transmit data, as well as performing a differential receive of any incoming data. The USB PHY provides both single-ended and differential receive data to the line state detection module.

The USB PHY has built in pull-up and pull-down resistors. If the controller is acting as a Full Speed device then the DP pin is pulled up to indicate to the host that a Full Speed device has been connected. In host mode, a weak pull down is applied to DP and DM so that the lines are pulled to a logical zero until the device pulls up DP for Full Speed or DM for Low Speed.

4.1.2.4. Line state detection

The [2] defines several line states (Bus Reset, Connected, Suspend, Resume, Data 1, Data 0, etc) that need to be detected. The line state detection module has several state machines to detect these states and signal events to the other hardware components. There is no shared clock signal in USB, so the RX data must be sampled by an internal clock. The maximum data rate of USB Full Speed is 12Mbps. The RX data is sampled at 48MHz, giving 4 clock cycles to capture and filter the bus state. The line state detection module distributes the filtered RX data to the Serial RX Engine.

4.1.2.5. Serial RX Engine

The serial receive engine decodes receive data captured by the line state detection module. It produces the following information:

• • The PID of the incoming data packet
• • The device address for the incoming data
• • The device endpoint for the incoming data
• • Data bytes

The serial receive engine also detects errors in RX data by performing a CRC check on the incoming data. Any errors are signalled to the other hardware blocks and can raise an interrupt.

i NOTE

If you disconnect the USB cable during a packet in either host or device mode you will see errors raised by the hardware. Your software will need to take this scenario into account if you enable error interrupts.

4.1.2.6. Serial TX Engine

The serial transmit engine is a mirror of the serial receive engine. It is connected to the currently active controller (either device or host). It creates TOKEN and DATA packets, including calculating the CRC, and transmits them on the bus.

4.1.2.7. DPSRAM

The USB controller has 4kB (4096 bytes) of DPSRAM (Dual Port SRAM). The DPSRAM is used to store control registers and data buffers. The DPSRAM is accessible as a 32-bit wide memory at address 0 of the USB controller ( 0x50100000 ).

The DPSRAM has the following characteristics, which are different to most registers on RP2040:

• • Supports 8/16/32-bit accesses. Registers typically support 32-bit accesses only
• • The DPSRAM does not support set / clear aliases. RP2040 registers typically support these

Data Buffers are typically 64 bytes long as this is the max normal packet size for most FS packets. For Isochronous endpoints a maximum buffer size of 1023 bytes is supported. For other packet types the maximum size is 64 bytes per buffer.

4.1.2.7.1. Concurrent access

The DPSRAM in the USB controller should be considered asynchronous and not atomic. It is a dual port SRAM which means the processor has a port to read/write the memory and the USB controller also has a port to read/write the memory. This means that both the processor and the USB controller can access the same memory address at the same time. One could be writing and one could be reading. It is possible to get inconsistent data if the controller is reading the memory while the processor is writing the memory. Care must be taken to avoid this scenario.

The AVAILABLE bit in the buffer control register is used to indicate who has ownership of a buffer. This bit should be set to 1 by the processor to give the controller ownership of the buffer. The controller will set the bit back to 0 when it has used the buffer. The AVAILABLE bit should be set separately to the rest of the data in the buffer control register, so that the rest of the data in the buffer control register is accurate when the AVAILABLE bit is set.

This is necessary because the processor clock clk_sys can be running several times faster than the clk_usb clock. Therefore clk_sys can update the data during a read by the USB controller on a slower clock. The correct process is:

• • Write buffer information (length, etc.) to buffer control register

• • nop for some clk_sys cycles to ensure that at least one clk_usb cycle has passed. For example if clk_sys was running at 125MHz and clk_usb was running at 48MHz then 125/48 rounded up would be 3 nop instructions
• • Set AVAILABLE bit

If clk_sys and clk_usb are running at the same frequency then it is not necessary to set the AVAILABLE bit separately.

i NOTE

When the controller is writing status back to the DPSRAM it does a 16 bit write to the lower 2 bytes for buffer 0 and the upper 2 bytes for buffer 1. Therefore, if using double buffered mode, it is safest to treat the buffer control register as two 16 bit registers when updating it in software.

4.1.2.7.2. Layout

Addresses 0x0-0xff are used for control registers containing configuration data. The remaining space, addresses 0x100-0xffff (3840 bytes) can be used for data buffers. The controller has control registers that start at address 0x10000 .

The memory layout is different depending on if the controller is in Device or Host mode. In device mode, there are multiple endpoints a host can access so there must be endpoint control and buffer control registers for each endpoint. In host mode, the host software running on the processor is deciding which endpoints and which devices to access, so there only needs to be one set of endpoint control and buffer control registers. As well as software driven transfers, the host controller can poll up to 15 interrupt endpoints and has a register for each of these interrupt endpoints.

Table 394. DPSRAM layout

4.1.2.7.3. Endpoint control register

The endpoint control register is used to configure an endpoint. It contains:

• • The endpoint type
• • The base address of its data buffer, or data buffers if double buffered
• • Interrupts events on the endpoint should trigger

A device must support Endpoint 0 so that it can reply to SETUP packets and be enumerated. As a result, there is no endpoint control register for EP0. Its buffers begin at 0x100 . All other endpoints can have either single or dual buffers and are mapped at the base address programmed. As EP0 has no endpoint control register, the interrupt enable controls for EP0 come from SIE_CTRL .

Table 395. Endpoint control register layout

i NOTE

The data buffer base address must be 64-byte aligned as bits 0-5 are ignored

4.1.2.7.4. Buffer control register

The buffer control register contains information about the state of the data buffers for that endpoint. It is shared between the processor and the controller. If the endpoint is configured to be single buffered, only the first half (bits 0-15) of the buffer are used.

If double buffering, the buffer select starts at buffer 0. From then on, the buffer select flips between buffer 0 and 1 unless the "reset buffer select" bit is set (which resets the buffer select to buffer 0). The value of the buffer select is internal to the controller and not accessible by the processor.

For host interrupt and isochronous packets on EPx, the buffer full bit will be set on completion even if the transfer was unsuccessful. The error bits in the SIE_STATUS register can be read to determine the error.

Table 396. Buffer control register layout

⚠ WARNING

If running clk_sys and clk_usb at different speeds, the available and stall bits should be set after the other data in the buffer control register. Otherwise the controller may initiate a transaction with data from a previous packet. That is to say, the controller could see the available bit set but get the data pid or length from the previous packet.

4.1.2.8. Device Controller

This section details how the device controller operates when it receives various packet types from the host.

4.1.2.8.1. SETUP

The device controller MUST always accept a setup packet from the host. That is why the first 8 bytes of the DPSRAM has dedicated space for the setup packet.

The [2] states that receiving a setup packet also clears any stall bits on EP0. For this reason, the stall bits for EP0 are gated with two bits in the EP_STALL_ARM register. These bits are cleared when a setup packet is received. This means that to send a stall on EP0, you have to set both the stall bit in the buffer control register, and the appropriate bit in EP_STALL_ARM .

Barring any errors, the setup packet will be put into the setup packet buffer at DPSRAM offset 0x0 . The device controller will then reply with an ACK.

Finally, SIE_STATUS.SETUP_REC is set to indicate that a setup packet has been received. This will trigger an interrupt if the programmer has enabled the SETUP_REC interrupt (see INTE ).

4.1.2.8.2. IN

From the device's point of view, an IN transfer means transferring data INTO the host. When an IN token is received from the host the request is handled as follows:

TOKEN phase:

• • If STALL is set in the buffer control register (and if EP0, the appropriate EP_STALL_ARM bit is set) then send a STALL response and go back to idle.
• • If AVAILABLE and FULL bits are set in buffer control move to the phase
• • Otherwise send NAK unless this is an Isochronous endpoint, in which case go to idle.

DATA phase:

• • Send DATA. If Isochronous go to idle. Otherwise move to ACK phase.

ACK phase:

• • Wait for ACK packet from host. If there is a timeout then raise a timeout error. If ACK is received then the packet is done, so move to status phase.

STATUS phase:

• • If this was the last buffer in the transfer (i.e. if the LAST_BUFFER bit in the buffer control register was set), set SIE_STATUS.TRANS_COMPLETE .
• • If the endpoint is double buffered, flip the buffer select to the other buffer.
• • Set a bit in BUFF_STATUS to indicate the buffer is done. When handling this event, the programmer should read BUFF_CPU_SHOULD_HANDLE to see if it is buffer 0 or buffer 1 that is finished. If the endpoint is double buffered it is possible to have both buffers done. The cleared BUFF_STATUS bit will be set again, and BUFF_CPU_SHOULD_HANDLE will change in this instance.
• • Update status in the appropriate half of the buffer control register: length, pid, and last_buff are set. Everything else is written to zero.

If a NAK gets sent to the host the host will retry again later.

4.1.2.8.3. OUT

When an OUT token is received from the host, the request is handled as follows:

TOKEN phase:

• • Is the DATA pid what is specified in the buffer control register? If not raise SIE_STATUS.DATA_SEQ_ERROR . (The data pid for an Isochronous endpoint is not checked because Isochronous data is always sent with a DATA0 pid.)
• • Is the AVAILABLE bit set and the FULL bit unset. If so go to the data phase, unless the STALL bit is set in which case the device controller will reply with a STALL .

DATA phase:

• • Store received data in buffer. If Isochronous go to STATUS phase. Otherwise go to ACK phase.

ACK phase:

• • Send ACK. Go to STATUS phase.

STATUS phase:

See status phase from Section 4.1.2.8.2 . The only difference is that the FULL bit is set in the buffer control register to indicate that data has been received whereas in the IN case the FULL bit is cleared to indicate that data has been sent.

4.1.2.8.4. Suspend and Resume

The USB device controller supports both suspend and resume, as well as remote resume (triggered with SIE_CTRL.RESUME ), where the device initiates the resume. There is an interrupt / status bit in SIE_STATUS . It is not necessary to enable the suspend and resume interrupts, as most devices do not need to care about suspend and resume.

The device goes into suspend when it does not see any start of frame packets (transmitted every 1ms) from the host.

i NOTE

If you enable the suspend interrupt, it is likely you will see a suspend interrupt when the device is first connected but the bus is idle. The bus can be idle for a few ms before the host begins sending start of frame packets. You will also see a suspend interrupt when the device is disconnected if you do not have a VBUS detect circuit connected. This is because without VBUS detection, it is impossible to tell the difference between being disconnected and suspended.

4.1.2.8.5. Errata

There are two hardware issues with the device controller, both of which have software workarounds on RP2040B0, RP2040B1, and are fixed in hardware on RP2040B2. See RP2040-E2 and RP2040-E5 for more information.

4.1.2.9. Host Controller

The host controller design is similar to the device controller. All transactions are started by the host, so the host is always dealing with transactions it has started. For this reason there is only one set of endpoint control / endpoint buffer control registers. There is also additional hardware to poll interrupt endpoints in the background when there are no software controlled transactions taking place.

The host needs to send keep-alive packets to the device every 1ms to keep the device from suspending. In Full Speed mode this is done by sending a SOF (start of frame) packet. In Low Speed mode, an EOP (end of packet) is sent. When setting up the controller, SIE_CTRL.KEEP_ALIVE_EN and SIE_CTRL.SOF_EN should be set to enable these packets.

Several bits in SIE_CTRL are used to begin a host transaction:

• • SEND_SETUP - Send a setup packet. This is typically used in conjunction with RECEIVE_TRANS so the setup packet will be sent followed by the additional data transaction expected from the device.
• • SEND_TRANS - This transfer is OUT from the host
• • RECEIVE_TRANS - This transfer is IN to the host
• • START_TRANS - Start the transfer - non-latching
• • STOP_TRANS - Stop the current transfer - non-latching
• • PREAMBLE_ENABLE - Use this to send a packet to a Low Speed device on a Full Speed hub. This will send a PRE token packet before every packet the host sends (i.e. pre, token, pre, data, pre, ack).
• • SOF_SYNC - The SOF Sync bit is used to delay the transaction until after the next SOF. This is useful for interrupt and isochronous endpoints. The Host controller prevents a transaction of 64bytes from clashing with the SOF packets.

For longer Isochronous packet the software is responsible for preventing a collision by using the SOF Sync bit and limiting the number of packets sent in one frame. If a transaction is set up with multiple packets the SOF Sync bit only applies to the first packet.

⚠ WARNING

The START_TRANS bit is synchronised separately to other control bits in the SIE_CTRL register. The START_TRANS bit should be set separately to the rest of the data in the SIE_CTRL register, so that the register contents are stable when the controller is prompted to start a transfer. This is necessary because the processor clock clk_sys can be asynchronous to the clk_usb clock.

• • Write fields in SIE_CTRL apart from START_TRANS
• • nop for some clk_sys cycles to ensure that at least two clk_usb cycles have passed. For example if clk_sys was running at 125MHz and clk_usb was running at 48MHz then 125/48 rounded up would be 6 nop instructions
• • Set the START_TRANS bit.

4.1.2.9.1. SETUP

The SETUP packet sent from the host always comes from the dedicated 8 bytes of space at offset 0x0 of the DPSRAM. Like the device controller, there are no control registers associated with the setup packet. The parameters are hard coded and loaded into the hardware when you write to START_TRANS with the SEND_SETUP bit set. Once the setup packet has been sent, the host state machine will wait for an ACK from the device. If there is a timeout then an RX_TIMEOUT error will be raised. If the SEND_TRANS bit is set then the host state machine will move to the OUT phase. Most commonly the SEND_SETUP packet is used in conjunction with the RECEIVE_TRANS bit and will therefore move to the IN phase after sending a setup packet.

4.1.2.9.2. IN

An IN transfer is triggered with the RECEIVE_TRANS bit set when the START_TRANS bit is set. This may be preceded by a SETUP packet being sent if the SEND_SETUP bit was set.

CONTROL phase:

• • Read EPx control register located at 0x80 to get the endpoint information:
  • ◦ Are we double buffered?
  • ◦ What interrupts to enable
  • ◦ Base address of the data buffer, or data buffers if in double buffered mode
  • ◦ Endpoint type
• • Read EPx buffer control register at 0x100 to get the endpoint buffer information such as transfer length and data pid. The host state machine still checks for the presence of the AVAILABLE bit, so this needs to be set and FULL needs to be unset. The transaction will not happen until this is the case.

TOKEN phase:

• • Send the IN token packet to the device. The target device address and endpoint come from the ADDR_ENDP register.

DATA phase:

• • Receive the first data packet from the device. Raise RX timeout error if the device doesn't reply. Raise DATA SEQ ERROR if the data packet has wrong DATA PID.

ACK phase:

• • Send ACK to device

STATUS phase:

• • Set BUFF_STATUS bit and update buffer control register. Will set FULL , LAST_BUFF if applicable, DATA_PID , WR_LEN . TRANS_COMPLETE will be set if this is the last buffer in the transfer.

CONTROL phase (pt 2):

• • The host state machine will keep performing IN transactions until LAST_BUFF is seen in the buffer_control register. If the host is in double buffered mode then the host controller will toggle between BUF0 and BUF1 sections of the buffer control register. Otherwise it will keep reading the buffer control register for buffer 0 and wait for the FULL to be unset and AVAILABLE to be set before starting the next IN transaction (i.e. wait in the control phase). The device can send a zero length packet to the host to indicate that it has no more data. In which case the host state machine will stop listening for more data regardless of if the LAST_BUFF flag was set or not. The host software can tell this has happened because BUFF_DONE will be set with a data length of 0 in the buffer control register.

⚠ WARNING

The USB host controller has a bug ( RP2040-E4 ) that means the status written back to the buffer control register can appear in the wrong half of the register. Bits 0-15 are for buffer 0, and bits 16-31 are for buffer 1. The host controller has a buffer selector that is flipped after each transfer is complete. This buffer selector is incorrectly used when writing status information back to the buffer control register even in single buffered mode. The buffer selector is not used when reading the buffer control register. The implication of this is that host software needs to keep track of the buffer selector and shift the buffer control register to the right by 16 bits if the buffer selector is 1.

For more information, see RP2040-E4 .

4.1.2.9.3. OUT

An OUT transfer is triggered with the SEND_TRANS bit set when the START_TRANS bit is set. This may be preceded by a SETUP packet being sent if the SEND_SETUP bit was set.

CONTROL phase:

• • Read EPx control to get endpoint information (same as Section 4.1.2.9.2 )
• • Read EPx buffer control to get the transfer length, data pid. AVAILABLE and FULL must be set for the transfer to start.

TOKEN phase

• • Send OUT packet to the device. The target device address and endpoint come from the ADDR_ENDP register.

DATA phase:

• • Send the first data packet to the device. If the endpoint type is Isochronous then there is no ACK phase so the host controller will go straight to status phase. If ACK received then go to status phase. Otherwise:
  • ◦ If no reply is received then raise SIE_STATUS.RX_TIMEOUT .
  • ◦ If NAK received raise SIE_STATUS.NAK_REC and send the data packet again.
  • ◦ If STALL received then raise SIE_STATUS.STALL_REC and go to idle.

STATUS phase:

• • Set BUFF_STATUS bit and update buffer control register. FULL will be set to 0. TRANS_COMPLETE will be set if this is the last buffer in the transfer.

⚠ WARNING

The bug mentioned above ( RP2040-E4 ) in the IN section also applies to the OUT section.

CONTROL phase (pt 2):

If this isn't the last buffer in the transfer then wait for FULL and AVAILABLE to be set in the EPx buffer control register again.

4.1.2.9.4. Interrupt Endpoints

The host controller can poll interrupt endpoints on many devices (up to a maximum of 15 endpoints). To enable these, the programmer must:

• • Pick the next free interrupt endpoint slot on the host controller (starting at 1, to a maximum of 15)
• • Program the appropriate endpoint control register and buffer control register like you would with a normal IN or OUT transfer. Note that interrupt endpoints are only single buffered so the BUF1 part of the buffer control register is invalid.
• • Set the address and endpoint of the device in the appropriate ADDR_ENDP register ( ADDR_ENDP1 to ADDR_ENDP15 ). The preamble bit should be set if the device is Low Speed but attached to a Full Speed hub. The endpoint direction bit should also be set.
• • Set the interrupt endpoint active bit in INT_EP_CTRL (i.e. set bit 1 to 15 of that register)

Typically an interrupt endpoint will be an IN transfer. For example, a USB hub would be polled to see if the state of any of its ports have changed. If there is no change the hub will reply with a NAK to the controller and nothing will happen. Similarly, a mouse will reply with a NAK unless the mouse has been moved since the last time the interrupt endpoint was polled.

Interrupt endpoints are polled by the controller once a SOF packet has been sent by the host controller.

The controller loops from 1 to 15 and will attempt to poll any interrupt endpoint with the EP_ACTIVE bit set to 1 in INT_EP_CTRL . The controller will then read the endpoint control register, and buffer control register to see if there is an available buffer (i.e. FULL + AVAILABLE if an OUT transfer and NOT FULL + AVAILABLE for an IN transfer). If not, the controller will move onto the next interrupt endpoint slot.

If there is an available buffer, then the transfer is dealt with the same as a normal IN or OUT transfer and the BUFF_DONE flag in BUFF_STATUS will be set when the interrupt endpoint has a valid buffer. BUFF_CPU_SHOULD_HANDLE is invalid for interrupt endpoints as there is only a single buffer that can ever be done ( RP2040-E3 ).

4.1.2.10. VBUS Control

The USB controller can be connected up to GPIO pins (see Section 2.19 ) for the purpose of VBUS control:

• • VBUS enable, used to enable VBUS in host mode. VBUS enable is set in SIE_CTRL
• • VBUS detect, used to detect that VBUS is present in device mode. VBUS detect is a bit in SIE_STATUS and can also raise a VBUS_DETECT interrupt (enabled in INTE )
• • VBUS overcurrent, used to detect an overcurrent event. Applicable to both device and host. VBUS overcurrent is a bit in SIE_STATUS .

It is not necessary to connect up any of these pins to GPIO. The host can permanently supply VBUS and detect a device being connected when either the DP or DM pin is pulled high. VBUS detect can be forced in USB_PWR .

4.1.3. Programmer's Model

4.1.3.1. TinyUSB

The RP2040 TinyUSB port should be considered as the reference implementation for this USB controller. This port can be found in:

https://github.com/hathach/tinyusb/blob/master/src/portable/raspberrypi/rp2040/dcd_rp2040.c

https://github.com/hathach/tinyusb/blob/master/src/portable/raspberrypi/rp2040/hcd_rp2040.c

https://github.com/hathach/tinyusb/blob/master/src/portable/raspberrypi/rp2040/rp2040_usb.h

4.1.3.2. Standalone device example

A standalone USB device example, dev_lowlevel , makes it easier to understand how to interact with the USB controller without needing to understand the TinyUSB abstractions. In addition to endpoint 0, the standalone device has two bulk endpoints: EP1 OUT and EP2 IN. The device is designed to send whatever data it receives on EP1 to EP2. The example comes with a small Python script that writes "Hello World" into EP1 and checks that it is correctly received on EP2.

The code included in this section will walk you through setting up to the USB device controller to receive a setup packet, and then respond to the setup packet.

Figure 58. USB analyser trace of the dev_lowlevel USB device example. The control transfers are the device enumeration. The first bulk OUT (out from the host) transfer, highlighted in blue, is the host sending "Hello World" to the device. The second bulk transfer IN (in to the host), is the device returning "Hello World" to the host.

4.1.3.2.1. Device controller initialisation

The following code initialises the USB device.

Pico Examples: https://github.com/raspberrypi/pico-examples/blob/master/usb/device/dev_lowlevel/dev_lowlevel.c Lines 183 - 217

183 void usb_device_init() {
184     // Reset usb controller
185     reset_unreset_block_num_wait_blocking(RESET_USBCTRL);
186
187     // Clear any previous state in dpram just in case
188     memset(usb_dpram, 0, sizeof(*usb_dpram)); ①
189
190     // Enable USB interrupt at processor
191     irq_set_enabled(USBCTRL_IRQ, true);
192
193     // Mux the controller to the onboard usb phy

194     usb_hw->muxing = USB_USB_MUXING_TO_PHY_BITS | USB_USB_MUXING_SOFTCON_BITS;
195
196     // Force VBUS detect so the device thinks it is plugged into a host
197     usb_hw->pwr = USB_USB_PWR_VBUS_DETECT_BITS | USB_USB_PWR_VBUS_DETECT_OVERRIDE_EN_BITS;
198
199     // Enable the USB controller in device mode.
200     usb_hw->main_ctrl = USB_MAIN_CTRL_CONTROLLER_EN_BITS;
201
202     // Enable an interrupt per EP0 transaction
203     usb_hw->sie_ctrl = USB_SIE_CTRL_EP0_INT_1BUF_BITS; ②
204
205     // Enable interrupts for when a buffer is done, when the bus is reset,
206     // and when a setup packet is received
207     usb_hw->inte = USB_INTS_BUFF_STATUS_BITS |
208                   USB_INTS_BUS_RESET_BITS |
209                   USB_INTS_SETUP_REQ_BITS;
210
211     // Set up endpoints (endpoint control registers)
212     // described by device configuration
213     usb_setup_endpoints();
214
215     // Present full speed device by enabling pull up on DP
216     usb_hw_set->sie_ctrl = USB_SIE_CTRL_PULLUP_EN_BITS;
217 }

4.1.3.2.2. Configuring the endpoint control registers for EP1 and EP2

The function usb_configure_endpoints loops through each endpoint defined in the device configuration (including EP0 in and EP0 out, which don't have an endpoint control register defined) and calls the usb_configure_endpoint function. This sets up the endpoint control register for that endpoint:

Pico Examples: https://github.com/raspberrypi/pico-examples/blob/master/usb/device/dev_lowlevel/dev_lowlevel.c Lines 149 - 164

149 void usb_setup_endpoint(const struct usb_endpoint_configuration *ep) {
150     printf("Set up endpoint 0x%x with buffer address 0x%p\n", ep->descriptor-
151           >bEndpointAddress, ep->data_buffer);
152
153     // EP0 doesn't have one so return if that is the case
154     if (!ep->endpoint_control) {
155         return;
156     }
157
158     // Get the data buffer as an offset of the USB controller's DPRAM
159     uint32_t dpram_offset = usb_buffer_offset(ep->data_buffer);
160     uint32_t reg = EP_CTRL_ENABLE_BITS
161                 | EP_CTRL_INTERRUPT_PER_BUFFER
162                 | (ep->descriptor->bmAttributes << EP_CTRL_BUFFER_TYPE_LSB)
163                 | dpram_offset;
164     *ep->endpoint_control = reg;
165 }

4.1.3.2.3. Receiving a setup packet

An interrupt is raised when a setup packet is received, so the interrupt handler must handle this event:

Pico Examples: https://github.com/raspberrypi/pico-examples/blob/master/usb/device/dev_lowlevel/dev_lowlevel.c Lines 494 - 504

494 void isr_usbctrl(void) {
495     // USB interrupt handler
496     uint32_t status = usb_hw->ints;
497     uint32_t handled = 0;
498
499     // Setup packet received
500     if (status & USB_INTS_SETUP_REQ_BITS) {
501         handled |= USB_INTS_SETUP_REQ_BITS;
502         usb_hw_clear->sie_status = USB_SIE_STATUS_SETUP_REC_BITS;
503         usb_handle_setup_packet();
504     }

The setup packet gets written to the first 8 bytes of the USB ram, so the setup packet handler casts that area of memory to struct usb_setup_packet * .

Pico Examples: https://github.com/raspberrypi/pico-examples/blob/master/usb/device/dev_lowlevel/dev_lowlevel.c Lines 383 - 427

383 void usb_handle_setup_packet(void) {
384     volatile struct usb_setup_packet *pkt = (volatile struct usb_setup_packet *) &usb_dpram
->setup_packet;
385     uint8_t req_direction = pkt->bmRequestType;
386     uint8_t req = pkt->bRequest;
387
388     // Reset PID to 1 for EP0 IN
389     usb_get_endpoint_configuration(EP0_IN_ADDR)->next_pid = 1u;
390
391     if (req_direction == USB_DIR_OUT) {
392         if (req == USB_REQUEST_SET_ADDRESS) {
393             usb_set_device_address(pkt);
394         } else if (req == USB_REQUEST_SET_CONFIGURATION) {
395             usb_set_device_configuration(pkt);
396         } else {
397             usb_acknowledge_out_request();
398             printf("Other OUT request (0x%x)\r\n", pkt->bRequest);
399         }
400     } else if (req_direction == USB_DIR_IN) {
401         if (req == USB_REQUEST_GET_DESCRIPTOR) {
402             uint16_t descriptor_type = pkt->wValue >> 8;
403
404             switch (descriptor_type) {
405                 case USB_DT_DEVICE:
406                     usb_handle_device_descriptor(pkt);
407                     printf("GET DEVICE DESCRIPTOR\r\n");
408                     break;
409
410                 case USB_DT_CONFIG:
411                     usb_handle_config_descriptor(pkt);
412                     printf("GET CONFIG DESCRIPTOR\r\n");
413                     break;
414
415                 case USB_DT_STRING:
416                     usb_handle_string_descriptor(pkt);
417                     printf("GET STRING DESCRIPTOR\r\n");
418                     break;
419
420                 default:
421                     printf("Unhandled GET_DESCRIPTOR type 0x%x\r\n", descriptor_type);
422             }
423         } else {
424             printf("Other IN request (0x%x)\r\n", pkt->bRequest);

425     }
426 }
427 }

4.1.3.2.4. Replying to a setup packet on EP0 IN

The first thing a host will request is the device descriptor, the following code handles that setup request.

Pico Examples: https://github.com/raspberrypi/pico-examples/blob/master/usb/device/dev_lowlevel/dev_lowlevel.c Lines 266 - 273

266 void usb_handle_device_descriptor(volatile struct usb_setup_packet *pkt) {
267     const struct usb_device_descriptor *d = dev_config.device_descriptor;
268     // EP0 in
269     struct usb_endpoint_configuration *ep = usb_get_endpoint_configuration(EP0_IN_ADDR);
270     // Always respond with pid 1
271     ep->next_pid = 1;
272     usb_start_transfer(ep, (uint8_t *) d, MIN(sizeof(struct usb_device_descriptor), pkt->wLength));
273 }

The usb_start_transfer function copies the data to send into the appropriate hardware buffer, and configures the buffer control register. Once the buffer control register has been written to, the device controller will respond to the host with the data. Before this point, the device will reply with a NAK .

Pico Examples: https://github.com/raspberrypi/pico-examples/blob/master/usb/device/dev_lowlevel/dev_lowlevel.c Lines 238 - 260

238 void usb_start_transfer(struct usb_endpoint_configuration *ep, uint8_t *buf, uint16_t len) {
239     // We are asserting that the length is <= 64 bytes for simplicity of the example.
240     // For multi packet transfers see the tinyusb port.
241     assert(len <= 64);
242
243     printf("Start transfer of len %d on ep addr 0x%x\n", len, ep->descriptor->bEndpointAddress);
244
245     // Prepare buffer control register value
246     uint32_t val = len | USB_BUF_CTRL_AVAIL;
247
248     if (ep_is_tx(ep)) {
249         // Need to copy the data from the user buffer to the usb memory
250         memcpy((void *) ep->data_buffer, (void *) buf, len);
251         // Mark as full
252         val |= USB_BUF_CTRL_FULL;
253     }
254
255     // Set pid and flip for next transfer
256     val |= ep->next_pid ? USB_BUF_CTRL_DATA1_PID : USB_BUF_CTRL_DATA0_PID;
257     ep->next_pid ^= 1u;
258
259     *ep->buffer_control = val;
260 }

4.1.4. List of Registers

The USB registers start at a base address of 0x50110000 (defined as USBCTRL_REGS_BASE in SDK).

Table 397. List of USB registers

USB: ADDR_ENDP Register

Offset: 0x00

Description

Device address and endpoint control

Table 398.
ADDR_ENDP Register

USB: ADDR_ENDP1, ADDR_ENDP2, ..., ADDR_ENDP14, ADDR_ENDP15 Registers

Offsets: 0x04, 0x08, ..., 0x38, 0x3c

Description

Interrupt endpoint N . Only valid for HOST mode.

Table 399.
ADDR_ENDP1,
ADDR_ENDP2, ...,
ADDR_ENDP14,
ADDR_ENDP15
Registers

USB: MAIN_CTRL Register

Offset: 0x40

Description

Main control register

Table 400.
MAIN_CTRL Register

USB: SOF_WR Register

Offset: 0x44

Description

Set the SOF (Start of Frame) frame number in the host controller. The SOF packet is sent every 1ms and the host will increment the frame number by 1 each time.

Table 401. SOF_WR
Register

USB: SOF_RD Register

Offset: 0x48

Description

Read the last SOF (Start of Frame) frame number seen. In device mode the last SOF received from the host. In host mode the last SOF sent by the host.

Table 402. SOF_RD
Register

USB: SIE_CTRL Register

Offset: 0x4c

Description

SIE control register

Table 403. SIE_CTRL Register

USB: SIE_STATUS Register

Offset: 0x50

Description

SIE status register

Table 404.
SIE_STATUS Register

USB: INT_EP_CTRL Register

Offset: 0x54

Description

interrupt endpoint control register

Table 405.
INT_EP_CTRL Register

USB: BUFF_STATUS Register

Offset: 0x58

Description

Buffer status register. A bit set here indicates that a buffer has completed on the endpoint (if the buffer interrupt is enabled). It is possible for 2 buffers to be completed, so clearing the buffer status bit may instantly re set it on the next clock cycle.

Table 406.
BUFF_STATUS
Register

USB: BUFF_CPU_SHOULD_HANDLE Register

Offset: 0x5c

Description

Which of the double buffers should be handled. Only valid if using an interrupt per buffer (i.e. not per 2 buffers). Not valid for host interrupt endpoint polling because they are only single buffered.

Table 407.
BUFF_CPU_SHOULD_H
ANDLE Register

USB: EP_ABORT Register

Offset: 0x60

Description

Device only: Can be set to ignore the buffer control register for this endpoint in case you would like to revoke a buffer. A NAK will be sent for every access to the endpoint until this bit is cleared. A corresponding bit in EP_ABORT_DONE is set when it is safe to modify the buffer control register.

Table 408. EP_ABORT Register

USB: EP_ABORT_DONE Register

Offset: 0x64

Description

Device only: Used in conjunction with EP_ABORT . Set once an endpoint is idle so the programmer knows it is safe to modify the buffer control register.

Table 409.
EP_ABORT_DONE
Register

USB: EP_STALL_ARM Register

Offset: 0x68

Device: this bit must be set in conjunction with the STALL bit in the buffer control register to send a STALL on EP0. The device controller clears these bits when a SETUP packet is received because the USB spec requires that a STALL condition is cleared when a SETUP packet is received.

Table 410.
EP_STALL_ARM
Register

Offset: 0x6c

Used by the host controller. Sets the wait time in microseconds before trying again if the device replies with a NAK.

Table 411. NAK_POLL
Register

Offset: 0x70

Device: bits are set when the IRQ_ON_NAK or IRQ_ON_STALL bits are set. For EP0 this comes from SIE_CTRL . For all other endpoints it comes from the endpoint control register.

Table 412.
EP_STATUS_STALL_NAK
Register

USB: USB_MUXING Register

Offset: 0x74

Description

Where to connect the USB controller. Should be to_phy by default.

Table 413.
USB_MUXING Register

USB: USB_PWR Register

Offset: 0x78

Description

Overrides for the power signals in the event that the VBUS signals are not hooked up to GPIO. Set the value of the override and then the override enable to switch over to the override value.

Table 414. USB_PWR Register

USB: USBPHY_DIRECT Register

Offset: 0x7c

Description

This register allows for direct control of the USB phy. Use in conjunction with usbphy_direct_override register to enable each override bit.

Table 415.
USBPHY_DIRECT
Register

USB: USBPHY_DIRECT_OVERRIDE Register

Offset: 0x80

Description

Override enable for each control in usbphy_direct

Table 416.
USBPHY_DIRECT_OVERRIDE Register

USB: USBPHY_TRIM Register

Offset: 0x84

Description

Used to adjust trim values of USB phy pull down resistors.

Table 417.
USBPHY_TRIM
Register

USB: INTR Register

Offset: 0x8c

Description

Raw Interrupts

Table 418. INTR
Register

USB: INTE Register

Offset: 0x90

Description

Interrupt Enable

Table 419. INTE Register

USB: INTF Register

Offset: 0x94

Description

Interrupt Force

Table 420. INTF Register

USB: INTS Register

Offset: 0x98

Description

Interrupt status after masking & forcing

Table 421. INTS Register

References

• ▪ [1] USB Made Simple
• ▪ [2] USB 2.0 Specification

4.2. UART

ARM Documentation

Excerpted from the PrimeCell UART (PL011) Technical Reference Manual . Used with permission.

RP2040 has 2 identical instances of a UART peripheral, based on the ARM Primecell UART (PL011) (Revision r1p5).

Each instance supports the following features:

• • Separate 32×8 Tx and 32×12 Rx FIFOs
• • Programmable baud rate generator, clocked by clk_peri (see Section 2.15.1 )
• • Standard asynchronous communication bits (start, stop, parity) added on transmit and removed on receive
• • line break detection
• • programmable serial interface (5, 6, 7, or 8 bits)
• • 1 or 2 stop bits
• • programmable hardware flow control

Each UART can be connected to a number of GPIO pins as defined in the GPIO muxing table in Section 2.19.2 . Connections to the GPIO muxing are prefixed with the UART instance name uart0_ or uart1_ , and include the following:

• • Transmit data tx (referred to as UARTTXD in the following sections)
• • Received data rx (referred to as UARTRXD in the following sections)
• • Output flow control rts (referred to as nUARTRTS in the following sections)
• • Input flow control cts (referred to as nUARTCTS in the following sections)

The modem mode and IrDA mode of the PL011 are not supported.

The UARTCLK is driven from clk_peri , and PCLK is driven from the system clock clk_sys (see Section 2.15.1 ).

4.2.1. Overview

The UART performs:

• • Serial-to-parallel conversion on data received from a peripheral device
• • Parallel-to-serial conversion on data transmitted to the peripheral device.

The CPU reads and writes data and control/status information through the AMBA APB interface. The transmit and receive paths are buffered with internal FIFO memories enabling up to 32-bytes to be stored independently in both

transmit and receive modes.

The UART:

• • Includes a programmable baud rate generator that generates a common transmit and receive internal clock from the UART internal reference clock input, UARTCLK
• • Offers similar functionality to the industry-standard 16C650 UART device
• • Supports a maximum baud rate of \( \text{UARTCLK} / 16 \) in UART mode (7.8 Mbaud at 125MHz)

The UART operation and baud rate values are controlled by the Line Control Register, UARTLCR_H and the baud rate divisor registers (Integer Baud Rate Register, UARTIBRD and Fractional Baud Rate Register, UARTFBRD ).

The UART can generate:

• • Individually-maskable interrupts from the receive (including timeout), transmit, modem status and error conditions
• • A single combined interrupt so that the output is asserted if any of the individual interrupts are asserted, and unmasked
• • DMA request signals for interfacing with a Direct Memory Access (DMA) controller.

If a framing, parity, or break error occurs during reception, the appropriate error bit is set, and is stored in the FIFO. If an overrun condition occurs, the overrun register bit is set immediately and FIFO data is prevented from being overwritten.

You can program the FIFOs to be 1-byte deep providing a conventional double-buffered UART interface.

There is a programmable hardware flow control feature that uses the nUARTCTS input and the nUARTRTS output to automatically control the serial data flow.

4.2.2. Functional description

Figure 59. UART block diagram. Test logic is not shown for clarity.

4.2.2.1. AMBA APB interface

The AMBA APB interface generates read and write decodes for accesses to status/control registers, and the transmit and receive FIFOs.

4.2.2.2. Register block

The register block stores data written, or to be read across the AMBA APB interface.

4.2.2.3. Baud rate generator

The baud rate generator contains free-running counters that generate the internal clocks: Baud16 and IrLPBaud16 signals. Baud16 provides timing information for UART transmit and receive control. Baud16 is a stream of pulses with a width of one UARTCLK clock period and a frequency of 16 times the baud rate.

4.2.2.4. Transmit FIFO

The transmit FIFO is an 8-bit wide, 32 location deep, FIFO memory buffer. CPU data written across the APB interface is stored in the FIFO until read out by the transmit logic. You can disable the transmit FIFO to act like a one-byte holding register.

4.2.2.5. Receive FIFO

The receive FIFO is a 12-bit wide, 32 location deep, FIFO memory buffer. Received data and corresponding error bits, are stored in the receive FIFO by the receive logic until read out by the CPU across the APB interface. The receive FIFO can be disabled to act like a one-byte holding register.

4.2.2.6. Transmit logic

The transmit logic performs parallel-to-serial conversion on the data read from the transmit FIFO. Control logic outputs the serial bit stream beginning with a start bit, data bits with the Least Significant Bit (LSB) first, followed by the parity bit, and then the stop bits according to the programmed configuration in control registers.

4.2.2.7. Receive logic

The receive logic performs serial-to-parallel conversion on the received bit stream after a valid start pulse has been detected. Overrun, parity, frame error checking, and line break detection are also performed, and their status accompanies the data that is written to the receive FIFO.

4.2.2.8. Interrupt generation logic

Individual maskable active HIGH interrupts are generated by the UART. A combined interrupt output is generated as an OR function of the individual interrupt requests and is connected to the processor interrupt controllers.

See Section 4.2.6 for more information.

4.2.2.9. DMA interface

The UART provides an interface to connect to the DMA controller as UART DMA interface in Section 4.2.5 describes.

4.2.2.10. Synchronizing registers and logic

The UART supports both asynchronous and synchronous operation of the clocks, PCLK and UARTCLK. Synchronization registers and handshaking logic have been implemented, and are active at all times. This has a minimal impact on performance or area. Synchronization of control signals is performed on both directions of data flow, that is from the PCLK to the UARTCLK domain, and from the UARTCLK to the PCLK domain.

4.2.3. Operation

4.2.3.1. Clock signals

The frequency selected for UARTCLK must accommodate the required range of baud rates:

• • \( F_{UARTCLK}(\min) \geq 16 \times \text{baud\_rate}(\max) \)
• • \( F_{UARTCLK}(\max) \leq 16 \times 65535 \times \text{baud\_rate}(\min) \)

For example, for a range of baud rates from 110 baud to 460800 baud the UARTCLK frequency must be between 7.3728MHz to 115.34MHz.

The frequency of UARTCLK must also be within the required error limits for all baud rates to be used.

There is also a constraint on the ratio of clock frequencies for PCLK to UARTCLK. The frequency of UARTCLK must be no more than 5/3 times faster than the frequency of PCLK:

• • \( F_{UARTCLK} \leq 5/3 \times F_{PCLK} \)

For example, in UART mode, to generate 921600 baud when UARTCLK is 14.7456MHz then PCLK must be greater than or equal to 8.85276MHz. This ensures that the UART has sufficient time to write the received data to the receive FIFO.

4.2.3.2. UART operation

Control data is written to the UART Line Control Register, UARTLCR. This register is 30-bits wide internally, but is externally accessed through the APB interface by writes to the following registers:

The UARTLCR_H register defines the:

• • transmission parameters
• • word length
• • buffer mode
• • number of transmitted stop bits
• • parity mode
• • break generation.

The UARTIBRD register defines the integer baud rate divider, and the UARTFBRD register defines the fractional baud rate divider.

4.2.3.2.1. Fractional baud rate divider

The baud rate divisor is a 22-bit number consisting of a 16-bit integer and a 6-bit fractional part. This is used by the baud rate generator to determine the bit period. The fractional baud rate divider enables the use of any clock with a frequency >3.6864MHz to act as UARTCLK, while it is still possible to generate all the standard baud rates.

The 16-bit integer is written to the Integer Baud Rate Register, UARTIBRD . The 6-bit fractional part is written to the Fractional Baud Rate Register, UARTFBRD . The Baud Rate Divisor has the following relationship to UARTCLK:

Baud Rate Divisor = \( \text{UARTCLK}/(16 \times \text{Baud Rate}) = \text{BRD}_I + \text{BRD}_F \) where \( \text{BRD}_I \) is the integer part and \( \text{BRD}_F \) is the fractional part separated by a decimal point as Figure 60 .

Figure 60. Baud rate divisor.

You can calculate the 6-bit number ( \( m \) ) by taking the fractional part of the required baud rate divisor and multiplying it by 64 (that is, \( 2^n \) , where \( n \) is the width of the UARTFBRD Register) and adding 0.5 to account for rounding errors:

An internal clock enable signal, Baud16, is generated, and is a stream of one UARTCLK wide pulses with an average frequency of 16 times the required baud rate. This signal is then divided by 16 to give the transmit clock. A low number in the baud rate divisor gives a short bit period, and a high number in the baud rate divisor gives a long bit period.

4.2.3.2.2. Data transmission or reception

Data received or transmitted is stored in two 32-byte FIFOs, though the receive FIFO has an extra four bits per character for status information. For transmission, data is written into the transmit FIFO. If the UART is enabled, it causes a data frame to start transmitting with the parameters indicated in the Line Control Register, UARTLCR_H . Data continues to be transmitted until there is no data left in the transmit FIFO. The BUSY signal goes HIGH as soon as data is written to the transmit FIFO (that is, the FIFO is non-empty) and remains asserted HIGH while data is being transmitted. BUSY is negated only when the transmit FIFO is empty, and the last character has been transmitted from the shift register, including the stop bits. BUSY can be asserted HIGH even though the UART might no longer be enabled.

For each sample of data, three readings are taken and the majority value is kept. In the following paragraphs the middle sampling point is defined, and one sample is taken either side of it.

When the receiver is idle (UARTRXD continuously 1, in the marking state) and a LOW is detected on the data input (a start bit has been received), the receive counter, with the clock enabled by Baud16, begins running and data is sampled on the eighth cycle of that counter in UART mode, or the fourth cycle of the counter in SIR mode to allow for the shorter logic 0 pulses (half way through a bit period).

The start bit is valid if UARTRXD is still LOW on the eighth cycle of Baud16, otherwise a false start bit is detected and it is ignored.

If the start bit was valid, successive data bits are sampled on every 16th cycle of Baud16 (that is, one bit period later) according to the programmed length of the data characters. The parity bit is then checked if parity mode was enabled.

Lastly, a valid stop bit is confirmed if UARTRXD is HIGH, otherwise a framing error has occurred. When a full word is received, the data is stored in the receive FIFO, with any error bits associated with that word

4.2.3.2.3. Error bits

Three error bits are stored in bits [10:8] of the receive FIFO, and are associated with a particular character. There is an additional error that indicates an overrun error and this is stored in bit 11 of the receive FIFO.

4.2.3.2.4. Overrun bit

The overrun bit is not associated with the character in the receive FIFO. The overrun error is set when the FIFO is full, and the next character is completely received in the shift register. The data in the shift register is overwritten, but it is not written into the FIFO. When an empty location is available in the receive FIFO, and another character is received, the state of the overrun bit is copied into the receive FIFO along with the received character. The overrun state is then cleared. Table 422 lists the bit functions of the receive FIFO.

Table 422. Receive FIFO bit functions

4.2.3.2.5. Disabling the FIFOs

Additionally, you can disable the FIFOs. In this case, the transmit and receive sides of the UART have 1-byte holding registers (the bottom entry of the FIFOs). The overrun bit is set when a word has been received, and the previous one was not yet read. In this implementation, the FIFOs are not physically disabled, but the flags are manipulated to give the illusion of a 1-byte register. When the FIFOs are disabled, a write to the data register bypasses the holding register unless the transmit shift register is already in use.

4.2.3.2.6. System and diagnostic loopback testing

You can perform loopback testing for UART data by setting the Loop Back Enable (LBE) bit to 1 in the Control Register, UARTCR .

Data transmitted on UARTTXD is received on the UARTRXD input.

4.2.3.3. UART character frame

Figure 61. UART character frame.

4.2.4. UART hardware flow control

The hardware flow control feature is fully selectable, and enables you to control the serial data flow by using the nUARTRTS output and nUARTCTS input signals. Figure 62 shows how two devices can communicate with each other using hardware flow control.

Figure 62. Hardware flow control between two similar devices.

When the RTS flow control is enabled, nUARTRTS is asserted until the receive FIFO is filled up to the programmed watermark level. When the CTS flow control is enabled, the transmitter can only transmit data when nUARTCTS is asserted.

The hardware flow control is selectable using the RTSEn and CTSEn bits in the Control Register, UARTCR . Table 423 lists how you must set the bits to enable RTS and CTS flow control both simultaneously, and independently.

Table 423. Control bits to enable and disable hardware flow control.

NOTE

When RTS flow control is enabled, the software cannot use the RTSEn bit in the Control Register, UARTCR , to control the status of nUARTRTS.

4.2.4.1. RTS flow control

The RTS flow control logic is linked to the programmable receive FIFO watermark levels. When RTS flow control is enabled, the nUARTRTS is asserted until the receive FIFO is filled up to the watermark level. When the receive FIFO watermark level is reached, the nUARTRTS signal is deasserted, indicating that there is no more room to receive any more data. The transmission of data is expected to cease after the current character has been transmitted.

The nUARTRTS signal is reasserted when data has been read out of the receive FIFO so that it is filled to less than the watermark level. If RTS flow control is disabled and the UART is still enabled, then data is received until the receive FIFO is full, or no more data is transmitted to it.

4.2.4.2. CTS flow control

If CTS flow control is enabled, then the transmitter checks the nUARTCTS signal before transmitting the next byte. If the nUARTCTS signal is asserted, it transmits the byte otherwise transmission does not occur.

The data continues to be transmitted while nUARTCTS is asserted, and the transmit FIFO is not empty. If the transmit FIFO is empty and the nUARTCTS signal is asserted no data is transmitted.

If the nUARTCTS signal is deasserted and CTS flow control is enabled, then the current character transmission is completed before stopping. If CTS flow control is disabled and the UART is enabled, then the data continues to be transmitted until the transmit FIFO is empty.

4.2.5. UART DMA Interface

The UART provides an interface to connect to a DMA controller. The DMA operation of the UART is controlled using the DMA Control Register, UARTDMACR . The DMA interface includes the following signals:

For receive:

UARTRXDMASREQ

Single character DMA transfer request, asserted by the UART. For receive, one character consists of up to 12 bits. This signal is asserted when the receive FIFO contains at least one character.

UARTRXDMABREQ

Burst DMA transfer request, asserted by the UART. This signal is asserted when the receive FIFO contains more characters than the programmed watermark level. You can program the watermark level for each FIFO using the Interrupt FIFO Level Select Register, UARTIFLS .

UARTRXDMACLR

DMA request clear, asserted by a DMA controller to clear the receive request signals. If DMA burst transfer is requested, the clear signal is asserted during the transfer of the last data in the burst.

For transmit:

UARTTXDMASREQ

Single character DMA transfer request, asserted by the UART. For transmit one character consists of up to eight bits. This signal is asserted when there is at least one empty location in the transmit FIFO.

UARTTXDMABREQ

Burst DMA transfer request, asserted by the UART. This signal is asserted when the transmit FIFO contains less characters than the watermark level. You can program the watermark level for each FIFO using the Interrupt FIFO Level Select Register, UARTIFLS .

UARTTXDMACLR

DMA request clear, asserted by a DMA controller to clear the transmit request signals. If DMA burst transfer is requested, the clear signal is asserted during the transfer of the last data in the burst.

The burst transfer and single transfer request signals are not mutually exclusive, they can both be asserted at the same time. For example, when there is more data than the watermark level in the receive FIFO, the burst transfer request and the single transfer request are asserted. When the amount of data left in the receive FIFO is less than the watermark level, the single request only is asserted. This is useful for situations where the number of characters left to be received in the stream is less than a burst.

For example, if 19 characters have to be received and the watermark level is programmed to be four. The DMA controller then transfers four bursts of four characters and three single transfers to complete the stream.

NOTE

For the remaining three characters the UART cannot assert the burst request.

Each request signal remains asserted until the relevant DMACLR signal is asserted. After the request clear signal is deasserted, a request signal can become active again, depending on the conditions described previously. All request signals are deasserted if the UART is disabled or the relevant DMA enable bit, TXDMAE or RXDMAE, in the DMA Control Register, UARTDMACR , is cleared.

If you disable the FIFOs in the UART then it operates in character mode and only the DMA single transfer mode can operate, because only one character can be transferred to, or from the FIFOs at any time. UARTRXDMASREQ and UARTTXDMASREQ are the only request signals that can be asserted. See the Line Control Register, UARTLCR_H , for information about disabling the FIFOs.

When the UART is in the FIFO enabled mode, data transfers can be made by either single or burst transfers depending on the programmed watermark level and the amount of data in the FIFO. Table 424 lists the trigger points for UARTRXDMABREQ and UARTTXDMABREQ depending on the watermark level, for the transmit and receive FIFOs.

Table 424. DMA trigger points for the transmit and receive FIFOs.

In addition, the DMAONERR bit in the DMA Control Register, UARTDMACR , supports the use of the receive error interrupt, UARTEINTR. It enables the DMA receive request outputs, UARTRXDMASREQ or UARTRXDMABREQ, to be masked out when the UART error interrupt, UARTEINTR, is asserted. The DMA receive request outputs remain inactive until the UARTEINTR is cleared. The DMA transmit request outputs are unaffected.

Figure 63. DMA transfer waveforms.

Figure 63 shows the timing diagram for both a single transfer request and a burst transfer request with the appropriate DMACLR signal. The signals are all synchronous to PCLK. For the sake of clarity it is assumed that there is no synchronization of the request signals in the DMA controller.

4.2.6. Interrupts

There are eleven maskable interrupts generated in the UART. On RP2040, only the combined interrupt output, UARTRINTR , is connected.

You can enable or disable the individual interrupts by changing the mask bits in the Interrupt Mask Set/Clear Register, UARTIMSC . Setting the appropriate mask bit HIGH enables the interrupt.

Provision of individual outputs and the combined interrupt output, enables you to use either a global interrupt service routine, or modular device drivers to handle interrupts.

The transmit and receive dataflow interrupts UARTRXINTR and UARTRXINTR have been separated from the status interrupts. This enables you to use UARTRXINTR and UARTRXINTR so that data can be read or written in response to the FIFO trigger levels.

The error interrupt, UARTEINTR, can be triggered when there is an error in the reception of data. A number of error conditions are possible.

The modem status interrupt, UARTRMSINTR, is a combined interrupt of all the individual modem status signals.

The status of the individual interrupt sources can be read either from the Raw Interrupt Status Register, UARTRIS , or from the Masked Interrupt Status Register, UARTMIS .

4.2.6.1. UARTRMSINTR

The modem status interrupt is asserted if any of the modem status signals (nUARTRCTS, nUARTRDCD, nUARTRDSR, and nUARTRRI) change. It is cleared by writing a 1 to the corresponding bit(s) in the Interrupt Clear Register, UARTICR , depending on the modem status signals that generated the interrupt.

4.2.6.2. UARTRXINTR

The receive interrupt changes state when one of the following events occurs:

• • If the FIFOs are enabled and the receive FIFO reaches the programmed trigger level. When this happens, the receive interrupt is asserted HIGH. The receive interrupt is cleared by reading data from the receive FIFO until it becomes less than the trigger level, or by clearing the interrupt.
• • If the FIFOs are disabled (have a depth of one location) and data is received thereby filling the location, the receive interrupt is asserted HIGH. The receive interrupt is cleared by performing a single read of the receive FIFO, or by clearing the interrupt.

4.2.6.3. UARTRXINTR

The transmit interrupt changes state when one of the following events occurs:

• • If the FIFOs are enabled and the transmit FIFO is equal to or lower than the programmed trigger level then the transmit interrupt is asserted HIGH. The transmit interrupt is cleared by writing data to the transmit FIFO until it becomes greater than the trigger level, or by clearing the interrupt.
• • If the FIFOs are disabled (have a depth of one location) and there is no data present in the transmitters single location, the transmit interrupt is asserted HIGH. It is cleared by performing a single write to the transmit FIFO, or by clearing the interrupt.

To update the transmit FIFO you must:

• • Write data to the transmit FIFO, either prior to enabling the UART and the interrupts, or after enabling the UART and interrupts.

i NOTE

The transmit interrupt is based on a transition through a level, rather than on the level itself. When the interrupt and the UART is enabled before any data is written to the transmit FIFO the interrupt is not set. The interrupt is only set, after written data leaves the single location of the transmit FIFO and it becomes empty.

4.2.6.4. UARTRTINTR

The receive timeout interrupt is asserted when the receive FIFO is not empty, and no more data is received during a 32-bit period. The receive timeout interrupt is cleared either when the FIFO becomes empty through reading all the data (or by reading the holding register), or when a 1 is written to the corresponding bit of the Interrupt Clear Register, UARTICR .

4.2.6.5. UARTEINTR

The error interrupt is asserted when an error occurs in the reception of data by the UART. The interrupt can be caused by a number of different error conditions:

• • framing
• • parity
• • break
• • overrun.

You can determine the cause of the interrupt by reading the Raw Interrupt Status Register, UARTRIS , or the Masked Interrupt Status Register, UARTMIS . It can be cleared by writing to the relevant bits of the Interrupt Clear Register, UARTICR (bits 7 to 10 are the error clear bits).

4.2.6.6. UARTINTR

The interrupts are also combined into a single output, that is an OR function of the individual masked sources. You can connect this output to a system interrupt controller to provide another level of masking on a individual peripheral basis.

The combined UART interrupt is asserted if any of the individual interrupts are asserted and enabled.

4.2.7. Programmer's Model

The SDK provides a uart_init function to configure the UART with a particular baud rate. Once the UART is initialised, the user must configure a GPIO pin as UART_TX and UART_RX . See Section 2.19.5.1 for more information on selecting a GPIO function.

To initialise the UART, the uart_init function takes the following steps:

• • Deassert the reset
• • Enable clk_peri
• • Set enable bits in the control register
• • Enable the FIFOs
• • Set the baud rate divisors
• • Set the format

SDK: https://github.com/raspberrypi/pico-sdk/blob/master/src/tp2_common/hardware_uart/uart.c Lines 42 - 92

42 uint uart_init(uart_inst_t *uart, uint baudrate) {
43     invalid_params_if(HARDWARE_UART, uart != uart0 && uart != uart1);
44
45     if (uart_clock_get_hz(uart) == 0) {
46         return 0;
47     }
48
49     uart_reset(uart);
50     uart_unreset(uart);
51
52     uart_set_translate_crlf(uart, PICO_UART_DEFAULT_CRLF);
53
54     // Any LCR writes need to take place before enabling the UART
55     uint baud = uart_set_baudrate(uart, baudrate);
56
57     // inline the uart_set_format() call, as we don't need the CR disable/re-enable
58     // protection, and also many people will never call it again, so having
59     // the generic function is not useful, and much bigger than this inlined
60     // code which is only a handful of instructions.
61     //
62     // The UART_UARTLCR_H_FEN_BITS setting is combined as well as it is the same register
63 #ifdef 0
64     uart_set_format(uart, 8, 1, UART_PARITY_NONE);
65     // Enable FIFOs (must be before setting UARTEN, as this is an LCR access)
66     hw_set_bits(&uart_get_hw(uart)->lcr_h, UART_UARTLCR_H_FEN_BITS);
67 #else
68     uint data_bits = 8;
69     uint stop_bits = 1;
70     uint parity = UART_PARITY_NONE;
71     hw_write_masked(&uart_get_hw(uart)->lcr_h,
72         ((data_bits - 5u) << UART_UARTLCR_H_WLEN_LSB) |
73         ((stop_bits - 1u) << UART_UARTLCR_H_STP2_LSB) |
74         (bool_to_bit(parity != UART_PARITY_NONE) << UART_UARTLCR_H_PEN_LSB) |
75         (bool_to_bit(parity == UART_PARITY_EVEN) << UART_UARTLCR_H_EPS_LSB) |

76         UART_UARTLCR_H_FEN_BITS,
77         UART_UARTLCR_H_WLEN_BITS | UART_UARTLCR_H_STP2_BITS |
78         UART_UARTLCR_H_PEN_BITS | UART_UARTLCR_H_EPS_BITS |
79         UART_UARTLCR_H_FEN_BITS);
80 #endif
81
82 // Enable the UART, both TX and RX
83 uart_get_hw(uart)->cr = UART_UARTCR_UARTEN_BITS | UART_UARTCR_TXE_BITS |
    UART_UARTCR_RXE_BITS;
84 // Always enable DREQ signals -- no harm in this if DMA is not listening
85 uart_get_hw(uart)->dmacr = UART_UARTDMACR_TXDMAE_BITS | UART_UARTDMACR_RXDMAE_BITS;
86
87 return baud;
88 }

4.2.7.1. Baud Rate Calculation

The uart baud rate is derived from dividing clk_peri .

If the required baud rate is 115200 and UARTCLK = 125MHz then:

Baud Rate Divisor = \( (125 * 10^6) / (16 * 115200) \approx 67.817 \)

Therefore, BRDI = 67 and BRDF = 0.817,

Therefore, fractional part, m = integer((0.817 * 64) + 0.5) = 52

Generated baud rate divider = \( 67 + 52/64 = 67.8125 \)

Generated baud rate = \( (125 * 10^6) / (16 * 67.8125) \approx 115207 \)

Error = \( (\text{abs}(115200 - 115207) / 115200) * 100 \approx 0.006\% \)

SDK: https://github.com/raspberrypi/pico-sdk/blob/master/src/rp2-common/hardware_uart/uart.c Lines 155 - 180

155 uint uart_set_baudrate(uart_inst_t *uart, uint baudrate) {
156     invalid_params_if(HARDWARE_UART, baudrate == 0);
157     uint32_t baud_rate_div = (8 * uart_clock_get_hz(uart) / baudrate) + 1;
158     uint32_t baud_ibrd = baud_rate_div >> 7;
159     uint32_t baud_fbrd;
160
161     if (baud_ibrd == 0) {
162         baud_ibrd = 1;
163         baud_fbrd = 0;
164     } else if (baud_ibrd >= 65535) {
165         baud_ibrd = 65535;
166         baud_fbrd = 0;
167     } else {
168         baud_fbrd = (baud_rate_div & 0x7f) >> 1;
169     }
170
171     uart_get_hw(uart)->ibrd = baud_ibrd;
172     uart_get_hw(uart)->fbrd = baud_fbrd;
173
174     // PL011 needs a (dummy) LCR_H write to latch in the divisors.
175     // We don't want to actually change LCR_H contents here.
176     uart_write_lcr_bits_masked(uart, 0, 0);
177
178     // See datasheet
179     return (4 * uart_clock_get_hz(uart)) / (64 * baud_ibrd + baud_fbrd);
180 }

4.2.8. List of Registers

The UART0 and UART1 registers start at base addresses of 0x40034000 and 0x40038000 respectively (defined as UART0_BASE and UART1_BASE in SDK).

Table 425. List of UART registers

UART: UARTDR Register

Offset: 0x000

Description

Data Register, UARTDR

Table 426. UARTDR Register

UART: UARTSR Register

Offset: 0x004

Description

Receive Status Register/Error Clear Register, UARTSR/UARTECR

Table 427. UARTSR Register

UART: UARTFR Register

Offset: 0x018

Flag Register, UARTFR

Table 428. UARTFR Register

UART: UARTILPR Register

Offset: 0x020

IrDA Low-Power Counter Register, UARTILPR

Table 429. UARTILPR Register

UART: UARTIBRD Register

Offset: 0x024

Description

Integer Baud Rate Register, UARTIBRD

Table 430. UARTIBRD Register

UART: UARTFBRD Register

Offset: 0x028

Description

Fractional Baud Rate Register, UARTFBRD

Table 431. UARTFBRD Register

UART: UARTLCR_H Register

Offset: 0x02c

Description

Line Control Register, UARTLCR_H

Table 432. UARTLCR_H Register

UART: UARTCR Register

Offset: 0x030

Description

Control Register, UARTCR

Table 433. UARTCR Register

UART: UARTIFLS Register

Offset: 0x034

Description

Interrupt FIFO Level Select Register, UARTIFLS

Table 434. UARTIFLS Register

UART: UARTIMSC Register

Interrupt Mask Set/Clear Register, UARTIMSC

Table 435. UARTIMSC Register

Raw Interrupt Status Register, UARTRIS

Table 436. UARTRIS Register

UART: UARTMIS Register

Offset: 0x040

Description

Masked Interrupt Status Register, UARTMIS

Table 437. UARTMIS Register

UART: UARTICR Register

Offset: 0x044

Description

Interrupt Clear Register, UARTICR

Table 438. UARTICR Register

UART: UARTDMACR Register

Offset: 0x048

Description

DMA Control Register, UARTDMACR

Table 439. UARTDMACR Register

UART: UARTPERIPHID0 Register

Offset: 0xfe0

Description

UARTPeriphID0 Register

Table 440.
UARTPERIPHID0
Register

UART: UARTPERIPHID1 Register

Offset: 0xfe4

Description

UARTPeriphID1 Register

Table 441.
UARTPERIPHID1
Register

UART: UARTPERIPHID2 Register

Offset: 0xfe8

Description

UARTPeriphID2 Register

Table 442.
UARTPERIPHID2
Register

UART: UARTPERIPHID3 Register

Offset: 0xfec

Description

UARTPeriphID3 Register

Table 443.
UARTPERIPHD3
Register

UART: UARTPCELLID0 Register

Offset: 0xff0

Description

UARTPCellID0 Register

Table 444.
UARTPCELLID0
Register

UART: UARTPCELLID1 Register

Offset: 0xff4

Description

UARTPCellID1 Register

Table 445.
UARTPCELLID1
Register

UART: UARTPCELLID2 Register

Offset: 0xff8

Description

UARTPCellID2 Register

Table 446.
UARTPCELLID2
Register

UART: UARTPCELLID3 Register

Offset: 0xffc

Description

UARTPCellID3 Register

Table 447.
UARTPCELLID3
Register

4.3. I2C

Synopsys Documentation

Synopsys Proprietary. Used with permission.

I2C is a commonly used 2-wire interface that can be used to connect devices for low speed data transfer using clock SCL and data SDA wires.

RP2040 has two identical instances of an I2C controller. The external pins of each controller are connected to GPIO pins as defined in the GPIO muxing table in Section 2.19.2 . The muxing options give some IO flexibility.

4.3.1. Features

Each I2C controller is based on a configuration of the Synopsys DW_apb_i2c (v2.01) IP. The following features are supported:

• • Master or Slave (Default to Master mode)
• • Standard mode, Fast mode or Fast mode plus
• • Default slave address 0x055
• • Supports 10-bit addressing in Master mode
• • 16-element transmit buffer
• • 16-element receive buffer
• • Can be driven from DMA
• • Can generate interrupts

4.3.1.1. Standard

The I2C controller was designed for I2C Bus specification, version 6.0, dated April 2014.

4.3.1.2. Clocking

All clocks in the I2C controller are connected to clk_sys , including ic_clk which is mentioned in later sections. The I2C clock is generated by dividing down this clock, controlled by registers inside the block.

4.3.1.3. IOs

Each controller must connect its clock SCL and data SDA to one pair of GPIOs. The I2C standard requires that drivers drive a signal low, or when not driven the signal will be pulled high. This applies to SCL and SDA. The GPIO pads should be configured for:

• • pull-up enabled
• • slew rate limited
• • schmitt trigger enabled

There should also be external pull-ups on the board as the internal pad pull-ups may not be strong enough to pull up external circuits.

4.3.2. IP Configuration

I2C configuration details (each instance is fully independent):

• • 32-bit APB access
• • Supports Standard mode, Fast mode or Fast mode plus (not High speed)
• • Default slave address of 0x055
• • Master or Slave mode
• • Master by default (Slave mode disabled at reset)
• • 10-bit addressing supported in master mode (7-bit by default)
• • 16 entry transmit buffer
• • 16 entry receive buffer
• • Allows restart conditions when a master (can be disabled for legacy device support)
• • Configurable timing to adjust TsuDAT/ThDAT
• • General calls responded to on reset
• • Interface to DMA
• • Single interrupt output
• • Configurable timing to adjust clock frequency
• • Spike suppression (default 7 clk_sys cycles)
• • Can NACK after data received by Slave
• • Hold transfer when TX FIFO empty
• • Hold bus until space available in RX FIFO
• • Restart detect interrupt in Slave mode
• • Optional blocking Master commands (not enabled by default)

4.3.3. I2C Overview

The I2C bus is a 2-wire serial interface, consisting of a serial data line SDA and a serial clock SCL . These wires carry information between the devices connected to the bus. Each device is recognized by a unique address and can operate as either a “transmitter” or “receiver”, depending on the function of the device. Devices can also be considered as masters or slaves when performing data transfers. A master is a device that initiates a data transfer on the bus and generates the clock signals to permit that transfer. At that time, any device addressed is considered a slave.

NOTE

The I2C block must only be programmed to operate in either master OR slave mode only. Operating as a master and slave simultaneously is not supported.

The I2C block can operate in these modes:

• • standard mode (with data rates from 0 to 100kbps),
• • fast mode (with data rates less than or equal to 400kbps),
• • fast mode plus (with data rates less than or equal to 1000kbps).

These modes are not supported:

• • High-speed mode (with data rates less than or equal to 3.4Mbps),
• • Ultra-Fast Speed Mode (with data rates less than or equal to 5Mbps).

NOTE

References to fast mode also apply to fast mode plus, unless specifically stated otherwise.

The I2C block can communicate with devices in one of these modes as long as they are attached to the bus. Additionally, fast mode devices are downward compatible. For instance, fast mode devices can communicate with standard mode devices in 0 to 100kbps I2C bus system. However standard mode devices are not upward compatible and should not be incorporated in a fast-mode I2C bus system as they cannot follow the higher transfer rate and unpredictable states would occur.

An example of high-speed mode devices are LCD displays, high-bit count ADCs, and high capacity EEPROMs. These devices typically need to transfer large amounts of data. Most maintenance and control applications, the common use for the I2C bus, typically operate at 100kHz (in standard and fast modes). Any DW_apb_i2c device can be attached to an I2C-bus and every device can talk with any master, passing information back and forth. There needs to be at least one master (such as a microcontroller or DSP) on the bus but there can be multiple masters, which require them to arbitrate for ownership. Multiple masters and arbitration are explained later in this chapter. The I2C block does not support SMBus and PMBus protocols (for System Management and Power management).

The DW_apb_i2c is made up of an AMBA APB slave interface, an I2C interface, and FIFO logic to maintain coherency between the two interfaces. The blocks of the component are illustrated in Figure 64 .

Figure 64. I2C Block diagram

graph TD
    subgraph DW_apb_i2c
        direction TB
        subgraph Row1
            A[AMBA Bus Interface Unit]
            B[Register File]
            C[Slave State Machine]
            D[Master State Machine]
        end
        subgraph Row2
            E[Clock Generator]
            F[Rx Shift]
            G[Tx Shift]
            H[Rx Filter]
        end
        subgraph Row3
            I[Toggle]
            J[Synchronizer]
            K[DMA Interface]
            L[Interrupt Controller]
        end
        subgraph Row4
            M[RX FIFO]
            N[TX FIFO]
        end
    end

The following define the functions of the blocks in Figure 64 :

• • AMBA Bus Interface Unit — Takes the APB interface signals and translates them into a common generic interface that allows the register file to be bus protocol-agnostic.

• • Register File — Contains configuration registers and is the interface with software.
• • Slave State Machine — Follows the protocol for a slave and monitors bus for address match.
• • Master State Machine — Generates the I2C protocol for the master transfers.
• • Clock Generator — Calculates the required timing to do the following:
  • ◦ Generate the SCL clock when configured as a master
  • ◦ Check for bus idle
  • ◦ Generate a START and a STOP
  • ◦ Setup the data and hold the data
• • Rx Shift — Takes data into the design and extracts it in byte format.
• • Tx Shift — Presents data supplied by CPU for transfer on the I2C bus.
• • Rx Filter — Detects the events in the bus; for example, start, stop and arbitration lost.
• • Toggle — Generates pulses on both sides and toggles to transfer signals across clock domains.
• • Synchronizer — Transfers signals from one clock domain to another.
• • DMA Interface — Generates the handshaking signals to the central DMA controller in order to automate the data transfer without CPU intervention.
• • Interrupt Controller — Generates the raw interrupt and interrupt flags, allowing them to be set and cleared.
• • RX FIFO/TX FIFO — Holds the RX FIFO and TX FIFO register banks and controllers, along with their status levels.

4.3.4. I2C Terminology

The following terms are used and are defined as follows:

4.3.4.1. I2C Bus Terms

The following terms relate to how the role of the I2C device and how it interacts with other I2C devices on the bus.

• • Transmitter — the device that sends data to the bus. A transmitter can either be a device that initiates the data transmission to the bus (a master-transmitter) or responds to a request from the master to send data to the bus (a slave-transmitter).
• • Receiver — the device that receives data from the bus. A receiver can either be a device that receives data on its own request (a master-receiver) or in response to a request from the master (a slave-receiver).
• • Master — the component that initializes a transfer (START command), generates the clock SCL signal and terminates the transfer (STOP command). A master can be either a transmitter or a receiver.
• • Slave — the device addressed by the master. A slave can be either receiver or transmitter.
• • Multi-master — the ability for more than one master to co-exist on the bus at the same time without collision or data loss.
• • Arbitration — the predefined procedure that authorizes only one master at a time to take control of the bus. For more information about this behaviour, refer to Section 4.3.8 .
• • Synchronization — the predefined procedure that synchronizes the clock signals provided by two or more masters. For more information about this feature, refer to Section 4.3.9 .
• • SDA — data signal line (Serial Data)
• • SCL — clock signal line (Serial Clock)

4.3.4.2. Bus Transfer Terms

The following terms are specific to data transfers that occur to/from the I2C bus.

• • START (RESTART) – data transfer begins with a START or RESTART condition. The level of the SDA data line changes from high to low, while the SCL clock line remains high. When this occurs, the bus becomes busy.

NOTE

START and RESTART conditions are functionally identical.

• • STOP – data transfer is terminated by a STOP condition. This occurs when the level on the SDA data line passes from the low state to the high state, while the SCL clock line remains high. When the data transfer has been terminated, the bus is free or idle once again. The bus stays busy if a RESTART is generated instead of a STOP condition.

4.3.5. I2C Behaviour

The DW_apb_i2c can be controlled via software to be either:

• • An I2C master only, communicating with other I2C slaves; OR
• • An I2C slave only, communicating with one or more I2C masters.

The master is responsible for generating the clock and controlling the transfer of data. The slave is responsible for either transmitting or receiving data to/from the master. The acknowledgement of data is sent by the device that is receiving data, which can be either a master or a slave. As mentioned previously, the I2C protocol also allows multiple masters to reside on the I2C bus and uses an arbitration procedure to determine bus ownership.

Each slave has a unique address that is determined by the system designer. When a master wants to communicate with a slave, the master transmits a START/RESTART condition that is then followed by the slave’s address and a control bit (R/W) to determine if the master wants to transmit data or receive data from the slave. The slave then sends an acknowledge (ACK) pulse after the address.

If the master (master-transmitter) is writing to the slave (slave-receiver), the receiver gets one byte of data. This transaction continues until the master terminates the transmission with a STOP condition. If the master is reading from a slave (master-receiver), the slave transmits (slave-transmitter) a byte of data to the master, and the master then acknowledges the transaction with the ACK pulse. This transaction continues until the master terminates the transmission by not acknowledging (NACK) the transaction after the last byte is received, and then the master issues a STOP condition or addresses another slave after issuing a RESTART condition. This behaviour is illustrated in Figure 65.

Figure 65. Data transfer on the I2C Bus

The DW_apb_i2c is a synchronous serial interface. The SDA line is a bidirectional signal and changes only while the SCL line is low, except for STOP, START, and RESTART conditions. The output drivers are open-drain or open-collector to perform wire-AND functions on the bus. The maximum number of devices on the bus is limited by only the maximum capacitance specification of 400 pF. Data is transmitted in byte packages.

The I2C protocols implemented in DW_apb_i2c are described in more details in Section 4.3.6.

4.3.5.1. START and STOP Generation

When operating as an I2C master, putting data into the transmit FIFO causes the DW_apb_i2c to generate a START condition on the I2C bus. Writing a 1 to IC_DATA_CMD.STOP causes the DW_apb_i2c to generate a STOP condition on

the I2C bus; a STOP condition is not issued if this bit is not set, even if the transmit FIFO is empty.

When operating as a slave, the DW_apb_i2c does not generate START and STOP conditions, as per the protocol. However, if a read request is made to the DW_apb_i2c, it holds the SCL line low until read data has been supplied to it. This stalls the I2C bus until read data is provided to the slave DW_apb_i2c, or the DW_apb_i2c slave is disabled by writing a 0 to IC_ENABLE.ENABLE .

4.3.5.2. Combined Formats

The DW_apb_i2c supports mixed read and write combined format transactions in both 7-bit and 10-bit addressing modes. The DW_apb_i2c does not support mixed address and mixed address format—that is, a 7-bit address transaction followed by a 10-bit address transaction or vice versa—combined format transactions. To initiate combined format transfers, IC_CON.IC_RESTART_EN should be set to 1. With this value set and operating as a master, when the DW_apb_i2c completes an I2C transfer, it checks the transmit FIFO and executes the next transfer. If the direction of this transfer differs from the previous transfer, the combined format is used to issue the transfer. If the transmit FIFO is empty when the current I2C transfer completes:

• • IC_DATA_CMD.STOP is checked and:
  • ◦ If set to 1, a STOP bit is issued.
  • ◦ If set to 0, the SCL is held low until the next command is written to the transmit FIFO.

For more details, refer to Section 4.3.7 .

4.3.6. I2C Protocols

The DW_apb_i2c has the protocols discussed in this section.

4.3.6.1. START and STOP Conditions

When the bus is idle, both the SCL and SDA signals are pulled high through external pull-up resistors on the bus. When the master wants to start a transmission on the bus, the master issues a START condition. This is defined to be a high-to-low transition of the SDA signal while SCL is 1. When the master wants to terminate the transmission, the master issues a STOP condition. This is defined to be a low-to-high transition of the SDA line while SCL is 1. Figure 66 shows the timing of the START and STOP conditions. When data is being transmitted on the bus, the SDA line must be stable when SCL is 1.

Figure 66. I2C START and STOP Condition

i NOTE

The signal transitions for the START/STOP conditions, as depicted in Figure 66 , reflect those observed at the output signals of the Master driving the I2C bus. Care should be taken when observing the SDA/SCL signals at the input signals of the Slave(s), because unequal line delays may result in an incorrect SDA/SCL timing relationship.

4.3.6.2. Addressing Slave Protocol

There are two address formats: the 7-bit address format and the 10-bit address format.

4.3.6.2.1. 7-bit Address Format

During the 7-bit address format, the first seven bits (bits 7:1) of the first byte set the slave address and the LSB bit (bit 0) is the R/W bit as shown in Figure 67 . When bit 0 (R/W) is set to 0, the master writes to the slave. When bit 0 (R/W) is set to 1, the master reads from the slave.

Figure 67. I2C 7-bit Address Format

4.3.6.2.2. 10-bit Address Format

During 10-bit addressing, two bytes are transferred to set the 10-bit address. The transfer of the first byte contains the following bit definition. The first five bits (bits 7:3) notify the slaves that this is a 10-bit transfer followed by the next two bits (bits 2:1), which set the slaves address bits 9:8, and the LSB bit (bit 0) is the R/W bit. The second byte transferred sets bits 7:0 of the slave address. Figure 68 shows the 10-bit address format.

Figure 68. 10-bit Address Format

This table defines the special purpose and reserved first byte addresses.

Table 448. I2C/SMBus Definition of Bits in First Byte

DW_apb_i2c does not restrict you from using these reserved addresses. However, if you use these reserved addresses,

you may run into incompatibilities with other I2C components.

4.3.6.3. Transmitting and Receiving Protocol

The master can initiate data transmission and reception to/from the bus, acting as either a master-transmitter or master-receiver. A slave responds to requests from the master to either transmit data or receive data to/from the bus, acting as either a slave-transmitter or slave-receiver, respectively.

4.3.6.3.1. Master-Transmitter and Slave-Receiver

All data is transmitted in byte format, with no limit on the number of bytes transferred per data transfer. After the master sends the address and R/W bit or the master transmits a byte of data to the slave, the slave-receiver must respond with the acknowledge signal (ACK). When a slave-receiver does not respond with an ACK pulse, the master aborts the transfer by issuing a STOP condition. The slave must leave the SDA line high so that the master can abort the transfer. If the master-transmitter is transmitting data as shown in Figure 69 , then the slave-receiver responds to the master-transmitter with an acknowledge pulse after every byte of data is received.

Figure 69. I2C Master-Transmitter Protocol

4.3.6.3.2. Master-Receiver and Slave-Transmitter

If the master is receiving data as shown in Figure 70 , then the master responds to the slave-transmitter with an acknowledge pulse after a byte of data has been received, except for the last byte. This is the way the master-receiver notifies the slave-transmitter that this is the last byte. The slave-transmitter relinquishes the SDA line after detecting the No Acknowledge (NACK) so that the master can issue a STOP condition.

Figure 70. I2C Master-Receiver Protocol

When a master does not want to relinquish the bus with a STOP condition, the master can issue a RESTART condition. This is identical to a START condition except it occurs after the ACK pulse. Operating in master mode, the DW_apb_i2c can then communicate with the same slave using a transfer of a different direction. For a description of the combined format transactions that the DW_apb_i2c supports, refer to Section 4.3.5.2 .

The DW_apb_i2c must be completely disabled before the target slave address register ( IC_TAR ) can be reprogrammed.

The START BYTE transfer protocol is set up for systems that do not have an on-board dedicated I2C hardware module. When the DW_apb_i2c is addressed as a slave, it always samples the I2C bus at the highest speed supported so that it never requires a START BYTE transfer. However, when DW_apb_i2c is a master, it supports the generation of START BYTE transfers at the beginning of every transfer in case a slave device requires it.

This protocol consists of seven zeros being transmitted followed by a one, as illustrated in Figure 71 . This allows the processor that is polling the bus to under-sample the address phase until zero is detected. Once the microcontroller detects a zero, it switches from the under sampling rate to the correct rate of the master.

Figure 71. I2C Start Byte Transfer

The START BYTE procedure is as follows:

1. 1. Master generates a START condition.
2. 2. Master transmits the START byte (0000 0001).
3. 3. Master transmits the ACK clock pulse. (Present only to conform with the byte handling format used on the bus)
4. 4. No slave sets the ACK signal to zero.
5. 5. Master generates a RESTART (R) condition.

A hardware receiver does not respond to the START BYTE because it is a reserved address and resets after the RESTART condition is generated.

When operating as a master, the DW_apb_i2c component supports the mode of Tx FIFO management illustrated in Figure 72

The component does not generate a STOP if the Tx FIFO becomes empty; in this situation the component holds the SCL line low, stalling the bus until a new entry is available in the Tx FIFO. A STOP condition is generated only when the user specifically requests it by setting bit nine (Stop bit) of the command written to IC_DATA_CMD register. Figure 72 shows the bits in the IC_DATA_CMD register.

Figure 72.
IC_DATA_CMD
Register

Figure 73 illustrates the behaviour of the DW_apb_i2c when the Tx FIFO becomes empty while operating as a master transmitter, as well as showing the generation of a STOP condition.

Figure 73. Master Transmitter - Tx FIFO Empties/STOP Generation

Figure 74 illustrates the behaviour of the DW_apb_i2c when the Tx FIFO becomes empty while operating as a master receiver, as well as showing the generation of a STOP condition.

Figure 74. Master Receiver - Tx FIFO Empties/STOP Generation

Figure 75 and Figure 76 illustrate configurations where the user can control the generation of RESTART conditions on the I2C bus. If bit 10 (Restart) of the IC_DATA_CMD register is set and the restart capability is enabled (IC_RESTART_EN=1), a RESTART is generated before the data byte is written to or read from the slave. If the restart capability is not enabled a STOP followed by a START is generated in place of the RESTART. Figure 75 illustrates this situation during operation as a master transmitter.

Figure 75. Master Transmitter – Restart Bit of IC_DATA_CMD Is Set

Figure 76 illustrates the same situation, but during operation as a master receiver.

Figure 76. Master Receiver – Restart Bit of IC_DATA_CMD Is Set

Figure 77 illustrates operation as a master transmitter where the Stop bit of the IC_DATA_CMD register is set and the Tx FIFO is not empty

Figure 77. Master Transmitter – Stop Bit of IC_DATA_CMD Set/Tx FIFO Not Empty

Figure 78 illustrates operation as a master transmitter where the first byte loaded into the Tx FIFO is allowed to go empty with the Restart bit set

Figure 78. Master Transmitter – First Byte Loaded Into Tx FIFO Allowed to Empty, Restart Bit Set

Figure 79 illustrates operation as a master receiver where the Stop bit of the IC_DATA_CMD register is set and the Tx FIFO is not empty

Figure 79. Master Receiver – Stop Bit of IC_DATA_CMD Set/Tx FIFO Not Empty

Figure 80 illustrates operation as a master receiver where the first command loaded after the Tx FIFO is allowed to empty and the Restart bit is set

Figure 80. Master Receiver – First Command Loaded After Tx FIFO Allowed to Empty/Restart Bit Set

4.3.8. Multiple Master Arbitration

The DW_apb_i2c bus protocol allows multiple masters to reside on the same bus. If there are two masters on the same I2C-bus, there is an arbitration procedure if both try to take control of the bus at the same time by generating a START condition at the same time. Once a master (for example, a microcontroller) has control of the bus, no other master can take control until the first master sends a STOP condition and places the bus in an idle state.

Arbitration takes place on the SDA line, while the SCL line is one. The master, which transmits a one while the other master transmits zero, loses arbitration and turns off its data output stage. The master that lost arbitration can continue to generate clocks until the end of the byte transfer. If both masters are addressing the same slave device, the arbitration could go into the data phase.

Upon detecting that it has lost arbitration to another master, the DW_apb_i2c will stop generating SCL (will disable the output driver). Figure 81 illustrates the timing of when two masters are arbitrating on the bus.

Figure 81. Multiple Master Arbitration

Control of the bus is determined by address or master code and data sent by competing masters, so there is no central master nor any order of priority on the bus.

Arbitration is not allowed between the following conditions:

• • A RESTART condition and a data bit
• • A STOP condition and a data bit
• • A RESTART condition and a STOP condition

NOTE

Slaves are not involved in the arbitration process.

4.3.9. Clock Synchronization

When two or more masters try to transfer information on the bus at the same time, they must arbitrate and synchronize the SCL clock. All masters generate their own clock to transfer messages. Data is valid only during the high period of SCL clock. Clock synchronization is performed using the wired-AND connection to the SCL signal. When the master transitions the SCL clock to zero, the master starts counting the low time of the SCL clock and transitions the SCL clock signal to one at the beginning of the next clock period. However, if another master is holding the SCL line to 0, then the master goes into a HIGH wait state until the SCL clock line transitions to one.

All masters then count off their high time, and the master with the shortest high time transitions the SCL line to zero. The masters then count out their low time and the one with the longest low time forces the other masters into a HIGH wait state. Therefore, a synchronized SCL clock is generated, which is illustrated in Figure 82. Optionally, slaves may hold the SCL line low to slow down the timing on the I2C bus.

Figure 82. Multi-Master Clock Synchronization

4.3.10. Operation Modes

This section provides information on operation modes.

i NOTE

It is important to note that the DW_apb_i2c should only be set to operate as an I2C Master, or I2C Slave, but not both simultaneously. This is achieved by ensuring that IC_CON.IC_SLAVE_DISABLE and IC_CON.MASTER_MODE are never set to zero and one, respectively.

4.3.10.1. Slave Mode Operation

This section discusses slave mode procedures.

4.3.10.1.1. Initial Configuration

To use the DW_apb_i2c as a slave, perform the following steps:

1. 1. Disable the DW_apb_i2c by writing a '0' to IC_ENABLE.ENABLE .
2. 2. Write to the IC_SAR register (bits 9:0) to set the slave address. This is the address to which the DW_apb_i2c responds.
3. 3. Write to the IC_CON register to specify which type of addressing is supported (7-bit or 10-bit by setting bit 3). Enable the DW_apb_i2c in slave-only mode by writing a '0' into bit six ( IC_SLAVE_DISABLE ) and a '0' to bit zero ( MASTER_MODE ).

i NOTE

Slaves and masters do not have to be programmed with the same type of addressing 7-bit or 10-bit address. For instance, a slave can be programmed with 7-bit addressing and a master with 10-bit addressing, and vice versa.

1. 1. Enable the DW_apb_i2c by writing a '1' to IC_ENABLE.ENABLE .

i NOTE

Depending on the reset values chosen, steps two and three may not be necessary because the reset values can be configured. For instance, if the device is only going to be a master, there would be no need to set the slave address because you can configure DW_apb_i2c to have the slave disabled after reset and to enable the master after reset. The values stored are static and do not need to be reprogrammed if the DW_apb_i2c is disabled.

⚠ WARNING

It is recommended that the DW_apb_i2c Slave be brought out of reset only when the I2C bus is IDLE. De-asserting the reset when a transfer is ongoing on the bus causes internal synchronization flip-flops used to synchronize SDA and SCL to toggle from a reset value of one to the actual value on the bus. This can result in SDA toggling from one to zero while SCL is one, thereby causing a false START condition to be detected by the DW_apb_i2c Slave. This scenario can also be avoided by configuring the DW_apb_i2c with IC_SLAVE_DISABLE = 1 and MASTER_MODE = 1 so that the Slave interface is disabled after reset. It can then be enabled by programming IC_CON[0] = 0 and IC_CON[6] = 0 after the internal SDA and SCL have synchronized to the value on the bus; this takes approximately six ic_clk cycles after reset de-assertion.

4.3.10.1.2. Slave-Transmitter Operation for a Single Byte

When another I2C master device on the bus addresses the DW_apb_i2c and requests data, the DW_apb_i2c acts as a slave-transmitter and the following steps occur:

1. 1. The other I2C master device initiates an I2C transfer with an address that matches the slave address in the IC_SAR register of the DW_apb_i2c.
2. 2. The DW_apb_i2c acknowledges the sent address and recognizes the direction of the transfer to indicate that it is acting as a slave-transmitter.
3. 3. The DW_apb_i2c asserts the RD_REQ interrupt (bit five of the IC_RAW_INTR_STAT register) and holds the SCL line low. It is in a wait state until software responds. If the RD_REQ interrupt has been masked, due to IC_INTR_MASK.M_RD_REQ being set to zero, then it is recommended that a hardware and/or software timing routine be used to instruct the CPU to perform periodic reads of the IC_RAW_INTR_STAT register.
   1. a. Reads that indicate IC_RAW_INTR_STAT.RD_REQ being set to one must be treated as the equivalent of the RD_REQ interrupt being asserted.
   2. b. Software must then act to satisfy the I2C transfer.
   3. c. The timing interval used should be in the order of 10 times the fastest SCL clock period the DW_apb_i2c can handle. For example, for 400kbps, the timing interval is 25µs.

NOTE

The value of 10 is recommended here because this is approximately the amount of time required for a single byte of data transferred on the I2C bus.

1. 1. If there is any data remaining in the Tx FIFO before receiving the read request, then the DW_apb_i2c asserts a TX_ABRT interrupt (bit six of the IC_RAW_INTR_STAT register) to flush the old data from the TX FIFO. If the TX_ABRT interrupt has been masked, due to IC_INTR_MASK.M_TX_ABRT being set to zero, then it is recommended that re-using the timing routine (described in the previous step), or a similar one, be used to read the IC_RAW_INTR_STAT register.

NOTE

Because the DW_apb_i2c's Tx FIFO is forced into a flushed/reset state whenever a TX_ABRT event occurs, it is necessary for software to release the DW_apb_i2c from this state by reading the IC_CLR_TX_ABRT register before attempting to write into the Tx FIFO. See register IC_RAW_INTR_STAT for more details.

1. a. Reads that indicate bit six ( R_TX_ABRT ) being set to one must be treated as the equivalent of the TX_ABRT interrupt being asserted.
2. b. There is no further action required from software.
3. c. The timing interval used should be similar to that described in the previous step for the IC_RAW_INTR_STAT.RD_REQ register.
   1. 1. Software writes to the IC_DATA_CMD register with the data to be written (by writing a '0' in bit 8).
   2. 2. Software must clear the RD_REQ and TX_ABRT interrupts (bits five and six, respectively) of the IC_RAW_INTR_STAT register before proceeding. If the RD_REQ and/or TX_ABRT interrupts have been masked, then clearing of the IC_RAW_INTR_STAT register will have already been performed when either the R_RD_REQ or R_TX_ABRT bit has been read as one.
   3. 3. The DW_apb_i2c releases the SCL and transmits the byte.
   4. 4. The master may hold the I2C bus by issuing a RESTART condition or release the bus by issuing a STOP condition.

Slave-Transmitter Operation for a Single Byte is not applicable in Ultra-Fast Mode as Read transfers are not supported.

When another I2C master device on the bus addresses the DW_apb_i2c and is sending data, the DW_apb_i2c acts as a slave-receiver and the following steps occur:

1. 1. The other I2C master device initiates an I2C transfer with an address that matches the DW_apb_i2c's slave address in the IC_SAR register.
2. 2. The DW_apb_i2c acknowledges the sent address and recognizes the direction of the transfer to indicate that the DW_apb_i2c is acting as a slave-receiver.
3. 3. DW_apb_i2c receives the transmitted byte and places it in the receive buffer.

If the Rx FIFO is completely filled with data when a byte is pushed, then the DW_apb_i2c slave holds the I2C SCL line low until the Rx FIFO has some space, and then continues with the next read request.

1. 1. DW_apb_i2c asserts the RX_FULL interrupt IC_RAW_INTR_STAT.RX_FULL . If the RX_FULL interrupt has been masked, due to setting IC_INTR_MASK.M_RX_FULL register to zero or setting IC_TX_TL to a value larger than zero, then it is recommended that a timing routine (described in Section 4.3.10.1.2 ) be implemented for periodic reads of the IC_STATUS register. Reads of the IC_STATUS register, with bit 3 (RFNE) set at one, must then be treated by software as the equivalent of the RX_FULL interrupt being asserted.
2. 2. Software may read the byte from the IC_DATA_CMD register (bits 7:0).
3. 3. The other master device may hold the I2C bus by issuing a RESTART condition, or release the bus by issuing a STOP condition.

In the standard I2C protocol, all transactions are single byte transactions and the programmer responds to a remote master read request by writing one byte into the slave's TX FIFO. When a slave (slave-transmitter) is issued with a read request (RD_REQ) from the remote master (master-receiver), at a minimum there should be at least one entry placed into the slave-transmitter's TX FIFO. DW_apb_i2c is designed to handle more data in the TX FIFO so that subsequent read requests can take that data without raising an interrupt to get more data. Ultimately, this eliminates the possibility of significant latencies being incurred between raising the interrupt for data each time had there been a restriction of having only one entry placed in the TX FIFO. This mode only occurs when DW_apb_i2c is acting as a slave-transmitter. If the remote master acknowledges the data sent by the slave-transmitter and there is no data in the slave's TX FIFO, the DW_apb_i2c holds the I2C SCL line low while it raises the read request interrupt (RD_REQ) and waits for data to be written into the TX FIFO before it can be sent to the remote master.

If the RD_REQ interrupt is masked, due to IC_INTR_STAT.R_RD_REQ set to zero, then it is recommended that a timing routine be used to activate periodic reads of the IC_RAW_INTR_STAT register. Reads of IC_RAW_INTR_STAT that return bit five (RD_REQ) set to one must be treated as the equivalent of the RD_REQ interrupt referred to in this section. This timing routine is similar to that described in Section 4.3.10.1.2 .

The RD_REQ interrupt is raised upon a read request, and like interrupts, must be cleared when exiting the interrupt service handling routine (ISR). The ISR allows you to either write one byte or more than one byte into the Tx FIFO. During the transmission of these bytes to the master, if the master acknowledges the last byte, then the slave must raise the RD_REQ again because the master is requesting for more data. If the programmer knows in advance that the remote master is requesting a packet of 'n' bytes, then when another master addresses DW_apb_i2c and requests data, the Tx FIFO could be written with 'n' bytes and the remote master receives it as a continuous stream of data. For example, the

DW_apb_i2c slave continues to send data to the remote master as long as the remote master is acknowledging the data sent and there is data available in the Tx FIFO. There is no need to hold the SCL line low or to issue RD_REQ again.

If the remote master is to receive 'n' bytes from the DW_apb_i2c but the programmer wrote a number of bytes larger than 'n' to the Tx FIFO, then when the slave finishes sending the requested 'n' bytes, it clears the Tx FIFO and ignores any excess bytes.

The DW_apb_i2c generates a transmit abort (TX_ABRT) event to indicate the clearing of the Tx FIFO in this example. At the time an ACK/NACK is expected, if a NACK is received, then the remote master has all the data it wants. At this time, a flag is raised within the slave's state machine to clear the leftover data in the Tx FIFO. This flag is transferred to the processor bus clock domain where the FIFO exists and the contents of the Tx FIFO is cleared at that time.

4.3.10.2. Master Mode Operation

This section discusses master mode procedures.

4.3.10.2.1. Initial Configuration

To use the DW_apb_i2c as a master perform the following steps:

1. 1. Disable the DW_apb_i2c by writing zero to IC_ENABLE.ENABLE .
2. 2. Write to the IC_CON register to set the maximum speed mode supported (bits 2:1) and the desired speed of the DW_apb_i2c master-initiated transfers, either 7-bit or 10-bit addressing (bit 4). Ensure that bit six ( IC_SLAVE_DISABLE ) is written with a '1' and bit zero ( MASTER_MODE ) is written with a '1'.

Note: Slaves and masters do not have to be programmed with the same type of 7-bit or 10-bit address. For instance, a slave can be programmed with 7-bit addressing and a master with 10-bit addressing, and vice versa.

1. 1. Write to the IC_TAR register the address of the I2C device to be addressed (bits 9:0). This register also indicates whether a General Call or a START BYTE command is going to be performed by I2C.
2. 2. Enable the DW_apb_i2c by writing a one to IC_ENABLE.ENABLE .
3. 3. Now write transfer direction and data to be sent to the IC_DATA_CMD register. If the IC_DATA_CMD register is written before the DW_apb_i2c is enabled, the data and commands are lost as the buffers are kept cleared when DW_apb_i2c is disabled. This step generates the START condition and the address byte on the DW_apb_i2c. Once DW_apb_i2c is enabled and there is data in the TX FIFO, DW_apb_i2c starts reading the data.

i NOTE

Depending on the reset values chosen, steps two, three, four, and five may not be necessary because the reset values can be configured. The values stored are static and do not need to be reprogrammed if the DW_apb_i2c is disabled, with the exception of the transfer direction and data.

4.3.10.2.2. Master Transmit and Master Receive

The DW_apb_i2c supports switching back and forth between reading and writing dynamically. To transmit data, write the data to be written to the lower byte of the I2C Rx/Tx Data Buffer and Command Register ( IC_DATA_CMD ). The CMD bit [8] should be written to zero for I2C write operations. Subsequently, a read command may be issued by writing "don't cares" to the lower byte of the IC_DATA_CMD register, and a one should be written to the CMD bit. The DW_apb_i2c master continues to initiate transfers as long as there are commands present in the transmit FIFO. If the transmit FIFO becomes empty the master either inserts a STOP condition after completing the current transfers.

• • If set to one, it issues a STOP condition after completing the current transfer.
• • If set to zero, it holds SCL low until next command is written to the transmit FIFO.

For more details, refer to Section 4.3.7 .

4.3.10.3. Disabling DW_apb_i2c

The register IC_ENABLE_STATUS is added to allow software to unambiguously determine when the hardware has completely shutdown in response to IC_ENABLE.ENABLE being set from one to zero.

Only one register is required to be monitored, as opposed to monitoring two registers ( IC_STATUS and IC_RAW_INTR_STAT ) which was a requirement for earlier versions of DW_apb_i2c.

4.3.10.3.1. Procedure

1. 1. Define a timer interval ( \( t_{i2c\_poll} \) ) equal to the 10 times the signalling period for the highest I2C transfer speed used in the system and supported by DW_apb_i2c. For example, if the highest I2C transfer mode is 400kbps, then this \( t_{i2c\_poll} \) is 25 \( \mu s \) .
2. 2. Define a maximum time-out parameter, MAX_T_POLL_COUNT , such that if any repeated polling operation exceeds this maximum value, an error is reported.
3. 3. Execute a blocking thread/process/function that prevents any further I2C master transactions to be started by software, but allows any pending transfers to be completed.

4.3.10.4. Aborting I2C Transfers

The ABORT control bit of the IC_ENABLE register allows the software to relinquish the I2C bus before completing the issued transfer commands from the Tx FIFO. In response to an ABORT request, the controller issues the STOP condition over the I2C bus, followed by Tx FIFO flush. Aborting the transfer is allowed only in master mode of operation.

4.3.10.4.1. Procedure

1. 1. Stop filling the Tx FIFO ( IC_DATA_CMD ) with new commands.
2. 2. When operating in DMA mode, disable the transmit DMA by setting TDMAE to zero.
3. 3. Set IC_ENABLE.ABORT to one.
4. 4. Wait for the M_TX_ABORT interrupt.

• 5. Read the IC_TX_ABRT_SOURCE register to identify the source as ABRT_USER_ABRT .

4.3.11. Spike Suppression

The DW_apb_i2c contains programmable spike suppression logic that match requirements imposed by the I2C Bus Specification for SS/FS modes. This logic is based on counters that monitor the input signals ( SCL and SDA ), checking if they remain stable for a predetermined amount of ic_clk cycles before they are sampled internally. There is one separate counter for each signal ( SCL and SDA ). The number of ic_clk cycles can be programmed by the user and should be calculated taking into account the frequency of ic_clk and the relevant spike length specification. Each counter is started whenever its input signal changes its value. Depending on the behaviour of the input signal, one of the following scenarios occurs:

• • The input signal remains unchanged until the counter reaches its count limit value. When this happens, the internal version of the signal is updated with the input value, and the counter is reset and stopped. The counter is not restarted until a new change on the input signal is detected.
• • The input signal changes again before the counter reaches its count limit value. When this happens, the counter is reset and stopped, but the internal version of the signal is not updated. The counter remains stopped until a new change on the input signal is detected.

The timing diagram in Figure 83 illustrates the behaviour described above.

Figure 83. Spike Suppression Example

NOTE

There is a 2-stage synchronizer on the SCL input, but for the sake of simplicity this synchronization delay was not included in the timing diagram in Figure 83 .

The I2C Bus Specification calls for different maximum spike lengths according to the operating mode – 50ns for SS and FS, so this register is required to store the values needed:

• • Register IC_FS_SPKLEN holds the maximum spike length for SS and FS modes

This register is 8 bits wide and accessible through the APB interface for read and write purposes; however, they can be written to only when the DW_apb_i2c is disabled. The minimum value that can be programmed into these registers is one; attempting to program a value smaller than one results in the value one being written.

The default value for these registers is based on the value of 100ns for ic_clk period, so should be updated for the clk_sys period in use on RP2040.

• • Because the minimum value that can be programmed into the IC_FS_SPKLEN register is one, the spike length specification can be exceeded for low frequencies of ic_clk . Consider the simple example of a 10MHz (100ns period) ic_clk ; in this case, the minimum spike length that can be programmed is 100ns, which means that spikes up to this length are suppressed.
• • Standard synchronization logic (two flip-flops in series) is implemented upstream of the spike suppression logic and is not affected in any way by the contents of the spike length registers or the operation of the spike suppression logic; the two operations (synchronization and spike suppression) are completely independent. Because the SCL and SDA inputs are asynchronous to ic_clk , there is one ic_clk cycle uncertainty in the sampling of these signals; that is, depending on when they occur relative to the rising edge of ic_clk , spikes of the same original length might show a difference of one ic_clk cycle after being sampled.
• • Spike suppression is symmetrical; that is, the behaviour is exactly the same for transitions from zero to one and from one to zero.

4.3.12. Fast Mode Plus Operation

In fast mode plus, the DW_apb_i2c allows the fast mode operation to be extended to support speeds up to 1000kbps. To enable the DW_apb_i2c for fast mode plus operation, perform the following steps before initiating any data transfer:

1. 1. Set ic_clk frequency greater than or equal to 32MHz (refer to Section 4.3.14.2.1 ).
2. 2. Program the IC_CON register [2:1] = 2'b10 for fast mode or fast mode plus.
3. 3. Program IC_FS_SCL_LCNT and IC_FS_SCL_HCNT registers to meet the fast mode plus SCL (refer to Section 4.3.14 ).
4. 4. Program the IC_FS_SPKLEN register to suppress the maximum spike of 50ns.
5. 5. Program the IC_SDA_SETUP register to meet the minimum data setup time (tSU; DAT).

4.3.13. Bus Clear Feature

DW_apb_i2c supports the bus clear feature that provides graceful recovery of data SDA and clock SCL lines during unlikely events in which either the clock or data line is stuck at LOW.

4.3.13.1. SDA Line Stuck at LOW Recovery

In case of SDA line stuck at LOW, the master performs the following actions to recover as shown in Figure 84 and Figure 85 :

1. 1. Master sends a maximum of nine clock pulses to recover the bus LOW within those nine clocks.
   • ◦ The number of clock pulses will vary with the number of bits that remain to be sent by the slave. As the maximum number of bits is nine, master sends up to nine clock pulses and allows the slave to recover it.
   • ◦ The master attempts to assert a Logic 1 on the SDA line and check whether SDA is recovered. If the SDA is not recovered, it will continue to send a maximum of nine SCL clocks.
2. 2. If SDA line is recovered within nine clock pulses then the master will send the STOP to release the bus.
3. 3. If SDA line is not recovered even after the ninth clock pulse then system needs a hardware reset.

Figure 84. SDA Recovery with 9 SCL Clocks

Figure 85. SDA Recovery with 6 SCL Clocks

4.3.13.2. SCL Line is Stuck at LOW

In the unlikely event (due to an electric failure of a circuit) where the clock (SCL) is stuck to LOW, there is no effective method to overcome this problem but to reset the bus using the hardware reset signal.

4.3.14. IC_CLK Frequency Configuration

When the DW_apb_i2c is configured as a Standard (SS), Fast (FS)/Fast-Mode Plus (FM+), the *CNT registers must be set before any I2C bus transaction can take place in order to ensure proper I/O timing. The *CNT registers are:

• • IC_SS_SCL_HCNT
• • IC_SS_SCL_LCNT
• • IC_FS_SCL_HCNT
• • IC_FS_SCL_LCNT

i NOTE

The tBUF timing and setup/hold time of START, STOP and RESTART registers uses *HCNT/*LCNT register settings for the corresponding speed mode.

i NOTE

It is not necessary to program any of the *CNT registers if the DW_apb_i2c is enabled to operate only as an I2C slave, since these registers are used only to determine the SCL timing requirements for operation as an I2C master.

Table 449 lists the derivation of I2C timing parameters from the *CNT programming registers.

Table 449. Derivation of I2C Timing Parameters from *CNT Registers

4.3.14.1. Minimum High and Low Counts in SS, FS, and FM+ Modes.

When the DW_apb_i2c operates as an I2C master, in both transmit and receive transfers:

• • IC_SS_SCL_LCNT and IC_FS_SCL_LCNT register values must be larger than IC_FS_SPKLEN + 7.
• • IC_SS_SCL_HCNT and IC_FS_SCL_HCNT register values must be larger than IC_FS_SPKLEN + 5.

Details regarding the DW_apb_i2c high and low counts are as follows:

• • The minimum value of IC_*_SPKLEN + 7 for the *_LCNT registers is due to the time required for the DW_apb_i2c to drive SDA after a negative edge of SCL.
• • The minimum value of IC_*_SPKLEN + 5 for the *_HCNT registers is due to the time required for the DW_apb_i2c to sample SDA during the high period of SCL.
• • The DW_apb_i2c adds one cycle to the programmed *_LCNT value in order to generate the low period of the SCL clock; this is due to the counting logic for SCL low counting to (*_LCNT + 1).
• • The DW_apb_i2c adds IC_*_SPKLEN + 7 cycles to the programmed *_HCNT value in order to generate the high period of the SCL clock; this is due to the following factors:
  • ◦ The counting logic for SCL high counts to (*_HCNT+1).
  • ◦ The digital filtering applied to the SCL line incurs a delay of SPKLEN + 2 ic_clk cycles, where SPKLEN is:
    • ▪ IC_FS_SPKLEN if the component is operating in SS or FS
  • ◦ Whenever SCL is driven one to zero by the DW_apb_i2c—that is, completing the SCL high time—an internal logic latency of three ic_clk cycles is incurred. Consequently, the minimum SCL low time of which the DW_apb_i2c is capable is nine ic_clk periods (7 + 1 + 1), while the minimum SCL high time is thirteen ic_clk periods (6 + 1 + 3 + 3).

i NOTE

The total high time and low time of SCL generated by the DW_apb_i2c master is also influenced by the rise time and fall time of the SCL line, as shown in the illustration and equations in Figure 86. It should be noted that the SCL rise and fall time parameters vary, depending on external factors such as:

• • Characteristics of IO driver
• • Pull-up resistor value
• • Total capacitance on SCL line, and so on

These characteristics are beyond the control of the DW_apb_i2c.

Figure 86. Impact of SCL Rise Time and Fall Time on Generated SCL

4.3.14.2. Minimum IC_CLK Frequency

This section describes the minimum ic_clk frequencies that the DW_apb_i2c supports for each speed mode, and the associated high and low count values. In Slave mode, IC_SDA_HOLD (Thd;dat) and IC_SDA_SETUP (Tsu;dat) need to be programmed to satisfy the I2C protocol timing requirements. The following examples are for the case where IC_FS_SPKLEN is programmed to two.

4.3.14.2.1. Standard Mode (SM), Fast Mode (FM), and Fast Mode Plus (FM+)

This section details how to derive a minimum ic_clk value for standard and fast modes of the DW_apb_i2c. Although the following method shows how to do fast mode calculations, you can also use the same method in order to do calculations for standard mode and fast mode plus.

NOTE

The following computations do not consider the SCL_Rise_time and SCL_Fall_time.

Given conditions and calculations for the minimum DW_apb_i2c ic_clk value in fast mode:

• Fast mode has data rate of 400kbps; implies SCL period of 1/400kHz = 2.5μs
• Minimum hcnt value of 14 as a seed value; IC_HCNT_FS = 14
• Protocol minimum SCL high and low times:
  • MIN_SCL_LOWtime_FS = 1300ns
  • MIN_SCL_HIGHtime_FS = 600ns

Derived equations:

Combined, the previous equations produce the following:

Solving for IC_LCNT_FS:

The previous equation gives:

These calculations produce \( IC\_LCNT\_FS = 16 \) and \( IC\_HCNT\_FS = 14 \) , giving an \( ic\_clk \) value of:

Testing these results shows that protocol requirements are satisfied.

Table 450 lists the minimum \( ic\_clk \) values for all modes with high and low count values.

Table 450. \( ic\_clk \) in Relation to High and Low Counts

• The \( IC\_*_SCL\_LCNT \) and \( IC\_*_SCL\_HCNT \) registers are programmed using the SCL low and high program values in Table 450, which are calculated using SCL low count minus one, and SCL high counts minus eight, respectively. The values in Table 450 are based on \( IC\_SDA\_RX\_HOLD = 0 \) . The maximum \( IC\_SDA\_RX\_HOLD \) value depends on the \( IC\_*CNT \) registers in Master mode.
• In order to compute the HCNT and LCNT considering RC timings, use the following equations:
  • \( IC\_HCNT\_* = [(HCNT + IC\_*_SPKLEN + 7) * ic\_clk] + SCL\_Fall\_time \)
  • \( IC\_LCNT\_* = [(LCNT + 1) * ic\_clk] - SCL\_Fall\_time + SCL\_Rise\_time \)

4.3.14.3. Calculating High and Low Counts

The calculations below show how to calculate SCL high and low counts for each speed mode in the DW_apb_i2c. For the calculations to work, the \( ic\_clk \) frequencies used must not be less than the minimum \( ic\_clk \) frequencies specified in Table 450.

The default \( ic\_clk \) period value is set to 100ns, so default SCL high and low count values are calculated for each speed mode based on this clock. These values need updating according to the guidelines below.

The equation to calculate the proper number of \( ic\_clk \) signals required for setting the proper SCL clocks high and low times is as follows:

MIN_SCL_HIGHTime = Minimum High Period
MIN_SCL_HIGHTime = 4000ns for 100kbps,
600ns for 400kbps,
260ns for 1000kbps,

MIN_SCL_LOWtime = Minimum Low Period
MIN_SCL_LOWtime = 4700ns for 100kbps,

1300ns for 400kbps,
500ns for 1000kbps,

OSCFREQ = ic_clk Clock Frequency (Hz).

For example:

OSCFREQ = 100MHz
I2Cmode = fast, 400kbps
MIN_SCL_HIGHTime = 600ns.
MIN_SCL_LOWtime = 1300ns.

IC_xCNT = (ROUNDUP(MIN_SCL_HIGH_LOWtime*OSCFREQ,0))

IC_HCNT = (ROUNDUP(600ns * 100MHz,0))
IC_HCNTSCL PERIOD = 60
IC_LCNT = (ROUNDUP(1300ns * 100MHz,0))
IC_LCNTSCL PERIOD = 130
Actual MIN_SCL_HIGHTime = 60*(1/100MHz) = 600ns
Actual MIN_SCL_LOWtime = 130*(1/100MHz) = 1300ns

4.3.15. DMA Controller Interface

The DW_apb_i2c has built-in DMA capability; it has a handshaking interface to the DMA Controller to request and control transfers. The APB bus is used to perform the data transfer to or from the DMA. DMA transfers are transferred as single accesses as data rate is relatively low.

4.3.15.1. Enabling the DMA Controller Interface

To enable the DMA Controller interface on the DW_apb_i2c, you must write the DMA Control Register ( IC_DMA_CR ). Writing a one into the TDMAE bit field of IC_DMA_CR register enables the DW_apb_i2c transmit handshaking interface. Writing a one into the RDMAE bit field of the IC_DMA_CR register enables the DW_apb_i2c receive handshaking interface.

4.3.15.2. Overview of Operation

The DMA Controller is programmed with the number of data items (transfer count) that are to be transmitted or received by DW_apb_i2c.

The transfer is broken into single transfers on the bus, each initiated by a request from the DW_apb_i2c.

For example, where the transfer count programmed into the DMA Controller is four. The DMA transfer consists of a series of four single transactions. If the DW_apb_i2c makes a transmit request to this channel, a single data item is written to the DW_apb_i2c TX FIFO. Similarly, if the DW_apb_i2c makes a receive request to this channel, a single data item is read from the DW_apb_i2c RX FIFO. Four separate requests must be made to this DMA channel before all four data items are written or read.

4.3.15.3. Watermark Levels

In DW_apb_i2c the registers for setting watermarks to allow DMA bursts do not need be set to anything other than their reset value. Specifically IC_DMA_TDLR and IC_DMA_RDLR can be left at reset values of zero. This is because only single transfers are needed due to the low bandwidth of I2C relative to system bandwidth, and also the DMA controller

normally has highest priority on the system bus so will generally complete very quickly.

4.3.16. Operation of Interrupt Registers

Table 451 lists the operation of the DW_apb_i2c interrupt registers and how they are set and cleared. Some bits are set by hardware and cleared by software, whereas other bits are set and cleared by hardware.

Table 451. Clearing and Setting of Interrupt Registers

4.3.17. List of Registers

The I2C0 and I2C1 registers start at base addresses of 0x40044000 and 0x40048000 respectively (defined as I2C0_BASE and I2C1_BASE in SDK).

NOTE

You may see references to configuration constants in the I2C register descriptions; these are fixed values, set at hardware design time. A full list of their values can be found in https://github.com/raspberrypi/pico-sdk/blob/master/src/rp2040/hardware_regs/include/hardware/regs/i2c.h

Table 452. List of I2C registers

I2C: IC_CON Register

Offset: 0x00

I2C Control Register. This register can be written only when the DW_apb_i2c is disabled, which corresponds to the IC_ENABLE[0] register being set to 0. Writes at other times have no effect.

Read/Write Access: - bit 10 is read only. - bit 11 is read only - bit 16 is read only - bit 17 is read only - bits 18 and 19 are read only.

Table 453. IC_CON Register

I2C: IC_TAR Register

Offset: 0x04

Description

I2C Target Address Register

This register is 12 bits wide, and bits 31:12 are reserved. This register can be written to only when IC_ENABLE[0] is set to 0.

Note: If the software or application is aware that the DW_apb_i2c is not using the TAR address for the pending commands in the Tx FIFO, then it is possible to update the TAR address even while the Tx FIFO has entries (IC_STATUS[2]= 0). - It is not necessary to perform any write to this register if DW_apb_i2c is enabled as an I2C slave only.

Table 454. IC_TAR Register

I2C: IC_SAR Register

Offset: 0x08

Description

I2C Slave Address Register

Table 455. IC_SAR Register

I2C: IC_DATA_CMD Register

Offset: 0x10

I2C Rx/Tx Data Buffer and Command Register; this is the register the CPU writes to when filling the TX FIFO and the CPU reads from when retrieving bytes from RX FIFO.

The size of the register changes as follows:

Write: - 11 bits when IC_EMPTYFIFO_HOLD_MASTER_EN=1 - 9 bits when IC_EMPTYFIFO_HOLD_MASTER_EN=0 Read: - 12 bits when IC_FIRST_DATA_BYTE_STATUS = 1 - 8 bits when IC_FIRST_DATA_BYTE_STATUS = 0 Note: In order for the DW_apb_i2c to continue acknowledging reads, a read command should be written for every byte that is to be received; otherwise the DW_apb_i2c will stop acknowledging.

Table 456.
IC_DATA_CMD
Register

I2C: IC_SS_SCL_HCNT Register

Offset: 0x14

Description

Standard Speed I2C Clock SCL High Count Register

Table 457.
IC_SS_SCL_HCNT
Register

I2C: IC_SS_SCL_LCNT Register

Offset: 0x18

Description

Standard Speed I2C Clock SCL Low Count Register

Table 458.
IC_SS_SCL_LCNT
Register

I2C: IC_FS_SCL_HCNT Register

Offset: 0x1c

Description

Fast Mode or Fast Mode Plus I2C Clock SCL High Count Register

Table 459.
IC_FS_SCL_HCNT
Register

I2C: IC_FS_SCL_LCNT Register

Offset: 0x20

Description

Fast Mode or Fast Mode Plus I2C Clock SCL Low Count Register

Table 460.
IC_FS_SCL_LCNT
Register

I2C: IC_INTR_STAT Register

Offset: 0x2c

Description

I2C Interrupt Status Register

Each bit in this register has a corresponding mask bit in the IC_INTR_MASK register. These bits are cleared by reading the matching interrupt clear register. The unmasked raw versions of these bits are available in the IC_RAW_INTR_STAT

register.

Table 461.
IC_INTR_STAT
Register