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 seq_diagrams_sched 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  * @if (SD_S110 && !SD_S310)
00043  * For an example usage of the scheduler, see the implementations of
00044  * @ref ble_sdk_app_hids_mouse and @ref ble_sdk_app_hids_keyboard.
00045  * @endif
00046  *
00047  * @image html scheduler_working.jpg The high level design of the scheduler
00048  */
00049 
00050 #ifndef APP_SCHEDULER_H__
00051 #define APP_SCHEDULER_H__
00052 
00053 #include <stdint.h>
00054 #include "app_error.h "
00055 
00056 #define APP_SCHED_EVENT_HEADER_SIZE 8       /**< Size of app_scheduler.event_header_t (only for use inside APP_SCHED_BUF_SIZE()). */
00057 
00058 /**@brief Compute number of bytes required to hold the scheduler buffer.
00059  *
00060  * @param[in] EVENT_SIZE   Maximum size of events to be passed through the scheduler.
00061  * @param[in] QUEUE_SIZE   Number of entries in scheduler queue (i.e. the maximum number of events
00062  *                         that can be scheduled for execution).
00063  *
00064  * @return    Required scheduler buffer size (in bytes).
00065  */
00066 #define APP_SCHED_BUF_SIZE(EVENT_SIZE, QUEUE_SIZE)                                                 \
00067             (((EVENT_SIZE) + APP_SCHED_EVENT_HEADER_SIZE) * ((QUEUE_SIZE) + 1))
00068             
00069 /**@brief Scheduler event handler type. */
00070 typedef void (*app_sched_event_handler_t)(void * p_event_data, uint16_t event_size);
00071 
00072 /**@brief Macro for initializing the event scheduler.
00073  *
00074  * @details It will also handle dimensioning and allocation of the memory buffer required by the
00075  *          scheduler, making sure the buffer is correctly aligned.
00076  *
00077  * @param[in] EVENT_SIZE   Maximum size of events to be passed through the scheduler.
00078  * @param[in] QUEUE_SIZE   Number of entries in scheduler queue (i.e. the maximum number of events
00079  *                         that can be scheduled for execution).
00080  *
00081  * @note Since this macro allocates a buffer, it must only be called once (it is OK to call it
00082  *       several times as long as it is from the same location, e.g. to do a reinitialization).
00083  */
00084 #define APP_SCHED_INIT(EVENT_SIZE, QUEUE_SIZE)                                                     \
00085     do                                                                                             \
00086     {                                                                                              \
00087         static uint32_t APP_SCHED_BUF[CEIL_DIV(APP_SCHED_BUF_SIZE((EVENT_SIZE), (QUEUE_SIZE)),     \
00088                                                sizeof(uint32_t))];                                 \
00089         uint32_t ERR_CODE = app_sched_init((EVENT_SIZE), (QUEUE_SIZE), APP_SCHED_BUF);             \
00090         APP_ERROR_CHECK(ERR_CODE);                                                                 \
00091     } while (0)
00092 
00093 /**@brief Function for initializing the Scheduler.
00094  *
00095  * @details It must be called before entering the main loop.
00096  *
00097  * @param[in]   max_event_size   Maximum size of events to be passed through the scheduler.
00098  * @param[in]   queue_size       Number of entries in scheduler queue (i.e. the maximum number of
00099  *                               events that can be scheduled for execution).
00100  * @param[in]   p_evt_buffer   Pointer to memory buffer for holding the scheduler queue. It must
00101  *                               be dimensioned using the APP_SCHED_BUFFER_SIZE() macro. The buffer
00102  *                               must be aligned to a 4 byte boundary.
00103  *
00104  * @note Normally initialization should be done using the APP_SCHED_INIT() macro, as that will both
00105  *       allocate the scheduler buffer, and also align the buffer correctly.
00106  *
00107  * @retval      NRF_SUCCESS               Successful initialization.
00108  * @retval      NRF_ERROR_INVALID_PARAM   Invalid parameter (buffer not aligned to a 4 byte
00109  *                                        boundary).
00110  */
00111 uint32_t app_sched_init(uint16_t max_event_size, uint16_t queue_size, void * p_evt_buffer);
00112 
00113 /**@brief Function for executing all scheduled events.
00114  *
00115  * @details This function must be called from within the main loop. It will execute all events
00116  *          scheduled since the last time it was called.
00117  */
00118 void app_sched_execute(void);
00119 
00120 /**@brief Function for scheduling an event.
00121  *
00122  * @details Puts an event into the event queue.
00123  *
00124  * @param[in]   p_event_data   Pointer to event data to be scheduled.
00125  * @param[in]   event_size   Size of event data to be scheduled.
00126  * @param[in]   handler        Event handler to receive the event.
00127  *
00128  * @return      NRF_SUCCESS on success, otherwise an error code.
00129  */
00130 uint32_t app_sched_event_put(void *                    p_event_data,
00131                              uint16_t                  event_size,
00132                              app_sched_event_handler_t handler);
00133 
00134 #ifdef APP_SCHEDULER_WITH_PAUSE
00135 /**@brief A function to pause the scheduler.
00136  *
00137  * @details When the scheduler is paused events are not pulled from the scheduler queue for
00138  *          processing. The function can be called multiple times. To unblock the scheduler the
00139  *          function @ref app_sched_resume has to be called the same number of times.
00140  */
00141 void app_sched_pause(void);
00142 
00143 /**@brief A function to resume a scheduler.
00144  *
00145  * @details To unblock the scheduler this function has to be called the same number of times as
00146  *          @ref app_sched_pause function.
00147  */
00148 void app_sched_resume(void);
00149 #endif
00150 #endif // APP_SCHEDULER_H__
00151 
00152 /** @} */