ns16550a

https://docs.rs/ns16550a/
Admin
ns16550a is a no_std Rust driver for the NS16550A UART peripheral, commonly used in embedded systems...
Tokens:9,285
Snippets:126
Trust Score:9.1
Update:1 month ago
Show doc for...
Tokens:
Raw
### Usage example for ns16550a UART driver

Source: https://docs.rs/ns16550a/latest/ns16550a/index.html

Shows how to create a UART instance, configure it, initialize with a baud rate, and perform data transmission and reception. Uses the Uart::new, init, put, get methods and the fmt::Write trait.

```rust
use ns16550a::{Uart, UartConfig, WordLength, StopBits, ParityBit, ParitySelect, StickParity, Break, DMAMode, Divisor};
use core::fmt::Write;

// Create a UART instance at base address 0x10000000
let mut uart = Uart::new(0x10000000);

// Configure UART settings
let config = UartConfig {
    word_length: WordLength::EIGHT,
    stop_bits: StopBits::ONE,
    parity_bit: ParityBit::DISABLE,
    parity_select: ParitySelect::EVEN,
    stick_parity: StickParity::DISABLE,
    break_: Break::DISABLE,
    dma_mode: DMAMode::MODE0,
};

// Initialize UART with 1200 baud rate
uart.init(config, Divisor::BAUD1200);

// Write data
uart.put(b'A');

// Write using fmt::Write trait
writeln!(&mut uart, "Hello, world!").unwrap();

// Read data
if let Some(byte) = uart.get() {
    // Process received byte
}
```

--------------------------------

### Initialize UartConfig

Source: https://docs.rs/ns16550a/latest/ns16550a/struct.UartConfig.html

An example demonstrating how to instantiate the UartConfig struct with specific parameters.

```rust
use ns16550a::{UartConfig, WordLength, StopBits, ParityBit, ParitySelect, StickParity, Break, DMAMode};

let config = UartConfig {
    word_length: WordLength::EIGHT,
    stop_bits: StopBits::ONE,
    parity_bit: ParityBit::DISABLE,
    parity_select: ParitySelect::EVEN,
    stick_parity: StickParity::DISABLE,
    break_: Break::DISABLE,
    dma_mode: DMAMode::MODE0,
};
```

--------------------------------

### Example: Creating a LineControlConfig

Source: https://docs.rs/ns16550a/latest/ns16550a/struct.LineControlConfig.html

Example usage of LineControlConfig, showing how to instantiate it with typical values. This config is used with Uart::set_lcr() or internally by Uart::init().

```rust
use ns16550a::{LineControlConfig, WordLength, StopBits, ParityBit, ParitySelect, StickParity, Break, DLAB};

let config = LineControlConfig {
    word_length: WordLength::EIGHT,
    stop_bits: StopBits::ONE,
    parity_bit: ParityBit::DISABLE,
    parity_select: ParitySelect::EVEN,
    stick_parity: StickParity::DISABLE,
    break_: Break::DISABLE,
    dlab: DLAB::CLEAR,
};
```

--------------------------------

### Get base address with Uart::base_address

Source: https://docs.rs/ns16550a/latest/ns16550a/struct.Uart.html

Returns the memory-mapped base address of the UART peripheral. The example creates a Uart and asserts the returned address matches the input.

```rust
let uart = Uart::new(0x10000000);
assert_eq!(uart.base_address(), 0x10000000);
```

--------------------------------

### Initialize UART with Uart::init

Source: https://docs.rs/ns16550a/latest/ns16550a/struct.Uart.html

Configures the UART with a UartConfig and a baud rate divisor. Sets up line control, FIFO control, and baud rate registers. The example uses UartConfig::default() and Divisor::BAUD115200.

```rust
use ns16550a::{Uart, UartConfig, WordLength, StopBits, ParityBit, ParitySelect, StickParity, Break, DMAMode, Divisor};

let uart = Uart::new(0x10000000);
let config = UartConfig::default();
uart.init(config, Divisor::BAUD115200);
```

--------------------------------

### Receive a byte with Uart::get

Source: https://docs.rs/ns16550a/latest/ns16550a/struct.Uart.html

Reads a byte from the receiver buffer register. Returns Some(byte) if data is available, or None if no data is ready. The example checks the result with if let.

