Subversion Repositories neorv32

<<<
:sectnums:
==== Primary Universal Asynchronous Receiver and Transmitter (UART0)

[cols="<3,<3,<4"]
[frame="topbot",grid="none"]
|=======================
| Hardware source file(s): | neorv32_uart.vhd | 
| Software driver file(s): | neorv32_uart.c |
|                          | neorv32_uart.h |
| Top entity port:         | `uart0_txd_o` | serial transmitter output UART0
|                          | `uart0_rxd_i` | serial receiver input UART0
|                          | `uart0_rts_o` | flow control: RX ready to receive
|                          | `uart0_cts_i` | flow control: TX allowed to send
| Configuration generics:  | _IO_UART0_EN_   | implement UART0 when _true_
|                          | _UART0_RX_FIFO_ | RX FIFO depth (power of 2, min 1)
|                          | _UART0_TX_FIFO_ | TX FIFO depth (power of 2, min 1)
| CPU interrupts:          | fast IRQ channel 2 | RX interrupt
|                          | fast IRQ channel 3 | TX interrupt (see <<_processor_interrupts>>)
|=======================

The UART is a standard serial interface mainly used to establish a communication channel between a host computer
computer/user and an application running on the embedded processor.

The NEORV32 UARTs feature independent transmitter and receiver with a fixed frame configuration of 8 data bits,
an optional parity bit (even or odd) and a fixed stop bit. The actual transmission rate - the Baudrate - is
programmable via software. Optional FIFOs with custom sizes can be configured for the transmitter and receiver
independently.

The UART features two memory-mapped registers `CTRL` and `DATA`, which are used for configuration, status
check and data transfer.

.Standard Console(s)
[NOTE]
Please note that _all_ default example programs and software libraries of the NEORV32 software
framework (including the bootloader and the runtime environment) use the primary UART
(_UART0_) as default user console interface. Furthermore, UART0 is used to implement all the standard
input, output and error consoles (`STDIN`, `STDOUT` and `STDERR`).


**Theory of Operation**

UART0 is enabled by setting the _UART_CTRL_EN_ bit in the UART0 control register `CTRL`. The Baud rate
is configured via a 12-bit _UART_CTRL_BAUDxx_ baud prescaler (`baud_prsc`) and a 3-bit _UART_CTRL_PRSCx_
clock prescaler (`clock_prescaler`) that scales the processor's primary clock (_f~main~_).

.UART0 prescaler configuration
[cols="<4,^1,^1,^1,^1,^1,^1,^1,^1"]
[options="header",grid="rows"]
|=======================
| **`UART_CTRL_PRSCx`**       | `0b000` | `0b001` | `0b010` | `0b011` | `0b100` | `0b101` | `0b110` | `0b111`
| Resulting `clock_prescaler` |       2 |       4 |       8 |      64 |     128 |    1024 |    2048 |    4096
|=======================

_**Baud rate**_ = (_f~main~[Hz]_ / `clock_prescaler`) / (`baud_prsc` + 1)

A new transmission is started by writing the data byte to be send to the lowest byte of the `DATA` register. The
transfer is completed when the _UART_CTRL_TX_BUSY_ control register flag returns to zero. A new received byte
is available when the _UART_DATA_AVAIL_ flag of the `DATA` register is set. A "frame error" in a received byte
(invalid stop bit) is indicated via the _UART_DATA_FERR_ flag in the `DATA` register. The flag is cleared by
reading the `DATA` register.

[TIP]
A transmission (RX or TX) can be terminated at any time by disabling the UART module
by clearing the _UART_CTRL_EN_ control register bit.


**RX and TX FIFOs**

UART0 provides optional FIFO buffers for the transmitter and the receiver. The _UART0_RX_FIFO_ generic defines
the depth of the RX FIFO (for receiving data) while the _UART0_TX_FIFO_ defines the depth of the TX FIFO
(for sending data). Both generics have to be a power of two with a minimal allowed value of 1. This minimal
value will implement simple "double-buffering" instead of full-featured FIFOs.
Both FIFOs are cleared whenever UART0 is disabled (clearing _UART_CTRL_EN_ in `CTRL`).

The state of both FIFO (_empty_, _at lest half-full_, _full_) is available via the _UART_CTRL_?X_EMPTY_,
 _UART_CTRL_?X_HALF_ and _UART_CTRL_*X_FULL_ flags in the `CTRL` register.

If the RX FIFO is already full and new data is received by the receiver unit, the _UART_DATA_OVERR_ flag
in the `DATA` register is set indicating an "overrun". This flag is cleared by reading the `DATA` register.

