2.0.0.4R9
Software Development Kit
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules
Serial Line

Data Structures

struct  input_stream_from_uart
 Concrete struct for a Serial Line input stream. More...
 
struct  ltrx_line_capabilities
 Represents capabilities of a Serial Line. More...
 
struct  ltrx_line_driver
 API's for a serial line driver. More...
 
struct  ltrx_line_protocol
 Represents a line protocol for registration. More...
 
struct  output_stream_to_uart
 Concrete struct for a Serial Line output stream. More...
 

Macros

#define LINE_REGISTRATION_FAILED   0xff
 Index out of range error code. More...
 

Functions

bool ltrx_input_stream_init_from_uart (struct input_stream_from_uart *inStream, unsigned int zeroBasedIndex)
 Set up an input stream from a Serial Line. More...
 
void ltrx_line_close (uint16_t zeroBasedLine)
 Relinquish a line previously opened. More...
 
const struct
ltrx_line_capabilities
ltrx_line_get_capabilities (uint16_t zeroBasedLine)
 Gets the capabilities of the line. More...
 
bool ltrx_line_get_dsr (uint16_t zeroBasedLine, bool *dsr)
 Get DSR status. More...
 
uint8_t ltrx_line_get_registered_count (void)
 Get the count of registered lines. More...
 
const char * ltrx_line_get_registered_name (uint16_t zeroBasedLine)
 Get the registered name of a Line. More...
 
bool ltrx_line_open (uint16_t zeroBasedLine, uint32_t blockTimeMsec)
 Open a line for exclusive use. More...
 
void ltrx_line_purge (uint16_t zeroBasedLine)
 Purge data. More...
 
uint16_t ltrx_line_read (uint16_t zeroBasedLine, uint8_t **dataPointerLocation, size_t max_size, bool *optBreakDetected, uint32_t blockTimeMsec)
 Read data. More...
 
uint16_t ltrx_line_read_bytes_available (uint16_t zeroBasedLine, struct ltrx_trigger *optReadTrigger)
 How many bytes are available? More...
 
void ltrx_line_set_dtr (uint16_t zeroBasedLine, bool dtr)
 Set DTR value. More...
 
bool ltrx_line_write (uint16_t zeroBasedLine, const void *data, size_t size, struct ltrx_trigger *optWriteTrigger)
 Write data. More...
 
uint8_t ltrx_logical_line_driver_register (uint8_t numberOfLinesToRegister, const struct ltrx_line_driver *driver, const char **names)
 Register a driver for one or more logical Lines. More...
 
bool ltrx_output_stream_init_to_uart (struct output_stream_to_uart *outStream, unsigned int zeroBasedIndex)
 Set up an output stream to a Serial Line. More...
 

Detailed Description

The Serial Line refers to a Universal Asynchronous Receiver/Transmitter (UART) interface. These definitions relate to operation of the interface.

Macro Definition Documentation

#define LINE_REGISTRATION_FAILED   0xff

Index out of range error code.

This error code indicates the number of registered line is over the max number of lines allowed

Function Documentation

bool ltrx_input_stream_init_from_uart ( struct input_stream_from_uart inStream,
unsigned int  zeroBasedIndex 
)

Set up an input stream from a Serial Line.

Return values
trueSuccess.
falseFailed.
Parameters
[out]inStreamYour UART input stream struct to initialize.
[in]zeroBasedIndex0 for line 1, 1 for line 2, and so on.
void ltrx_line_close ( uint16_t  zeroBasedLine)

Relinquish a line previously opened.

Previously you would have called ltrx_line_open() and saw it return true. This will allow other threads to open the line.

Parameters
[in]zeroBasedLine0 for line 1, 1 for line 2, and so on.
const struct ltrx_line_capabilities* ltrx_line_get_capabilities ( uint16_t  zeroBasedLine)

Gets the capabilities of the line.

Returns
Capabilities of the designated Serial Line.
Parameters
[in]zeroBasedLine0 for line 1, 1 for line 2, and so on.
bool ltrx_line_get_dsr ( uint16_t  zeroBasedLine,
bool *  dsr 
)

Get DSR status.

Note that on some lines, a CP may need to be configured to read DSR.

Return values
trueThe result is in dsr.
falseNo DSR status was available.
Parameters
[in]zeroBasedLine0 for line 1, 1 for line 2, and so on.
[out]dsrDSR status: true for asserted.
uint8_t ltrx_line_get_registered_count ( void  )

