Unit Serial

From Ultibo.org
Revision as of 03:15, 7 October 2016 by Ultibo (Talk | contribs)

Jump to: navigation, search

Return to Unit Reference


Description


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


To be documented

Type definitions


To be documented

Public variables


To be documented

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 ?rom 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 ?rom 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 ?rom 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