[NOTE]
In contrast to other FIFO-equipped peripherals, software **cannot** determine the UART's FIFO size configuration
by reading specific control register bits (simply because there are no bits left in the control register).


**Hardware Flow Control - RTS/CTS**

UART0 supports optional hardware flow control using the standard CTS (clear to send) and/or RTS (ready to send
/ ready to receive "RTR") signals. Both hardware control flow mechanisms can be enabled individually.

* If **RTS hardware flow control** is enabled by setting the _UART_CTRL_RTS_EN_ control register flag, the UART
will pull the `uart0_rts_o` signal low if the UART's receiver is ready to receive new data.
As long as this signal is low the connected device can send new data. `uart0_rts_o` is always LOW if the UART is disabled.
The RTS line is de-asserted (going high) as soon as the start bit of a new incoming char has been
detected.

* If **CTS hardware flow control** is enabled by setting the _UART_CTRL_CTS_EN_ control register flag, the UART's
transmitter will not start sending a new data until the `uart0_cts_i` signal goes low. During this time, the UART busy flag
_UART_CTRL_TX_BUSY_ remains set. If `uart0_cts_i` is asserted, no new data transmission will be started by the UART.
The state of the `uart0_cts_i` signal has no effect on a transmission being already in progress. Application software can check
the current state of the `uart0_cts_o` input signal via the _UART_CTRL_CTS_ control register flag.


**Parity Modes**

An optional parity bit can be added to the data stream if the _UART_CTRL_PMODE1_ flag is set.
When _UART_CTRL_PMODE0_ is zero, the UART operates in "even parity" mode. If this flag is set, the UART operates in "odd parity" mode.
Parity errors in received data are indicated via the _UART_DATA_PERR_ flag in the `DATA` register. This flag is updated with each new
received character and is cleared by reading the `DATA` register.


**UART Interrupts**

UART0 features two independent interrupt for signaling certain RX and TX conditions. The behavior of these conditions differs
based on the configured FIFO sizes. If the according FIFO size is greater than 1, the _UART_CTRL_RX_IRQ_ and _UART_CTRL_TX_IRQ_
`CTRL` flags allow a more fine-grained IRQ configuration. An interrupt can only become pending if the according interrupt
condition is fulfilled and the UART is enabled at all.

* If _UART0_RX_FIFO_ is exactly 1, the RX interrupt goes pending when data _becomes_ available in the RX FIFO
(-> _UART_CTRL_RX_EMPTY_ clears). _UART_CTRL_RX_IRQ_ is hardwired to `0` in this case.
* If _UART0_TX_FIFO_ is exactly 1, the TX interrupt goes pending when at least one entry in the TX FIFO _becomes_ free
(-> _UART_CTRL_TX_FULL_ clears). _UART_CTRL_TX_IRQ_ is hardwired to `0` in this case.

* If _UART0_RX_FIFO_ is greater than 1: If _UART_CTRL_RX_IRQ_ is `0` the RX interrupt goes pending when data _becomes_
available in the RX FIFO (-> _UART_CTRL_RX_EMPTY_ clears). If _UART_CTRL_RX_IRQ_ is `1` the RX interrupt becomes pending
the RX FIFO _becomes_ at least half-full (-> _UART_CTRL_RX_HALF_ sets).
* If _UART0_TX_FIFO_ is greater than 1: If _UART_CTRL_TX_IRQ_ is `0` the TX interrupt goes pending when at least one entry
in the TX FIFO _becomes_ free (-> _UART_CTRL_TX_FULL_ clears). If _UART_CTRL_TX_IRQ_ is `1` the TX interrupt goes pending
when the RX FIFO _becomes_ less than half-full (-> _UART_CTRL_TX_HALF_ clears).

Once the RX or TX interrupt has become pending, it has to be explicitly cleared again by
writing zero to the according <<_mip>> CSR bit.


**Simulation Mode**

The default UART0 operation will transmit any data written to the `DATA` register via the serial TX line at
the defined baud rate via the physical link. To accelerate UART0 output during simulation
(and also to dump large amounts of data) the UART0 features a _simulation mode_.

Simulation mode is enabled by setting the _UART_CTRL_SIM_MODE_ bit in the UART0's control register
`CTRL`. Any other UART0 configuration bits are irrelevant for this mode but UART0 has to be enabled via the
_UART_CTRL_EN_ bit. There will be no physical UART0 transmissions via `uart0_txd_o` at all when
simulation mode is enabled. Furthermore, no interrupts (RX & TX) will be triggered.

When the simulation mode is enabled any data written to `DATA[7:0]` is
directly output as ASCII char to the simulator console. Additionally, all chars are also stored to a text file
`neorv32.uart0.sim_mode.text.out` in the simulation home folder.