Get the count of registered lines.

Returns the number of registered lines.

const char* ltrx_line_get_registered_name ( uint16_t  zeroBasedLine)

Get the registered name of a Line.

Returns
Name.
Return values
NULLFailed.
Parameters
[in]zeroBasedLine0 for line 1, 1 for line 2, and so on.
bool ltrx_line_open ( uint16_t  zeroBasedLine,
uint32_t  blockTimeMsec 
)

Open a line for exclusive use.

Warning: Check the return value even if you specify TIME_WAIT_FOREVER because your thread can return early if another thread calls ltrx_thread_wake().

Return values
trueSuccess.
falseFailed.
Parameters
[in]zeroBasedLine0 for line 1, 1 for line 2, and so on.
[in]blockTimeMsecHow long to wait if line is in use. To wait indefinitely, use TIME_WAIT_FOREVER.
void ltrx_line_purge ( uint16_t  zeroBasedLine)

Purge data.

Clears any data not yet read from the Serial Line and any data previously written but not yet sent out on the Serial Line.

Parameters
[in]zeroBasedLine0 for line 1, 1 for line 2, and so on.
uint16_t ltrx_line_read ( uint16_t  zeroBasedLine,
uint8_t **  dataPointerLocation,
size_t  max_size,
bool *  optBreakDetected,
uint32_t  blockTimeMsec 
)

Read data.

The number of bytes to be read will be limited by max_size, but this call will generally return with fewer bytes. The number of bytes is governed by the Line configured Gap Timer and Threshold.

If /c 0 bytes were read, your data pointer will not have been filled in, so do not attempt to reference it.

You are free to read the data under the data pointer until either your next call to ltrx_line_read() or ltrx_line_close().

Returns
Number of bytes sitting under the data pointer.
Parameters
[in]zeroBasedLine0 for line 1, 1 for line 2, and so on.
[out]dataPointerLocationPoints to a data pointer to be filled in.
[in]max_sizeMaximum bytes to read.
[out]optBreakDetectedOptional pointer to flag to detect line breaks.
[in]blockTimeMsecHow long to wait for data. To wait indefinitely, use TIME_WAIT_FOREVER.
uint16_t ltrx_line_read_bytes_available ( uint16_t  zeroBasedLine,
struct ltrx_trigger *  optReadTrigger 
)

How many bytes are available?

If optReadTrigger is not NULL, the trigger will later be signaled when data is available.

Returns
Number of bytes available to read.
Parameters
[in]zeroBasedLine0 for line 1, 1 for line 2, and so on.
[in]optReadTriggerOptional pointer to trigger.
void ltrx_line_set_dtr ( uint16_t  zeroBasedLine,
bool  dtr 
)

Set DTR value.

Note that on some lines, a CP may need to be configured to write DTR.

Parameters
[in]zeroBasedLine0 for line 1, 1 for line 2, and so on.
[in]dtrDTR value: true for asserted.
bool ltrx_line_write ( uint16_t  zeroBasedLine,
const void *  data,
size_t  size,
struct ltrx_trigger *  optWriteTrigger 
)

Write data.

If optWriteTrigger is NULL, this function blocks until the write is completed. Otherwise this routine returns without blocking and the trigger will later be signaled when the write has completed.

Return values
trueSuccess.
falseFailure.
Parameters
[in]zeroBasedLine0 for line 1, 1 for line 2, and so on.
[in]dataData to be written.
[in]sizeNumber of bytes under data to be written.
[in]optWriteTriggerOptional pointer to trigger.
uint8_t ltrx_logical_line_driver_register ( uint8_t  numberOfLinesToRegister,
const struct ltrx_line_driver driver,
const char **  names 
)

Register a driver for one or more logical Lines.

Return values
LINE_REGISTRATION_FAILEDFailed.
Returns
Index of the first Line.
Parameters
[in]numberOfLinesToRegisterNumber of Lines to be registered by this call. If more than one is requested and successfully registered, they will have sequential indices.
[in]driverStructure comprising the Line driver.
[in]namesArray containing the name for each Line being registered.
bool ltrx_output_stream_init_to_uart ( struct output_stream_to_uart outStream,
unsigned int  zeroBasedIndex 
)

Set up an output stream to a Serial Line.

Return values
trueSuccess.
falseFailed.
Parameters
[out]outStreamYour UART output stream struct to initialize.
[in]zeroBasedIndex0 for line 1, 1 for line 2, and so on.