Difference between revisions of "Unit Serial"

Revision as of 05:28, 26 March 2018

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 wait directions SERIAL_WAIT_*

`SERIAL_WAIT_NONE = 0;`
`SERIAL_WAIT_RECEIVE = 1;`	Wait for data to be available in the receive buffer
`SERIAL_WAIT_TRANSMIT = 2;`	Wait for space to be available in the transmit buffer

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_WARN = LOG_LEVEL_WARN;`	Serial warning messages
`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 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

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)
`DeviceWait:TSerialDeviceWait;`	A Device specific DeviceWait method implementing the standard Serial device interface (Or nil if the default method is suitable)
`DeviceFlush:TSerialDeviceFlush;`	A Device specific DeviceFlush method implementing the standard Serial device interface (Or nil if the default method is suitable)
`DeviceGetStatus:TSerialDeviceGetStatus;`	A Device specific DeviceGetStatus method implementing the standard Serial device interface (Or nil if the default method is suitable)
`DeviceSetStatus:TSerialDeviceSetStatus;`	A Device specific DeviceSetStatus method implementing the standard Serial device interface (Optional)
`DeviceGetProperties:TSerialDeviceGetProperties;`	A Device specific DeviceGetProperties method implementing the standard Serial device interface (Or nil if the default method is suitable)
`DeviceSetProperties:TSerialDeviceSetProperties;`	A Device specific DeviceSetProperties 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: Open a Serial device ready for sending and receiving

Serial	The Serial device to open
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)
Transmit Depth	Size of the transmit buffer (0 = Default size)
Return	ERROR_SUCCESS if completed or another error code on failure

function SerialDeviceClose(Serial:PSerialDevice):LongWord;

Description: Close a Serial device and terminate sending and receiving

Serial	The Serial device to close
Note	ERROR_SUCCESS if completed or another error code on failure

function SerialDeviceRead(Serial:PSerialDevice; Buffer:Pointer; Size,Flags:LongWord; var Count:LongWord):LongWord;

Description: Read data from a Serial device

Serial	The Serial device to read from
Buffer	Pointer to a buffer to receive the data
Size	The size of the buffer
Flags	The flags to control reading (eg SERIAL_READ_NON_BLOCK)
Count	The number of bytes read on return
Return	ERROR_SUCCESS if completed or another error code on failure

function SerialDeviceWrite(Serial:PSerialDevice; Buffer:Pointer; Size,Flags:LongWord; var Count:LongWord):LongWord;

Description: Write data to a Serial device

Serial	The Serial device to write to
Buffer	Pointer to a buffer of data to transmit
Size	The size of the buffer
Flags	The flags to control writing (eg SERIAL_WRITE_NON_BLOCK)
Count	The number of bytes written on return
Return	ERROR_SUCCESS if completed or another error code on failure

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

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	ERROR_SUCCESS if completed or another error code on failure

function SerialDeviceFlush(Serial:PSerialDevice; Flags:LongWord):LongWord;

Description: Discard the contents of the receive and/or transmit buffers of a Serial device

Serial	The Serial device to flush
Flags	The flags to indicate what to flush (eg SERIAL_FLUSH_RECEIVE)
Return	ERROR_SUCCESS if completed or another error code on failure

function SerialDeviceStatus(Serial:PSerialDevice):LongWord; inline;

Description: Get the current line status of a Serial device

Serial	The Serial device to get the status from
Return	A set of flags containing the device status (eg SERIAL_STATUS_RTS)

function SerialDeviceGetStatus(Serial:PSerialDevice):LongWord;

Description: Get the current line status of a Serial device

Serial	The Serial device to get the status from
Return	A set of flags containing the device status (eg SERIAL_STATUS_RTS)

function SerialDeviceSetStatus(Serial:PSerialDevice; Status:LongWord):LongWord;

Description: Set the current line status of a Serial device

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

function SerialDeviceProperties(Serial:PSerialDevice; Properties:PSerialProperties):LongWord; inline;

Description: Get the properties for the specified Serial device

Serial	The Serial device to get properties from
Properties	Pointer to a PSerialProperties structure to fill in
Return	ERROR_SUCCESS if completed or another error code on failure
Note	Replaced by SerialDeviceGetProperties for consistency

function SerialDeviceGetProperties(Serial:PSerialDevice; Properties:PSerialProperties):LongWord;

Description: Get the properties for the specified Serial device

Serial	The Serial device to get properties from
Properties	Pointer to a PSerialProperties structure to fill in
Return	ERROR_SUCCESS if completed or another error code on failure

function SerialDeviceSetProperties(Serial:PSerialDevice; Properties:PSerialProperties):LongWord;

Description: Set the properties for the specified Serial device

Serial	The Serial device to set properties for
Properties	Pointer to a PSerialProperties structure to use
Return	ERROR_SUCCESS if completed or another error code on failure

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

Serial	The serial device to destroy
Return	ERROR_SUCCESS if completed or another error code on failure

function SerialDeviceRegister(Serial:PSerialDevice):LongWord;

Description: Register a new Serial in the Serial table

Serial	The serial device to register
Return	ERROR_SUCCESS if completed or another error code on failure

function SerialDeviceDeregister(Serial:PSerialDevice):LongWord;

Description: Deregister a Serial from the Serial table

Serial	The serial device to deregister
Return	ERROR_SUCCESS if completed or another error code on failure

function SerialDeviceFind(SerialId:LongWord):PSerialDevice;

Description: Find a serial device by Id in the serial table

SerialId	The Id number of the serial to find
Return	Pointer to serial device entry or nil if not found