Furthermore, the whole 32-bit word written to `DATA[31:0]` is stored as plain 8-char hexadecimal value to a
second text file `neorv32.uart0.sim_mode.data.out` also located in the simulation home folder.

[TIP]
More information regarding the simulation-mode of the UART0 can be found in the User Guide
section https://stnolting.github.io/neorv32/ug/#_simulating_the_processor[Simulating the Processor].


.UART0 register map (`struct NEORV32_UART0`)
[cols="<6,<7,<10,^2,<18"]
[options="header",grid="all"]
|=======================
| Address | Name [C] | Bit(s), Name [C] | R/W | Function
.21+<| `0xffffffa0` .21+<| `NEORV32_UART0.CTRL` <|`11:0` _UART_CTRL_BAUDxx_ ^| r/w <| 12-bit BAUD value configuration value
                                                <|`12` _UART_CTRL_SIM_MODE_ ^| r/w <| enable **simulation mode**
                                                <|`13` _UART_CTRL_RX_EMPTY_ ^| r/- <| RX FIFO is empty
                                                <|`14` _UART_CTRL_RX_HALF_  ^| r/- <| RX FIFO is at least half-full
                                                <|`15` _UART_CTRL_RX_FULL_  ^| r/- <| RX FIFO is full
                                                <|`16` _UART_CTRL_TX_EMPTY_ ^| r/- <| TX FIFO is empty
                                                <|`17` _UART_CTRL_TX_HALF_  ^| r/- <| TX FIFO is at least half-full
                                                <|`18` _UART_CTRL_TX_FULL_  ^| r/- <| TX FIFO is full
                                                <|`19` -                    ^| r/- <| _reserved_, read as zero
                                                <|`20` _UART_CTRL_RTS_EN_   ^| r/w <| enable RTS hardware flow control
                                                <|`21` _UART_CTRL_CTS_EN_   ^| r/w <| enable CTS hardware flow control
                                                <|`22` _UART_CTRL_PMODE0_   ^| r/w .2+<| parity bit enable and configuration (`00`/`01`= no parity; `10`=even parity; `11`=odd parity)
                                                <|`23` _UART_CTRL_PMODE1_   ^| r/w 
                                                <|`24` _UART_CTRL_PRSC0_    ^| r/w .3+<| 3-bit baudrate clock prescaler select
                                                <|`25` _UART_CTRL_PRSC1_    ^| r/w 
                                                <|`26` _UART_CTRL_PRSC2_    ^| r/w 
                                                <|`27` _UART_CTRL_CTS_      ^| r/- <| current state of UART's CTS input signal
                                                <|`28` _UART_CTRL_EN_       ^| r/w <| UART enable
                                                <|`29` _UART_CTRL_RX_IRQ_   ^| r/w <| RX IRQ mode: `1`=FIFO at least half-full; `0`=FIFO not empty
                                                <|`30` _UART_CTRL_TX_IRQ_   ^| r/w <| TX IRQ mode: `1`=FIFO less than half-full; `0`=FIFO not full
                                                <|`31` _UART_CTRL_TX_BUSY_  ^| r/- <| transmitter busy flag
.6+<| `0xffffffa4` .6+<| `NEORV32_UART0.DATA` <|`7:0` _UART_DATA_MSB_ : _UART_DATA_LSB_ ^| r/w <| receive/transmit data (8-bit)
                                              <|`31:0` -                ^| -/w <| **simulation data output**
                                              <|`28` _UART_DATA_PERR_   ^| r/- <| RX parity error
                                              <|`29` _UART_DATA_FERR_   ^| r/- <| RX data frame error (stop bit nt set)
                                              <|`30` _UART_DATA_OVERR_  ^| r/- <| RX data overrun
                                              <|`31` _UART_DATA_AVAIL_  ^| r/- <| RX data available when set
|=======================



<<<
// ####################################################################################################################
:sectnums:
==== Secondary Universal Asynchronous Receiver and Transmitter (UART1)

[cols="<3,<3,<4"]
[frame="topbot",grid="none"]
|=======================
| Hardware source file(s): | neorv32_uart.vhd | 
| Software driver file(s): | neorv32_uart.c |
|                          | neorv32_uart.h |
| Top entity port:         | `uart1_txd_o` | serial transmitter output UART1
|                          | `uart1_rxd_i` | serial receiver input UART1
|                          | `uart1_rts_o` | flow control: RX ready to receive
|                          | `uart1_cts_i` | flow control: TX allowed to send
| Configuration generics:  | _IO_UART1_EN_   | implement UART1 when _true_
|                          | _UART1_RX_FIFO_ | RX FIFO depth (power of 2, min 1)
|                          | _UART1_TX_FIFO_ | TX FIFO depth (power of 2, min 1)
| CPU interrupts:          | fast IRQ channel 4 | RX interrupt
|                          | fast IRQ channel 5 | TX interrupt (see <<_processor_interrupts>>)
|=======================


