Subversion Repositories neorv32

<<<

:sectnums:

==== Two-Wire Serial Interface Controller (TWI)

[cols="<3,<3,<4"]

[frame="topbot",grid="none"]

|=======================

| Hardware source file(s): | neorv32_twi.vhd |

| Software driver file(s): | neorv32_twi.c |

|                          | neorv32_twi.h |

| Top entity port:         | `twi_sda_io` | 1-bit bi-directional serial data

|                          | `twi_scl_io` | 1-bit bi-directional serial clock

| Configuration generics:  | _IO_TWI_EN_ | implement TWI controller when _true_

| CPU interrupts:          | fast IRQ channel 7 | transmission done interrupt (see <<_processor_interrupts>>)

|=======================

**Theory of Operation**

The two wire interface - also called "I²C" - is a quite famous interface for connecting several on-board

components. Since this interface only needs two signals (the serial data line `twi_sda_io` and the serial

clock line `twi_scl_io`) - despite of the number of connected devices - it allows easy interconnections of

several peripheral nodes.

The NEORV32 TWI implements a **TWI controller**. It features "clock stretching" (if enabled via the control

register), so a slow peripheral can halt the transmission by pulling the SCL line low. Currently, **no multi-controller

support** is available. Also, the NEORV32 TWI unit cannot operate in peripheral mode.

The TWI is enabled via the _TWI_CTRL_EN_ bit in the `CTRL` control register. The user program can start / stop a

transmission by issuing a START or STOP condition. These conditions are generated by setting the

according bits (_TWI_CTRL_START_ or _TWI_CTRL_STOP_) in the control register.

Data is send by writing a byte to the `DATA` register. Received data can also be read from this

register. The TWI controller is busy (transmitting data or performing a START or STOP condition) as long as the

_TWI_CTRL_BUSY_ bit in the control register is set.

An accessed peripheral has to acknowledge each transferred byte. When the _TWI_CTRL_ACK_ bit is set after a

completed transmission, the accessed peripheral has send an acknowledge. If it is cleared after a

transmission, the peripheral has send a not-acknowledge (NACK). The NEORV32 TWI controller can also

send an ACK by itself ("controller acknowledge _MACK_") after a transmission by pulling SDA low during the

ACK time slot. Set the _TWI_CTRL_MACK_ bit to activate this feature. If this bit is cleared, the ACK/NACK of the

peripheral is sampled in this time slot instead (normal mode).

In summary, the following independent TWI operations can be triggered by the application program:

* send START condition (also as REPEATED START condition)

* send STOP condition

* send (at least) one byte while also sampling one byte from the bus

[IMPORTANT]

The serial clock (SCL) and the serial data (SDA) lines can only be actively driven low by the

controller. Hence, external pull-up resistors are required for these lines.

The TWI clock frequency is defined via the 3-bit _TWI_CTRL_PRSCx_ clock prescaler. The following prescalers

are available:

.TWI prescaler configuration

[cols="<4,^1,^1,^1,^1,^1,^1,^1,^1"]

[options="header",grid="rows"]

|=======================

| **`TWI_CTRL_PRSCx`**        | `0b000` | `0b001` | `0b010` | `0b011` | `0b100` | `0b101` | `0b110` | `0b111`

| Resulting `clock_prescaler` |       2 |       4 |       8 |      64 |     128 |    1024 |    2048 |    4096

|=======================

Based on the _TWI_CTRL_PRSCx_ configuration, the actual TWI clock frequency f~SCL~ is derived from the processor main clock f~main~ and is determined by:

_**f~SCL~**_ = _f~main~[Hz]_ / (4 * `clock_prescaler`)

**Interrupt**

The TWI module provides a single interrupt to singal _idle state_ (= read for new transmission) to the CPU. Whenever TWI SPI module

is currently idle (and enabled), the interrupt request is active. A pending interrupt request is cleared

by triggering a new TWI transmission or by disabling the device.

.TWI register map (`struct NEORV32_TWI`)

[cols="<2,<2,<4,^1,<7"]

[options="header",grid="all"]

|=======================

| Address | Name [C] | Bit(s), Name [C] | R/W | Function

.10+<| `0xffffffb0` .10+<| `NEORV32_TWI.CTRL` <|`0` _TWI_CTRL_EN_     ^| r/w <| TWI enable

                                              <|`1` _TWI_CTRL_START_  ^| r/w <| generate START condition

                                              <|`2` _TWI_CTRL_STOP_   ^| r/w <| generate STOP condition

                                              <|`3` _TWI_CTRL_PRSC0_  ^| r/w .3+<| 3-bit clock prescaler select

                                              <|`4` _TWI_CTRL_PRSC1_  ^| r/w

                                              <|`5` _TWI_CTRL_PRSC2_  ^| r/w

                                              <|`6` _TWI_CTRL_MACK_   ^| r/w <| generate controller ACK for each transmission ("MACK")

                                              <|`7` _TWI_CTRL_CKSTEN_ ^| r/w <| allow clock-stretching by peripherals when set

                                              <|`30` _TWI_CTRL_ACK_   ^| r/- <| ACK received when set

                                              <|`31` _TWI_CTRL_BUSY_  ^| r/- <| transfer/START/STOP in progress when set

| `0xffffffb4` | `NEORV32_TWI.DATA` |`7:0` _TWI_DATA_MSB_ : TWI_DATA_LSB_ | r/w | receive/transmit data

|=======================