tool/mbed/mbed-sdk/libraries/mbed/targets/hal/TARGET_NORDIC/TARGET_MCU_NRF51822/Lib/nordic_sdk/components/libraries/scheduler/app_scheduler.h

   1 /* Copyright (c) 2012 Nordic Semiconductor. All Rights Reserved.
   2  *
   3  * The information contained herein is property of Nordic Semiconductor ASA.
   4  * Terms and conditions of usage are described in detail in NORDIC
   5  * SEMICONDUCTOR STANDARD SOFTWARE LICENSE AGREEMENT.
   6  *
   7  * Licensees are granted free, non-transferable use of the information. NO
   8  * WARRANTY of ANY KIND is provided. This heading must NOT be removed from
   9  * the file.
  10  *
  11  */
  12
  13 /** @file
  14  *
  15  * @defgroup app_scheduler Scheduler
  16  * @{
  17  * @ingroup app_common
  18  *
  19  * @brief The scheduler is used for transferring execution from the interrupt context to the main
  20  *        context.
  21  *
  22  * @details See @ref seq_diagrams_sched for sequence diagrams illustrating the flow of events
  23  *          when using the Scheduler.
  24  *
  25  * @section app_scheduler_req Requirements:
  26  *
  27  * @subsection main_context_logic Logic in main context:
  28  *
  29  *   - Define an event handler for each type of event expected.
  30  *   - Initialize the scheduler by calling the APP_SCHED_INIT() macro before entering the
  31  *     application main loop.
  32  *   - Call app_sched_execute() from the main loop each time the application wakes up because of an
  33  *     event (typically when sd_app_evt_wait() returns).
  34  *
  35  * @subsection int_context_logic Logic in interrupt context:
  36  *
  37  *   - In the interrupt handler, call app_sched_event_put()
  38  *     with the appropriate data and event handler. This will insert an event into the
  39  *     scheduler's queue. The app_sched_execute() function will pull this event and call its
  40  *     handler in the main context.
  41  *
  42  * @if (SD_S110 && !SD_S310)
  43  * For an example usage of the scheduler, see the implementations of
  44  * @ref ble_sdk_app_hids_mouse and @ref ble_sdk_app_hids_keyboard.
  45  * @endif
  46  *
  47  * @image html scheduler_working.jpg The high level design of the scheduler
  48  */
  49
  50 #ifndef APP_SCHEDULER_H__
  51 #define APP_SCHEDULER_H__
  52
  53 #include <stdint.h>
  54 #include "app_error.h"
  55
  56 #define APP_SCHED_EVENT_HEADER_SIZE 8       /**< Size of app_scheduler.event_header_t (only for use inside APP_SCHED_BUF_SIZE()). */
  57
  58 /**@brief Compute number of bytes required to hold the scheduler buffer.
  59  *
  60  * @param[in] EVENT_SIZE   Maximum size of events to be passed through the scheduler.
  61  * @param[in] QUEUE_SIZE   Number of entries in scheduler queue (i.e. the maximum number of events
  62  *                         that can be scheduled for execution).
  63  *
  64  * @return    Required scheduler buffer size (in bytes).
  65  */
  66 #define APP_SCHED_BUF_SIZE(EVENT_SIZE, QUEUE_SIZE)                                                 \
  67             (((EVENT_SIZE) + APP_SCHED_EVENT_HEADER_SIZE) * ((QUEUE_SIZE) + 1))
  68
  69 /**@brief Scheduler event handler type. */
  70 typedef void (*app_sched_event_handler_t)(void * p_event_data, uint16_t event_size);
  71
  72 /**@brief Macro for initializing the event scheduler.
  73  *
  74  * @details It will also handle dimensioning and allocation of the memory buffer required by the
  75  *          scheduler, making sure the buffer is correctly aligned.
  76  *
  77  * @param[in] EVENT_SIZE   Maximum size of events to be passed through the scheduler.
  78  * @param[in] QUEUE_SIZE   Number of entries in scheduler queue (i.e. the maximum number of events
  79  *                         that can be scheduled for execution).
  80  *
  81  * @note Since this macro allocates a buffer, it must only be called once (it is OK to call it
  82  *       several times as long as it is from the same location, e.g. to do a reinitialization).
  83  */
  84 #define APP_SCHED_INIT(EVENT_SIZE, QUEUE_SIZE)                                                     \
  85     do                                                                                             \
  86     {                                                                                              \
  87         static uint32_t APP_SCHED_BUF[CEIL_DIV(APP_SCHED_BUF_SIZE((EVENT_SIZE), (QUEUE_SIZE)),     \
  88                                                sizeof(uint32_t))];                                 \
  89         uint32_t ERR_CODE = app_sched_init((EVENT_SIZE), (QUEUE_SIZE), APP_SCHED_BUF);             \
  90         APP_ERROR_CHECK(ERR_CODE);                                                                 \
  91     } while (0)
  92
  93 /**@brief Function for initializing the Scheduler.
  94  *
  95  * @details It must be called before entering the main loop.
  96  *
  97  * @param[in]   max_event_size   Maximum size of events to be passed through the scheduler.
  98  * @param[in]   queue_size       Number of entries in scheduler queue (i.e. the maximum number of
  99  *                               events that can be scheduled for execution).
 100  * @param[in]   p_evt_buffer   Pointer to memory buffer for holding the scheduler queue. It must
 101  *                               be dimensioned using the APP_SCHED_BUFFER_SIZE() macro. The buffer
 102  *                               must be aligned to a 4 byte boundary.
 103  *
 104  * @note Normally initialization should be done using the APP_SCHED_INIT() macro, as that will both
 105  *       allocate the scheduler buffer, and also align the buffer correctly.
 106  *
 107  * @retval      NRF_SUCCESS               Successful initialization.
 108  * @retval      NRF_ERROR_INVALID_PARAM   Invalid parameter (buffer not aligned to a 4 byte
 109  *                                        boundary).
 110  */
 111 uint32_t app_sched_init(uint16_t max_event_size, uint16_t queue_size, void * p_evt_buffer);
 112
 113 /**@brief Function for executing all scheduled events.
 114  *
 115  * @details This function must be called from within the main loop. It will execute all events
 116  *          scheduled since the last time it was called.
 117  */
 118 void app_sched_execute(void);
 119
 120 /**@brief Function for scheduling an event.
 121  *
 122  * @details Puts an event into the event queue.
 123  *
 124  * @param[in]   p_event_data   Pointer to event data to be scheduled.
 125  * @param[in]   event_size   Size of event data to be scheduled.
 126  * @param[in]   handler        Event handler to receive the event.
 127  *
 128  * @return      NRF_SUCCESS on success, otherwise an error code.
 129  */
 130 uint32_t app_sched_event_put(void *                    p_event_data,
 131                              uint16_t                  event_size,
 132                              app_sched_event_handler_t handler);
 133
 134 #ifdef APP_SCHEDULER_WITH_PAUSE
 135 /**@brief A function to pause the scheduler.
 136  *
 137  * @details When the scheduler is paused events are not pulled from the scheduler queue for
 138  *          processing. The function can be called multiple times. To unblock the scheduler the
 139  *          function @ref app_sched_resume has to be called the same number of times.
 140  */
 141 void app_sched_pause(void);
 142
 143 /**@brief A function to resume a scheduler.
 144  *
 145  * @details To unblock the scheduler this function has to be called the same number of times as
 146  *          @ref app_sched_pause function.
 147  */
 148 void app_sched_resume(void);
 149 #endif
 150 #endif // APP_SCHEDULER_H__
 151
 152 /** @} */