```rust
use ns16550a::Uart;

let uart = Uart::new(0x10000000);
if let Some(byte) = uart.get() {
    // Byte was read
}
```

--------------------------------

### Set line control register with Uart::set_lcr

Source: https://docs.rs/ns16550a/latest/ns16550a/struct.Uart.html

Writes a LineControlConfig to the Line Control Register (LCR). The example constructs a LineControlConfig with explicit fields and calls set_lcr.

```rust
use ns16550a::{Uart, LineControlConfig, WordLength, StopBits, ParityBit, ParitySelect, StickParity, Break, DLAB};

let uart = Uart::new(0x10000000);
let config = LineControlConfig {
    word_length: WordLength::EIGHT,
    stop_bits: StopBits::ONE,
    parity_bit: ParityBit::DISABLE,
    parity_select: ParitySelect::EVEN,
    stick_parity: StickParity::DISABLE,
    break_: Break::DISABLE,
    dlab: DLAB::CLEAR,
};
uart.set_lcr(config);
```

--------------------------------

### Transmit a byte with Uart::put

Source: https://docs.rs/ns16550a/latest/ns16550a/struct.Uart.html

Writes a byte to the transmitter holding register. Returns Some(c) if the byte was written, or None if the transmitter is busy. The example checks the result with if let.

```rust
use ns16550a::Uart;

let uart = Uart::new(0x10000000);
if let Some(byte) = uart.put(b'A') {
    // Byte was written
}
```

--------------------------------

### Set FIFO control register with Uart::set_fcr

Source: https://docs.rs/ns16550a/latest/ns16550a/struct.Uart.html

Configures the FIFO Control Register (FCR) with a DMA mode and enables FIFO mode. The example uses DMAMode::MODE0.

```rust
use ns16550a::{Uart, DMAMode};

let uart = Uart::new(0x10000000);
uart.set_fcr(DMAMode::MODE0);
```

--------------------------------

### Uart::init

Source: https://docs.rs/ns16550a/latest/ns16550a/index.html

Initializes the UART with the given configuration and baud rate divisor.

```APIDOC
## Uart::init

### Description
Initializes the UART peripheral with the provided configuration and baud rate divisor.

### Method
init

### Signature
`pub fn init(&mut self, config: UartConfig, divisor: Divisor)`

### Parameters
- **config** (UartConfig) - Required - The UART configuration settings.
- **divisor** (Divisor) - Required - The divisor for setting the baud rate.

```

--------------------------------

### Uart::new

Source: https://docs.rs/ns16550a/latest/ns16550a/index.html

Creates a new UART instance at the given base address.

```APIDOC
## Uart::new

### Description
Creates a new UART instance at the specified base address.

### Method
new

### Signature
`pub fn new(base_address: usize) -> Self`

### Parameters
- **base_address** (usize) - Required - The base address of the UART peripheral.

### Returns
- **Uart** - A new UART instance.

```

--------------------------------

### UartConfig

Source: https://docs.rs/ns16550a/latest/ns16550a/struct.UartConfig.html

Configuration for UART initialization. Contains all parameters needed to initialize a UART peripheral. Use with Uart::init().

```APIDOC
## UartConfig

### Description
Configuration for UART initialization. This struct contains all the parameters needed to initialize a UART peripheral. Use this with the `Uart::init()` method to configure the UART.

### Fields
- **word_length** (WordLength) - Data word length (5-8 bits)
- **stop_bits** (StopBits) - Number of stop bits (1 or 2)
- **parity_bit** (ParityBit) - Parity bit enable/disable
- **parity_select** (ParitySelect) - Parity type (even or odd)
- **stick_parity** (StickParity) - Stick parity mode
- **break_** (Break) - Break signal control
- **dma_mode** (DMAMode) - DMA mode selection

### Example
```rust
use ns16550a::{UartConfig, WordLength, StopBits, ParityBit, ParitySelect, StickParity, Break, DMAMode};

