Unit Serial

From Ultibo.org
Revision as of 02:52, 8 June 2017 by Ultibo (Talk | contribs)

Jump to: navigation, search

Return to Unit Reference


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 specific constants SERIAL_*
SERIAL_NAME_PREFIX = 'Serial'; Name prefix for Serial Devices
 
SERIAL_LOGGING_DESCRIPTION = 'Serial Logging';  
 
SERIAL_RECEIVE_DEPTH_DEFAULT = SIZE_2K; Default receive buffer size in bytes
SERIAL_TRANSMIT_DEPTH_DEFAULT = SIZE_2K; Default transmit buffer size in bytes
 
SERIAL_PUSH_TIMEOUT = 50; Timeout (Milliseconds) for Push RX/TX (Implementation specific)


Serial device type SERIAL_TYPE_*
SERIAL_TYPE_NONE = 0;  
SERIAL_TYPE_UART = 1;  
SERIAL_TYPE_USB = 2;  


Serial device state SERIAL_STATE_*
SERIAL_STATE_CLOSED = 0;  
SERIAL_STATE_CLOSING = 1;  
SERIAL_STATE_OPENING = 2;  
SERIAL_STATE_OPEN = 3;  


Serial device flag SERIAL_FLAG_*
SERIAL_FLAG_NONE = $00000000;  
SERIAL_FLAG_DATA_8BIT = $00000001; Device supports 8 data bits
SERIAL_FLAG_DATA_7BIT = $00000002; Device supports 7 data bits
SERIAL_FLAG_DATA_6BIT = $00000004; Device supports 6 data bits
SERIAL_FLAG_DATA_5BIT = $00000008; Device supports 5 data bits
SERIAL_FLAG_STOP_1BIT = $00000010; Device supports 1 stop bit
SERIAL_FLAG_STOP_2BIT = $00000020; Device supports 2 stop bits
SERIAL_FLAG_STOP_1BIT5 = $00000040; Device supports 1.5 stop bits
SERIAL_FLAG_PARITY_ODD = $00000080; Device supports odd parity
SERIAL_FLAG_PARITY_EVEN = $00000100; Device supports even parity
SERIAL_FLAG_PARITY_MARK = $00000200; Device supports mark parity
SERIAL_FLAG_PARITY_SPACE = $00000400; Device supports space parity
SERIAL_FLAG_FLOW_RTS_CTS = $00000800; Device supports RTS/CTS flow control
SERIAL_FLAG_FLOW_DSR_DTR = $00001000; Device supports DSR/DTR flow control
SERIAL_FLAG_PUSH_RX = $00002000; Device requires pushed receive (Implementation specific)
SERIAL_FLAG_PUSH_TX = $00004000; Device requires pushed transmit (Implementation specific)


Serial read flag SERIAL_READ_*
SERIAL_READ_NONE = $00000000;  
SERIAL_READ_NON_BLOCK = $00000001; Do not block when reading, if the buffer is empty return immediately
SERIAL_READ_PEEK_BUFFER = $00000002; Return the number of bytes available in the receive buffer without reading them


Serial write flag SERIAL_WRITE_*
SERIAL_WRITE_NONE = $00000000;  
SERIAL_WRITE_NON_BLOCK = $00000001; Do not block when writing, if the buffer is full return immediately
SERIAL_WRITE_PEEK_BUFFER = $00000002; Return the number of bytes free in the transmit buffer without writing anything


Serial flush flag SERIAL_FLUSH_*
SERIAL_FLUSH_NONE = $00000000;  
SERIAL_FLUSH_RECEIVE = $00000001; Flush the receive buffer
SERIAL_FLUSH_TRANSMIT = $00000002; Flush the transmit buffer


