Difference between revisions of "Unit Serial"

From Ultibo.org
Jump to: navigation, search
Line 251: Line 251:
 
----
 
----
  
−
''To be documented''
+
 
 +
'''Serial properties'''
 +
 
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial;">
 +
<code>PSerialProperties = ^TSerialProperties;</code>
 +
 
 +
<code>TSerialProperties = record</code>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
| <code>Flags:LongWord;</code>
 +
| Device flags (eg SERIAL_FLAG_DATA_8BIT)
 +
|-
 +
| <code>MinRate:LongWord;</code>
 +
| Minimum supported baud rate (0 for any rate supported)
 +
|-
 +
| <code>MaxRate:LongWord;</code>
 +
| Maximum supported baud rate (0 for any rate supported)
 +
|-
 +
| <code>BaudRate:LongWord;</code>
 +
| Current baud rate setting
 +
|-
 +
| <code>DataBits:LongWord;</code>
 +
| Current data bits setting
 +
|-
 +
| <code>StopBits:LongWord;</code>
 +
| Current stop bits setting
 +
|-
 +
| <code>Parity:LongWord;</code>
 +
| Current parity setting
 +
|-
 +
| <code>FlowControl:LongWord;</code>
 +
| Current flow control setting
 +
|-
 +
| <code>ReceiveDepth:LongWord;</code>
 +
| Current receive depth setting
 +
|-
 +
| <code>TransmitDepth:LongWord;</code>
 +
| Current transmit depth setting
 +
|-
 +
|}
 +
</div></div>
 +
 
 +
'''Serial buffer'''
 +
 
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial;">
 +
<code>PSerialBuffer = ^TSerialBuffer;</code>
 +
 
 +
<code>TSerialBuffer = record</code>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
| <code>Wait:TEventHandle;</code>
 +
| Data ready / Buffer free event
 +
|-
 +
| <code>Start:LongWord;</code>
 +
| Index of first byte in buffer
 +
|-
 +
| <code>Count:LongWord;</code>
 +
| Number of bytes in buffer
 +
|-
 +
| <code>Size:LongWord;</code>
 +
| Size of buffer
 +
|-
 +
| <code>Data:Pointer;</code>
 +
| Buffered data
 +
|-
 +
|}
 +
</div></div>
 +
 
 +
'''Serial enumeration callback'''
 +
 
 +
{| class="wikitable" style="font-size: 14px; text-align: left; width: 100%; height: 50px;"
 +
|-
 +
| <code>TSerialEnumerate = function(Serial:PSerialDevice; Data:Pointer):LongWord;</code>
 +
| style="width: 40%;"|
 +
|-
 +
|}
 +
 
 +
'''Serial notification callback'''
 +
 
 +
{| class="wikitable" style="font-size: 14px; text-align: left; width: 100%; height: 50px;"
 +
|-
 +
| <code>TSerialNotification = function(Device:PDevice; Data:Pointer; Notification:LongWord):LongWord;</code>
 +
| style="width: 40%;"|
 +
|-
 +
|}
 +
 
 +
'''Serial device open'''
 +
 
 +
{| class="wikitable" style="font-size: 14px; text-align: left; width: 100%; height: 50px;"
 +
|-
 +
| <code>TSerialDeviceOpen = function(Serial:PSerialDevice; BaudRate,DataBits,StopBits,Parity,FlowControl,ReceiveDepth,TransmitDepth:LongWord):LongWord;</code>
 +
| style="width: 40%;"|
 +
|-
 +
|}
 +
 
 +
'''Serial device close'''
 +
 
 +
{| class="wikitable" style="font-size: 14px; text-align: left; width: 100%; height: 50px;"
 +
|-
 +
| <code>TSerialDeviceClose = function(Serial:PSerialDevice):LongWord;</code>
 +
| style="width: 40%;"|
 +
|-
 +
|}
 +
 
 +
'''Serial device read'''
 +
 
 +
{| class="wikitable" style="font-size: 14px; text-align: left; width: 100%; height: 50px;"
 +
|-
 +
| <code>TSerialDeviceRead = function(Serial:PSerialDevice; Buffer:Pointer; Size,Flags:LongWord; var Count:LongWord):LongWord;</code>
 +
| style="width: 40%;"|
 +
|-
 +
|}
 +
 
 +
