HM_IOT_Demo / nrf51-sdk

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Fork of nrf51-sdk by Nordic Semiconductor

source/nordic_sdk/components/libraries/scheduler/app_scheduler.h@27:0fe148f1bca3, 2016-04-07 (annotated)

Committer:
vcoubard
Date:
Thu Apr 07 17:37:52 2016 +0100
Revision:
27:0fe148f1bca3
Parent:
24:2aea0c1c57ee
Child:
28:041dac1366b2
Synchronized with git rev 25dc1a71

Author: Andres Amaya Garcia

Add ifdef to include correct mbed.h file in mbedOS

Who changed what in which revision?

UserRevisionLine numberNew 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 27:0fe148f1bca3 62 * @if (SD_S110 && !SD_S310)
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"
Vincent Coubard 0:f2542974c862 75
Vincent Coubard 0:f2542974c862 76 #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 77
Vincent Coubard 0:f2542974c862 78 /**@brief Compute number of bytes required to hold the scheduler buffer.
Vincent Coubard 0:f2542974c862 79 *
Vincent Coubard 0:f2542974c862 80 * @param[in] EVENT_SIZE Maximum size of events to be passed through the scheduler.
Vincent Coubard 0:f2542974c862 81 * @param[in] QUEUE_SIZE Number of entries in scheduler queue (i.e. the maximum number of events
Vincent Coubard 0:f2542974c862 82 * that can be scheduled for execution).
Vincent Coubard 0:f2542974c862 83 *
Vincent Coubard 0:f2542974c862 84 * @return Required scheduler buffer size (in bytes).
Vincent Coubard 0:f2542974c862 85 */
Vincent Coubard 0:f2542974c862 86 #define APP_SCHED_BUF_SIZE(EVENT_SIZE, QUEUE_SIZE) \
Vincent Coubard 0:f2542974c862 87 (((EVENT_SIZE) + APP_SCHED_EVENT_HEADER_SIZE) * ((QUEUE_SIZE) + 1))
Vincent Coubard 0:f2542974c862 88
Vincent Coubard 0:f2542974c862 89 /**@brief Scheduler event handler type. */
Vincent Coubard 0:f2542974c862 90 typedef void (*app_sched_event_handler_t)(void * p_event_data, uint16_t event_size);
Vincent Coubard 0:f2542974c862 91
Vincent Coubard 0:f2542974c862 92 /**@brief Macro for initializing the event scheduler.
Vincent Coubard 0:f2542974c862 93 *
Vincent Coubard 0:f2542974c862 94 * @details It will also handle dimensioning and allocation of the memory buffer required by the
Vincent Coubard 0:f2542974c862 95 * scheduler, making sure the buffer is correctly aligned.
Vincent Coubard 0:f2542974c862 96 *
Vincent Coubard 0:f2542974c862 97 * @param[in] EVENT_SIZE Maximum size of events to be passed through the scheduler.
Vincent Coubard 0:f2542974c862 98 * @param[in] QUEUE_SIZE Number of entries in scheduler queue (i.e. the maximum number of events
Vincent Coubard 0:f2542974c862 99 * that can be scheduled for execution).
Vincent Coubard 0:f2542974c862 100 *
Vincent Coubard 0:f2542974c862 101 * @note Since this macro allocates a buffer, it must only be called once (it is OK to call it
Vincent Coubard 0:f2542974c862 102 * several times as long as it is from the same location, e.g. to do a reinitialization).
Vincent Coubard 0:f2542974c862 103 */
Vincent Coubard 0:f2542974c862 104 #define APP_SCHED_INIT(EVENT_SIZE, QUEUE_SIZE) \
Vincent Coubard 0:f2542974c862 105 do \
Vincent Coubard 0:f2542974c862 106 { \
Vincent Coubard 0:f2542974c862 107 static uint32_t APP_SCHED_BUF[CEIL_DIV(APP_SCHED_BUF_SIZE((EVENT_SIZE), (QUEUE_SIZE)), \
Vincent Coubard 0:f2542974c862 108 sizeof(uint32_t))]; \
Vincent Coubard 0:f2542974c862 109 uint32_t ERR_CODE = app_sched_init((EVENT_SIZE), (QUEUE_SIZE), APP_SCHED_BUF); \
Vincent Coubard 0:f2542974c862 110 APP_ERROR_CHECK(ERR_CODE); \
Vincent Coubard 0:f2542974c862 111 } while (0)
Vincent Coubard 0:f2542974c862 112
Vincent Coubard 0:f2542974c862 113 /**@brief Function for initializing the Scheduler.
Vincent Coubard 0:f2542974c862 114 *
Vincent Coubard 0:f2542974c862 115 * @details It must be called before entering the main loop.
Vincent Coubard 0:f2542974c862 116 *
Vincent Coubard 0:f2542974c862 117 * @param[in] max_event_size Maximum size of events to be passed through the scheduler.
Vincent Coubard 0:f2542974c862 118 * @param[in] queue_size Number of entries in scheduler queue (i.e. the maximum number of
Vincent Coubard 0:f2542974c862 119 * events that can be scheduled for execution).
Vincent Coubard 0:f2542974c862 120 * @param[in] p_evt_buffer Pointer to memory buffer for holding the scheduler queue. It must
Vincent Coubard 0:f2542974c862 121 * be dimensioned using the APP_SCHED_BUFFER_SIZE() macro. The buffer
Vincent Coubard 0:f2542974c862 122 * must be aligned to a 4 byte boundary.
Vincent Coubard 0:f2542974c862 123 *
Vincent Coubard 0:f2542974c862 124 * @note Normally initialization should be done using the APP_SCHED_INIT() macro, as that will both
Vincent Coubard 0:f2542974c862 125 * allocate the scheduler buffer, and also align the buffer correctly.
Vincent Coubard 0:f2542974c862 126 *
Vincent Coubard 0:f2542974c862 127 * @retval NRF_SUCCESS Successful initialization.
Vincent Coubard 0:f2542974c862 128 * @retval NRF_ERROR_INVALID_PARAM Invalid parameter (buffer not aligned to a 4 byte
Vincent Coubard 0:f2542974c862 129 * boundary).
Vincent Coubard 0:f2542974c862 130 */
Vincent Coubard 0:f2542974c862 131 uint32_t app_sched_init(uint16_t max_event_size, uint16_t queue_size, void * p_evt_buffer);
Vincent Coubard 0:f2542974c862 132
Vincent Coubard 0:f2542974c862 133 /**@brief Function for executing all scheduled events.
Vincent Coubard 0:f2542974c862 134 *
Vincent Coubard 0:f2542974c862 135 * @details This function must be called from within the main loop. It will execute all events
Vincent Coubard 0:f2542974c862 136 * scheduled since the last time it was called.
Vincent Coubard 0:f2542974c862 137 */
Vincent Coubard 0:f2542974c862 138 void app_sched_execute(void);
Vincent Coubard 0:f2542974c862 139
Vincent Coubard 0:f2542974c862 140 /**@brief Function for scheduling an event.
Vincent Coubard 0:f2542974c862 141 *
Vincent Coubard 0:f2542974c862 142 * @details Puts an event into the event queue.
Vincent Coubard 0:f2542974c862 143 *
Vincent Coubard 0:f2542974c862 144 * @param[in] p_event_data Pointer to event data to be scheduled.
Vincent Coubard 0:f2542974c862 145 * @param[in] event_size Size of event data to be scheduled.
Vincent Coubard 0:f2542974c862 146 * @param[in] handler Event handler to receive the event.
Vincent Coubard 0:f2542974c862 147 *
Vincent Coubard 0:f2542974c862 148 * @return NRF_SUCCESS on success, otherwise an error code.
Vincent Coubard 0:f2542974c862 149 */
Vincent Coubard 0:f2542974c862 150 uint32_t app_sched_event_put(void * p_event_data,
Vincent Coubard 0:f2542974c862 151 uint16_t event_size,
Vincent Coubard 0:f2542974c862 152 app_sched_event_handler_t handler);
Vincent Coubard 0:f2542974c862 153
Vincent Coubard 0:f2542974c862 154 #ifdef APP_SCHEDULER_WITH_PAUSE
Vincent Coubard 0:f2542974c862 155 /**@brief A function to pause the scheduler.
Vincent Coubard 0:f2542974c862 156 *
Vincent Coubard 0:f2542974c862 157 * @details When the scheduler is paused events are not pulled from the scheduler queue for
Vincent Coubard 0:f2542974c862 158 * processing. The function can be called multiple times. To unblock the scheduler the
Vincent Coubard 0:f2542974c862 159 * function @ref app_sched_resume has to be called the same number of times.
Vincent Coubard 0:f2542974c862 160 */
Vincent Coubard 0:f2542974c862 161 void app_sched_pause(void);
Vincent Coubard 0:f2542974c862 162
Vincent Coubard 0:f2542974c862 163 /**@brief A function to resume a scheduler.
Vincent Coubard 0:f2542974c862 164 *
Vincent Coubard 0:f2542974c862 165 * @details To unblock the scheduler this function has to be called the same number of times as
Vincent Coubard 0:f2542974c862 166 * @ref app_sched_pause function.
Vincent Coubard 0:f2542974c862 167 */
Vincent Coubard 0:f2542974c862 168 void app_sched_resume(void);
Vincent Coubard 0:f2542974c862 169 #endif
Vincent Coubard 0:f2542974c862 170 #endif // APP_SCHEDULER_H__
Vincent Coubard 0:f2542974c862 171
vcoubard 1:ebc0e0ef0a11 172 /** @} */