function SerialDeviceFindByName(const Name:String):PSerialDevice; inline;

Description: Find a serial device by name in the serial table

Name	The name of the serial to find (eg Serial0)
Return	Pointer to serial device entry or nil if not found

function SerialDeviceFindByDescription(const Description:String):PSerialDevice; inline;

Description: Find a serial device by description in the serial table

Description	The description of the serial to find (eg BCM2836 PL011 UART)
Return	Pointer to serial device entry or nil if not found

function SerialDeviceEnumerate(Callback:TSerialEnumerate; Data:Pointer):LongWord;

Description: Enumerate all serial devices in the serial table

Callback	The callback function to call for each serial in the table
Data	A private data pointer to pass to callback for each serial in the table
Return	ERROR_SUCCESS if completed or another error code on failure

function SerialDeviceNotification(Serial:PSerialDevice; Callback:TSerialNotification; Data:Pointer; Notification,Flags:LongWord):LongWord;

Description: Register a notification for serial device changes

Serial	The serial device to notify changes for (Optional, pass nil for all serial devices)
Callback	The function to call when a notification event occurs
Data	A private data pointer to pass to callback when a notification event occurs
Notification	The events to register for notification of (eg DEVICE_NOTIFICATION_REGISTER)
Flags	The flags to control the notification (eg NOTIFIER_FLAG_WORKER)

Serial logging functions

function SerialLoggingStart(Logging:PLoggingDevice):LongWord;

Description: Implementation of LoggingDeviceStart API for Serial Logging

Note	Not intended to be called directly by applications, use LoggingDeviceStart instead

function SerialLoggingStop(Logging:PLoggingDevice):LongWord;

Description: Implementation of LoggingDeviceStop API for Serial Logging

Note	Not intended to be called directly by applications, use LoggingDeviceStop instead

function SerialLoggingOutput(Logging:PLoggingDevice; const Data:String):LongWord;

Description: Implementation of LoggingDeviceOutput API for Serial Logging

Note	Not intended to be called directly by applications, use LoggingDeviceOutput instead

RTL text IO functions

function SysTextIOReadChar(var ACh:Char; AUserData:Pointer):Boolean;

Description: Handler for platform TextIOReadChar function

Note	Not intended to be called directly by applications

function SysTextIOWriteChar(ACh:Char; AUserData:Pointer):Boolean;

Description: Handler for platform TextIOWriteChar function

Note	Not intended to be called directly by applications

function SysTextIOWriteBuffer(ABuffer:PChar; ACount:LongInt; AUserData:Pointer):LongInt;

Description: Handler for platform TextIOWriteBuffer function

Note	Not intended to be called directly by applications

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 SerialDeviceRedirectInput(Serial:PSerialDevice):Boolean;

Description: Redirect standard input to the serial device specified by Serial

Serial	The serial device to redirect input to (or nil to stop redirection)
Return	True if completed successfully or False if an error occurred
Note	Redirects the input of the text file Input which also redirects the input of Read, ReadLn and the standard C library

function SerialDeviceRedirectOutput(Serial:PSerialDevice):Boolean;

Description: Redirect standard output to the serial device specified by Serial

Serial	The serial device to redirect output to (or nil to stop redirection)
Return	True if completed successfully or False if an error occurred
Note	Redirects the output of the text files Output, ErrOutput, StdOut and StdErr which also redirects the output of Write, WriteLn and the standard C library

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 SerialLogWarn(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: Add a new serial logging device on receipt of a device register notification

Note	None documented

function SerialLoggingDeviceRemove(Serial:PSerialDevice):LongWord;

Description: Remove a serial logging device on receipt of a device deregister notification

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: Enumeration callback for serial logging initialization

Note	Not intended to be called directly by applications

function SerialLoggingDeviceNotify(Device:PDevice; Data:Pointer; Notification:LongWord):LongWord;

Description: Notification callback for serial logging device creation or remove

Note	Not intended to be called directly by applications

Return to Unit Reference

Difference between revisions of "Unit Serial"

Revision as of 05:28, 26 March 2018

Contents

Description

Constants

Type definitions

Public variables

Function declarations

Navigation menu

Personal tools

Namespaces

Variants

Views

More

Search

Navigation

Tools

@@ Line 172: / Line 172: @@
 | <code>SERIAL_WRITE_PEEK_BUFFER = $00000002;</code>
 | 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>
+| &nbsp;
+|-
+| <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>
 | 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>
@@ Line 398: / Line 418: @@
 |-
 | <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%;"|
 |-
@@ Line 411: / Line 440: @@
 |}
-'''Serial device status'''
+'''Serial device get status'''
 {| class="wikitable" style="font-size: 14px; text-align: left; width: 100%; height: 50px;"
 |-
-| <code>TSerialDeviceStatus = function(Serial:PSerialDevice):LongWord;</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%;"|
 |-
@@ 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'''
@@ Line 466: / Line 513: @@
 | A Device specific DeviceWrite method implementing the standard Serial device interface (Mandatory)
 |-
-| <code>DeviceStatus:TSerialDeviceStatus;</code>
+| <code>DeviceWait:TSerialDeviceWait;</code>
-| A Device specific DeviceStatus method implementing the standard Serial device interface (Or nil if the default method is suitable)
+| 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>
 | 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''
@@ Line 694: / Line 753: @@
 ! '''Count'''
 | 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'''
@@ Line 720: / Line 803: @@
 <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 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 class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
@@ Line 730: / Line 813: @@
 ! '''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 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'''
 | 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'''
@@ 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;">
 <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 class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">