In order to initialize the UNICENS library the application shall call Ucs_SetDefaultConfig(), modify the initialization structure and call Ucs_Init().
After calling Ucs_Init() the application is allowed to call the Basic API functions of the UNICENS library. The Basic API functions are required to drive the API. It is responsible to update timers and process internal events. The following functions are Basic API functions:
When the Ucs_Init() result callback notifies UCS_INIT_RES_SUCCESS, then the application is allowed to call the Basic API and all other API functions. After the UNICENS API notifies termination the application shall not call any API function but restart from scratch if required.
The following events will terminate the UNICENS API:
The most easiest and robust way of driving the UNICENS library is to call Ucs_Init() to initialize the API and call Ucs_Service() as long as the UNICENS library is running. If Ucs_Service() does not require to process internal events it returns and will consume few CPU load.
The UNICENS library can deal also with delays of 10 milliseconds or more between two calls of Ucs_Service(). Although, the UNICENS library can reach high performance results (for delays <= 10ms). However, depending on the LLD and system design the use of delays between two Ucs_Service() calls will mean that an application may also increase the number of LLD Tx and Rx buffer for the communication with the INIC. It is recommended to run individual tests with high and low message load to find a balanced setup.
A good compromise to balance a system can be the following approach:
A more efficient way of driving the UNICENS library is the Event Driven Service. In this mode the UNICENS library signals to the application when the next Service or Timer must be processed. Hence, the application can invoke the UNICENS API only if required. This decreases the CPU usage of UNICENS library to a minimum.
In order to run the Event Driven Service mode of the UNICENS library, the application must assign the following two callback functions in the initialization structure: general.request_service_fptr() and general.set_application_timer_fptr(). It is required that the application assigns both events callback functions. Otherwise, Ucs_Init() will return UCS_RET_ERR_PARAM.
A small example for Event Driven Service is printed below.
The implementation of the callback function App_OnServiceRequest()
should be rather simply. It must wakeup the process and signal that Ucs_Service() must be called.
The implementation of the callback function App_OnSetAppTimer()
must consider some particularities.
timeout
is "0", the application has to stop the reference timer.timeout
is ">0", the application has to stop the reference timer and restart it with the new value.