Difference between revisions of "Unit Serial"
Line 172: | Line 172: | ||
| <code>SERIAL_WRITE_PEEK_BUFFER = $00000002;</code> | | <code>SERIAL_WRITE_PEEK_BUFFER = $00000002;</code> | ||
| Return the number of bytes free in the transmit buffer without writing anything | | Return the number of bytes free in the transmit buffer without writing anything | ||
+ | |- | ||
+ | |} | ||
+ | </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;">'''Serial wait directions''' <code> SERIAL_WAIT_* </code></div> | ||
+ | <div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;"> | ||
+ | {| class="wikitable" style="font-size: 14px; background: white;" | ||
+ | |- | ||
+ | | <code>SERIAL_WAIT_NONE = 0;</code> | ||
+ | | | ||
+ | |- | ||
+ | | <code>SERIAL_WAIT_RECEIVE = 1;</code> | ||
+ | | Wait for data to be available in the receive buffer | ||
+ | |- | ||
+ | | <code>SERIAL_WAIT_TRANSMIT = 2;</code> | ||
+ | | Wait for space to be available in the transmit buffer | ||
|- | |- | ||
|} | |} | ||
Line 259: | Line 276: | ||
| <code>SERIAL_LOG_LEVEL_INFO = LOG_LEVEL_INFO;</code> | | <code>SERIAL_LOG_LEVEL_INFO = LOG_LEVEL_INFO;</code> | ||
| Serial informational messages, such as a device being attached or detached | | Serial informational messages, such as a device being attached or detached | ||
+ | |- | ||
+ | | <code>SERIAL_LOG_LEVEL_WARN = LOG_LEVEL_WARN;</code> | ||
+ | | Serial warning messages | ||
|- | |- | ||
| <code>SERIAL_LOG_LEVEL_ERROR = LOG_LEVEL_ERROR;</code> | | <code>SERIAL_LOG_LEVEL_ERROR = LOG_LEVEL_ERROR;</code> | ||
Line 398: | Line 418: | ||
|- | |- | ||
| <code>TSerialDeviceWrite = function(Serial:PSerialDevice; Buffer:Pointer; Size,Flags:LongWord; var Count:LongWord):LongWord;</code> | | <code>TSerialDeviceWrite = function(Serial:PSerialDevice; Buffer:Pointer; Size,Flags:LongWord; var Count:LongWord):LongWord;</code> | ||
+ | | style="width: 40%;"| | ||
+ | |- | ||
+ | |} | ||
+ | |||
+ | '''Serial device wait''' | ||
+ | |||
+ | {| class="wikitable" style="font-size: 14px; text-align: left; width: 100%; height: 50px;" | ||
+ | |- | ||
+ | | <code>TSerialDeviceWait = function(Serial:PSerialDevice; Direction,Timeout:LongWord; var Count:LongWord):LongWord;</code> | ||
| style="width: 40%;"| | | style="width: 40%;"| | ||
|- | |- | ||
Line 411: | Line 440: | ||
|} | |} | ||
− | '''Serial device status''' | + | '''Serial device get status''' |
{| 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>TSerialDeviceGetStatus = function(Serial:PSerialDevice):LongWord;</code> |
+ | | style="width: 40%;"| | ||
+ | |- | ||
+ | |} | ||
+ | |||
+ | '''Serial device set status''' | ||
+ | |||
+ | {| class="wikitable" style="font-size: 14px; text-align: left; width: 100%; height: 50px;" | ||
+ | |- | ||
+ | | <code>TSerialDeviceSetStatus = function(Serial:PSerialDevice; Status:LongWord):LongWord;</code> | ||
| style="width: 40%;"| | | style="width: 40%;"| | ||
|- | |- | ||
Line 428: | Line 466: | ||
|- | |- | ||
|} | |} | ||
+ | |||
+ | '''Serial device set properties''' | ||
+ | |||
+ | {| class="wikitable" style="font-size: 14px; text-align: left; width: 100%; height: 50px;" | ||
+ | |- | ||
+ | | <code>TSerialDeviceSetProperties = function(Serial:PSerialDevice; Properties:PSerialProperties):LongWord;</code> | ||
+ | | style="width: 40%;"| | ||
+ | |- | ||
+ | |} | ||
'''Serial device''' | '''Serial device''' | ||
Line 466: | Line 513: | ||
| A Device specific DeviceWrite method implementing the standard Serial device interface (Mandatory) | | A Device specific DeviceWrite method implementing the standard Serial device interface (Mandatory) | ||
|- | |- | ||
− | | <code> | + | | <code>DeviceWait:TSerialDeviceWait;</code> |
− | | A Device specific | + | | A Device specific DeviceWait method implementing the standard Serial device interface (Or nil if the default method is suitable) |
+ | |- | ||
+ | | <code>DeviceFlush:TSerialDeviceFlush;</code> | ||
+ | | A Device specific DeviceFlush method implementing the standard Serial device interface (Or nil if the default method is suitable) | ||
+ | |- | ||
+ | | <code>DeviceGetStatus:TSerialDeviceGetStatus;</code> | ||
+ | | A Device specific DeviceGetStatus method implementing the standard Serial device interface (Or nil if the default method is suitable) | ||
+ | |- | ||
+ | | <code>DeviceSetStatus:TSerialDeviceSetStatus;</code> | ||
+ | | A Device specific DeviceSetStatus method implementing the standard Serial device interface (Optional) | ||
|- | |- | ||
| <code>DeviceGetProperties:TSerialDeviceGetProperties;</code> | | <code>DeviceGetProperties:TSerialDeviceGetProperties;</code> | ||
| A Device specific DeviceGetProperties method implementing the standard Serial device interface (Or nil if the default method is suitable) | | A Device specific DeviceGetProperties method implementing the standard Serial device interface (Or nil if the default method is suitable) | ||
+ | |- | ||
+ | | <code>DeviceSetProperties:TSerialDeviceSetProperties;</code> | ||
+ | | A Device specific DeviceSetProperties method implementing the standard Serial device interface (Or nil if the default method is suitable) | ||
|- | |- | ||
|colspan="2"|''Driver Properties'' | |colspan="2"|''Driver Properties'' | ||
Line 694: | Line 753: | ||
! '''Count''' | ! '''Count''' | ||
| The number of bytes written on return | | The number of bytes written on return | ||
+ | |- | ||
+ | ! '''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 SerialDeviceWait(Serial:PSerialDevice; Direction,Timeout:LongWord; var Count:LongWord):LongWord;</pre> | ||
+ | <div style="font-size: 14px; padding-left: 12px;">'''Description:''' Wait for data to be available in the receive or transmit buffers of a Serial device</div> | ||
+ | <div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;"> | ||
+ | {| class="wikitable" style="font-size: 14px; background: white;" | ||
+ | |- | ||
+ | ! '''Serial''' | ||
+ | | The Serial device to wait for | ||
+ | |- | ||
+ | ! '''Direction''' | ||
+ | | The direction of data to wait for (eg SERIAL_WAIT_RECEIVE) | ||
+ | |- | ||
+ | ! '''Timeout''' | ||
+ | | The number of milliseconds to wait for data (INFINITE to wait forever) | ||
+ | |- | ||
+ | ! '''Count''' | ||
+ | | The number of bytes available on return | ||
|- | |- | ||
! '''Return''' | ! '''Return''' | ||
Line 720: | Line 803: | ||
<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 SerialDeviceStatus(Serial:PSerialDevice):LongWord;</pre> | + | <pre style="border: 0; padding-bottom:0px;">function SerialDeviceStatus(Serial:PSerialDevice):LongWord; inline;</pre> |
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Get the current line status of a Serial device</div> | <div style="font-size: 14px; padding-left: 12px;">'''Description:''' Get the current line status of a Serial 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 730: | Line 813: | ||
! '''Return''' | ! '''Return''' | ||
| A set of flags containing the device status (eg SERIAL_STATUS_RTS) | | A set of flags containing the device status (eg SERIAL_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 SerialDeviceGetStatus(Serial:PSerialDevice):LongWord;</pre> | ||
+ | <div style="font-size: 14px; padding-left: 12px;">'''Description:''' Get the current line status of a Serial device</div> | ||
+ | <div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;"> | ||
+ | {| class="wikitable" style="font-size: 14px; background: white;" | ||
+ | |- | ||
+ | ! '''Serial''' | ||
+ | | The Serial device to get the status from | ||
+ | |- | ||
+ | ! '''Return''' | ||
+ | | A set of flags containing the device status (eg SERIAL_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 SerialDeviceSetStatus(Serial:PSerialDevice; Status:LongWord):LongWord;</pre> | ||
+ | <div style="font-size: 14px; padding-left: 12px;">'''Description:''' Set the current line status of a Serial device</div> | ||
+ | <div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;"> | ||
+ | {| class="wikitable" style="font-size: 14px; background: white;" | ||
+ | |- | ||
+ | ! '''Serial''' | ||
+ | | The Serial device to set the status for | ||
+ | |- | ||
+ | ! '''Status''' | ||
+ | | The device status flags to be set (eg SERIAL_STATUS_RTS) | ||
+ | |- | ||
+ | ! '''Return''' | ||
+ | | ERROR_SUCCESS if completed or another error code on failure | ||
+ | |- | ||
+ | ! '''Note''' | ||
+ | | Not all SERIAL_STATUS_* flags can be set, the device may ignore invalid values | ||
+ | Not all serial devices support set status, returns ERROR_CALL_NOT_IMPLEMENTED if not supported | ||
|- | |- | ||
|} | |} | ||
Line 766: | Line 886: | ||
! '''Properties''' | ! '''Properties''' | ||
| Pointer to a PSerialProperties structure to fill in | | Pointer to a PSerialProperties 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 SerialDeviceSetProperties(Serial:PSerialDevice; Properties:PSerialProperties):LongWord;</pre> | ||
+ | <div style="font-size: 14px; padding-left: 12px;">'''Description:''' Set the properties for the specified Serial device</div> | ||
+ | <div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;"> | ||
+ | {| class="wikitable" style="font-size: 14px; background: white;" | ||
+ | |- | ||
+ | ! '''Serial''' | ||
+ | | The Serial device to set properties for | ||
+ | |- | ||
+ | ! '''Properties''' | ||
+ | | Pointer to a PSerialProperties structure to use | ||
|- | |- | ||
! '''Return''' | ! '''Return''' | ||
Line 1,252: | Line 1,390: | ||
<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 SerialLogInfo(Serial:PSerialDevice; const AText:String); inline;</pre> | <pre style="border: 0; padding-bottom:0px;">procedure SerialLogInfo(Serial:PSerialDevice; 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 SerialLogWarn(Serial:PSerialDevice; 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 05:28, 26 March 2018
Return to Unit Reference
Contents
[hide]Description
Ultibo Serial interface unit
Serial devices represent a communication device that can be both read and written and has a set of common properties and capabilities. The underlying device may be an actual UART or it may be some other form of device such as a USB to Serial converter. As long as the device can implement the common capabilities then it can be accessed as a serial device without regard to the actual implementation.
Each serial 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 from and writes to serial devices are buffered so that varying data transfer rates can be accomodated and 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.
This unit also implements the serial logging device which can be configured via parameters in the GlobalConfig unit or from the command line.
Constants
SERIAL_*
SERIAL_TYPE_*
SERIAL_STATE_*
SERIAL_FLAG_*
SERIAL_READ_*
SERIAL_WRITE_*
SERIAL_WAIT_*
SERIAL_FLUSH_*
SERIAL_STATUS_*
SERIAL_LOG_*
Type definitions
Serial properties
Serial buffer
Serial enumeration callback
TSerialEnumerate = function(Serial:PSerialDevice; Data:Pointer):LongWord;
|
Serial notification callback
TSerialNotification = function(Device:PDevice; Data:Pointer; Notification:LongWord):LongWord;
|
Serial device open
TSerialDeviceOpen = function(Serial:PSerialDevice; BaudRate,DataBits,StopBits,Parity,FlowControl,ReceiveDepth,TransmitDepth:LongWord):LongWord;
|
Serial device close
TSerialDeviceClose = function(Serial:PSerialDevice):LongWord;
|
Serial device read
TSerialDeviceRead = function(Serial:PSerialDevice; Buffer:Pointer; Size,Flags:LongWord; var Count:LongWord):LongWord;
|
Serial device write
TSerialDeviceWrite = function(Serial:PSerialDevice; Buffer:Pointer; Size,Flags:LongWord; var Count:LongWord):LongWord;
|
Serial device wait
TSerialDeviceWait = function(Serial:PSerialDevice; Direction,Timeout:LongWord; var Count:LongWord):LongWord;
|
Serial device flush
TSerialDeviceFlush = function(Serial:PSerialDevice;Flags:LongWord):LongWord;
|
Serial device get status
TSerialDeviceGetStatus = function(Serial:PSerialDevice):LongWord;
|
Serial device set status
TSerialDeviceSetStatus = function(Serial:PSerialDevice; Status:LongWord):LongWord;
|
Serial device get properties
TSerialDeviceGetProperties = function(Serial:PSerialDevice; Properties:PSerialProperties):LongWord;
|
Serial device set properties
TSerialDeviceSetProperties = function(Serial:PSerialDevice; Properties:PSerialProperties):LongWord;
|
Serial device
Serial logging
Public variables
Serial logging
SERIAL_DEFAULT_LOG_LEVEL:LongWord = SERIAL_LOG_LEVEL_DEBUG;
|
Minimum level for Serial messages. Only messages with level greater than or equal to this will be printed. |
SERIAL_LOG_ENABLED:Boolean;
|
Function declarations
Initialization functions
Serial functions
function SerialDeviceOpen(Serial:PSerialDevice; BaudRate,DataBits,StopBits,Parity,FlowControl,ReceiveDepth,TransmitDepth:LongWord):LongWord;
function SerialDeviceClose(Serial:PSerialDevice):LongWord;
function SerialDeviceRead(Serial:PSerialDevice; Buffer:Pointer; Size,Flags:LongWord; var Count:LongWord):LongWord;
function SerialDeviceWrite(Serial:PSerialDevice; Buffer:Pointer; Size,Flags:LongWord; var Count:LongWord):LongWord;
function SerialDeviceWait(Serial:PSerialDevice; Direction,Timeout:LongWord; var Count:LongWord):LongWord;
function SerialDeviceFlush(Serial:PSerialDevice; Flags:LongWord):LongWord;
function SerialDeviceStatus(Serial:PSerialDevice):LongWord; inline;
function SerialDeviceGetStatus(Serial:PSerialDevice):LongWord;
function SerialDeviceSetStatus(Serial:PSerialDevice; Status:LongWord):LongWord;
function SerialDeviceProperties(Serial:PSerialDevice; Properties:PSerialProperties):LongWord; inline;
function SerialDeviceGetProperties(Serial:PSerialDevice; Properties:PSerialProperties):LongWord;
function SerialDeviceSetProperties(Serial:PSerialDevice; Properties:PSerialProperties):LongWord;
function SerialDeviceCreateEx(Size:LongWord):PSerialDevice;
function SerialDeviceDestroy(Serial:PSerialDevice):LongWord;
function SerialDeviceRegister(Serial:PSerialDevice):LongWord;
function SerialDeviceDeregister(Serial:PSerialDevice):LongWord;
function SerialDeviceFind(SerialId:LongWord):PSerialDevice;
function SerialDeviceFindByName(const Name:String):PSerialDevice; inline;
function SerialDeviceFindByDescription(const Description:String):PSerialDevice; inline;
function SerialDeviceEnumerate(Callback:TSerialEnumerate; Data:Pointer):LongWord;
function SerialDeviceNotification(Serial:PSerialDevice; Callback:TSerialNotification; Data:Pointer; Notification,Flags:LongWord):LongWord;
Serial logging functions
function SerialLoggingStart(Logging:PLoggingDevice):LongWord;
function SerialLoggingStop(Logging:PLoggingDevice):LongWord;
function SerialLoggingOutput(Logging:PLoggingDevice; const Data:String):LongWord;
RTL text IO functions
function SysTextIOReadChar(var ACh:Char; AUserData:Pointer):Boolean;
function SysTextIOWriteChar(ACh:Char; AUserData:Pointer):Boolean;
function SysTextIOWriteBuffer(ABuffer:PChar; ACount:LongInt; AUserData:Pointer):LongInt;
RTL serial functions
function SysSerialOpen(BaudRate,DataBits,StopBits,Parity,FlowControl,ReceiveDepth,TransmitDepth:LongWord):LongWord;
function SysSerialClose:LongWord;
function SysSerialRead(Buffer:Pointer; Size:LongWord; var Count:LongWord):LongWord;
function SysSerialWrite(Buffer:Pointer; Size:LongWord; var Count:LongWord):LongWord;
Serial helper functions
function SerialDeviceGetDefault:PSerialDevice; inline;
function SerialDeviceSetDefault(Serial:PSerialDevice):LongWord;
function SerialDeviceCheck(Serial:PSerialDevice):PSerialDevice;
function SerialDeviceRedirectInput(Serial:PSerialDevice):Boolean;
function SerialDeviceRedirectOutput(Serial:PSerialDevice):Boolean;
function SerialBufferReadStart(Buffer:PSerialBuffer; var Available:LongWord):Pointer;
function SerialBufferReadComplete(Buffer:PSerialBuffer; Removed:LongWord):Boolean;
function SerialBufferWriteStart(Buffer:PSerialBuffer; var Available:LongWord):Pointer;
function SerialBufferWriteComplete(Buffer:PSerialBuffer; Added:LongWord):Boolean;
procedure SerialLog(Level:LongWord; Serial:PSerialDevice; const AText:String);
procedure SerialLogInfo(Serial:PSerialDevice; const AText:String); inline;
procedure SerialLogWarn(Serial:PSerialDevice; const AText:String); inline;
procedure SerialLogError(Serial:PSerialDevice; const AText:String); inline;
procedure SerialLogDebug(Serial:PSerialDevice; const AText:String); inline;
Serial logging helper functions
function SerialLoggingDeviceAdd(Serial:PSerialDevice):LongWord;
function SerialLoggingDeviceRemove(Serial:PSerialDevice):LongWord;
function SerialLoggingDeviceParameters(Serial:PSerialDevice; const Parameters:String; var BaudRate,Parity,DataBits,StopBits:LongWord):LongWord;
function SerialLoggingFirstWord(var Value:String;const Delimiter:String):String;
function SerialLoggingDeviceEnum(Serial:PSerialDevice; Data:Pointer):LongWord;
function SerialLoggingDeviceNotify(Device:PDevice; Data:Pointer; Notification:LongWord):LongWord;
Return to Unit Reference