The low-level driver (LLD) is responsible to forward Tx messages from the UNICENS library to the INIC and Rx messages from the INIC to the UNICENS library. The UNICENS library currently provides one interface to exchange control messages with the INIC. Therefore, the control messages will be wrapped in a so called Port Message. The low-level driver is responsible to transmit and receive the Port Messages over the interface that is adjusted in the INIC Configuration String.
The following example shows how to assign low-level driver functions which are invoked by the UNICENS library.
See also Getting Started, section Initialization. |
The exemplary implementation of callback functions refers the following local data. In order to call UNICENS API functions the low-level driver has to store a set of callback functions and an internal handle which is required to invoke a callback function.
The UNICENS library invokes the mandatory callback functions start_fptr()
and stop_fptr()
to signal when internal data is valid and the LLD may access UNICENS callback functions and message objects for transmission and reception.
The function Lld_SysInitialize()
is not called by the UNICENS library. This example function is system specific and might be necessary to set local data to definite values and to initialize the device driver before UNICENS library will start to transmit and receive.
The low-level driver is allowed to initialize and run the communication with the INIC before the UNICENS Library calls Lld_Start()
. While the UNICENS callback functions are invalid, it is recommended to discard incoming Rx messages.
Before leaving the function Lld_Stop()
the LLD must ensure not accessing UCS memory and callback functions any longer.
The low-level driver must implement a transmit function which requires a reference to Ucs_Lld_TxMsg_t. The code section below shows the declaration of the Ucs_Lld_TxMsg_t and the referred Ucs_Mem_Buffer_t type. The Ucs_Mem_Buffer_t structure contains values to describe the pointer and the size of the buffer. Furthermore it is possible that one buffer refers a second buffer if next_buffer_ptr is set. This means that it is possible to concatenate multiple buffers. Furthermore, one message structure refers a buffer structure. The custom_next_msg_ptr
is not set by UNICENS library. It can be used by the Low Level Driver to concatenate messages, e.g. for asynchronous transmission.
The transmit function shall copy the data from the memory buffers to the target buffer. Therefore, the low-level driver has to iterate over all buffers. After the low-level driver does no longer refer the message object, it has to call tx_release_fptr
. It is important to call tx_release_fptr
in the same order as the messages are passed to the transmit function.
custom_next_msg_ptr
. If the LLD detects an unrecoverable transmission error the LLD shall abort the transmission and call tx_release_fptr()
.See also API Reference, sections Low-Level Driver and Ucs_Lld_Api_t. |
The low-level driver has to forward messages to the UNICENS library by calling rx_allocate_fptr()
and rx_receive_fptr()
. The structure of the provided Rx message object is shown in the code section below.
If rx_allocate_fptr()
returns a valid reference to a Ucs_Lld_RxMsg_t structure, the low-level driver has to copy the received message to the data_ptr
attribute. The value of data_size
is already set to the same value as initially stated to rx_allocate_fptr()
. After the copy operation, the low-level driver shall call rx_receive_fptr()
which hands the Rx message over to the UNICENS library.
See also API Reference, sections Low-Level Driver and Ucs_Lld_Api_t. |