Nordic nrf51 sdk sources. Mirrored from https://github.com/ARMmbed/nrf51-sdk.
source/nordic_sdk/components/libraries/scheduler/app_scheduler.h@24:2aea0c1c57ee, 2016-04-07 (annotated)
- Committer:
- vcoubard
- Date:
- Thu Apr 07 17:37:49 2016 +0100
- Revision:
- 24:2aea0c1c57ee
- Parent:
- 22:67a8d2c0bbbf
- Child:
- 27:0fe148f1bca3
Synchronized with git rev 709d3cdb
Author: Liyou Zhou
Change version number in README
Who changed what in which revision?
User | Revision | Line number | New contents of line |
---|---|---|---|
vcoubard | 20:a90c48eb1d30 | 1 | /* |
vcoubard | 20:a90c48eb1d30 | 2 | * Copyright (c) Nordic Semiconductor ASA |
vcoubard | 20:a90c48eb1d30 | 3 | * All rights reserved. |
vcoubard | 20:a90c48eb1d30 | 4 | * |
vcoubard | 20:a90c48eb1d30 | 5 | * Redistribution and use in source and binary forms, with or without modification, |
vcoubard | 20:a90c48eb1d30 | 6 | * are permitted provided that the following conditions are met: |
vcoubard | 20:a90c48eb1d30 | 7 | * |
vcoubard | 20:a90c48eb1d30 | 8 | * 1. Redistributions of source code must retain the above copyright notice, this |
vcoubard | 20:a90c48eb1d30 | 9 | * list of conditions and the following disclaimer. |
vcoubard | 20:a90c48eb1d30 | 10 | * |
vcoubard | 20:a90c48eb1d30 | 11 | * 2. Redistributions in binary form must reproduce the above copyright notice, this |
vcoubard | 20:a90c48eb1d30 | 12 | * list of conditions and the following disclaimer in the documentation and/or |
vcoubard | 20:a90c48eb1d30 | 13 | * other materials provided with the distribution. |
vcoubard | 20:a90c48eb1d30 | 14 | * |
vcoubard | 20:a90c48eb1d30 | 15 | * 3. Neither the name of Nordic Semiconductor ASA nor the names of other |
vcoubard | 20:a90c48eb1d30 | 16 | * contributors to this software may be used to endorse or promote products |
vcoubard | 20:a90c48eb1d30 | 17 | * derived from this software without specific prior written permission. |
vcoubard | 20:a90c48eb1d30 | 18 | * |
vcoubard | 20:a90c48eb1d30 | 19 | * |
vcoubard | 20:a90c48eb1d30 | 20 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND |
vcoubard | 20:a90c48eb1d30 | 21 | * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED |
vcoubard | 20:a90c48eb1d30 | 22 | * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE |
vcoubard | 20:a90c48eb1d30 | 23 | * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR |
vcoubard | 20:a90c48eb1d30 | 24 | * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES |
vcoubard | 20:a90c48eb1d30 | 25 | * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; |
vcoubard | 20:a90c48eb1d30 | 26 | * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON |
vcoubard | 20:a90c48eb1d30 | 27 | * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
vcoubard | 20:a90c48eb1d30 | 28 | * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS |
vcoubard | 20:a90c48eb1d30 | 29 | * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
vcoubard | 20:a90c48eb1d30 | 30 | * |
Vincent Coubard |
0:f2542974c862 | 31 | */ |
Vincent Coubard |
0:f2542974c862 | 32 | |
Vincent Coubard |
0:f2542974c862 | 33 | /** @file |
Vincent Coubard |
0:f2542974c862 | 34 | * |
Vincent Coubard |
0:f2542974c862 | 35 | * @defgroup app_scheduler Scheduler |
Vincent Coubard |
0:f2542974c862 | 36 | * @{ |
Vincent Coubard |
0:f2542974c862 | 37 | * @ingroup app_common |
Vincent Coubard |
0:f2542974c862 | 38 | * |
Vincent Coubard |
0:f2542974c862 | 39 | * @brief The scheduler is used for transferring execution from the interrupt context to the main |
Vincent Coubard |
0:f2542974c862 | 40 | * context. |
Vincent Coubard |
0:f2542974c862 | 41 | * |
Vincent Coubard |
0:f2542974c862 | 42 | * @details See @ref seq_diagrams_sched for sequence diagrams illustrating the flow of events |
Vincent Coubard |
0:f2542974c862 | 43 | * when using the Scheduler. |
Vincent Coubard |
0:f2542974c862 | 44 | * |
Vincent Coubard |
0:f2542974c862 | 45 | * @section app_scheduler_req Requirements: |
Vincent Coubard |
0:f2542974c862 | 46 | * |
Vincent Coubard |
0:f2542974c862 | 47 | * @subsection main_context_logic Logic in main context: |
Vincent Coubard |
0:f2542974c862 | 48 | * |
Vincent Coubard |
0:f2542974c862 | 49 | * - Define an event handler for each type of event expected. |
Vincent Coubard |
0:f2542974c862 | 50 | * - Initialize the scheduler by calling the APP_SCHED_INIT() macro before entering the |
Vincent Coubard |
0:f2542974c862 | 51 | * application main loop. |
Vincent Coubard |
0:f2542974c862 | 52 | * - Call app_sched_execute() from the main loop each time the application wakes up because of an |
Vincent Coubard |
0:f2542974c862 | 53 | * event (typically when sd_app_evt_wait() returns). |
Vincent Coubard |
0:f2542974c862 | 54 | * |
Vincent Coubard |
0:f2542974c862 | 55 | * @subsection int_context_logic Logic in interrupt context: |
Vincent Coubard |
0:f2542974c862 | 56 | * |
Vincent Coubard |
0:f2542974c862 | 57 | * - In the interrupt handler, call app_sched_event_put() |
Vincent Coubard |
0:f2542974c862 | 58 | * with the appropriate data and event handler. This will insert an event into the |
Vincent Coubard |
0:f2542974c862 | 59 | * scheduler's queue. The app_sched_execute() function will pull this event and call its |
Vincent Coubard |
0:f2542974c862 | 60 | * handler in the main context. |
Vincent Coubard |
0:f2542974c862 | 61 | * |
vcoubard | 24:2aea0c1c57ee | 62 | * @if (PERIPHERAL) |
Vincent Coubard |
0:f2542974c862 | 63 | * For an example usage of the scheduler, see the implementations of |
Vincent Coubard |
0:f2542974c862 | 64 | * @ref ble_sdk_app_hids_mouse and @ref ble_sdk_app_hids_keyboard. |
Vincent Coubard |
0:f2542974c862 | 65 | * @endif |
Vincent Coubard |
0:f2542974c862 | 66 | * |
Vincent Coubard |
0:f2542974c862 | 67 | * @image html scheduler_working.jpg The high level design of the scheduler |
Vincent Coubard |
0:f2542974c862 | 68 | */ |
Vincent Coubard |
0:f2542974c862 | 69 | |
Vincent Coubard |
0:f2542974c862 | 70 | #ifndef APP_SCHEDULER_H__ |
Vincent Coubard |
0:f2542974c862 | 71 | #define APP_SCHEDULER_H__ |
Vincent Coubard |
0:f2542974c862 | 72 | |
Vincent Coubard |
0:f2542974c862 | 73 | #include <stdint.h> |
Vincent Coubard |
0:f2542974c862 | 74 | #include "app_error.h" |
vcoubard | 24:2aea0c1c57ee | 75 | #include "app_util.h" |
Vincent Coubard |
0:f2542974c862 | 76 | |
Vincent Coubard |
0:f2542974c862 | 77 | #define APP_SCHED_EVENT_HEADER_SIZE 8 /**< Size of app_scheduler.event_header_t (only for use inside APP_SCHED_BUF_SIZE()). */ |
Vincent Coubard |
0:f2542974c862 | 78 | |
Vincent Coubard |
0:f2542974c862 | 79 | /**@brief Compute number of bytes required to hold the scheduler buffer. |
Vincent Coubard |
0:f2542974c862 | 80 | * |
Vincent Coubard |
0:f2542974c862 | 81 | * @param[in] EVENT_SIZE Maximum size of events to be passed through the scheduler. |
Vincent Coubard |
0:f2542974c862 | 82 | * @param[in] QUEUE_SIZE Number of entries in scheduler queue (i.e. the maximum number of events |
Vincent Coubard |
0:f2542974c862 | 83 | * that can be scheduled for execution). |
Vincent Coubard |
0:f2542974c862 | 84 | * |
Vincent Coubard |
0:f2542974c862 | 85 | * @return Required scheduler buffer size (in bytes). |
Vincent Coubard |
0:f2542974c862 | 86 | */ |
Vincent Coubard |
0:f2542974c862 | 87 | #define APP_SCHED_BUF_SIZE(EVENT_SIZE, QUEUE_SIZE) \ |
Vincent Coubard |
0:f2542974c862 | 88 | (((EVENT_SIZE) + APP_SCHED_EVENT_HEADER_SIZE) * ((QUEUE_SIZE) + 1)) |
Vincent Coubard |
0:f2542974c862 | 89 | |
Vincent Coubard |
0:f2542974c862 | 90 | /**@brief Scheduler event handler type. */ |
Vincent Coubard |
0:f2542974c862 | 91 | typedef void (*app_sched_event_handler_t)(void * p_event_data, uint16_t event_size); |
Vincent Coubard |
0:f2542974c862 | 92 | |
Vincent Coubard |
0:f2542974c862 | 93 | /**@brief Macro for initializing the event scheduler. |
Vincent Coubard |
0:f2542974c862 | 94 | * |
Vincent Coubard |
0:f2542974c862 | 95 | * @details It will also handle dimensioning and allocation of the memory buffer required by the |
Vincent Coubard |
0:f2542974c862 | 96 | * scheduler, making sure the buffer is correctly aligned. |
Vincent Coubard |
0:f2542974c862 | 97 | * |
Vincent Coubard |
0:f2542974c862 | 98 | * @param[in] EVENT_SIZE Maximum size of events to be passed through the scheduler. |
Vincent Coubard |
0:f2542974c862 | 99 | * @param[in] QUEUE_SIZE Number of entries in scheduler queue (i.e. the maximum number of events |
Vincent Coubard |
0:f2542974c862 | 100 | * that can be scheduled for execution). |
Vincent Coubard |
0:f2542974c862 | 101 | * |
Vincent Coubard |
0:f2542974c862 | 102 | * @note Since this macro allocates a buffer, it must only be called once (it is OK to call it |
Vincent Coubard |
0:f2542974c862 | 103 | * several times as long as it is from the same location, e.g. to do a reinitialization). |
Vincent Coubard |
0:f2542974c862 | 104 | */ |
Vincent Coubard |
0:f2542974c862 | 105 | #define APP_SCHED_INIT(EVENT_SIZE, QUEUE_SIZE) \ |
Vincent Coubard |
0:f2542974c862 | 106 | do \ |
Vincent Coubard |
0:f2542974c862 | 107 | { \ |
Vincent Coubard |
0:f2542974c862 | 108 | static uint32_t APP_SCHED_BUF[CEIL_DIV(APP_SCHED_BUF_SIZE((EVENT_SIZE), (QUEUE_SIZE)), \ |
Vincent Coubard |
0:f2542974c862 | 109 | sizeof(uint32_t))]; \ |
Vincent Coubard |
0:f2542974c862 | 110 | uint32_t ERR_CODE = app_sched_init((EVENT_SIZE), (QUEUE_SIZE), APP_SCHED_BUF); \ |
Vincent Coubard |
0:f2542974c862 | 111 | APP_ERROR_CHECK(ERR_CODE); \ |
Vincent Coubard |
0:f2542974c862 | 112 | } while (0) |
Vincent Coubard |
0:f2542974c862 | 113 | |
Vincent Coubard |
0:f2542974c862 | 114 | /**@brief Function for initializing the Scheduler. |
Vincent Coubard |
0:f2542974c862 | 115 | * |
Vincent Coubard |
0:f2542974c862 | 116 | * @details It must be called before entering the main loop. |
Vincent Coubard |
0:f2542974c862 | 117 | * |
Vincent Coubard |
0:f2542974c862 | 118 | * @param[in] max_event_size Maximum size of events to be passed through the scheduler. |
Vincent Coubard |
0:f2542974c862 | 119 | * @param[in] queue_size Number of entries in scheduler queue (i.e. the maximum number of |
Vincent Coubard |
0:f2542974c862 | 120 | * events that can be scheduled for execution). |
Vincent Coubard |
0:f2542974c862 | 121 | * @param[in] p_evt_buffer Pointer to memory buffer for holding the scheduler queue. It must |
Vincent Coubard |
0:f2542974c862 | 122 | * be dimensioned using the APP_SCHED_BUFFER_SIZE() macro. The buffer |
Vincent Coubard |
0:f2542974c862 | 123 | * must be aligned to a 4 byte boundary. |
Vincent Coubard |
0:f2542974c862 | 124 | * |
Vincent Coubard |
0:f2542974c862 | 125 | * @note Normally initialization should be done using the APP_SCHED_INIT() macro, as that will both |
Vincent Coubard |
0:f2542974c862 | 126 | * allocate the scheduler buffer, and also align the buffer correctly. |
Vincent Coubard |
0:f2542974c862 | 127 | * |
Vincent Coubard |
0:f2542974c862 | 128 | * @retval NRF_SUCCESS Successful initialization. |
Vincent Coubard |
0:f2542974c862 | 129 | * @retval NRF_ERROR_INVALID_PARAM Invalid parameter (buffer not aligned to a 4 byte |
Vincent Coubard |
0:f2542974c862 | 130 | * boundary). |
Vincent Coubard |
0:f2542974c862 | 131 | */ |
Vincent Coubard |
0:f2542974c862 | 132 | uint32_t app_sched_init(uint16_t max_event_size, uint16_t queue_size, void * p_evt_buffer); |
Vincent Coubard |
0:f2542974c862 | 133 | |
Vincent Coubard |
0:f2542974c862 | 134 | /**@brief Function for executing all scheduled events. |
Vincent Coubard |
0:f2542974c862 | 135 | * |
Vincent Coubard |
0:f2542974c862 | 136 | * @details This function must be called from within the main loop. It will execute all events |
Vincent Coubard |
0:f2542974c862 | 137 | * scheduled since the last time it was called. |
Vincent Coubard |
0:f2542974c862 | 138 | */ |
Vincent Coubard |
0:f2542974c862 | 139 | void app_sched_execute(void); |
Vincent Coubard |
0:f2542974c862 | 140 | |
Vincent Coubard |
0:f2542974c862 | 141 | /**@brief Function for scheduling an event. |
Vincent Coubard |
0:f2542974c862 | 142 | * |
Vincent Coubard |
0:f2542974c862 | 143 | * @details Puts an event into the event queue. |
Vincent Coubard |
0:f2542974c862 | 144 | * |
Vincent Coubard |
0:f2542974c862 | 145 | * @param[in] p_event_data Pointer to event data to be scheduled. |
Vincent Coubard |
0:f2542974c862 | 146 | * @param[in] event_size Size of event data to be scheduled. |
Vincent Coubard |
0:f2542974c862 | 147 | * @param[in] handler Event handler to receive the event. |
Vincent Coubard |
0:f2542974c862 | 148 | * |
Vincent Coubard |
0:f2542974c862 | 149 | * @return NRF_SUCCESS on success, otherwise an error code. |
Vincent Coubard |
0:f2542974c862 | 150 | */ |
Vincent Coubard |
0:f2542974c862 | 151 | uint32_t app_sched_event_put(void * p_event_data, |
Vincent Coubard |
0:f2542974c862 | 152 | uint16_t event_size, |
Vincent Coubard |
0:f2542974c862 | 153 | app_sched_event_handler_t handler); |
Vincent Coubard |
0:f2542974c862 | 154 | |
Vincent Coubard |
0:f2542974c862 | 155 | #ifdef APP_SCHEDULER_WITH_PAUSE |
Vincent Coubard |
0:f2542974c862 | 156 | /**@brief A function to pause the scheduler. |
Vincent Coubard |
0:f2542974c862 | 157 | * |
Vincent Coubard |
0:f2542974c862 | 158 | * @details When the scheduler is paused events are not pulled from the scheduler queue for |
Vincent Coubard |
0:f2542974c862 | 159 | * processing. The function can be called multiple times. To unblock the scheduler the |
Vincent Coubard |
0:f2542974c862 | 160 | * function @ref app_sched_resume has to be called the same number of times. |
Vincent Coubard |
0:f2542974c862 | 161 | */ |
Vincent Coubard |
0:f2542974c862 | 162 | void app_sched_pause(void); |
Vincent Coubard |
0:f2542974c862 | 163 | |
Vincent Coubard |
0:f2542974c862 | 164 | /**@brief A function to resume a scheduler. |
Vincent Coubard |
0:f2542974c862 | 165 | * |
Vincent Coubard |
0:f2542974c862 | 166 | * @details To unblock the scheduler this function has to be called the same number of times as |
Vincent Coubard |
0:f2542974c862 | 167 | * @ref app_sched_pause function. |
Vincent Coubard |
0:f2542974c862 | 168 | */ |
Vincent Coubard |
0:f2542974c862 | 169 | void app_sched_resume(void); |
Vincent Coubard |
0:f2542974c862 | 170 | #endif |
Vincent Coubard |
0:f2542974c862 | 171 | #endif // APP_SCHEDULER_H__ |
Vincent Coubard |
0:f2542974c862 | 172 | |
vcoubard | 1:ebc0e0ef0a11 | 173 | /** @} */ |