Difference between revisions of "Unit UART"
From Ultibo.org
| Line 350: | Line 350: | ||
|} | |} | ||
| − | '''UART device properties''' | + | '''UART device get properties''' |
{| class="wikitable" style="font-size: 14px; text-align: left; width: 100%; height: 50px;" | {| class="wikitable" style="font-size: 14px; text-align: left; width: 100%; height: 50px;" | ||
|- | |- | ||
| − | | <code> | + | | <code>TUARTDeviceGetProperties = function(UART:PUARTDevice; Properties:PUARTProperties):LongWord;</code> |
| style="width: 40%;"| | | style="width: 40%;"| | ||
|- | |- | ||
| Line 402: | Line 402: | ||
| A Device specific DeviceStatus method implementing the standard UART device interface (Or nil if the default method is suitable) | | A Device specific DeviceStatus method implementing the standard UART device interface (Or nil if the default method is suitable) | ||
|- | |- | ||
| − | | <code> | + | | <code>DeviceGetProperties:TUARTDeviceGetProperties;</code> |
| − | | A Device specific | + | | A Device specific DeviceGetProperties method implementing the standard UART device interface (Or nil if the default method is suitable) |
|- | |- | ||
|colspan="2"|''Driver Properties'' | |colspan="2"|''Driver Properties'' | ||
Revision as of 04:44, 8 June 2017
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 specific 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 device type
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 device mode
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 device state
UART_STATE_* UART_STATE_DISABLED = 0;
|
|
UART_STATE_ENABLED = 1;
|
UART device flag
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 flag
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 flag
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 status flag
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 logging
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_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 status
TUARTDeviceStatus = function(UART:PUARTDevice):LongWord;
|
UART device get properties
TUARTDeviceGetProperties = 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) |
DeviceStatus:TUARTDeviceStatus;
|
A Device specific DeviceStatus method implementing the standard UART device interface (Or nil if the default method is suitable) |
DeviceGetProperties:TUARTDeviceGetProperties;
|
A Device specific DeviceGetProperties 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;
Description: Initialize the UART unit and UART device table
| Note | Called only during system startup |
|---|
UART functions
function UARTDeviceOpen(UART:PUARTDevice; BaudRate,DataBits,StopBits,Parity,FlowControl:LongWord):LongWord;
Description: To be documented
| Note | None documented |
|---|
function UARTDeviceClose(UART:PUARTDevice):LongWord;
Description: To be documented
| Note | None documented |
|---|
function UARTDeviceRead(UART:PUARTDevice; Buffer:Pointer; Size,Flags:LongWord;var Count:LongWord):LongWord;
Description: To be documented
| Note | None documented |
|---|
function UARTDeviceWrite(UART:PUARTDevice; Buffer:Pointer; Size,Flags:LongWord;var Count:LongWord):LongWord;
Description: To be documented
| Note | None documented |
|---|
function UARTDeviceStatus(UART:PUARTDevice):LongWord;
Description: To be documented
| Note | None documented |
|---|
function UARTDeviceProperties(UART:PUARTDevice; Properties:PUARTProperties):LongWord;
Description: To be documented
| Note | None documented |
|---|
function UARTDeviceCreate:PUARTDevice;
Description: Create a new UART entry
| Return | Pointer to new UART entry or nil if UART could not be created |
|---|
function UARTDeviceCreateEx(Size:LongWord):PUARTDevice;
Description: Create a new UART entry
| 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;
Description: Destroy an existing UART entry
| Note | None documented |
|---|
function UARTDeviceRegister(UART:PUARTDevice):LongWord;
Description: Register a new UART in the UART table
| Note | None documented |
|---|
function UARTDeviceDeregister(UART:PUARTDevice):LongWord;
Description: Deregister a UART from the UART table
| Note | None documented |
|---|
function UARTDeviceFind(UARTId:LongWord):PUARTDevice;
Description: To be documented
| Note | None documented |
|---|
function UARTDeviceFindByName(const Name:String):PUARTDevice; inline;
Description: To be documented
| Note | None documented |
|---|
function UARTDeviceFindByDescription(const Description:String):PUARTDevice; inline;
Description: To be documented
| Note | None documented |
|---|
function UARTDeviceEnumerate(Callback:TUARTEnumerate; Data:Pointer):LongWord;
Description: To be documented
| Note | None documented |
|---|
function UARTDeviceNotification(UART:PUARTDevice; Callback:TUARTNotification; Data:Pointer; Notification,Flags:LongWord):LongWord;
Description: To be documented
| Note | None documented |
|---|
UART serial functions
function UARTSerialDeviceOpen(Serial:PSerialDevice; BaudRate,DataBits,StopBits,Parity,FlowControl,ReceiveDepth,TransmitDepth:LongWord):LongWord;
Description: To be documented
| Note | None documented |
|---|
function UARTSerialDeviceClose(Serial:PSerialDevice):LongWord;
Description: To be documented
| Note | None documented |
|---|
function UARTSerialDeviceRead(Serial:PSerialDevice; Buffer:Pointer; Size,Flags:LongWord; var Count:LongWord):LongWord;
Description: To be documented
| Note | None documented |
|---|
function UARTSerialDeviceWrite(Serial:PSerialDevice; Buffer:Pointer; Size,Flags:LongWord; var Count:LongWord):LongWord;
Description: To be documented
| Note | None documented |
|---|
function UARTSerialDeviceStatus(Serial:PSerialDevice):LongWord;
Description: To be documented
| Note | None documented |
|---|
function UARTSerialDeviceProperties(Serial:PSerialDevice; Properties:PSerialProperties):LongWord;
Description: To be documented
| Note | None documented |
|---|
UART helper functions
function UARTGetCount:LongWord; inline;
Description: Get the current UART count
| Note | None documented |
|---|
function UARTDeviceGetDefault:PUARTDevice; inline;
Description: Get the current default UART device
| Note | None documented |
|---|
function UARTDeviceSetDefault(UART:PUARTDevice):LongWord;
Description: Set the current default UART device
| Note | None documented |
|---|
function UARTDeviceCheck(UART:PUARTDevice):PUARTDevice;
Description: Check if the supplied UART is in the UART table
| Note | None documented |
|---|
procedure UARTLog(Level:LongWord;UART:PUARTDevice; const AText:String);
Description: To be documented
| Note | None documented |
|---|
procedure UARTLogInfo(UART:PUARTDevice; const AText:String); inline;
Description: To be documented
| Note | None documented |
|---|
procedure UARTLogError(UART:PUARTDevice; const AText:String); inline;
Description: To be documented
| Note | None documented |
|---|
procedure UARTLogDebug(UART:PUARTDevice; const AText:String); inline;
Description: To be documented
| Note | None documented |
|---|
UART serial helper functions
function UARTSerialDeviceReceive(UART:PUARTDevice):LongWord;
Description: To be documented
| Note | None documented |
|---|
function UARTSerialDeviceTransmit(UART:PUARTDevice):LongWord;
Description: To be documented
| Note | None documented |
|---|
Return to Unit Reference
