Difference between revisions of "Unit UART"
Line 166: | Line 166: | ||
| <code>UART_WRITE_NON_BLOCK = SERIAL_WRITE_NON_BLOCK;</code> | | <code>UART_WRITE_NON_BLOCK = SERIAL_WRITE_NON_BLOCK;</code> | ||
| Do not block when transmitting, if the FIFO is full return immediately | | Do not block when transmitting, if the FIFO is full return immediately | ||
+ | |- | ||
+ | |} | ||
+ | </div></div> | ||
+ | <br /> | ||
+ | <div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 20px; padding-bottom: 15px;"> | ||
+ | <div style="font-size: 14px; padding-left: 12px;">'''UART wait direction''' <code> UART_WAIT_* </code></div> | ||
+ | <div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;"> | ||
+ | {| class="wikitable" style="font-size: 14px; background: white;" | ||
+ | |- | ||
+ | | <code>UART_WAIT_NONE = SERIAL_WAIT_NONE;</code> | ||
+ | | | ||
+ | |- | ||
+ | | <code>UART_WAIT_RECEIVE = SERIAL_WAIT_RECEIVE;</code> | ||
+ | | Wait for data to be available in the receive FIFO | ||
+ | |- | ||
+ | | <code>UART_WAIT_TRANSMIT = SERIAL_WAIT_TRANSMIT;</code> | ||
+ | | Wait for space to be available in the transmit FIFO | ||
|- | |- | ||
|} | |} | ||
Line 236: | Line 253: | ||
| <code>UART_LOG_LEVEL_INFO = LOG_LEVEL_INFO;</code> | | <code>UART_LOG_LEVEL_INFO = LOG_LEVEL_INFO;</code> | ||
| UART informational messages, such as a device being attached or detached | | UART informational messages, such as a device being attached or detached | ||
+ | |- | ||
+ | | <code>UART_LOG_LEVEL_WARN = LOG_LEVEL_WARN;</code> | ||
+ | | UART warning messages | ||
|- | |- | ||
| <code>UART_LOG_LEVEL_ERROR = LOG_LEVEL_ERROR;</code> | | <code>UART_LOG_LEVEL_ERROR = LOG_LEVEL_ERROR;</code> | ||
Line 341: | Line 361: | ||
|} | |} | ||
− | '''UART device | + | '''UART device wait''' |
{| 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>TUARTDeviceWait = function(UART:PUARTDevice; Direction,Timeout:LongWord):LongWord;</code> |
+ | | style="width: 40%;"| | ||
+ | |- | ||
+ | |} | ||
+ | |||
+ | '''UART device get status''' | ||
+ | |||
+ | {| class="wikitable" style="font-size: 14px; text-align: left; width: 100%; height: 50px;" | ||
+ | |- | ||
+ | | <code>TUARTDeviceGetStatus = function(UART:PUARTDevice):LongWord;</code> | ||
+ | | style="width: 40%;"| | ||
+ | |- | ||
+ | |} | ||
+ | |||
+ | '''UART device set status''' | ||
+ | |||
+ | {| class="wikitable" style="font-size: 14px; text-align: left; width: 100%; height: 50px;" | ||
+ | |- | ||
+ | | <code>TUARTDeviceSetStatus = function(UART:PUARTDevice; Status:LongWord):LongWord;</code> | ||
| style="width: 40%;"| | | style="width: 40%;"| | ||
|- | |- | ||
Line 358: | Line 396: | ||
|- | |- | ||
|} | |} | ||
+ | |||
+ | '''UART device set properties''' | ||
+ | |||
+ | {| class="wikitable" style="font-size: 14px; text-align: left; width: 100%; height: 50px;" | ||
+ | |- | ||
+ | | <code>TUARTDeviceSetProperties = function(UART:PUARTDevice; Properties:PUARTProperties):LongWord;</code> | ||
+ | | style="width: 40%;"| | ||
+ | |- | ||
+ | |} | ||
'''UART device''' | '''UART device''' | ||
Line 399: | Line 446: | ||
| A Device specific DeviceWrite method implementing the standard UART device interface (Mandatory) | | A Device specific DeviceWrite method implementing the standard UART device interface (Mandatory) | ||
|- | |- | ||
− | | <code> | + | | <code>DeviceWait:TUARTDeviceWait;</code> |
− | | A Device specific | + | | A Device specific DeviceWait method implementing the standard UART device interface (Or nil if the default method is suitable) |
+ | |- | ||
+ | | <code>DeviceGetStatus:TUARTDeviceGetStatus;</code> | ||
+ | | A Device specific DeviceGetStatus method implementing the standard UART device interface (Or nil if the default method is suitable) | ||
+ | |- | ||
+ | | <code>DeviceSetStatus:TUARTDeviceSetStatus;</code> | ||
+ | | A Device specific DeviceSetStatus method implementing the standard UART device interface (Optional) | ||
|- | |- | ||
| <code>DeviceGetProperties:TUARTDeviceGetProperties;</code> | | <code>DeviceGetProperties:TUARTDeviceGetProperties;</code> | ||
| A Device specific DeviceGetProperties method implementing the standard UART device interface (Or nil if the default method is suitable) | | A Device specific DeviceGetProperties method implementing the standard UART device interface (Or nil if the default method is suitable) | ||
+ | |- | ||
+ | | <code>DeviceSetProperties:TUARTDeviceSetProperties;</code> | ||
+ | | A Device specific DeviceSetProperties method implementing the standard UART device interface (Or nil if the default method is suitable) | ||
|- | |- | ||
|colspan="2"|''Driver Properties'' | |colspan="2"|''Driver Properties'' | ||
Line 591: | Line 647: | ||
<br /> | <br /> | ||
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;"> | <div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;"> | ||
− | <pre style="border: 0; padding-bottom:0px;">function UARTDeviceStatus(UART:PUARTDevice):LongWord;</pre> | + | <pre style="border: 0; padding-bottom:0px;">function UARTDeviceWait(UART:PUARTDevice; Direction,Timeout:LongWord):LongWord;</pre> |
+ | <div style="font-size: 14px; padding-left: 12px;">'''Description:''' Wait for data to be available in the receive or transmit FIFO of a UART device</div> | ||
+ | <div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;"> | ||
+ | {| class="wikitable" style="font-size: 14px; background: white;" | ||
+ | |- | ||
+ | ! '''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 | ||
+ | |- | ||
+ | |} | ||
+ | </div></div> | ||
+ | <br /> | ||
+ | <div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;"> | ||
+ | <pre style="border: 0; padding-bottom:0px;">function UARTDeviceStatus(UART:PUARTDevice):LongWord; inline;</pre> | ||
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Get the current line status of a UART device</div> | <div style="font-size: 14px; padding-left: 12px;">'''Description:''' Get the current line status of a UART device</div> | ||
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;"> | <div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;"> | ||
Line 601: | Line 678: | ||
! '''Return''' | ! '''Return''' | ||
| A set of flags containing the device status (eg UART_STATUS_RTS) | | A set of flags containing the device status (eg UART_STATUS_RTS) | ||
+ | |- | ||
+ | ! '''Note''' | ||
+ | | Replaced by UARTDeviceGetStatus for consistency | ||
+ | |- | ||
+ | |} | ||
+ | </div></div> | ||
+ | <br /> | ||
+ | <div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;"> | ||
+ | <pre style="border: 0; padding-bottom:0px;">function UARTDeviceGetStatus(UART:PUARTDevice):LongWord;</pre> | ||
+ | <div style="font-size: 14px; padding-left: 12px;">'''Description:''' Get the current line status of a UART device</div> | ||
+ | <div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;"> | ||
+ | {| class="wikitable" style="font-size: 14px; background: white;" | ||
+ | |- | ||
+ | ! '''UART''' | ||
+ | | The UART device to get the status from | ||
+ | |- | ||
+ | ! '''Return''' | ||
+ | | A set of flags containing the device status (eg UART_STATUS_RTS) | ||
+ | |- | ||
+ | |} | ||
+ | </div></div> | ||
+ | <br /> | ||
+ | <div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;"> | ||
+ | <pre style="border: 0; padding-bottom:0px;">function UARTDeviceSetStatus(UART:PUARTDevice;Status:LongWord):LongWord;</pre> | ||
+ | <div style="font-size: 14px; padding-left: 12px;">'''Description:''' Set the current line status of a UART device</div> | ||
+ | <div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;"> | ||
+ | {| class="wikitable" style="font-size: 14px; background: white;" | ||
+ | |- | ||
+ | ! '''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 | ||
|- | |- | ||
|} | |} | ||
Line 637: | Line 754: | ||
! '''Properties''' | ! '''Properties''' | ||
| Pointer to a PUARTProperties structure to fill in | | Pointer to a PUARTProperties structure to fill in | ||
+ | |- | ||
+ | ! '''Return''' | ||
+ | | ERROR_SUCCESS if completed or another error code on failure | ||
+ | |- | ||
+ | |} | ||
+ | </div></div> | ||
+ | <br /> | ||
+ | <div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;"> | ||
+ | <pre style="border: 0; padding-bottom:0px;">function UARTDeviceSetProperties(UART:PUARTDevice; Properties:PUARTProperties):LongWord;</pre> | ||
+ | <div style="font-size: 14px; padding-left: 12px;">'''Description:''' Set the properties for the specified UART device</div> | ||
+ | <div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;"> | ||
+ | {| class="wikitable" style="font-size: 14px; background: white;" | ||
+ | |- | ||
+ | ! '''UART''' | ||
+ | | The UART device to set properties for | ||
+ | |- | ||
+ | ! '''Properties''' | ||
+ | | Pointer to a PUARTProperties structure to use | ||
|- | |- | ||
! '''Return''' | ! '''Return''' | ||
Line 855: | Line 990: | ||
<br /> | <br /> | ||
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;"> | <div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;"> | ||
− | <pre style="border: 0; padding-bottom:0px;">function UARTSerialDeviceStatus(Serial:PSerialDevice):LongWord;</pre> | + | <pre style="border: 0; padding-bottom:0px;">function UARTSerialDeviceWait(Serial:PSerialDevice; Direction,Timeout:LongWord; var Count:LongWord):LongWord;</pre> |
+ | <div style="font-size: 14px; padding-left: 12px;">'''Description:''' Implementation of SerialDeviceWait API for UART Serial</div> | ||
+ | <div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;"> | ||
+ | {| class="wikitable" style="font-size: 14px; background: white;" | ||
+ | |- | ||
+ | ! '''Note''' | ||
+ | | Not intended to be called directly by applications, use SerialDeviceWait instead | ||
+ | |- | ||
+ | |} | ||
+ | </div></div> | ||
+ | <br /> | ||
+ | <div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;"> | ||
+ | <pre style="border: 0; padding-bottom:0px;">function UARTSerialDeviceStatus(Serial:PSerialDevice):LongWord; inline;</pre> | ||
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Implementation of SerialDeviceStatus API for UART Serial</div> | <div style="font-size: 14px; padding-left: 12px;">'''Description:''' Implementation of SerialDeviceStatus API for UART Serial</div> | ||
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;"> | <div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;"> | ||
Line 862: | Line 1,009: | ||
! '''Note''' | ! '''Note''' | ||
| Not intended to be called directly by applications, use SerialDeviceStatus instead | | Not intended to be called directly by applications, use SerialDeviceStatus instead | ||
+ | Replaced by UARTSerialDeviceGetStatus for consistency | ||
+ | |- | ||
+ | |} | ||
+ | </div></div> | ||
+ | <br /> | ||
+ | <div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;"> | ||
+ | <pre style="border: 0; padding-bottom:0px;">function UARTSerialDeviceGetStatus(Serial:PSerialDevice):LongWord;</pre> | ||
+ | <div style="font-size: 14px; padding-left: 12px;">'''Description:''' Implementation of SerialDeviceGetStatus API for UART Serial</div> | ||
+ | <div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;"> | ||
+ | {| class="wikitable" style="font-size: 14px; background: white;" | ||
+ | |- | ||
+ | ! '''Note''' | ||
+ | | Not intended to be called directly by applications, use SerialDeviceGetStatus instead | ||
+ | |- | ||
+ | |} | ||
+ | </div></div> | ||
+ | <br /> | ||
+ | <div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;"> | ||
+ | <pre style="border: 0; padding-bottom:0px;">function UARTSerialDeviceSetStatus(Serial:PSerialDevice; Status:LongWord):LongWord;</pre> | ||
+ | <div style="font-size: 14px; padding-left: 12px;">'''Description:''' Implementation of SerialDeviceSetStatus API for UART Serial</div> | ||
+ | <div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;"> | ||
+ | {| class="wikitable" style="font-size: 14px; background: white;" | ||
+ | |- | ||
+ | ! '''Note''' | ||
+ | | Not intended to be called directly by applications, use SerialDeviceSetStatus instead | ||
|- | |- | ||
|} | |} | ||
Line 943: | Line 1,115: | ||
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;"> | <div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;"> | ||
<pre style="border: 0; padding-bottom:0px;">procedure UARTLogInfo(UART:PUARTDevice; const AText:String); inline;</pre> | <pre style="border: 0; padding-bottom:0px;">procedure UARTLogInfo(UART:PUARTDevice; const AText:String); inline;</pre> | ||
+ | <div style="font-size: 14px; padding-left: 12px;">'''Description:''' To be documented</div> | ||
+ | <div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;"> | ||
+ | {| class="wikitable" style="font-size: 14px; background: white;" | ||
+ | |- | ||
+ | ! '''Note''' | ||
+ | | None documented | ||
+ | |- | ||
+ | |} | ||
+ | </div></div> | ||
+ | <br /> | ||
+ | <div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;"> | ||
+ | <pre style="border: 0; padding-bottom:0px;">procedure UARTLogWarn(UART:PUARTDevice; const AText:String); inline;</pre> | ||
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' To be documented</div> | <div style="font-size: 14px; padding-left: 12px;">'''Description:''' To be documented</div> | ||
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;"> | <div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;"> |
Revision as of 04:05, 27 March 2018
Return to Unit Reference
Contents
[hide]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_TYPE_*
UART_MODE_*
UART_STATE_*
UART_FLAG_*
UART_READ_*
UART_WRITE_*
UART_WAIT_*
UART_STATUS_*
UART_LOG_*
Type definitions
UART properties
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
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
UART functions
function UARTDeviceOpen(UART:PUARTDevice; BaudRate,DataBits,StopBits,Parity,FlowControl:LongWord):LongWord;
function UARTDeviceClose(UART:PUARTDevice):LongWord;
function UARTDeviceRead(UART:PUARTDevice; Buffer:Pointer; Size,Flags:LongWord;var Count:LongWord):LongWord;
function UARTDeviceWrite(UART:PUARTDevice; Buffer:Pointer; Size,Flags:LongWord;var Count:LongWord):LongWord;
function UARTDeviceWait(UART:PUARTDevice; Direction,Timeout:LongWord):LongWord;
function UARTDeviceStatus(UART:PUARTDevice):LongWord; inline;
function UARTDeviceGetStatus(UART:PUARTDevice):LongWord;
function UARTDeviceSetStatus(UART:PUARTDevice;Status:LongWord):LongWord;
function UARTDeviceProperties(UART:PUARTDevice; Properties:PUARTProperties):LongWord; inline;
function UARTDeviceGetProperties(UART:PUARTDevice;Properties:PUARTProperties):LongWord;
function UARTDeviceSetProperties(UART:PUARTDevice; Properties:PUARTProperties):LongWord;
function UARTDeviceCreateEx(Size:LongWord):PUARTDevice;
function UARTDeviceDestroy(UART:PUARTDevice):LongWord;
function UARTDeviceRegister(UART:PUARTDevice):LongWord;
function UARTDeviceDeregister(UART:PUARTDevice):LongWord;
function UARTDeviceFind(UARTId:LongWord):PUARTDevice;
function UARTDeviceFindByName(const Name:String):PUARTDevice; inline;
function UARTDeviceFindByDescription(const Description:String):PUARTDevice; inline;
function UARTDeviceEnumerate(Callback:TUARTEnumerate; Data:Pointer):LongWord;
function UARTDeviceNotification(UART:PUARTDevice; Callback:TUARTNotification; Data:Pointer; Notification,Flags:LongWord):LongWord;
UART serial functions
function UARTSerialDeviceOpen(Serial:PSerialDevice; BaudRate,DataBits,StopBits,Parity,FlowControl,ReceiveDepth,TransmitDepth:LongWord):LongWord;
function UARTSerialDeviceClose(Serial:PSerialDevice):LongWord;
function UARTSerialDeviceRead(Serial:PSerialDevice; Buffer:Pointer; Size,Flags:LongWord; var Count:LongWord):LongWord;
function UARTSerialDeviceWrite(Serial:PSerialDevice; Buffer:Pointer; Size,Flags:LongWord; var Count:LongWord):LongWord;
function UARTSerialDeviceWait(Serial:PSerialDevice; Direction,Timeout:LongWord; var Count:LongWord):LongWord;
function UARTSerialDeviceStatus(Serial:PSerialDevice):LongWord; inline;
function UARTSerialDeviceGetStatus(Serial:PSerialDevice):LongWord;
function UARTSerialDeviceSetStatus(Serial:PSerialDevice; Status:LongWord):LongWord;
function UARTSerialDeviceGetProperties(Serial:PSerialDevice;Properties:PSerialProperties):LongWord;
UART helper functions
function UARTDeviceGetDefault:PUARTDevice; inline;
function UARTDeviceSetDefault(UART:PUARTDevice):LongWord;
function UARTDeviceCheck(UART:PUARTDevice):PUARTDevice;
procedure UARTLog(Level:LongWord;UART:PUARTDevice; const AText:String);
procedure UARTLogInfo(UART:PUARTDevice; const AText:String); inline;
procedure UARTLogWarn(UART:PUARTDevice; const AText:String); inline;
procedure UARTLogError(UART:PUARTDevice; const AText:String); inline;
procedure UARTLogDebug(UART:PUARTDevice; const AText:String); inline;
UART serial helper functions
function UARTSerialDeviceReceive(UART:PUARTDevice):LongWord;
function UARTSerialDeviceTransmit(UART:PUARTDevice):LongWord;
Return to Unit Reference