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 "nordic_global.h"
00053 #include "app_error.h "
00054 
00055 #define APP_SCHED_EVENT_HEADER_SIZE 8       /**< Size of app_scheduler.event_header_t (only for use inside APP_SCHED_BUF_SIZE()). */
00056 
00057 /**@brief Compute number of bytes required to hold the scheduler buffer.
00058  *
00059  * @param[in] EVENT_SIZE   Maximum size of events to be passed through the scheduler.
00060  * @param[in] QUEUE_SIZE   Number of entries in scheduler queue (i.e. the maximum number of events
00061  *                         that can be scheduled for execution).
00062  *
00063  * @return    Required scheduler buffer size (in bytes).
00064  */
00065 #define APP_SCHED_BUF_SIZE(EVENT_SIZE, QUEUE_SIZE)                                                 \
00066             (((EVENT_SIZE) + APP_SCHED_EVENT_HEADER_SIZE) * ((QUEUE_SIZE) + 1))
00067             
00068 /**@brief Scheduler event handler type. */
00069 typedef void (*app_sched_event_handler_t)(void * p_event_data, uint16_t event_size);
00070 
00071 /**@brief Macro for initializing the event scheduler.
00072  *
00073  * @details It will also handle dimensioning and allocation of the memory buffer required by the
00074  *          scheduler, making sure the buffer is correctly aligned.
00075  *
00076  * @param[in] EVENT_SIZE   Maximum size of events to be passed through the scheduler.
00077  * @param[in] QUEUE_SIZE   Number of entries in scheduler queue (i.e. the maximum number of events
00078  *                         that can be scheduled for execution).
00079  *
00080  * @note Since this macro allocates a buffer, it must only be called once (it is OK to call it
00081  *       several times as long as it is from the same location, e.g. to do a reinitialization).
00082  */
00083 #define APP_SCHED_INIT(EVENT_SIZE, QUEUE_SIZE)                                                     \
00084     do                                                                                             \
00085     {                                                                                              \
00086         static uint32_t APP_SCHED_BUF[CEIL_DIV(APP_SCHED_BUF_SIZE((EVENT_SIZE), (QUEUE_SIZE)),     \
00087                                                sizeof(uint32_t))];                                 \
00088         uint32_t ERR_CODE = app_sched_init((EVENT_SIZE), (QUEUE_SIZE), APP_SCHED_BUF);             \
00089         APP_ERROR_CHECK(ERR_CODE);                                                                 \
00090     } while (0)
00091 
00092 /**@brief Function for initializing the Scheduler.
00093  *
00094  * @details It must be called before entering the main loop.
00095  *
00096  * @param[in]   max_event_size   Maximum size of events to be passed through the scheduler.
00097  * @param[in]   queue_size       Number of entries in scheduler queue (i.e. the maximum number of
00098  *                               events that can be scheduled for execution).
00099  * @param[in]   p_event_buffer   Pointer to memory buffer for holding the scheduler queue. It must
00100  *                               be dimensioned using the APP_SCHED_BUFFER_SIZE() macro. The buffer
00101  *                               must be aligned to a 4 byte boundary.
00102  *
00103  * @note Normally initialization should be done using the APP_SCHED_INIT() macro, as that will both
00104  *       allocate the scheduler buffer, and also align the buffer correctly.
00105  *
00106  * @retval      NRF_SUCCESS               Successful initialization.
00107  * @retval      NRF_ERROR_INVALID_PARAM   Invalid parameter (buffer not aligned to a 4 byte
00108  *                                        boundary).
00109  */
00110 uint32_t app_sched_init(uint16_t max_event_size, uint16_t queue_size, void * p_evt_buffer);
00111 
00112 /**@brief Function for executing all scheduled events.
00113  *
00114  * @details This function must be called from within the main loop. It will execute all events
00115  *          scheduled since the last time it was called.
00116  */
00117 void app_sched_execute(void);
00118 
00119 /**@brief Function for scheduling an event.
00120  *
00121  * @details Puts an event into the event queue.
00122  *
00123  * @param[in]   p_event_data   Pointer to event data to be scheduled.
00124  * @param[in]   p_event_size   Size of event data to be scheduled.
00125  * @param[in]   handler        Event handler to receive the event.
00126  *
00127  * @return      NRF_SUCCESS on success, otherwise an error code.
00128  */
00129 uint32_t app_sched_event_put(void *                    p_event_data,
00130                              uint16_t                  event_size,
00131                              app_sched_event_handler_t handler);
00132 
00133 #endif // APP_SCHEDULER_H__
00134 
00135 /** @} */