Unit UART
Return to Unit Reference
Description
Ultibo UART Interface unit
UART (Universal Asynchronous Receiver Transmitter) devices represent the industry standard serial communications devices that are available on almost every system.
This unit implements the framework for UART devices and provides a standardized API to allow driver specific implementation to be abstracted. All UART devices are also represented as a serial device and this unit handles the relationship between the two devices.
Each UART device returns a set of properties that describe the capabilities of the device and includes a set of flags that indicate what features are supported.
Reads and writes to UART devices are unbuffered and simply pass raw data to and from the caller unless the serial interface is used instead which includes buffering of transmitted and received data. Both reads and writes allow for non blocking so that a caller can avoid waiting for received data to be available or the device to be ready to transmit.
Constants
UART_*
UART_NAME_PREFIX = 'UART';
|
Name prefix for UART Devices |
UART_PUSH_TIMEOUT = SERIAL_PUSH_TIMEOUT;
|
Timeout (Milliseconds) for Push RX/TX (Implementation specific) |
UART_TYPE_*
UART_TYPE_NONE = 0;
|
|
UART_TYPE_8250 = 1;
|
8250 UART and similar variants (Differences are handled by driver) |
UART_TYPE_16550 = 2;
|
16550 UART and similar variants (eg 16550A) (Differences are handled by driver) |
UART_TYPE_16650 = 3;
|
16650 UART and similar variants (eg 16C650) (Differences are handled by driver) |
UART_TYPE_MAX = 3;
|
UART_MODE_*
UART_MODE_NONE = 0;
|
|
UART_MODE_UART = 1;
|
The UART was opened as a UART device and all reads and writes are direct |
UART_MODE_SERIAL = 2;
|
The UART was opened as a Serial device so reads and writes are being buffered |
UART_MODE_MAX = 2;
|
UART_STATE_*
UART_STATE_DISABLED = 0;
|
|
UART_STATE_ENABLED = 1;
|
|
UART_STATE_MAX = 1;
|
UART_FLAG_*
UART_FLAG_NONE = SERIAL_FLAG_NONE;
|
|
UART_FLAG_DATA_8BIT = SERIAL_FLAG_DATA_8BIT;
|
Device supports 8 data bits |
UART_FLAG_DATA_7BIT = SERIAL_FLAG_DATA_7BIT;
|
Device supports 7 data bits |
UART_FLAG_DATA_6BIT = SERIAL_FLAG_DATA_6BIT;
|
Device supports 6 data bits |
UART_FLAG_DATA_5BIT = SERIAL_FLAG_DATA_5BIT;
|
Device supports 5 data bits |
UART_FLAG_STOP_1BIT = SERIAL_FLAG_STOP_1BIT;
|
Device supports 1 stop bit |
UART_FLAG_STOP_2BIT = SERIAL_FLAG_STOP_2BIT;
|
Device supports 2 stop bits |
UART_FLAG_STOP_1BIT5 = SERIAL_FLAG_STOP_1BIT5;
|
Device supports 1.5 stop bits |
UART_FLAG_PARITY_ODD = SERIAL_FLAG_PARITY_ODD;
|
Device supports odd parity |
UART_FLAG_PARITY_EVEN = SERIAL_FLAG_PARITY_EVEN;
|
Device supports even parity |
UART_FLAG_PARITY_MARK = SERIAL_FLAG_PARITY_MARK;
|
Device supports mark parity |
UART_FLAG_PARITY_SPACE = SERIAL_FLAG_PARITY_SPACE;
|
Device supports space parity |
UART_FLAG_FLOW_RTS_CTS = SERIAL_FLAG_FLOW_RTS_CTS;
|
Device supports RTS/CTS flow control |
UART_FLAG_FLOW_DSR_DTR = SERIAL_FLAG_FLOW_DSR_DTR;
|
Device supports DSR/DTR flow control |
UART_FLAG_PUSH_RX = SERIAL_FLAG_PUSH_RX;
|
Device requires pushed receive (Implementation specific) |
UART_FLAG_PUSH_TX = SERIAL_FLAG_PUSH_TX;
|
Device requires pushed transmit (Implementation specific) |
UART_READ_*
UART_READ_NONE = SERIAL_READ_NONE;
|
|
UART_READ_NON_BLOCK = SERIAL_READ_NON_BLOCK;
|
Do not block when receiving, if the FIFO is empty return immediately |
UART_WRITE_*
UART_WRITE_NONE = SERIAL_WRITE_NONE;
|
|
UART_WRITE_NON_BLOCK = SERIAL_WRITE_NON_BLOCK;
|
Do not block when transmitting, if the FIFO is full return immediately |
UART_WAIT_*
UART_WAIT_NONE = SERIAL_WAIT_NONE;
|
|
UART_WAIT_RECEIVE = SERIAL_WAIT_RECEIVE;
|
Wait for data to be available in the receive FIFO |
UART_WAIT_TRANSMIT = SERIAL_WAIT_TRANSMIT;
|
Wait for space to be available in the transmit FIFO |
UART_STATUS_*
UART_STATUS_NONE = SERIAL_STATUS_NONE;
|
|
UART_STATUS_RTS = SERIAL_STATUS_RTS;
|
|
UART_STATUS_CTS = SERIAL_STATUS_CTS;
|
|
UART_STATUS_DSR = SERIAL_STATUS_DSR;
|
|
UART_STATUS_DTR = SERIAL_STATUS_DTR;
|
|
UART_STATUS_RX_FULL = SERIAL_STATUS_RX_FULL;
|
|
UART_STATUS_RX_EMPTY = SERIAL_STATUS_RX_EMPTY;
|
|
UART_STATUS_TX_FULL = SERIAL_STATUS_TX_FULL;
|
|
UART_STATUS_TX_EMPTY = SERIAL_STATUS_TX_EMPTY;
|
|
UART_STATUS_BUSY = SERIAL_STATUS_BUSY;
|
|
UART_STATUS_BREAK_ERROR = SERIAL_STATUS_BREAK_ERROR;
|
|
UART_STATUS_PARITY_ERROR = SERIAL_STATUS_PARITY_ERROR;
|
|
UART_STATUS_FRAMING_ERROR = SERIAL_STATUS_FRAMING_ERROR;
|
|
UART_STATUS_OVERRUN_ERROR = SERIAL_STATUS_OVERRUN_ERROR;
|
|
UART_STATUS_DCD = SERIAL_STATUS_DCD;
|
|
UART_STATUS_RI = SERIAL_STATUS_RI;
|
UART_LOG_*
UART_LOG_LEVEL_DEBUG = LOG_LEVEL_DEBUG;
|
UART debugging messages |
UART_LOG_LEVEL_INFO = LOG_LEVEL_INFO;
|
UART informational messages, such as a device being attached or detached |
UART_LOG_LEVEL_WARN = LOG_LEVEL_WARN;
|
UART warning messages |
UART_LOG_LEVEL_ERROR = LOG_LEVEL_ERROR;
|
UART error messages |
UART_LOG_LEVEL_NONE = LOG_LEVEL_NONE;
|
No UART messages |
Type definitions
UART properties
PUARTProperties = ^TUARTProperties;
TUARTProperties = record
Flags:LongWord;
|
Device flags (eg UART_FLAG_DATA_8BIT) |
MinRate:LongWord;
|
Minimum supported baud rate |
MaxRate:LongWord;
|
Maximum supported baud rate |
BaudRate:LongWord;
|
Current baud rate setting |
DataBits:LongWord;
|
Current data bits setting |
StopBits:LongWord;
|
Current stop bits setting |
Parity:LongWord;
|
Current parity setting |
FlowControl:LongWord;
|
Current flow control setting |
UART enumeration callback
TUARTEnumerate = function(UART:PUARTDevice; Data:Pointer):LongWord;
|
UART notification callback
TUARTNotification = function(Device:PDevice; Data:Pointer; Notification:LongWord):LongWord;
|
UART device open
TUARTDeviceOpen = function(UART:PUARTDevice; BaudRate,DataBits,StopBits,Parity,FlowControl:LongWord):LongWord;
|
UART device close
TUARTDeviceClose = function(UART:PUARTDevice):LongWord;
|
UART device read
TUARTDeviceRead = function(UART:PUARTDevice; Buffer:Pointer; Size,Flags:LongWord; var Count:LongWord):LongWord;
|
UART device write
TUARTDeviceWrite = function(UART:PUARTDevice; Buffer:Pointer; Size,Flags:LongWord; var Count:LongWord):LongWord;
|
UART device wait
TUARTDeviceWait = function(UART:PUARTDevice; Direction,Timeout:LongWord):LongWord;
|
UART device get status
TUARTDeviceGetStatus = function(UART:PUARTDevice):LongWord;
|
UART device set status
TUARTDeviceSetStatus = function(UART:PUARTDevice; Status:LongWord):LongWord;
|
UART device get properties
TUARTDeviceGetProperties = function(UART:PUARTDevice; Properties:PUARTProperties):LongWord;
|
UART device set properties
TUARTDeviceSetProperties = function(UART:PUARTDevice; Properties:PUARTProperties):LongWord;
|
UART device
PUARTDevice = ^TUARTDevice;
TUARTDevice = record
Device Properties | |
Device:TDevice;
|
The Device entry for this UART |
UART Properties | |
UARTId:LongWord;
|
Unique Id of this UART in the UART table |
UARTMode:LongWord;
|
UART mode (eg UART_MODE_SERIAL) |
UARTState:LongWord;
|
UART state (eg UART_STATE_ENABLED) |
UARTStatus:LongWord;
|
UART status (eg UART_STATUS_RX_FULL)(May not be real time status depending on the driver) |
DeviceOpen:TUARTDeviceOpen;
|
A Device specific DeviceOpen method implementing the standard UART device interface (Mandatory) |
DeviceClose:TUARTDeviceClose;
|
A Device specific DeviceClose method implementing the standard UART device interface (Mandatory) |
DeviceRead:TUARTDeviceRead;
|
A Device specific DeviceRead method implementing the standard UART device interface (Mandatory) |
DeviceWrite:TUARTDeviceWrite;
|
A Device specific DeviceWrite method implementing the standard UART device interface (Mandatory) |
DeviceWait:TUARTDeviceWait;
|
A Device specific DeviceWait method implementing the standard UART device interface (Or nil if the default method is suitable) |
DeviceGetStatus:TUARTDeviceGetStatus;
|
A Device specific DeviceGetStatus method implementing the standard UART device interface (Or nil if the default method is suitable) |
DeviceSetStatus:TUARTDeviceSetStatus;
|
A Device specific DeviceSetStatus method implementing the standard UART device interface (Optional) |
DeviceGetProperties:TUARTDeviceGetProperties;
|
A Device specific DeviceGetProperties method implementing the standard UART device interface (Or nil if the default method is suitable) |
DeviceSetProperties:TUARTDeviceSetProperties;
|
A Device specific DeviceSetProperties method implementing the standard UART device interface (Or nil if the default method is suitable) |
Driver Properties | |
Lock:TMutexHandle;
|
Device lock |
ReceiveWait:TEventHandle;
|
Read wait event |
TransmitWait:TEventHandle;
|
Write wait event |
Properties:TUARTProperties;
|
Device properties |
Serial:PSerialDevice;
|
The Serial device represented by this UART |
Statistics Properties | |
ReceiveCount:LongWord;
|
|
ReceiveErrors:LongWord;
|
|
TransmitCount:LongWord;
|
|
TransmitErrors:LongWord;
|
|
Internal Properties | |
Prev:PUARTDevice;
|
Previous entry in UART table |
Next:PUARTDevice;
|
Next entry in UART table |
Public variables
UART logging
UART_DEFAULT_LOG_LEVEL:LongWord = UART_LOG_LEVEL_DEBUG;
|
Minimum level for UART messages. Only messages with level greater than or equal to this will be printed. |
UART_LOG_ENABLED:Boolean;
|
Function declarations
Initialization functions
procedure UARTInit;
Note | Called only during system startup |
---|
UART functions
function UARTDeviceOpen(UART:PUARTDevice; BaudRate,DataBits,StopBits,Parity,FlowControl:LongWord):LongWord;
UART | The UART device to open |
---|---|
BaudRate | Baud rate for the connection (eg 9600, 57600, 115200 etc) |
DataBits | Size of the data (eg SERIAL_DATA_8BIT) |
StopBits | Number of stop bits (eg SERIAL_STOP_1BIT) |
Parity | Parity type for the data (eg SERIAL_PARITY_NONE) |
FlowControl | Flow control for the connection (eg SERIAL_FLOW_NONE) |
Return | ERROR_SUCCESS if completed or another error code on failure |
function UARTDeviceClose(UART:PUARTDevice):LongWord;
UART | The UART device to close |
---|---|
Return | ERROR_SUCCESS if completed or another error code on failure |
function UARTDeviceRead(UART:PUARTDevice; Buffer:Pointer; Size,Flags:LongWord;var Count:LongWord):LongWord;
UART | The UART device to read from |
---|---|
Buffer | Pointer to a buffer to receive the data |
Size | The size of the buffer |
Flags | The flags to control reading (eg UART_READ_NON_BLOCK) |
Count | The number of bytes read on return |
Return | ERROR_SUCCESS if completed or another error code on failure |
function UARTDeviceWrite(UART:PUARTDevice; Buffer:Pointer; Size,Flags:LongWord;var Count:LongWord):LongWord;
UART | The UART device to write to |
---|---|
Buffer | Pointer to a buffer of data to transmit |
Size | The size of the buffer |
Flags | The flags to control writing (eg UART_WRITE_NON_BLOCK) |
Count | The number of bytes written on return |
Return | ERROR_SUCCESS if completed or another error code on failure |
function UARTDeviceWait(UART:PUARTDevice; Direction,Timeout:LongWord):LongWord;
UART | The UART device to wait for |
---|---|
Direction | The direction of data to wait for (eg UART_WAIT_RECEIVE) |
Timeout | The number of milliseconds to wait for data (INFINITE to wait forever) |
Return | ERROR_SUCCESS if completed or another error code on failure |
function UARTDeviceStatus(UART:PUARTDevice):LongWord; inline;
UART | The UART device to get the status from |
---|---|
Return | A set of flags containing the device status (eg UART_STATUS_RTS) |
Note | Replaced by UARTDeviceGetStatus for consistency |
function UARTDeviceGetStatus(UART:PUARTDevice):LongWord;
UART | The UART device to get the status from |
---|---|
Return | A set of flags containing the device status (eg UART_STATUS_RTS) |
function UARTDeviceSetStatus(UART:PUARTDevice;Status:LongWord):LongWord;
UART | The UART device to set the status for |
---|---|
Status | The device status flags to be set (eg UART_STATUS_RTS) |
Return | ERROR_SUCCESS if completed or another error code on failure |
Note | Not all UART_STATUS_* flags can be set, the device may ignore invalid values.
Not all UART devices support set status, returns ERROR_CALL_NOT_IMPLEMENTED if not supported. |
function UARTDeviceProperties(UART:PUARTDevice; Properties:PUARTProperties):LongWord; inline;
UART | The UART device to get properties from |
---|---|
Properties | Pointer to a PUARTProperties structure to fill in |
Return | ERROR_SUCCESS if completed or another error code on failure |
Note | Replaced by UARTDeviceGetProperties for consistency |
function UARTDeviceGetProperties(UART:PUARTDevice;Properties:PUARTProperties):LongWord;
UART | The UART device to get properties from |
---|---|
Properties | Pointer to a PUARTProperties structure to fill in |
Return | ERROR_SUCCESS if completed or another error code on failure |
function UARTDeviceSetProperties(UART:PUARTDevice; Properties:PUARTProperties):LongWord;
UART | The UART device to set properties for |
---|---|
Properties | Pointer to a PUARTProperties structure to use |
Return | ERROR_SUCCESS if completed or another error code on failure |
function UARTDeviceCreate:PUARTDevice;
Return | Pointer to new UART entry or nil if UART could not be created |
---|
function UARTDeviceCreateEx(Size:LongWord):PUARTDevice;
Size | Size in bytes to allocate for new UART (Including the UART entry) |
---|---|
Return | Pointer to new UART entry or nil if UART could not be created |
function UARTDeviceDestroy(UART:PUARTDevice):LongWord;
UART | The UART device to destroy |
---|---|
Return | ERROR_SUCCESS if completed or another error code on failure |
function UARTDeviceRegister(UART:PUARTDevice):LongWord;
UART | The UART device to register |
---|---|
Return | ERROR_SUCCESS if completed or another error code on failure |
function UARTDeviceDeregister(UART:PUARTDevice):LongWord;
UART | The UART device to deregister |
---|---|
Return | ERROR_SUCCESS if completed or another error code on failure |
function UARTDeviceFind(UARTId:LongWord):PUARTDevice;
UARTId | The Id number of the UART to find |
---|---|
Return | Pointer to UART device entry or nil if not found |
function UARTDeviceFindByName(const Name:String):PUARTDevice; inline;
Name | The name of the UART to find (eg UART0) |
---|---|
Return | Pointer to UART device entry or nil if not found |
function UARTDeviceFindByDescription(const Description:String):PUARTDevice; inline;
Description | The description of the UART to find (eg BCM2836 PL011 UART) |
---|---|
Return | Pointer to UART device entry or nil if not found |
function UARTDeviceEnumerate(Callback:TUARTEnumerate; Data:Pointer):LongWord;
Callback | The callback function to call for each UART in the table |
---|---|
Data | A private data pointer to pass to callback for each UART in the table |
Return | ERROR_SUCCESS if completed or another error code on failure |
function UARTDeviceNotification(UART:PUARTDevice; Callback:TUARTNotification; Data:Pointer; Notification,Flags:LongWord):LongWord;
UART | The UART device to notify changes for (Optional, pass nil for all UART devices) |
---|---|
Callback | The function to call when a notification event occurs |
Data | A private data pointer to pass to callback when a notification event occurs |
Notification | The events to register for notification of (eg DEVICE_NOTIFICATION_REGISTER) |
Flags | The flags to control the notification (eg NOTIFIER_FLAG_WORKER) |
UART serial functions
function UARTSerialDeviceOpen(Serial:PSerialDevice; BaudRate,DataBits,StopBits,Parity,FlowControl,ReceiveDepth,TransmitDepth:LongWord):LongWord;
Note | Not intended to be called directly by applications, use SerialDeviceOpen instead. |
---|
function UARTSerialDeviceClose(Serial:PSerialDevice):LongWord;
Note | Not intended to be called directly by applications, use SerialDeviceClose instead. |
---|
function UARTSerialDeviceRead(Serial:PSerialDevice; Buffer:Pointer; Size,Flags:LongWord; var Count:LongWord):LongWord;
Note | Not intended to be called directly by applications, use SerialDeviceRead instead. |
---|
function UARTSerialDeviceWrite(Serial:PSerialDevice; Buffer:Pointer; Size,Flags:LongWord; var Count:LongWord):LongWord;
Note | Not intended to be called directly by applications, use SerialDeviceWrite instead. |
---|
function UARTSerialDeviceWait(Serial:PSerialDevice; Direction,Timeout:LongWord; var Count:LongWord):LongWord;
Note | Not intended to be called directly by applications, use SerialDeviceWait instead. |
---|
function UARTSerialDeviceStatus(Serial:PSerialDevice):LongWord; inline;
Note | Not intended to be called directly by applications, use SerialDeviceStatus instead.
Replaced by UARTSerialDeviceGetStatus for consistency |
---|
function UARTSerialDeviceGetStatus(Serial:PSerialDevice):LongWord;
Note | Not intended to be called directly by applications, use SerialDeviceGetStatus instead. |
---|
function UARTSerialDeviceSetStatus(Serial:PSerialDevice; Status:LongWord):LongWord;
Note | Not intended to be called directly by applications, use SerialDeviceSetStatus instead. |
---|
function UARTSerialDeviceGetProperties(Serial:PSerialDevice;Properties:PSerialProperties):LongWord;
Note | Not intended to be called directly by applications, use SerialDeviceGetProperties instead. |
---|
UART helper functions
function UARTGetCount:LongWord;
Note | None documented |
---|
function UARTDeviceGetDefault:PUARTDevice;
Note | None documented |
---|
function UARTDeviceSetDefault(UART:PUARTDevice):LongWord;
Note | None documented |
---|
function UARTDeviceCheck(UART:PUARTDevice):PUARTDevice;
Note | None documented |
---|
function UARTTypeToString(UARTType:LongWord):String;
Note | None documented |
---|
function UARTModeToString(UARTMode:LongWord):String;
Note | None documented |
---|
function UARTStateToString(UARTState:LongWord):String;
Note | None documented |
---|
procedure UARTLog(Level:LongWord;UART:PUARTDevice; const AText:String);
Note | None documented |
---|
procedure UARTLogInfo(UART:PUARTDevice; const AText:String); inline;
Note | None documented |
---|
procedure UARTLogWarn(UART:PUARTDevice; const AText:String); inline;
Note | None documented |
---|
procedure UARTLogError(UART:PUARTDevice; const AText:String); inline;
Note | None documented |
---|
procedure UARTLogDebug(UART:PUARTDevice; const AText:String); inline;
Note | None documented |
---|
UART serial helper functions
function UARTSerialDeviceReceive(UART:PUARTDevice):LongWord;
Note | Not intended to be called directly by applications
Caller must hold the lock on the serial device which owns the UART |
---|
function UARTSerialDeviceTransmit(UART:PUARTDevice):LongWord;
Note | Not intended to be called directly by applications
Caller must hold the lock on the serial device which owns the UART |
---|
Return to Unit Reference