long dao / nRF51822

Old version

Dependents:   VNG_BLE_Basic

Fork of nRF51822 by Nordic Semiconductor

nordic/nrf-sdk/sd_common/softdevice_handler.h@94:22533f51b97f, 2016-01-21 (annotated)

Committer:
longdh
Date:
Thu Jan 21 02:04:47 2016 +0000
Revision:
94:22533f51b97f
Parent:
0:eff01767de02
Child:
37:c29c330d942c
First commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
bogdanm 0:eff01767de02 1 /* Copyright (c) 2013 Nordic Semiconductor. All Rights Reserved.
bogdanm 0:eff01767de02 2 *
bogdanm 0:eff01767de02 3 * The information contained herein is property of Nordic Semiconductor ASA.
bogdanm 0:eff01767de02 4 * Terms and conditions of usage are described in detail in NORDIC
bogdanm 0:eff01767de02 5 * SEMICONDUCTOR STANDARD SOFTWARE LICENSE AGREEMENT.
bogdanm 0:eff01767de02 6 *
bogdanm 0:eff01767de02 7 * Licensees are granted free, non-transferable use of the information. NO
bogdanm 0:eff01767de02 8 * WARRANTY of ANY KIND is provided. This heading must NOT be removed from
bogdanm 0:eff01767de02 9 * the file.
bogdanm 0:eff01767de02 10 *
bogdanm 0:eff01767de02 11 */
bogdanm 0:eff01767de02 12
bogdanm 0:eff01767de02 13 /** @file
bogdanm 0:eff01767de02 14 *
bogdanm 0:eff01767de02 15 * @defgroup softdevice_handler SoftDevice Event Handler
bogdanm 0:eff01767de02 16 * @{
bogdanm 0:eff01767de02 17 * @ingroup app_common
bogdanm 0:eff01767de02 18 * @brief API for initializing and disabling the SoftDevice
bogdanm 0:eff01767de02 19 *
bogdanm 0:eff01767de02 20 * @details This API contains the functions and defines exposed by the @ref lib_softdevice_handler.
bogdanm 0:eff01767de02 21 * For more information on the library and how the application should use it, please refer
bogdanm 0:eff01767de02 22 * @ref lib_softdevice_handler.
bogdanm 0:eff01767de02 23 *
bogdanm 0:eff01767de02 24 * @note Use the USE_SCHEDULER parameter of the SOFTDEVICE_HANDLER_INIT() macro to select if
bogdanm 0:eff01767de02 25 * the @ref app_scheduler is to be used or not.
bogdanm 0:eff01767de02 26 *
bogdanm 0:eff01767de02 27 * @note Even if the scheduler is not used, softdevice_handler.h will include app_scheduler.h.
bogdanm 0:eff01767de02 28 * So when compiling, app_scheduler.h must be available in one of the compiler include
bogdanm 0:eff01767de02 29 * paths.
bogdanm 0:eff01767de02 30 */
bogdanm 0:eff01767de02 31
bogdanm 0:eff01767de02 32 #ifndef SOFTDEVICE_HANDLER_H__
bogdanm 0:eff01767de02 33 #define SOFTDEVICE_HANDLER_H__
bogdanm 0:eff01767de02 34
bogdanm 0:eff01767de02 35 #include <stdlib.h>
bogdanm 0:eff01767de02 36 #include "nordic_global.h"
bogdanm 0:eff01767de02 37 #include "nrf_sdm.h"
bogdanm 0:eff01767de02 38 #include "app_error.h"
bogdanm 0:eff01767de02 39 #include "app_scheduler.h"
bogdanm 0:eff01767de02 40 #include "app_util.h"
bogdanm 0:eff01767de02 41 #include "ble_stack_handler_types.h"
bogdanm 0:eff01767de02 42 #include "ant_stack_handler_types.h"
bogdanm 0:eff01767de02 43
bogdanm 0:eff01767de02 44 #define SOFTDEVICE_SCHED_EVT_SIZE 0 /**< Size of button events being passed through the scheduler (is to be used for computing the maximum size of scheduler events). For SoftDevice events, this size is 0, since the events are being pulled in the event handler. */
bogdanm 0:eff01767de02 45 #define SYS_EVT_MSG_BUF_SIZE sizeof(uint32_t) /**< Size of System (SOC) event message buffer. */
bogdanm 0:eff01767de02 46
bogdanm 0:eff01767de02 47 /**@brief Type of function for passing events from the stack handler module to the scheduler. */
bogdanm 0:eff01767de02 48 typedef uint32_t (*softdevice_evt_schedule_func_t) (void);
bogdanm 0:eff01767de02 49
bogdanm 0:eff01767de02 50 /**@brief Application System (SOC) event handler type. */
bogdanm 0:eff01767de02 51 typedef void (*sys_evt_handler_t) (uint32_t evt_id);
bogdanm 0:eff01767de02 52
bogdanm 0:eff01767de02 53
bogdanm 0:eff01767de02 54 /**@brief Macro for initializing the stack event handler.
bogdanm 0:eff01767de02 55 *
bogdanm 0:eff01767de02 56 * @details It will handle dimensioning and allocation of the memory buffer required for reading
bogdanm 0:eff01767de02 57 * events from the stack, making sure the buffer is correctly aligned. It will also
bogdanm 0:eff01767de02 58 * connect the stack event handler to the scheduler (if specified).
bogdanm 0:eff01767de02 59 *
bogdanm 0:eff01767de02 60 * @param[in] CLOCK_SOURCE Low frequency clock source and accuracy (type nrf_clock_lfclksrc_t,
bogdanm 0:eff01767de02 61 * see sd_softdevice_enable() for details).
bogdanm 0:eff01767de02 62 * @param[in] USE_SCHEDULER TRUE if the application is using the event scheduler, FALSE
bogdanm 0:eff01767de02 63 * otherwise.
bogdanm 0:eff01767de02 64 *
bogdanm 0:eff01767de02 65 * @note Since this macro allocates a buffer, it must only be called once (it is OK to call it
bogdanm 0:eff01767de02 66 * several times as long as it is from the same location, that is to do a
bogdanm 0:eff01767de02 67 * reinitialization).
bogdanm 0:eff01767de02 68 */
bogdanm 0:eff01767de02 69 /*lint -emacro(506, SOFTDEVICE_HANDLER_INIT) */ /* Suppress "Constant value Boolean */
bogdanm 0:eff01767de02 70 #define SOFTDEVICE_HANDLER_INIT(CLOCK_SOURCE, \
bogdanm 0:eff01767de02 71 USE_SCHEDULER) \
bogdanm 0:eff01767de02 72 do \
bogdanm 0:eff01767de02 73 { \
bogdanm 0:eff01767de02 74 static uint32_t EVT_BUFFER[CEIL_DIV(MAX( \
bogdanm 0:eff01767de02 75 MAX(BLE_STACK_EVT_MSG_BUF_SIZE, \
bogdanm 0:eff01767de02 76 ANT_STACK_EVT_STRUCT_SIZE), \
bogdanm 0:eff01767de02 77 SYS_EVT_MSG_BUF_SIZE \
bogdanm 0:eff01767de02 78 ), \
bogdanm 0:eff01767de02 79 sizeof(uint32_t))]; \
bogdanm 0:eff01767de02 80 uint32_t ERR_CODE; \
bogdanm 0:eff01767de02 81 ERR_CODE = softdevice_handler_init((CLOCK_SOURCE), \
bogdanm 0:eff01767de02 82 EVT_BUFFER, \
bogdanm 0:eff01767de02 83 sizeof(EVT_BUFFER), \
bogdanm 0:eff01767de02 84 (USE_SCHEDULER) ? softdevice_evt_schedule : NULL); \
bogdanm 0:eff01767de02 85 APP_ERROR_CHECK(ERR_CODE); \
bogdanm 0:eff01767de02 86 } while (0)
bogdanm 0:eff01767de02 87
bogdanm 0:eff01767de02 88
bogdanm 0:eff01767de02 89 /**@brief Function for initializing the stack handler module.
bogdanm 0:eff01767de02 90 *
bogdanm 0:eff01767de02 91 * @details Enables the SoftDevice and the stack event interrupt handler.
bogdanm 0:eff01767de02 92 *
bogdanm 0:eff01767de02 93 * @note This function must be called before calling any function in the SoftDevice API.
bogdanm 0:eff01767de02 94 *
bogdanm 0:eff01767de02 95 * @note Normally initialization should be done using the SOFTDEVICE_HANDLER_INIT() macro,
bogdanm 0:eff01767de02 96 * as that will both allocate the event buffer, and also align the buffer correctly.
bogdanm 0:eff01767de02 97 *
bogdanm 0:eff01767de02 98 * @param[in] clock_source Low frequency clock source to be used by the SoftDevice.
bogdanm 0:eff01767de02 99 * @param[in] p_evt_buffer Buffer for holding one stack event. Since heap is not being
bogdanm 0:eff01767de02 100 * used, this buffer must be provided by the application. The
bogdanm 0:eff01767de02 101 * buffer must be large enough to hold the biggest stack event the
bogdanm 0:eff01767de02 102 * application is supposed to handle. The buffer must be aligned to
bogdanm 0:eff01767de02 103 * a 4 byte boundary. This parameter is unused if neither BLE nor
bogdanm 0:eff01767de02 104 * ANT stack support is required.
bogdanm 0:eff01767de02 105 * @param[in] evt_buffer_size Size of SoftDevice event buffer. This parameter is unused if
bogdanm 0:eff01767de02 106 * BLE stack support is not required.
bogdanm 0:eff01767de02 107 * @param[in] evt_schedule_func Function for passing events to the scheduler. Point to
bogdanm 0:eff01767de02 108 * ble_ant_stack_evt_schedule() to connect to the scheduler.
bogdanm 0:eff01767de02 109 * Set to NULL to make the stack handler module call the event
bogdanm 0:eff01767de02 110 * handler directly from the stack event interrupt handler.
bogdanm 0:eff01767de02 111 *
bogdanm 0:eff01767de02 112 * @retval NRF_SUCCESS Successful initialization.
bogdanm 0:eff01767de02 113 * @retval NRF_ERROR_INVALID_PARAM Invalid parameter (buffer not aligned to a 4 byte
bogdanm 0:eff01767de02 114 * boundary) or NULL.
bogdanm 0:eff01767de02 115 */
bogdanm 0:eff01767de02 116 uint32_t softdevice_handler_init(nrf_clock_lfclksrc_t clock_source,
bogdanm 0:eff01767de02 117 void * p_evt_buffer,
bogdanm 0:eff01767de02 118 uint16_t evt_buffer_size,
bogdanm 0:eff01767de02 119 softdevice_evt_schedule_func_t evt_schedule_func);
bogdanm 0:eff01767de02 120
bogdanm 0:eff01767de02 121
bogdanm 0:eff01767de02 122 /**@brief Function for disabling the SoftDevice.
bogdanm 0:eff01767de02 123 *
bogdanm 0:eff01767de02 124 * @details This function will disable the SoftDevice. It will also update the internal state
bogdanm 0:eff01767de02 125 * of this module.
bogdanm 0:eff01767de02 126 */
bogdanm 0:eff01767de02 127 uint32_t softdevice_handler_sd_disable(void);
bogdanm 0:eff01767de02 128
bogdanm 0:eff01767de02 129
bogdanm 0:eff01767de02 130 /**@brief Function for registering for System (SOC) events.
bogdanm 0:eff01767de02 131 *
bogdanm 0:eff01767de02 132 * @details The application should use this function to register for receiving System (SOC)
bogdanm 0:eff01767de02 133 * events from the SoftDevice. If the application does not call this function, then any
bogdanm 0:eff01767de02 134 * System (SOC) events that may be generated by the SoftDevice will NOT be fetched. Once
bogdanm 0:eff01767de02 135 * the application has registered for the events, it is not possible to possible to
bogdanm 0:eff01767de02 136 * cancel the registration. However, it is possible to register a different function for
bogdanm 0:eff01767de02 137 * handling the events at any point of time.
bogdanm 0:eff01767de02 138 *
bogdanm 0:eff01767de02 139 * @param[in] sys_evt_handler Function to be called for each received System (SOC) event.
bogdanm 0:eff01767de02 140 *
bogdanm 0:eff01767de02 141 * @retval NRF_SUCCESS Successful registration.
bogdanm 0:eff01767de02 142 * @retval NRF_ERROR_NULL Null pointer provided as input.
bogdanm 0:eff01767de02 143 */
bogdanm 0:eff01767de02 144 uint32_t softdevice_sys_evt_handler_set(sys_evt_handler_t sys_evt_handler);
bogdanm 0:eff01767de02 145
bogdanm 0:eff01767de02 146
bogdanm 0:eff01767de02 147 // Functions for connecting the Stack Event Handler to the scheduler:
bogdanm 0:eff01767de02 148 /**@cond NO_DOXYGEN */
bogdanm 0:eff01767de02 149 void intern_softdevice_events_execute(void);
bogdanm 0:eff01767de02 150
bogdanm 0:eff01767de02 151 static __INLINE void softdevice_evt_get(void * p_event_data, uint16_t event_size)
bogdanm 0:eff01767de02 152 {
bogdanm 0:eff01767de02 153 APP_ERROR_CHECK_BOOL(event_size == 0);
bogdanm 0:eff01767de02 154 intern_softdevice_events_execute();
bogdanm 0:eff01767de02 155 }
bogdanm 0:eff01767de02 156
bogdanm 0:eff01767de02 157 static __INLINE uint32_t softdevice_evt_schedule(void)
bogdanm 0:eff01767de02 158 {
bogdanm 0:eff01767de02 159 return app_sched_event_put(NULL, 0, softdevice_evt_get);
bogdanm 0:eff01767de02 160 }
bogdanm 0:eff01767de02 161 /**@endcond */
bogdanm 0:eff01767de02 162
bogdanm 0:eff01767de02 163 #endif // SOFTDEVICE_HANDLER_H__
bogdanm 0:eff01767de02 164
bogdanm 0:eff01767de02 165 /** @} */