Unit Serial

From Ultibo.org
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 accommodated 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



[Expand]
Serial specific constants SERIAL_*


[Expand]
Serial device type SERIAL_TYPE_*


[Expand]
Serial device state SERIAL_STATE_*


[Expand]
Serial device flag SERIAL_FLAG_*


[Expand]
Serial read flag SERIAL_READ_*


[Expand]
Serial write flag SERIAL_WRITE_*


[Expand]
Serial wait directions SERIAL_WAIT_*


[Expand]
Serial flush flag SERIAL_FLUSH_*


[Expand]
Serial status flag SERIAL_STATUS_*


[Expand]
Serial logging SERIAL_LOG_*


Type definitions



Serial properties

[Expand]

PSerialProperties = ^TSerialProperties;

TSerialProperties = record

Serial buffer

[Expand]

PSerialBuffer = ^TSerialBuffer;

TSerialBuffer = record

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

[Expand]

PSerialDevice = ^TSerialDevice;

TSerialDevice = record

Serial logging

[Expand]

PSerialLogging = ^TSerialLogging;

TSerialLogging = record


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

[Expand]
procedure SerialInit;
Description: Initialize the Serial unit and Serial device table


Serial functions

[Expand]
function SerialDeviceOpen(Serial:PSerialDevice; BaudRate,DataBits,StopBits,Parity,FlowControl,ReceiveDepth,TransmitDepth:LongWord):LongWord;
Description: Open a Serial device ready for sending and receiving


[Expand]
function SerialDeviceClose(Serial:PSerialDevice):LongWord;
Description: Close a Serial device and terminate sending and receiving


[Expand]
function SerialDeviceRead(Serial:PSerialDevice; Buffer:Pointer; Size,Flags:LongWord; var Count:LongWord):LongWord;
Description: Read data from a Serial device


[Expand]
function SerialDeviceWrite(Serial:PSerialDevice; Buffer:Pointer; Size,Flags:LongWord; var Count:LongWord):LongWord;
Description: Write data to a Serial device


[Expand]
function SerialDeviceWait(Serial:PSerialDevice; Direction,Timeout:LongWord; var Count:LongWord):LongWord;
Description: Wait for data to be available in the receive or transmit buffers of a Serial device


[Expand]
function SerialDeviceFlush(Serial:PSerialDevice; Flags:LongWord):LongWord;
Description: Discard the contents of the receive and/or transmit buffers of a Serial device


[Expand]
function SerialDeviceStatus(Serial:PSerialDevice):LongWord; inline;
Description: Get the current line status of a Serial device


[Expand]
function SerialDeviceGetStatus(Serial:PSerialDevice):LongWord;
Description: Get the current line status of a Serial device


[Expand]
function SerialDeviceSetStatus(Serial:PSerialDevice; Status:LongWord):LongWord;
Description: Set the current line status of a Serial device


[Expand]
function SerialDeviceProperties(Serial:PSerialDevice; Properties:PSerialProperties):LongWord; inline;
Description: Get the properties for the specified Serial device


[Expand]
function SerialDeviceGetProperties(Serial:PSerialDevice; Properties:PSerialProperties):LongWord;
Description: Get the properties for the specified Serial device


[Expand]
function SerialDeviceSetProperties(Serial:PSerialDevice; Properties:PSerialProperties):LongWord;
Description: Set the properties for the specified Serial device


[Expand]
function SerialDeviceCreate:PSerialDevice;
Description: Create a new Serial entry


[Expand]
function SerialDeviceCreateEx(Size:LongWord):PSerialDevice;
Description: Create a new Serial entry


[Expand]
function SerialDeviceDestroy(Serial:PSerialDevice):LongWord;
Description: Destroy an existing Serial entry


[Expand]
function SerialDeviceRegister(Serial:PSerialDevice):LongWord;
Description: Register a new Serial in the Serial table


[Expand]
function SerialDeviceDeregister(Serial:PSerialDevice):LongWord;
Description: Deregister a Serial from the Serial table


[Expand]
function SerialDeviceFind(SerialId:LongWord):PSerialDevice;
Description: Find a serial device by Id in the serial table


[Expand]
function SerialDeviceFindByName(const Name:String):PSerialDevice; inline;
Description: Find a serial device by name in the serial table


[Expand]
function SerialDeviceFindByDescription(const Description:String):PSerialDevice; inline;
Description: Find a serial device by description in the serial table


[Expand]
function SerialDeviceEnumerate(Callback:TSerialEnumerate; Data:Pointer):LongWord;
Description: Enumerate all serial devices in the serial table


[Expand]
function SerialDeviceNotification(Serial:PSerialDevice; Callback:TSerialNotification; Data:Pointer; Notification,Flags:LongWord):LongWord;
Description: Register a notification for serial device changes


Serial logging functions

[Expand]
function SerialLoggingStart(Logging:PLoggingDevice):LongWord;
Description: Implementation of LoggingDeviceStart API for Serial Logging