Serial status flag SERIAL_STATUS_*
SERIAL_STATUS_NONE = $00000000;  
SERIAL_STATUS_RTS = $00000001; RTS (Request to Send) is set (If applicable)
SERIAL_STATUS_CTS = $00000002; CTS (Clear to Send) is set (If applicable)
SERIAL_STATUS_DSR = $00000004; DSR (Data Set Ready) is set (If applicable)
SERIAL_STATUS_DTR = $00000008; DTR (Data Terminal Ready) is set (If applicable)
SERIAL_STATUS_RX_FULL = $00000010; Receive buffer is full
SERIAL_STATUS_RX_EMPTY = $00000020; Receive buffer is empty
SERIAL_STATUS_TX_FULL = $00000040; Transmit buffer is full
SERIAL_STATUS_TX_EMPTY = $00000080; Transmit buffer is empty
SERIAL_STATUS_BUSY = $00000100; Device is busy
SERIAL_STATUS_BREAK_ERROR = $00000200; Break error reported
SERIAL_STATUS_PARITY_ERROR = $00000400; Parity error reported
SERIAL_STATUS_FRAMING_ERROR = $00000800; Framing error reported
SERIAL_STATUS_OVERRUN_ERROR = $00001000; Overrun error reported
SERIAL_STATUS_DCD = $00002000; DCD (Data Carrier Detect) is set (If applicable)
SERIAL_STATUS_RI = $00004000; RI (Ring Indicator) is set (If applicable)


Serial logging SERIAL_LOG_*
SERIAL_LOG_LEVEL_DEBUG = LOG_LEVEL_DEBUG; Serial debugging messages
SERIAL_LOG_LEVEL_INFO = LOG_LEVEL_INFO; Serial informational messages, such as a device being attached or detached
SERIAL_LOG_LEVEL_ERROR = LOG_LEVEL_ERROR; Serial error messages
SERIAL_LOG_LEVEL_NONE = LOG_LEVEL_NONE; No Serial messages
 
SERIAL_LOGGING_LINE_END = Chr(13) + Chr(10); CR LF


Type definitions


Serial properties

PSerialProperties = ^TSerialProperties;

TSerialProperties = record

Flags:LongWord; Device flags (eg SERIAL_FLAG_DATA_8BIT)
MinRate:LongWord; Minimum supported baud rate (0 for any rate supported)
MaxRate:LongWord; Maximum supported baud rate (0 for any rate supported)
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
ReceiveDepth:LongWord; Current receive depth setting
TransmitDepth:LongWord; Current transmit depth setting

Serial buffer

PSerialBuffer = ^TSerialBuffer;

TSerialBuffer = record

Wait:TEventHandle; Data ready/Buffer free event
Start:LongWord; Index of first byte in buffer
Count:LongWord; Number of bytes in buffer
Size:LongWord; Size of buffer
Data:Pointer; Buffered data

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 status

TSerialDeviceStatus = function(Serial:PSerialDevice):LongWord;

Serial device properties

TSerialDeviceProperties = function(Serial:PSerialDevice; Properties:PSerialProperties):LongWord;

Serial device

PSerialDevice = ^TSerialDevice;

TSerialDevice = record

Device Properties
Device:TDevice; The Device entry for this Serial
Serial Properties
SerialId:LongWord; Unique Id of this Serial device in the Serial device table
SerialState:LongWord; Serial state (eg SERIAL_STATE_OPEN)
SerialStatus:LongWord; Serial status (eg SERIAL_STATUS_RX_FULL)(May not be real time status depending on the driver)
DeviceOpen:TSerialDeviceOpen; A Device specific DeviceOpen method implementing the standard Serial device interface (Mandatory)
DeviceClose:TSerialDeviceClose; A Device specific DeviceClose method implementing the standard Serial device interface (Mandatory)
DeviceRead:TSerialDeviceRead; A Device specific DeviceRead method implementing the standard Serial device interface (Mandatory)
DeviceWrite:TSerialDeviceWrite; A Device specific DeviceWrite method implementing the standard Serial device interface (Mandatory)
DeviceStatus:TSerialDeviceStatus; A Device specific DeviceStatus method implementing the standard Serial device interface (Or nil if the default method is suitable)
DeviceProperties:TSerialDeviceProperties; A Device specific DeviceProperties method implementing the standard Serial device interface (Or nil if the default method is suitable)
Driver Properties
Lock:TMutexHandle; Device lock
Receive:TSerialBuffer; Serial receive buffer
Transmit:TSerialBuffer; Serial transmit buffer
Properties:TSerialProperties; Device properties
Statistics Properties
ReceiveCount:LongWord;  
ReceiveErrors:LongWord;  
ReceiveOverruns:LongWord;  
TransmitCount:LongWord;  
TransmitErrors:LongWord;  
TransmitOverruns:LongWord;  
Internal Properties
Prev:PSerialDevice; Previous entry in Serial table
Next:PSerialDevice; Next entry in Serial table