let config = UartConfig {
    word_length: WordLength::EIGHT,
    stop_bits: StopBits::ONE,
    parity_bit: ParityBit::DISABLE,
    parity_select: ParitySelect::EVEN,
    stick_parity: StickParity::DISABLE,
    break_: Break::DISABLE,
    dma_mode: DMAMode::MODE0,
};
```

### Trait Implementations
- **Clone**: Provides `clone` and `clone_from` methods.
- **Copy**: Allows copying the struct.
- **Debug**: Provides formatting for debugging.
- **Default**: Provides a default value.

### Auto Trait Implementations
- Freeze
- RefUnwindSafe
- Send
- Sync
- Unpin
- UnsafeUnpin
- UnwindSafe

### Blanket Implementations
- Any, Borrow, BorrowMut, CloneToUninit, From, Into, TryFrom, TryInto

```

--------------------------------

### Create a new Uart instance with Uart::new

Source: https://docs.rs/ns16550a/latest/ns16550a/struct.Uart.html

Creates a Uart instance with a given memory-mapped base address. The constructor is a const fn, allowing compile-time instantiation.

```rust
let uart = Uart::new(0x10000000);
```

--------------------------------

### fmt::Write for Uart

Source: https://docs.rs/ns16550a/latest/ns16550a

Implements the fmt::Write trait for Uart, allowing formatted output.

```APIDOC
## fmt::Write for Uart

### Description
Allows using the Uart with the standard formatting macros like writeln!.

### Method
Trait Implementation

### Example
```rust
writeln!(&mut uart, "Hello, world!").unwrap();
```
```

--------------------------------

### Write for Uart

Source: https://docs.rs/ns16550a/latest/src/ns16550a/lib.rs.html

Implements the Write trait for Uart, allowing writing a string to the UART transmitter. This method writes each byte of the string, blocking until the transmitter is ready.

```APIDOC
## Write for Uart

### Description
Implements the Write trait for Uart, allowing writing a string to the UART transmitter. This method writes each byte of the string, blocking until the transmitter is ready.

### Method
fn write_str(&mut self, s: &str) -> Result

### Parameters
- **s** (&str) - Required - String to write

### Returns
- **Result** - Ok(()) on success

### Example
```rust
use std::fmt::Write;
use ns16550a::Uart;

let mut uart = Uart::new(0x10000000);
write!(uart, "Hello").unwrap();
```
```

--------------------------------

### UartConfig struct definition

Source: https://docs.rs/ns16550a/latest/ns16550a/struct.UartConfig.html

The definition of the UartConfig struct showing all available configuration fields.

```rust
pub struct UartConfig {
    pub word_length: WordLength,
    pub stop_bits: StopBits,
    pub parity_bit: ParityBit,
    pub parity_select: ParitySelect,
    pub stick_parity: StickParity,
    pub break_: Break,
    pub dma_mode: DMAMode,
}
```

--------------------------------

### DMAMode

Source: https://docs.rs/ns16550a/latest/src/ns16550a/lib.rs.html

Enum for DMA mode selection.

```APIDOC
## DMAMode

### Description
Enum representing DMA mode selection.

### Variants
- **MODE0** - DMA mode 0
- **MODE1** - DMA mode 1
```

--------------------------------

### Uart::get

Source: https://docs.rs/ns16550a/latest/ns16550a/index.html

Reads a single byte from the UART if available.

```APIDOC
## Uart::get

### Description
Receives a single byte from the UART if one is available.

### Method
get

### Signature
`pub fn get(&mut self) -> Option<u8>`

### Returns
- **Option<u8>** - The received byte, or `None` if no data is available.

```

--------------------------------

### Uart::base_address

Source: https://docs.rs/ns16550a/latest/ns16550a/struct.Uart.html

Returns the base address of the UART peripheral.

```APIDOC
## Uart::base_address

### Description
Returns the base address of the UART peripheral.

### Method
`pub const fn base_address(&self) -> usize`

### Returns
The memory-mapped base address.

### Example
```rust
let uart = Uart::new(0x10000000);
assert_eq!(uart.base_address(), 0x10000000);
```
```

--------------------------------

### LineControlConfig struct definition

Source: https://docs.rs/ns16550a/latest/ns16550a/struct.LineControlConfig.html

The struct definition for LineControlConfig, showing all public fields: word_length, stop_bits, parity_bit, parity_select, stick_parity, break_, and dlab.

