4.4 PLC Event Handling
Once the controller callbacks have been set up, the PL360 Host Controller component must be enabled. Then, the host MCU application is required to call the PL360 Host Controller API periodically to handle events from PL360 embedded firmware.
The PL360 Host Controller API allows the host MCU application to interact with the PL360 embedded firmware. To facilitate interaction, the PL360 Host Controller implements the host interface protocol described in section Host Interface Management. This protocol defines how to serialize and how to handle API requests and response callbacks over the SPI bus interface.
Some PL360 Host Controller APIs are synchronous function calls, whose return indicates that the requested action is completed. However, most API functions are asynchronous. This means that when the application calls an API to request a service, the call is non-blocking and returns immediately, usually before the requested action is completed. When the requested action is completed, a notification is provided in the form of a host interface protocol message from the PL360 embedded firmware to the PL360 Host Controller, which, in turn, delivers it to the application via callback functions. Asynchronous operation is essential when the requested service, such as a PLC message transmission, may take significant time to complete. In general, the PL360 embedded firmware uses asynchronous events to notify the host driver of status changes or pending data.
The PL360 device interrupts the host MCU when one or more events are pending in the PL360 embedded firmware. The host MCU application processes received data and events when the PL360 Host Controller calls the corresponding event callback function(s). In order to receive event callbacks, the host MCU application is required to periodically call the atpl360_handle_events function in the API.
When host MCU application calls atpl360_handle_events, the PL360 Host Controller checks for pending unhandled interrupts from the PL360 device. If no interrupt is pending, it returns immediately. If an interrupt is pending, atpl360_handle_events function dispatches the PLC event data to the respective registered callback. If the corresponding callback is not registered, the PLC event is discarded.
It is recommended to call this function either:
- From the main loop or from a dedicated task in the host MCU application; or,
- At least once when the host MCU application receives an interrupt from the PL360 embedded firmware