Serial logging

PSerialLogging = ^TSerialLogging;

TSerialLogging = record

Logging Properties
Logging:TLoggingDevice;  
Serial Properties
Serial:PSerialDevice;  
BaudRate:LongWord;  
DataBits:LongWord;  
StopBits:LongWord;  
Parity:LongWord;  
FlowControl:LongWord;  


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 

procedure SerialInit;
Description: Initialize the Serial unit and Serial device table
Note None documented


Serial functions 

function SerialDeviceOpen(Serial:PSerialDevice; BaudRate,DataBits,StopBits,Parity,FlowControl,ReceiveDepth,TransmitDepth:LongWord):LongWord;
Description: To be documented
Note None documented 


function SerialDeviceClose(Serial:PSerialDevice):LongWord;
Description: To be documented
Note None documented 


function SerialDeviceRead(Serial:PSerialDevice; Buffer:Pointer; Size,Flags:LongWord; var Count:LongWord):LongWord;
Description: To be documented
Note None documented 


function SerialDeviceWrite(Serial:PSerialDevice; Buffer:Pointer; Size,Flags:LongWord; var Count:LongWord):LongWord;
Description: To be documented
Note None documented 


function SerialDeviceStatus(Serial:PSerialDevice):LongWord;
Description: To be documented
Note None documented 


function SerialDeviceProperties(Serial:PSerialDevice; Properties:PSerialProperties):LongWord;
Description: To be documented
Note None documented 


function SerialDeviceCreate:PSerialDevice;
Description: Create a new Serial entry
Return Pointer to new Serial entry or nil if Serial could not be created 


function SerialDeviceCreateEx(Size:LongWord):PSerialDevice;
Description: Create a new Serial entry
Size Size in bytes to allocate for new Serial (Including the Serial entry)
Return Pointer to new Serial entry or nil if Serial could not be created 


function SerialDeviceDestroy(Serial:PSerialDevice):LongWord;
Description: Destroy an existing Serial entry
Note None documented 


function SerialDeviceRegister(Serial:PSerialDevice):LongWord;
Description: Register a new Serial in the Serial table
Note None documented 


function SerialDeviceDeregister(Serial:PSerialDevice):LongWord;
Description: Deregister a Serial from the Serial table
Note None documented 


function SerialDeviceFind(SerialId:LongWord):PSerialDevice;
Description: To be documented
Note None documented 


function SerialDeviceFindByName(const Name:String):PSerialDevice; inline;
Description: To be documented
Note None documented 


function SerialDeviceFindByDescription(const Description:String):PSerialDevice; inline;
Description: To be documented
Note None documented 


function SerialDeviceEnumerate(Callback:TSerialEnumerate; Data:Pointer):LongWord;
Description: To be documented
Note None documented 


function SerialDeviceNotification(Serial:PSerialDevice; Callback:TSerialNotification; Data:Pointer; Notification,Flags:LongWord):LongWord;
Description: To be documented
Note None documented


Serial logging functions 

function SerialLoggingStart(Logging:PLoggingDevice):LongWord;
Description: To be documented
Note None documented 


function SerialLoggingStop(Logging:PLoggingDevice):LongWord;
Description: To be documented
Note None documented 


function SerialLoggingOutput(Logging:PLoggingDevice; const Data:String):LongWord;
Description: To be documented
Note None documented


RTL serial functions 

function SysSerialAvailable:Boolean;
Description: Check if a Serial device is available
Note None documented 


function SysSerialOpen(BaudRate,DataBits,StopBits,Parity,FlowControl,ReceiveDepth,TransmitDepth:LongWord):LongWord;
Description: Open the default Serial device ready for sending and receiving
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)
ReceiveDepth Size of the receive buffer (0 = Default size)
TransmitDepth Size of the transmit buffer (0 = Default size) 