'''Serial device write'''
 +
 
 +
{| class="wikitable" style="font-size: 14px; text-align: left; width: 100%; height: 50px;"
 +
|-
 +
| <code>TSerialDeviceWrite = function(Serial:PSerialDevice; Buffer:Pointer; Size,Flags:LongWord; var Count:LongWord):LongWord;</code>
 +
| style="width: 40%;"|
 +
|-
 +
|}
 +
 
 +
'''Serial device status'''
 +
 
 +
{| class="wikitable" style="font-size: 14px; text-align: left; width: 100%; height: 50px;"
 +
|-
 +
| <code>TSerialDeviceStatus = function(Serial:PSerialDevice):LongWord;</code>
 +
| style="width: 40%;"|
 +
|-
 +
|}
 +
 
 +
'''Serial device properties'''
 +
 
 +
{| class="wikitable" style="font-size: 14px; text-align: left; width: 100%; height: 50px;"
 +
|-
 +
| <code>TSerialDeviceProperties = function(Serial:PSerialDevice; Properties:PSerialProperties):LongWord;</code>
 +
| style="width: 40%;"|
 +
|-
 +
|}
 +
 
 +
'''Serial device'''
 +
 
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial;">
 +
<code>PSerialDevice = ^TSerialDevice;</code>
 +
 
 +
<code>TSerialDevice = record</code>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
|colspan="2"|''Device Properties''
 +
|-
 +
| <code>Device:TDevice;</code>
 +
| The Device entry for this Serial
 +
|-
 +
|colspan="2"|''Serial Properties''
 +
|-
 +
| <code>SerialId:LongWord;</code>
 +
| Unique Id of this Serial device in the Serial device table
 +
|-
 +
| <code>SerialState:LongWord;</code>
 +
| Serial state (eg SERIAL_STATE_OPEN)
 +
|-
 +
| <code>SerialStatus:LongWord;</code>
 +
| Serial status (eg SERIAL_STATUS_RX_FULL)(May not be real time status depending on the driver)
 +
|-
 +
| <code>DeviceOpen:TSerialDeviceOpen;</code>
 +
| A Device specific DeviceOpen method implementing the standard Serial device interface (Mandatory)
 +
|-
 +
| <code>DeviceClose:TSerialDeviceClose;</code>
 +
| A Device specific DeviceClose method implementing the standard Serial device interface (Mandatory)
 +
|-
 +
| <code>DeviceRead:TSerialDeviceRead;</code>
 +
| A Device specific DeviceRead method implementing the standard Serial device interface (Mandatory)
 +
|-
 +
| <code>DeviceWrite:TSerialDeviceWrite;</code>
 +
| A Device specific DeviceWrite method implementing the standard Serial device interface (Mandatory)
 +
|-
 +
| <code>DeviceStatus:TSerialDeviceStatus;</code>
 +
| A Device specific DeviceStatus method implementing the standard Serial device interface (Or nil if the default method is suitable)
 +
|-
 +
| <code>DeviceProperties:TSerialDeviceProperties;</code>
 +
| A Device specific DeviceProperties method implementing the standard Serial device interface (Or nil if the default method is suitable)
 +
|-
 +
|colspan="2"|''Driver Properties''
 +
|-
 +
| <code>Lock:TMutexHandle;</code>
 +
| Device lock
 +
|-
 +
| <code>Receive:TSerialBuffer;</code>
 +
| Serial receive buffer
 +
|-
 +
| <code>Transmit:TSerialBuffer;</code>
 +
| Serial transmit buffer
 +
|-
 +
| <code>Properties:TSerialProperties;</code>
 +
| Device properties
 +
|-
 +
|colspan="2"|''Statistics Properties''
 +
|-
 +
| <code>ReceiveCount:LongWord;</code>
 +
| &nbsp;
 +
|-
 +
| <code>ReceiveErrors:LongWord;</code>
 +
| &nbsp;
 +
|-
 +
| <code>ReceiveOverruns:LongWord;</code>
 +
| &nbsp;
 +
|-
 +
| <code>TransmitCount:LongWord;</code>
 +