[Expand]
function SerialLoggingStop(Logging:PLoggingDevice):LongWord;
Description: Implementation of LoggingDeviceStop API for Serial Logging


[Expand]
function SerialLoggingOutput(Logging:PLoggingDevice; const Data:String):LongWord;
Description: Implementation of LoggingDeviceOutput API for Serial Logging


[Expand]
function SerialLoggingSetTarget(Logging:PLoggingDevice; const Target:String):LongWord;
Description: Implementation of LoggingDeviceSetTarget API for Serial Logging


RTL text IO functions

[Expand]
function SysTextIOReadChar(var ACh:Char; AUserData:Pointer):Boolean;
Description: Handler for platform TextIOReadChar function


[Expand]
function SysTextIOWriteChar(ACh:Char; AUserData:Pointer):Boolean;
Description: Handler for platform TextIOWriteChar function


[Expand]
function SysTextIOWriteBuffer(ABuffer:PChar; ACount:LongInt; AUserData:Pointer):LongInt;
Description: Handler for platform TextIOWriteBuffer function


RTL serial functions

[Expand]
function SysSerialAvailable:Boolean;
Description: Check if a Serial device is available


[Expand]
function SysSerialOpen(BaudRate,DataBits,StopBits,Parity,FlowControl,ReceiveDepth,TransmitDepth:LongWord):LongWord;
Description: Open the default Serial device ready for sending and receiving


[Expand]
function SysSerialClose:LongWord;
Description: Close the default Serial device and terminate sending and receiving


[Expand]
function SysSerialRead(Buffer:Pointer; Size:LongWord; var Count:LongWord):LongWord;
Description: Read data from the default Serial device


[Expand]
function SysSerialWrite(Buffer:Pointer; Size:LongWord; var Count:LongWord):LongWord;
Description: Write data to the default Serial device


Serial helper functions

[Expand]
function SerialGetCount:LongWord;
Description: Get the current Serial count


[Expand]
function SerialDeviceGetDefault:PSerialDevice;
Description: Get the current default Serial device


[Expand]
function SerialDeviceSetDefault(Serial:PSerialDevice):LongWord;
Description: Set the current default Serial device


[Expand]
function SerialDeviceCheck(Serial:PSerialDevice):PSerialDevice;
Description: Check if the supplied Serial is in the Serial table


[Expand]
function SerialTypeToString(SerialType:LongWord):String;
Description: Convert a Serial type value to a string


[Expand]
function SerialStateToString(SerialState:LongWord):String;
Description: Convert a Serial state value to a string


[Expand]
function SerialDeviceRedirectInput(Serial:PSerialDevice):Boolean;
Description: Redirect standard input to the serial device specified by Serial


[Expand]
function SerialDeviceRedirectOutput(Serial:PSerialDevice):Boolean;
Description: Redirect standard output to the serial device specified by Serial


[Expand]
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


[Expand]
function SerialBufferReadComplete(Buffer:PSerialBuffer; Removed:LongWord):Boolean;
Description: Update the buffer to reflect the number of bytes removed when reading


[Expand]
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


[Expand]
function SerialBufferWriteComplete(Buffer:PSerialBuffer; Added:LongWord):Boolean;
Description: Update the buffer to reflect the number of bytes added when writing


[Expand]
procedure SerialLog(Level:LongWord; Serial:PSerialDevice; const AText:String);
Description: To be documented


[Expand]
procedure SerialLogInfo(Serial:PSerialDevice; const AText:String); inline;
Description: To be documented


[Expand]
procedure SerialLogWarn(Serial:PSerialDevice; const AText:String); inline;
Description: To be documented


[Expand]
procedure SerialLogError(Serial:PSerialDevice; const AText:String); inline;
Description: To be documented


[Expand]
procedure SerialLogDebug(Serial:PSerialDevice; const AText:String); inline;
Description: To be documented


[Expand]
function SerialDataBitsToString(Parity:LongWord):String;
Description: To be documented


[Expand]
function SerialStopBitsToString(Parity:LongWord):String;
Description: To be documented


[Expand]
function SerialParityToString(Parity:LongWord):String;
Description: To be documented


[Expand]
function SerialFlowControlToString(Flow:LongWord):String;
Description: To be documented


Serial logging helper functions

[Expand]
function SerialLoggingDeviceAdd(Serial:PSerialDevice):LongWord;
Description: Add a new serial logging device on receipt of a device register notification


[Expand]
function SerialLoggingDeviceRemove(Serial:PSerialDevice):LongWord;
Description: Remove a serial logging device on receipt of a device deregister notification


[Expand]
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


[Expand]
function SerialLoggingFirstWord(var Value:String;const Delimiter:String):String;
Description: To be documented


[Expand]
function SerialLoggingDeviceEnum(Serial:PSerialDevice; Data:Pointer):LongWord;
Description: Enumeration callback for serial logging initialization


[Expand]
function SerialLoggingDeviceNotify(Device:PDevice; Data:Pointer; Notification:LongWord):LongWord;
Description: Notification callback for serial logging device creation or remove


Return to Unit Reference