function SysSerialClose:LongWord;
Description: Close the default Serial device and terminate sending and receiving
Note None documented 


function SysSerialRead(Buffer:Pointer; Size:LongWord; var Count:LongWord):LongWord;
Description: Read data from the default Serial device
Buffer Pointer to a buffer to receive the data
Size The size of the buffer
Count The number of bytes read on return 


function SysSerialWrite(Buffer:Pointer; Size:LongWord; var Count:LongWord):LongWord;
Description: Write data to the default Serial device
Buffer Pointer to a buffer of data to transmit
Size The size of the buffer
Count The number of bytes written on return


Serial helper functions 

function SerialGetCount:LongWord; inline;
Description: Get the current Serial count
Note None documented 


function SerialDeviceGetDefault:PSerialDevice; inline;
Description: Get the current default Serial device
Note None documented 


function SerialDeviceSetDefault(Serial:PSerialDevice):LongWord;
Description: Set the current default Serial device
Note None documented 


function SerialDeviceCheck(Serial:PSerialDevice):PSerialDevice;
Description: Check if the supplied Serial is in the Serial table
Note None documented 


function SerialBufferReadStart(Buffer:PSerialBuffer; var Available:LongWord):Pointer;
Description: Return a pointer to the next read from the buffer and the number of bytes that can be read
Note Caller must hold the lock on the serial device which owns the buffer 


function SerialBufferReadComplete(Buffer:PSerialBuffer; Removed:LongWord):Boolean;
Description: Update the buffer to reflect the number of bytes removed when reading
Note Caller must hold the lock on the serial device which owns the buffer 


function SerialBufferWriteStart(Buffer:PSerialBuffer; var Available:LongWord):Pointer;
Description: Return a pointer to the next write to the buffer and the number of bytes that can be written
Note Caller must hold the lock on the serial device which owns the buffer 


function SerialBufferWriteComplete(Buffer:PSerialBuffer; Added:LongWord):Boolean;
Description: Update the buffer to reflect the number of bytes added when writing
Note Caller must hold the lock on the serial device which owns the buffer 


procedure SerialLog(Level:LongWord; Serial:PSerialDevice; const AText:String);
Description: To be documented
Note None documented 


procedure SerialLogInfo(Serial:PSerialDevice; const AText:String); inline;
Description: To be documented
Note None documented 


procedure SerialLogError(Serial:PSerialDevice; const AText:String); inline;
Description: To be documented
Note None documented 


procedure SerialLogDebug(Serial:PSerialDevice; const AText:String); inline;
Description: To be documented
Note None documented 


function SerialParityToString(Parity:LongWord):String;
Description: To be documented
Note None documented 


function SerialFlowControlToString(Flow:LongWord):String;
Description: To be documented
Note None documented


Serial logging helper functions 

function SerialLoggingDeviceAdd(Serial:PSerialDevice):LongWord;
Description: To be documented
Note None documented 


function SerialLoggingDeviceRemove(Serial:PSerialDevice):LongWord;
Description: To be documented
Note None documented 


function SerialLoggingDeviceParameters(Serial:PSerialDevice; const Parameters:String; var BaudRate,Parity,DataBits,StopBits:LongWord):LongWord;
Description: Break down the serial parameters value into component parts of baud rate, parity, data bits and stop bits
Note The parameters must be in the form 'BaudRate,Parity,DataBits,StopBits' (eg '115200,N,8,1') 


function SerialLoggingFirstWord(var Value:String;const Delimiter:String):String;
Description: To be documented
Note None documented 


function SerialLoggingDeviceEnum(Serial:PSerialDevice; Data:Pointer):LongWord;
Description: To be documented
Note None documented 


function SerialLoggingDeviceNotify(Device:PDevice; Data:Pointer; Notification:LongWord):LongWord;
Description: To be documented
Note None documented


Return to Unit Reference

Retrieved from "https://ultibo.org/mediawiki_ultibo_org/index.php?title=Unit_Serial&oldid=3268"