| &nbsp;
 +
|-
 +
| <code>TransmitErrors:LongWord;</code>
 +
| &nbsp;
 +
|-
 +
| <code>TransmitOverruns:LongWord;</code>
 +
| &nbsp;
 +
|-
 +
|colspan="2"|''Internal Properties''
 +
|-
 +
| <code>Prev:PSerialDevice;</code>
 +
| Previous entry in Serial table
 +
|-
 +
| <code>Next:PSerialDevice;</code>
 +
| Next entry in Serial table
 +
|-
 +
|}
 +
</div></div> 
 +
 
 +
'''Serial logging'''
 +
 
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial;">
 +
<code>PSerialLogging = ^TSerialLogging;</code>
 +
 
 +
<code>TSerialLogging = record</code>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
|colspan="2"|''Logging Properties''
 +
|-
 +
| <code>Logging:TLoggingDevice;</code>
 +
| style="width: 50%;"|&nbsp;
 +
|-
 +
|colspan="2"|''Serial Properties''
 +
|-
 +
| <code>Serial:PSerialDevice;</code>
 +
| &nbsp;
 +
|-
 +
| <code>BaudRate:LongWord;</code>
 +
| &nbsp;
 +
|-
 +
| <code>DataBits:LongWord;</code>
 +
| &nbsp;
 +
|-
 +
| <code>StopBits:LongWord;</code>
 +
| &nbsp;
 +
|-
 +
| <code>Parity:LongWord;</code>
 +
| &nbsp;
 +
|-
 +
| <code>FlowControl:LongWord;</code>
 +
| &nbsp;
 +
|-
 +
|}
 +
</div></div>
 +
<br />
  
 
=== Public variables ===
 
=== Public variables ===

Revision as of 03:21, 25 January 2017

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


[Expand]
Serial specific constants SERIAL_*


[Expand]
Serial device type constants SERIAL_TYPE_*


[Expand]
Serial device state constants SERIAL_STATE_*


[Expand]
Serial device flag constants SERIAL_FLAG_*


[Expand]
Serial read flag constants SERIAL_READ_*


[Expand]
Serial write flag constants SERIAL_WRITE_*


[Expand]
Serial status flag constants SERIAL_STATUS_*


[Expand]
Serial logging constants SERIAL_LOG_*


[Expand]
Serial logging specific constants SERIAL_LOGGING_*


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 status

TSerialDeviceStatus = function(Serial:PSerialDevice):LongWord;

Serial device properties

TSerialDeviceProperties = 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: To be documented


[Expand] 
function SerialDeviceClose(Serial:PSerialDevice):LongWord;
Description: To be documented


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


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


[Expand] 
function SerialDeviceStatus(Serial:PSerialDevice):LongWord;
Description: To be documented


[Expand] 
function SerialDeviceProperties(Serial:PSerialDevice; Properties:PSerialProperties):LongWord;
Description: To be documented


[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: To be documented


[Expand] 
function SerialDeviceFindByName(const Name:String):PSerialDevice; inline;
Description: To be documented


[Expand] 
function SerialDeviceFindByDescription(const Description:String):PSerialDevice; inline;
Description: To be documented


[Expand] 
function SerialDeviceEnumerate(Callback:TSerialEnumerate; Data:Pointer):LongWord;
Description: To be documented


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


Serial logging functions

[Expand] 
function SerialLoggingStart(Logging:PLoggingDevice):LongWord;
Description: To be documented


[Expand] 
function SerialLoggingStop(Logging:PLoggingDevice):LongWord;
Description: To be documented


[Expand] 
function SerialLoggingOutput(Logging:PLoggingDevice; const Data:String):LongWord;
Description: To be documented


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; inline;
Description: Get the current Serial count


[Expand] 
function SerialDeviceGetDefault:PSerialDevice; inline;
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 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 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 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: To be documented


[Expand] 
function SerialLoggingDeviceRemove(Serial:PSerialDevice):LongWord;
Description: To be documented


[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: To be documented


[Expand] 
function SerialLoggingDeviceNotify(Device:PDevice; Data:Pointer; Notification:LongWord):LongWord;
Description: To be documented


Return to Unit Reference

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