mbed-dev | Mbed

Users » mbed_official » Code » mbed-dev

Dependents: Nucleo_Hello_Encoder BLE_iBeaconScan AM1805_DEMO DISCO-F429ZI_ExportTemplate1 ... more

targets/hal/TARGET_NORDIC/TARGET_MCU_NRF51822/Lib/nordic_sdk/components/libraries/scheduler/app_scheduler.h@142:d6373279a6f1, 2016-05-26 (annotated)

Committer:: mbed_official
Date:: Thu May 26 10:00:14 2016 +0100
Revision:: 142:d6373279a6f1

Synchronized with git revision db49c1edebc3516ee61197641f7cfbdeaea5482f



Full URL: https://github.com/mbedmicro/mbed/commit/db49c1edebc3516ee61197641f7cfbdeaea5482f/



Release v121

Who changed what in which revision?

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