app_scheduler.h

00001 /* Copyright (c) 2012 Nordic Semiconductor. All Rights Reserved.
00002  *
00003  * The information contained herein is property of Nordic Semiconductor ASA.
00004  * Terms and conditions of usage are described in detail in NORDIC
00005  * SEMICONDUCTOR STANDARD SOFTWARE LICENSE AGREEMENT.
00006  *
00007  * Licensees are granted free, non-transferable use of the information. NO
00008  * WARRANTY of ANY KIND is provided. This heading must NOT be removed from
00009  * the file.
00010  *
00011  */
00012 
00013 /** @file
00014  *
00015  * @defgroup app_scheduler Scheduler
00016  * @{
00017  * @ingroup app_common
00018  *
00019  * @brief The scheduler is used for transferring execution from the interrupt context to the main
00020  *        context.
00021  *
00022  * @details See @ref ble_sdk_apps_seq_diagrams for sequence diagrams illustrating the flow of events
00023  *          when using the Scheduler.
00024  *
00025  * @section app_scheduler_req Requirements:
00026  *
00027  * @subsection main_context_logic Logic in main context:
00028  *
00029  *   - Define an event handler for each type of event expected.
00030  *   - Initialize the scheduler by calling the APP_SCHED_INIT() macro before entering the
00031  *     application main loop.
00032  *   - Call app_sched_execute() from the main loop each time the application wakes up because of an
00033  *     event (typically when sd_app_evt_wait() returns).
00034  *
00035  * @subsection int_context_logic Logic in interrupt context:
00036  *
00037  *   - In the interrupt handler, call app_sched_event_put()
00038  *     with the appropriate data and event handler. This will insert an event into the
00039  *     scheduler's queue. The app_sched_execute() function will pull this event and call its
00040  *     handler in the main context.
00041  *
00042  * For an example usage of the scheduler, please see the implementations of
00043  * @ref ble_sdk_app_hids_mouse and @ref ble_sdk_app_hids_keyboard.
00044  *
00045  * @image html scheduler_working.jpg The high level design of the scheduler
00046  */
00047 
00048 #ifndef APP_SCHEDULER_H__
00049 #define APP_SCHEDULER_H__
00050 
00051 #include <stdint.h>
00052 #include "app_error.h "
00053 
00054 #define APP_SCHED_EVENT_HEADER_SIZE 8       /**< Size of app_scheduler.event_header_t (only for use inside APP_SCHED_BUF_SIZE()). */
00055 
00056 /**@brief Compute number of bytes required to hold the scheduler buffer.
00057  *
00058  * @param[in] EVENT_SIZE   Maximum size of events to be passed through the scheduler.
00059  * @param[in] QUEUE_SIZE   Number of entries in scheduler queue (i.e. the maximum number of events
00060  *                         that can be scheduled for execution).
00061  *
00062  * @return    Required scheduler buffer size (in bytes).
00063  */
00064 #define APP_SCHED_BUF_SIZE(EVENT_SIZE, QUEUE_SIZE)                                                 \
00065             (((EVENT_SIZE) + APP_SCHED_EVENT_HEADER_SIZE) * ((QUEUE_SIZE) + 1))
00066             
00067 /**@brief Scheduler event handler type. */
00068 typedef void (*app_sched_event_handler_t)(void * p_event_data, uint16_t event_size);
00069 
00070 /**@brief Macro for initializing the event scheduler.
00071  *
00072  * @details It will also handle dimensioning and allocation of the memory buffer required by the
00073  *          scheduler, making sure the buffer is correctly aligned.
00074  *
00075  * @param[in] EVENT_SIZE   Maximum size of events to be passed through the scheduler.
00076  * @param[in] QUEUE_SIZE   Number of entries in scheduler queue (i.e. the maximum number of events
00077  *                         that can be scheduled for execution).
00078  *
00079  * @note Since this macro allocates a buffer, it must only be called once (it is OK to call it
00080  *       several times as long as it is from the same location, e.g. to do a reinitialization).
00081  */
00082 #define APP_SCHED_INIT(EVENT_SIZE, QUEUE_SIZE)                                                     \
00083     do                                                                                             \
00084     {                                                                                              \
00085         static uint32_t APP_SCHED_BUF[CEIL_DIV(APP_SCHED_BUF_SIZE((EVENT_SIZE), (QUEUE_SIZE)),     \
00086                                                sizeof(uint32_t))];                                 \
00087         uint32_t ERR_CODE = app_sched_init((EVENT_SIZE), (QUEUE_SIZE), APP_SCHED_BUF);             \
00088         APP_ERROR_CHECK(ERR_CODE);                                                                 \
00089     } while (0)
00090 
00091 /**@brief Function for initializing the Scheduler.
00092  *
00093  * @details It must be called before entering the main loop.
00094  *
00095  * @param[in]   max_event_size   Maximum size of events to be passed through the scheduler.
00096  * @param[in]   queue_size       Number of entries in scheduler queue (i.e. the maximum number of
00097  *                               events that can be scheduled for execution).
00098  * @param[in]   p_event_buffer   Pointer to memory buffer for holding the scheduler queue. It must
00099  *                               be dimensioned using the APP_SCHED_BUFFER_SIZE() macro. The buffer
00100  *                               must be aligned to a 4 byte boundary.
00101  *
00102  * @note Normally initialization should be done using the APP_SCHED_INIT() macro, as that will both
00103  *       allocate the scheduler buffer, and also align the buffer correctly.
00104  *
00105  * @retval      NRF_SUCCESS               Successful initialization.
00106  * @retval      NRF_ERROR_INVALID_PARAM   Invalid parameter (buffer not aligned to a 4 byte
00107  *                                        boundary).
00108  */
00109 uint32_t app_sched_init(uint16_t max_event_size, uint16_t queue_size, void * p_evt_buffer);
00110 
00111 /**@brief Function for executing all scheduled events.
00112  *
00113  * @details This function must be called from within the main loop. It will execute all events
00114  *          scheduled since the last time it was called.
00115  */
00116 void app_sched_execute(void);
00117 
00118 /**@brief Function for scheduling an event.
00119  *
00120  * @details Puts an event into the event queue.
00121  *
00122  * @param[in]   p_event_data   Pointer to event data to be scheduled.
00123  * @param[in]   p_event_size   Size of event data to be scheduled.
00124  * @param[in]   handler        Event handler to receive the event.
00125  *
00126  * @return      NRF_SUCCESS on success, otherwise an error code.
00127  */
00128 uint32_t app_sched_event_put(void *                    p_event_data,
00129                              uint16_t                  event_size,
00130                              app_sched_event_handler_t handler);
00131 
00132 #endif // APP_SCHEDULER_H__
00133 
00134 /** @} */