```rust
pub struct LineControlConfig {
    pub word_length: WordLength,
    pub stop_bits: StopBits,
    pub parity_bit: ParityBit,
    pub parity_select: ParitySelect,
    pub stick_parity: StickParity,
    pub break_: Break,
    pub dlab: DLAB,
}
```

--------------------------------

### Break

Source: https://docs.rs/ns16550a/latest/src/ns16550a/lib.rs.html

Enum for break signal control.

```APIDOC
## Break

### Description
Enum representing break signal control.

### Variants
- **DISABLE** - Break signal disabled (normal operation)
- **ENABLE** - Break signal enabled (continuous low signal)
```

--------------------------------

### StickParity Enum

Source: https://docs.rs/ns16550a/latest/ns16550a/enum.StickParity.html

Enum representing stick parity configuration with variants DISABLE and ENABLE.

```APIDOC
## Enum StickParity

### Description
Stick parity configuration for UART. It has two variants: DISABLE (stick parity disabled) and ENABLE (stick parity enabled, parity bit is fixed).

### Variants
- **DISABLE** = 0 - Stick parity disabled
- **ENABLE** = 1 - Stick parity enabled (parity bit is fixed)

### Trait Implementations
- Clone
- Copy
- Debug
- Eq
- PartialEq
- StructuralPartialEq

### Auto Traits
- Freeze
- RefUnwindSafe
- Send
- Sync
- Unpin
- UnsafeUnpin
- UnwindSafe

### Blanket Implementations
- Any
- Borrow
- BorrowMut
- CloneToUninit
- From
- Into
- TryFrom
- TryInto
```

--------------------------------

### ParitySelect

Source: https://docs.rs/ns16550a/latest/src/ns16550a/lib.rs.html

Enum for selecting even or odd parity.

```APIDOC
## ParitySelect

### Description
Enum representing parity type selection.

### Variants
- **EVEN** - Even parity
- **ODD** - Odd parity
```

--------------------------------

### Uart::get

Source: https://docs.rs/ns16550a/latest/ns16550a/struct.Uart.html

Reads a byte from the receiver buffer register.

```APIDOC
## Uart::get

### Description
Reads a byte from the receiver buffer register. This method checks if data is available in the receiver buffer. If data is ready, it reads and returns the byte as `Some(byte)`. If no data is available, it returns `None`.

### Method
`pub fn get(&self) -> Option<u8>`

### Returns
- `Some(byte)` if data was successfully read
- `None` if no data is available

### Example
```rust
use ns16550a::Uart;

let uart = Uart::new(0x10000000);
if let Some(byte) = uart.get() {
    // Byte was read
}
```
```

--------------------------------

### Uart::put

Source: https://docs.rs/ns16550a/latest/ns16550a/struct.Uart.html

Writes a byte to the transmitter holding register.

```APIDOC
## Uart::put

### Description
Writes a byte to the transmitter holding register. This method attempts to write a byte to the UART transmitter. If the transmitter holding register is empty, it writes the byte and returns `Some(c)`. If the transmitter is busy, it returns `None`.

### Method
`pub fn put(&self, c: u8) -> Option<u8>`

### Parameters
- **c** (u8) - Required - Byte to transmit

### Returns
- `Some(c)` if the byte was successfully written
- `None` if the transmitter is busy

### Example
```rust
use ns16550a::Uart;

let uart = Uart::new(0x10000000);
if let Some(byte) = uart.put(b'A') {
    // Byte was written
}
```
```

--------------------------------

### Uart::put

Source: https://docs.rs/ns16550a/latest/ns16550a/index.html

Writes a single byte to the UART.

```APIDOC
## Uart::put

### Description
Transmits a single byte over the UART.

### Method
put

### Signature
`pub fn put(&mut self, data: u8)`

### Parameters
- **data** (u8) - Required - The byte to transmit.

```

--------------------------------

### Uart::set_lcr

Source: https://docs.rs/ns16550a/latest/ns16550a/struct.Uart.html

Sets the line control register with the given configuration.

```APIDOC
## Uart::set_lcr

### Description
Sets the line control register with the given configuration. This method directly writes to the Line Control Register (LCR) with the provided parameters.

### Method
`pub fn set_lcr(&self, config: LineControlConfig)`

### Parameters
- **config** (LineControlConfig) - Required - Line control configuration struct

### Example
```rust
use ns16550a::{Uart, LineControlConfig, WordLength, StopBits, ParityBit, ParitySelect, StickParity, Break, DLAB};

