 |
Wirepas SDK
|
|
Wirepas SDK
|
The System library collects together low-level functions such as interrupt handling, critical sections and power management.
The System library also provides a simple periodic callback facility that applications can use in place of a typical main loop, to perform tasks alongside the protocol stack. The periodic callback facility also doubles as a "bottom-half" callback, also known as a slow/soft interrupt handler or deferred procedure call, which can be triggered from interrupts. This allows writing interrupt routines that react to external events quickly and then do the rest of the processing in an application callback whenever it is convenient to do so.
Library services are accessed via lib_system handle.
Definition in file wms_system.h.
Go to the source code of this file.
Typedefs | |
| typedef void(* | app_lib_system_startup_cb_f) (void) |
| Startup callback. More... | |
| typedef void(* | app_lib_system_shutdown_cb_f) (void) |
| Shutdown callback. More... | |
| typedef uint32_t(* | app_lib_system_periodic_cb_f) (void) |
| Periodic callback. More... | |
| typedef void(* | app_lib_system_irq_handler_f) (void) |
| Interrupt handler callback. More... | |
| typedef app_res_e(* | app_lib_system_set_startup_cb_f) (app_lib_system_startup_cb_f startup_cb) |
| Set a callback to be called when the system starts up. More... | |
| typedef app_res_e(* | app_lib_system_set_shutdown_cb_f) (app_lib_system_shutdown_cb_f shutdown_cb) |
| Set a callback to be called just before the system shuts down. More... | |
| typedef app_res_e(* | app_lib_system_set_periodic_cb_f) (app_lib_system_periodic_cb_f work_cb, uint32_t initial_delay_us, uint32_t execution_time_us) |
| Set the periodic callback. More... | |
| typedef void(* | app_lib_system_enter_critical_section_f) (void) |
| Enter a critical section. More... | |
| typedef void(* | app_lib_system_exit_critical_section_f) (void) |
| Exit a critical section. More... | |
| typedef app_res_e(* | app_lib_system_disable_deep_sleep) (bool disable) |
| Disable/Enable deep sleep on stack. More... | |
| typedef app_res_e(* | app_lib_system_register_app_irq_table_f) (app_lib_system_irq_handler_f *table_p) |
| Register an interrupt handler table for the app. More... | |
| typedef app_res_e(* | app_lib_system_enable_app_irq_f) (uint8_t irq_n) |
| Enable an app interrupt. More... | |
| typedef app_res_e(* | app_lib_system_disable_app_irq_f) (uint8_t irq_n) |
| Disable an app interrupt. More... | |
| typedef app_res_e(* | app_lib_system_enable_fast_app_irq_f) (uint8_t irq_n, uint8_t priority) |
| Enable a fast app interrupt. More... | |
| typedef app_res_e(* | app_lib_system_enable_app_irq_with_handler_f) (bool fast, uint8_t irq_n, uint8_t priority, app_lib_system_irq_handler_f handler) |
| Enable a platform-specific interrupt with given handler and priority. More... | |
| typedef app_res_e(* | app_lib_system_clear_pending_fast_app_irq_f) (uint8_t irq_n) |
| Clear fast interrupt flag from NVIC. More... | |
| typedef uint32_t(* | app_lib_system_get_bootloader_version_f) (void) |
| Get bootloader version. More... | |
| typedef app_res_e(* | app_lib_system_get_radio_info_f) (app_lib_system_radio_info_t *info_p, size_t info_num_bytes) |
| Return radio hardware and platform information. More... | |
Data Structures | |
| struct | app_lib_system_radio_info_t |
| Radio information structure. More... | |
| struct | app_lib_system_t |
| List of library functions. More... | |
Macros | |
| #define | APP_LIB_SYSTEM_NAME 0x77db1bd5 |
| Library symbolic name. More... | |
| #define | APP_LIB_SYSTEM_VERSION 0x201 |
| Maximum supported library version. More... | |
| #define | APP_LIB_SYSTEM_STOP_PERIODIC UINT32_MAX |
| Constant to stop periodic callback. More... | |
| #define | APP_LIB_SYSTEM_IRQ_PRIO_HI 0 |
| Interrupt priority levels for application. More... | |
| #define | APP_LIB_SYSTEM_IRQ_PRIO_LO 1 |
| typedef app_res_e(* app_lib_system_clear_pending_fast_app_irq_f) (uint8_t irq_n) |
Clear fast interrupt flag from NVIC.
Clear platform-specific fast application interrupt irq_n in the interrupt controller. On most platforms it is also necessary to clear interrupt bits in the interrupting peripherals, which this function does not do.
| irq_n | The pending IRQ number to clear |
irq_n is invalid, APP_RES_RESOURCE_UNAVAILABLE if irq_n is not available for the application Definition at line 488 of file wms_system.h.
| typedef app_res_e(* app_lib_system_disable_app_irq_f) (uint8_t irq_n) |
Disable an app interrupt.
Disable a platform-specific interrupt irq_n. Calling this function is permitted even if the interrupt was not enabled previously.
| irq_n | The IRQ number to disable |
irq_n is invalid, APP_RES_RESOURCE_UNAVAILABLE if irq_n is not available for the application Definition at line 371 of file wms_system.h.
| typedef app_res_e(* app_lib_system_disable_deep_sleep) (bool disable) |
Disable/Enable deep sleep on stack.
Tell the stack if it is permissible to enter deep sleep or not. This can be used if the application is using a peripheral that cannot operate correctly if the stack turns off power to certain features of the hardware when sleeping.
A disable parameter value true disables deep sleep, at the expense of greatly increased power consumption. disable parameter value false, the default, will restore back normal operation. This function always returns APP_RES_OK.
| disable | If True, prevent the device from going to deep sleep. If False, enable the device to go to deep sleep state. |
Definition at line 332 of file wms_system.h.
| typedef app_res_e(* app_lib_system_enable_app_irq_f) (uint8_t irq_n) |
Enable an app interrupt.
| irq_n | The IRQ number to enable |
irq_n is invalid, APP_RES_RESOURCE_UNAVAILABLE if irq_n is not available for the application or APP_RES_INVALID_CONFIGURATION if no interrupt handler or table set Definition at line 355 of file wms_system.h.
| typedef app_res_e(* app_lib_system_enable_app_irq_with_handler_f) (bool fast, uint8_t irq_n, uint8_t priority, app_lib_system_irq_handler_f handler) |
Enable a platform-specific interrupt with given handler and priority.
The fast parameter allows to choose between the two supported types of application interrupt modes.
Fast interrupt handlers should be kept very short as they are executed in interrupt context. Most of the handling should be done later, in a "bottom-half" handler, also known as a slow/soft interrupt handler, or deferred procedure call. To facilitate this, the interrupt handler can call the lib_system->setPeriodicCb() function with an initial delay of zero. This causes the periodic callback to be called as soon as possible.
If fast is false, the interrupt is considered as deferred interrupt. Then, the top half of the interrupt is handled by the stack and interrupt handler (bottom half) set by the application is called as normal application task context. Then, the top half does not need to be implemented in application. Con is that it calling of the bottom half may be too late and deferred interrupt is not necessarily feasible for all peripherals.
Not all interrupts are available for application use. Each supported platform reserves some interrupts for protocol stack use. Trying to enable a reserved interrupt will result in an error. Application interrupt handlers will never be called for reserved interrupts.
| fast | True for a fast irq |
| irq_n | The IRQ number to enable |
| priority | Interrupt priority level (only for fast interrupt) Available levels depend on platform, but two levels are guaranteed: APP_LIB_SYSTEM_IRQ_PRIO_HI APP_LIB_SYSTEM_IRQ_PRIO_LO |
| handler | Interrupt handler to be called |
irq_n is invalid, APP_RES_RESOURCE_UNAVAILABLE if irq_n is not available for the application or APP_RES_INVALID_CONFIGURATION if no interrupt handler or table set Example:
Definition at line 468 of file wms_system.h.
| typedef app_res_e(* app_lib_system_enable_fast_app_irq_f) (uint8_t irq_n, uint8_t priority) |
Enable a fast app interrupt.
| irq_n | The IRQ number to enable |
| priority | Interrupt priority level. Available levels depend on platform, but two levels are guaranteed: APP_LIB_SYSTEM_IRQ_PRIO_HI APP_LIB_SYSTEM_IRQ_PRIO_LO |
irq_n is invalid, APP_RES_RESOURCE_UNAVAILABLE if irq_n is not available for the application or APP_RES_INVALID_CONFIGURATION if no interrupt handler or table set Definition at line 391 of file wms_system.h.
| typedef void(* app_lib_system_enter_critical_section_f) (void) |
Enter a critical section.
Interrupts are disabled for the duration of the critical section. This function and lib_system->exitCriticalSection() can be nested.
Code in critical sections must be kept extremely short and fast. Otherwise communication degradation or even total failure can result. The types of protocol timing bugs that arise from keeping interrupts disabled for too long are very difficult to diagnose.
Definition at line 297 of file wms_system.h.
| typedef void(* app_lib_system_exit_critical_section_f) (void) |
Exit a critical section.
Exit a critical section which was entered using the lib_system->enterCriticalSection() function. This function and lib_system->enterCriticalSection() can be nested. Interrupts are enabled again, if this was the outermost nesting level.
Definition at line 308 of file wms_system.h.
| typedef uint32_t(* app_lib_system_get_bootloader_version_f) (void) |
Get bootloader version.
Return a small positive integer that represents the version of the bootloader. For platforms without bootloader, this function returns 0.
Definition at line 499 of file wms_system.h.
| typedef app_res_e(* app_lib_system_get_radio_info_f) (app_lib_system_radio_info_t *info_p, size_t info_num_bytes) |
Return radio hardware and platform information.
| info_p | pointer to store system radio info result |
| num_bytes | the number of bytes of information to copy, at most the size of app_lib_system_radio_info_t. This allows making the information struct bigger in the future. |
info_num_bytes is invalid, APP_RES_INVALID_NULL_POINTER if info_p is NULL Definition at line 515 of file wms_system.h.
| typedef void(* app_lib_system_irq_handler_f) (void) |
Interrupt handler callback.
Interrupt handlers registered with lib_system->enableAppIrq().
Interrupt handlers have no parameters or return value.
Definition at line 216 of file wms_system.h.
| typedef uint32_t(* app_lib_system_periodic_cb_f) (void) |
Periodic callback.
This function is called after a set delay. If the set delay is zero, this function is called as soon as possible.
Any code, including interrupts can use lib_system->setPeriodicCb() function to set or change the periodic callback. This can be used the defer processing to a "bottom half", also known as a slow/soft interrupt handler, or deferred procedure call.
The return value is used as the next delay value, in microseconds. If APP_LIB_SYSTEM_STOP_PERIODIC is returned, the callback is not called again.
Because of limited range of return value (32 bits) and the internal comparison made by the scheduler, the maximum delay before being scheduled cannot be higher than the value returned by the lib_time->getMaxHpDelay service (This value is around 30 minutes).
Definition at line 206 of file wms_system.h.
| typedef app_res_e(* app_lib_system_register_app_irq_table_f) (app_lib_system_irq_handler_f *table_p) |
Register an interrupt handler table for the app.
| table_p | Pointer to the app interrupt handler table |
Definition at line 342 of file wms_system.h.
| typedef app_res_e(* app_lib_system_set_periodic_cb_f) (app_lib_system_periodic_cb_f work_cb, uint32_t initial_delay_us, uint32_t execution_time_us) |
Set the periodic callback.
Set the periodic callback to the given function. If NULL is passed, the periodic callback is disabled. The periodic callback is also disabled if the callback function returns APP_LIB_SYSTEM_STOP_PERIODIC.
Parameter initial_delay_us is the amount of time to wait, in microseconds, before calling the callback. If set to zero, the callback is called immediately whenever there is enough time. Parameter execution_time_us tells the stack what is the longest amount of time the function call is expected to take, in microseconds. The stack will then schedule the callback to the next available slot that has enough time. If the callback overruns its allocated time slot and returns late, the protocol timing is compromised.
Returns APP_RES_INVALID_VALUE if execution_time_us is greater than 100000 (100 ms). Otherwise, returns APP_RES_OK.
Because of limited range of return value (32 bits) and the internal comparison made by the scheduler, the maximum delay before being scheduled cannot be higher than the value returned by the lib_time->getMaxHpDelay() service (This value is around 30 minutes).
For more information on scheduling, see Cooperative MCU Access.
| work_cb | The function to be executed, or NULL to unset |
| initial_delay_us | Delay from now in us to call the work function |
| execution_time_us | Maximum time for the work function to execute in us |
execution_time_us is too high Definition at line 280 of file wms_system.h.
| typedef app_res_e(* app_lib_system_set_shutdown_cb_f) (app_lib_system_shutdown_cb_f shutdown_cb) |
Set a callback to be called just before the system shuts down.
| shutdown_cb | The function to be executed, or NULL to unset |
Definition at line 238 of file wms_system.h.
| typedef app_res_e(* app_lib_system_set_startup_cb_f) (app_lib_system_startup_cb_f startup_cb) |
Set a callback to be called when the system starts up.
| startup_cb | The function to be executed, or NULL to unset |
Definition at line 228 of file wms_system.h.
| typedef void(* app_lib_system_shutdown_cb_f) (void) |
Shutdown callback.
This callback is called when the lib_state->stopStack() function in the State library (state.h) is called, or some other reason (e.g. OTAP, Remote API) is causing the stack to stop. The lib_system->setShutdownCb() function can be used to set or change the shutdown callback.
There is no return value from this function. Returning from the callback reboots the node.
Definition at line 181 of file wms_system.h.
| typedef void(* app_lib_system_startup_cb_f) (void) |
Startup callback.
This callback is called after every interrupt, until the stack is started by calling lib_state->startStack() function in the State library (state.h). If the stack is running initially, the startup callback is not called at all. Any code, including interrupts can use lib_system->setStartupCb() function to set or change the startup callback.
There is no return value from this function. Returning from this callback will cause the node to enter a low power sleep, until another interrupt will cause it to wake up again.
Definition at line 166 of file wms_system.h.
| struct app_lib_system_radio_info_t |
Radio information structure.
Information returned by lib_system->getRadioInfo()
Definition at line 144 of file wms_system.h.
| Data Fields | ||
|---|---|---|
| uint32_t | hardware_magic |
Radio hardware magic number, app_lib_system_hardware_magic_e |
| uint32_t | protocol_profile |
Protocol profile, app_lib_system_protocol_profile_e |
| struct app_lib_system_t |
List of library functions.
Definition at line 521 of file wms_system.h.
| Data Fields | ||
|---|---|---|
| app_lib_system_clear_pending_fast_app_irq_f | clearPendingFastAppIrq | |
| app_lib_system_disable_app_irq_f | disableAppIrq | |
| app_lib_system_disable_deep_sleep | disableDeepSleep | |
| app_lib_system_enable_app_irq_with_handler_f | enableAppIrq | |
| app_lib_system_enter_critical_section_f | enterCriticalSection | |
| app_lib_system_exit_critical_section_f | exitCriticalSection | |
| app_lib_system_get_bootloader_version_f | getBootloaderVersion | |
| app_lib_system_get_radio_info_f | getRadioInfo | |
| app_lib_system_set_periodic_cb_f | setPeriodicCb | |
| app_lib_system_set_shutdown_cb_f | setShutdownCb | |
| app_lib_system_set_startup_cb_f | setStartupCb | |
Radio hardware magic number.
This number is returned by lib_system->getRadioInfo() function and can be used by the application to detect which radio platform it is running on.
Definition at line 64 of file wms_system.h.
Protocol profiles.
Protocol profile, which is a value that depends on the radio band, regulatory domain and platform capabilities such as available modulation types, channel spacing, output power levels, etc. This number is returned by lib_system->getRadioInfo().
Definition at line 110 of file wms_system.h.
| #define APP_LIB_SYSTEM_IRQ_PRIO_HI 0 |
Interrupt priority levels for application.
Definition at line 54 of file wms_system.h.
| #define APP_LIB_SYSTEM_IRQ_PRIO_LO 1 |
Definition at line 55 of file wms_system.h.
| #define APP_LIB_SYSTEM_NAME 0x77db1bd5 |
| #define APP_LIB_SYSTEM_STOP_PERIODIC UINT32_MAX |
Constant to stop periodic callback.
When this constant is returned from a periodic callback (app_lib_system_periodic_cb_f) , the stack will not call the callback again.
Definition at line 46 of file wms_system.h.
| #define APP_LIB_SYSTEM_VERSION 0x201 |
Maximum supported library version.
Definition at line 38 of file wms_system.h.