**Theory of Operation**

The secondary UART (UART1) is functional identical to the primary UART (<<_primary_universal_asynchronous_receiver_and_transmitter_uart0>>).
Obviously, UART1 has different addresses for the control register (`CTRL`) and the data register (`DATA`) - see the register map below.
The register's bits/flags use the same bit positions and naming as for the primary UART. The RX and TX interrupts of UART1 are
mapped to different CPU fast interrupt (FIRQ) channels.


**Simulation Mode**

The secondary UART (UART1) provides the same simulation options as the primary UART. However,
output data is written to UART1-specific files: `neorv32.uart1.sim_mode.text.out` is used to store
plain ASCII text and `neorv32.uart1.sim_mode.data.out` is used to store full 32-bit hexadecimal
data words.


.UART1 register map (`struct NEORV32_UART1`)
[cols="<6,<7,<10,^2,<18"]
[options="header",grid="all"]
|=======================
| Address | Name [C] | Bit(s), Name [C] | R/W | Function
.21+<| `0xffffffd0` .21+<| `NEORV32_UART1.CTRL` <|`11:0` _UART_CTRL_BAUDxx_ ^| r/w <| 12-bit BAUD value configuration value
                                                <|`12` _UART_CTRL_SIM_MODE_ ^| r/w <| enable **simulation mode**
                                                <|`13` _UART_CTRL_RX_EMPTY_ ^| r/- <| RX FIFO is empty
                                                <|`14` _UART_CTRL_RX_HALF_  ^| r/- <| RX FIFO is at least half-full
                                                <|`15` _UART_CTRL_RX_FULL_  ^| r/- <| RX FIFO is full
                                                <|`16` _UART_CTRL_TX_EMPTY_ ^| r/- <| TX FIFO is empty
                                                <|`17` _UART_CTRL_TX_HALF_  ^| r/- <| TX FIFO is at least half-full
                                                <|`18` _UART_CTRL_TX_FULL_  ^| r/- <| TX FIFO is full
                                                <|`19` -                    ^| r/- <| _reserved_, read as zero
                                                <|`20` _UART_CTRL_RTS_EN_   ^| r/w <| enable RTS hardware flow control
                                                <|`21` _UART_CTRL_CTS_EN_   ^| r/w <| enable CTS hardware flow control
                                                <|`22` _UART_CTRL_PMODE0_   ^| r/w .2+<| parity bit enable and configuration (`00`/`01`= no parity; `10`=even parity; `11`=odd parity)
                                                <|`23` _UART_CTRL_PMODE1_   ^| r/w 
                                                <|`24` _UART_CTRL_PRSC0_    ^| r/w .3+<| 3-bit baudrate clock prescaler select
                                                <|`25` _UART_CTRL_PRSC1_    ^| r/w 
                                                <|`26` _UART_CTRL_PRSC2_    ^| r/w 
                                                <|`27` _UART_CTRL_CTS_      ^| r/- <| current state of UART's CTS input signal
                                                <|`28` _UART_CTRL_EN_       ^| r/w <| UART enable
                                                <|`29` _UART_CTRL_RX_IRQ_   ^| r/w <| RX IRQ mode: `1`=FIFO at least half-full; `0`=FIFO not empty; hardwired to zero if _UART0_RX_FIFO_ = 1
                                                <|`30` _UART_CTRL_TX_IRQ_   ^| r/w <| TX IRQ mode: `1`=FIFO less than half-full; `0`=FIFO not full; hardwired to zero if _UART0_TX_FIFO_ = 1
                                                <|`31` _UART_CTRL_TX_BUSY_  ^| r/- <| transmitter busy flag
.6+<| `0xffffffd4` .6+<| `NEORV32_UART1.DATA` <|`7:0` _UART_DATA_MSB_ : _UART_DATA_LSB_ ^| r/w <| receive/transmit data (8-bit)
                                              <|`31:0` -                ^| -/w <| **simulation data output**
                                              <|`28` _UART_DATA_PERR_   ^| r/- <| RX parity error
                                              <|`29` _UART_DATA_FERR_   ^| r/- <| RX data frame error (stop bit nt set)
                                              <|`30` _UART_DATA_OVERR_  ^| r/- <| RX data overrun
                                              <|`31` _UART_DATA_AVAIL_  ^| r/- <| RX data available when set
|=======================