let uart = Uart::new(0x10000000);
let config = LineControlConfig {
    word_length: WordLength::EIGHT,
    stop_bits: StopBits::ONE,
    parity_bit: ParityBit::DISABLE,
    parity_select: ParitySelect::EVEN,
    stick_parity: StickParity::DISABLE,
    break_: Break::DISABLE,
    dlab: DLAB::CLEAR,
};
uart.set_lcr(config);
```
```

--------------------------------

### Uart::get

Source: https://docs.rs/ns16550a/latest/src/ns16550a/lib.rs.html

Reads a byte from the receiver buffer register. This method checks if data is available in the receiver buffer. If data is ready, it reads and returns the byte as Some(byte). If no data is available, it returns None.

```APIDOC
## Uart::get

### Description
Reads a byte from the receiver buffer register. This method checks if data is available in the receiver buffer. If data is ready, it reads and returns the byte as Some(byte). If no data is available, it returns None.

### Method
pub fn get(&self) -> Option<u8>

### Returns
- **Some(byte)** if data was successfully read
- **None** if no data is available

### Example
```rust
use ns16550a::Uart;

let uart = Uart::new(0x10000000);
if let Some(byte) = uart.get() {
    // Byte was read
}
```
```

--------------------------------

### Uart::set_fcr

Source: https://docs.rs/ns16550a/latest/ns16550a/struct.Uart.html

Sets the FIFO control register with the given DMA mode.

```APIDOC
## Uart::set_fcr

### Description
Sets the FIFO control register with the given DMA mode. This method configures the FIFO Control Register (FCR) and enables FIFO mode.

### Method
`pub fn set_fcr(&self, dma_mode: DMAMode)`

### Parameters
- **dma_mode** (DMAMode) - Required - DMA mode selection (MODE0 or MODE1)

### Example
```rust
use ns16550a::{Uart, DMAMode};

let uart = Uart::new(0x10000000);
uart.set_fcr(DMAMode::MODE0);
```
```

--------------------------------

### Enum Divisor

Source: https://docs.rs/ns16550a/latest/ns16550a/enum.Divisor.html

Documentation for the Divisor enum, which defines baud rate divisor values for the NS16550A UART.

```APIDOC
## Enum Divisor

### Description
Represents the divisor value for setting the baud rate on an NS16550A UART.

### Variants
- **BAUD50** = 2304 - 50 baud rate divisor
- **BAUD300** = 384 - 300 baud rate divisor
- **BAUD1200** = 96 - 1200 baud rate divisor
- **BAUD2400** = 48 - 2400 baud rate divisor
- **BAUD4800** = 24 - 4800 baud rate divisor
- **BAUD9600** = 12 - 9600 baud rate divisor
- **BAUD19200** = 6 - 19200 baud rate divisor
- **BAUD38400** = 3 - 38400 baud rate divisor
- **BAUD57600** = 2 - 57600 baud rate divisor
- **BAUD115200** = 1 - 115200 baud rate divisor

### Trait Implementations
- Clone
- Copy
- Debug
- Eq
- PartialEq
- StructuralPartialEq
```

--------------------------------

### DLAB

Source: https://docs.rs/ns16550a/latest/src/ns16550a/lib.rs.html

Enum for the Divisor Latch Access Bit.

```APIDOC
## DLAB

### Description
Enum representing the Divisor Latch Access Bit.

### Variants
- **CLEAR** - Normal operation mode (access to RBR/THR/IER)
- **SET** - Divisor latch mode (access to DLL/DLM)
```

--------------------------------

### WordLength enum definition

Source: https://docs.rs/ns16550a/latest/ns16550a/enum.WordLength.html

Defines the WordLength enum with variants for 5, 6, 7, and 8 data bits. EIGHT is the most common configuration.

```rust
pub enum WordLength {
    FIVE = 0,
    SIX = 1,
    SEVEN = 2,
    EIGHT = 3,
}
```

--------------------------------

### StopBits

Source: https://docs.rs/ns16550a/latest/src/ns16550a/lib.rs.html

Enum for the number of stop bits in UART communication.

```APIDOC
## StopBits

### Description
Enum representing the number of stop bits.

### Variants
- **ONE** - 1 stop bit (most common)
- **TWO** - 2 stop bits
```

--------------------------------

### WordLength Enum Definition

Source: https://docs.rs/ns16550a/latest/ns16550a/enum.WordLength.html

The WordLength enum defines the possible word length configurations for UART communication. Each variant corresponds to a specific number of data bits.

```APIDOC
## Enum WordLength

### Description
Word length configuration for UART communication.

### Variants
- **FIVE** = 0 - 5 data bits
- **SIX** = 1 - 6 data bits
- **SEVEN** = 2 - 7 data bits
- **EIGHT** = 3 - 8 data bits (most common)

### Trait Implementations
- **Clone** - Provides `clone` and `clone_from` methods.
- **Copy** - Allows copying the value.
- **Debug** - Provides `fmt` for formatting.
- **Eq** - Provides equality comparison.
- **PartialEq** - Provides `eq` and `ne` methods.

### Usage
This enum is used to configure the word length for UART communication. The default and most common setting is `EIGHT` (8 data bits).
```

--------------------------------

### StopBits Enum Definition

Source: https://docs.rs/ns16550a/latest/ns16550a/enum.StopBits.html

The StopBits enum defines the available configurations for UART stop bits, where ONE represents 1 stop bit and TWO represents 2 stop bits.

```rust
pub enum StopBits {
    ONE = 0,
    TWO = 1,
}
```

--------------------------------

### Divisor Enum Definition

Source: https://docs.rs/ns16550a/latest/ns16550a/enum.Divisor.html

The Divisor enum defines various baud rate settings as u16 values, ranging from 50 to 115200 baud.

```rust
#[repr(u16)]
pub enum Divisor {
    BAUD50 = 2_304,
    BAUD300 = 384,
    BAUD1200 = 96,
    BAUD2400 = 48,
    BAUD4800 = 24,
    BAUD9600 = 12,
    BAUD19200 = 6,
    BAUD38400 = 3,
    BAUD57600 = 2,
    BAUD115200 = 1,
}
```

--------------------------------

### ParityBit Enum

Source: https://docs.rs/ns16550a/latest/ns16550a/enum.ParityBit.html

The ParityBit enum represents the parity bit setting for UART communication. It has two variants: DISABLE (no parity bit) and ENABLE (parity bit enabled).

```APIDOC
## ParityBit Enum

### Description
The `ParityBit` enum represents the parity bit enable/disable setting for UART communication. It has two variants: `DISABLE` (no parity bit) and `ENABLE` (parity bit enabled).

### Variants
- **DISABLE** = 0 - No parity bit
- **ENABLE** = 1 - Parity bit enabled

### Trait Implementations
- `Clone` - Supports cloning.
- `Copy` - Supports copying.
- `Debug` - Supports formatting with `{:?}`.
- `Eq` - Supports equality comparisons.
- `PartialEq` - Supports partial equality comparisons.
- `StructuralPartialEq` - Supports structural equality.

### Usage
This enum is used to configure the parity bit in UART settings. Users can set the parity bit to either `DISABLE` or `ENABLE` as needed.

```

--------------------------------

### StopBits Enum Definition

Source: https://docs.rs/ns16550a/latest/ns16550a/enum.StopBits.html

Definition of the StopBits enum with variants ONE and TWO, representing 1 and 2 stop bits respectively.

```APIDOC
## StopBits Enum

### Description
Defines the number of stop bits for UART communication.

### Definition
```rust
pub enum StopBits {
    ONE = 0,
    TWO = 1,
}
```

### Variants
- **ONE** (= 0) - 1 stop bit (most common)
- **TWO** (= 1) - 2 stop bits

### Trait Implementations
- Clone
- Copy
- Debug
- Eq
- PartialEq
- StructuralPartialEq
```

--------------------------------

### StickParity enum definition

Source: https://docs.rs/ns16550a/latest/ns16550a/enum.StickParity.html

The StickParity enum determines stick parity behavior in ns16550a. When ENABLE, the parity bit is fixed. Variants have explicit discriminants 0 and 1.

```rust
pub enum StickParity {
    DISABLE = 0,
    ENABLE = 1,
}
```
Tokens:
Raw