long dao / nRF51822

Old version

Dependents:   VNG_BLE_Basic

Fork of nRF51822 by Nordic Semiconductor

nordic/nrf-sdk/sd_common/softdevice_handler.h@45:3c4df37ed83e, 2014-07-16 (annotated)

Committer:
Rohit Grover
Date:
Wed Jul 16 10:53:07 2014 +0100
Revision:
45:3c4df37ed83e
Parent:
37:c29c330d942c
Child:
56:a1071b629aa3
add cplusplus guards for the cases where C files include the headers

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>
Rohit Grover 37:c29c330d942c 36 #include "nordic_common.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
Rohit Grover 45:3c4df37ed83e 44 #ifdef __cplusplus
Rohit Grover 45:3c4df37ed83e 45 extern "C" {
Rohit Grover 45:3c4df37ed83e 46 #endif // #ifdef __cplusplus
Rohit Grover 45:3c4df37ed83e 47
bogdanm 0:eff01767de02 48 #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 49 #define SYS_EVT_MSG_BUF_SIZE sizeof(uint32_t) /**< Size of System (SOC) event message buffer. */
bogdanm 0:eff01767de02 50
bogdanm 0:eff01767de02 51 /**@brief Type of function for passing events from the stack handler module to the scheduler. */
bogdanm 0:eff01767de02 52 typedef uint32_t (*softdevice_evt_schedule_func_t) (void);
bogdanm 0:eff01767de02 53
bogdanm 0:eff01767de02 54 /**@brief Application System (SOC) event handler type. */
bogdanm 0:eff01767de02 55 typedef void (*sys_evt_handler_t) (uint32_t evt_id);
bogdanm 0:eff01767de02 56
bogdanm 0:eff01767de02 57
bogdanm 0:eff01767de02 58 /**@brief Macro for initializing the stack event handler.
bogdanm 0:eff01767de02 59 *
bogdanm 0:eff01767de02 60 * @details It will handle dimensioning and allocation of the memory buffer required for reading
bogdanm 0:eff01767de02 61 * events from the stack, making sure the buffer is correctly aligned. It will also
bogdanm 0:eff01767de02 62 * connect the stack event handler to the scheduler (if specified).
bogdanm 0:eff01767de02 63 *
bogdanm 0:eff01767de02 64 * @param[in] CLOCK_SOURCE Low frequency clock source and accuracy (type nrf_clock_lfclksrc_t,
bogdanm 0:eff01767de02 65 * see sd_softdevice_enable() for details).
bogdanm 0:eff01767de02 66 * @param[in] USE_SCHEDULER TRUE if the application is using the event scheduler, FALSE
bogdanm 0:eff01767de02 67 * otherwise.
bogdanm 0:eff01767de02 68 *
bogdanm 0:eff01767de02 69 * @note Since this macro allocates a buffer, it must only be called once (it is OK to call it
bogdanm 0:eff01767de02 70 * several times as long as it is from the same location, that is to do a
bogdanm 0:eff01767de02 71 * reinitialization).
bogdanm 0:eff01767de02 72 */
bogdanm 0:eff01767de02 73 /*lint -emacro(506, SOFTDEVICE_HANDLER_INIT) */ /* Suppress "Constant value Boolean */
bogdanm 0:eff01767de02 74 #define SOFTDEVICE_HANDLER_INIT(CLOCK_SOURCE, \
bogdanm 0:eff01767de02 75 USE_SCHEDULER) \
bogdanm 0:eff01767de02 76 do \
bogdanm 0:eff01767de02 77 { \
bogdanm 0:eff01767de02 78 static uint32_t EVT_BUFFER[CEIL_DIV(MAX( \
bogdanm 0:eff01767de02 79 MAX(BLE_STACK_EVT_MSG_BUF_SIZE, \
bogdanm 0:eff01767de02 80 ANT_STACK_EVT_STRUCT_SIZE), \
bogdanm 0:eff01767de02 81 SYS_EVT_MSG_BUF_SIZE \
bogdanm 0:eff01767de02 82 ), \
bogdanm 0:eff01767de02 83 sizeof(uint32_t))]; \
bogdanm 0:eff01767de02 84 uint32_t ERR_CODE; \
bogdanm 0:eff01767de02 85 ERR_CODE = softdevice_handler_init((CLOCK_SOURCE), \
bogdanm 0:eff01767de02 86 EVT_BUFFER, \
bogdanm 0:eff01767de02 87 sizeof(EVT_BUFFER), \
bogdanm 0:eff01767de02 88 (USE_SCHEDULER) ? softdevice_evt_schedule : NULL); \
bogdanm 0:eff01767de02 89 APP_ERROR_CHECK(ERR_CODE); \
bogdanm 0:eff01767de02 90 } while (0)
bogdanm 0:eff01767de02 91
bogdanm 0:eff01767de02 92
bogdanm 0:eff01767de02 93 /**@brief Function for initializing the stack handler module.
bogdanm 0:eff01767de02 94 *
bogdanm 0:eff01767de02 95 * @details Enables the SoftDevice and the stack event interrupt handler.
bogdanm 0:eff01767de02 96 *
bogdanm 0:eff01767de02 97 * @note This function must be called before calling any function in the SoftDevice API.
bogdanm 0:eff01767de02 98 *
bogdanm 0:eff01767de02 99 * @note Normally initialization should be done using the SOFTDEVICE_HANDLER_INIT() macro,
bogdanm 0:eff01767de02 100 * as that will both allocate the event buffer, and also align the buffer correctly.
bogdanm 0:eff01767de02 101 *
bogdanm 0:eff01767de02 102 * @param[in] clock_source Low frequency clock source to be used by the SoftDevice.
bogdanm 0:eff01767de02 103 * @param[in] p_evt_buffer Buffer for holding one stack event. Since heap is not being
bogdanm 0:eff01767de02 104 * used, this buffer must be provided by the application. The
bogdanm 0:eff01767de02 105 * buffer must be large enough to hold the biggest stack event the
bogdanm 0:eff01767de02 106 * application is supposed to handle. The buffer must be aligned to
bogdanm 0:eff01767de02 107 * a 4 byte boundary. This parameter is unused if neither BLE nor
bogdanm 0:eff01767de02 108 * ANT stack support is required.
bogdanm 0:eff01767de02 109 * @param[in] evt_buffer_size Size of SoftDevice event buffer. This parameter is unused if
bogdanm 0:eff01767de02 110 * BLE stack support is not required.
bogdanm 0:eff01767de02 111 * @param[in] evt_schedule_func Function for passing events to the scheduler. Point to
bogdanm 0:eff01767de02 112 * ble_ant_stack_evt_schedule() to connect to the scheduler.
bogdanm 0:eff01767de02 113 * Set to NULL to make the stack handler module call the event
bogdanm 0:eff01767de02 114 * handler directly from the stack event interrupt handler.
bogdanm 0:eff01767de02 115 *
bogdanm 0:eff01767de02 116 * @retval NRF_SUCCESS Successful initialization.
bogdanm 0:eff01767de02 117 * @retval NRF_ERROR_INVALID_PARAM Invalid parameter (buffer not aligned to a 4 byte
bogdanm 0:eff01767de02 118 * boundary) or NULL.
bogdanm 0:eff01767de02 119 */
bogdanm 0:eff01767de02 120 uint32_t softdevice_handler_init(nrf_clock_lfclksrc_t clock_source,
bogdanm 0:eff01767de02 121 void * p_evt_buffer,
bogdanm 0:eff01767de02 122 uint16_t evt_buffer_size,
bogdanm 0:eff01767de02 123 softdevice_evt_schedule_func_t evt_schedule_func);
bogdanm 0:eff01767de02 124
bogdanm 0:eff01767de02 125
bogdanm 0:eff01767de02 126 /**@brief Function for disabling the SoftDevice.
bogdanm 0:eff01767de02 127 *
bogdanm 0:eff01767de02 128 * @details This function will disable the SoftDevice. It will also update the internal state
bogdanm 0:eff01767de02 129 * of this module.
bogdanm 0:eff01767de02 130 */
bogdanm 0:eff01767de02 131 uint32_t softdevice_handler_sd_disable(void);
bogdanm 0:eff01767de02 132
bogdanm 0:eff01767de02 133
bogdanm 0:eff01767de02 134 /**@brief Function for registering for System (SOC) events.
bogdanm 0:eff01767de02 135 *
bogdanm 0:eff01767de02 136 * @details The application should use this function to register for receiving System (SOC)
bogdanm 0:eff01767de02 137 * events from the SoftDevice. If the application does not call this function, then any
bogdanm 0:eff01767de02 138 * System (SOC) events that may be generated by the SoftDevice will NOT be fetched. Once
bogdanm 0:eff01767de02 139 * the application has registered for the events, it is not possible to possible to
bogdanm 0:eff01767de02 140 * cancel the registration. However, it is possible to register a different function for
bogdanm 0:eff01767de02 141 * handling the events at any point of time.
bogdanm 0:eff01767de02 142 *
bogdanm 0:eff01767de02 143 * @param[in] sys_evt_handler Function to be called for each received System (SOC) event.
bogdanm 0:eff01767de02 144 *
bogdanm 0:eff01767de02 145 * @retval NRF_SUCCESS Successful registration.
bogdanm 0:eff01767de02 146 * @retval NRF_ERROR_NULL Null pointer provided as input.
bogdanm 0:eff01767de02 147 */
bogdanm 0:eff01767de02 148 uint32_t softdevice_sys_evt_handler_set(sys_evt_handler_t sys_evt_handler);
bogdanm 0:eff01767de02 149
bogdanm 0:eff01767de02 150
bogdanm 0:eff01767de02 151 // Functions for connecting the Stack Event Handler to the scheduler:
bogdanm 0:eff01767de02 152 /**@cond NO_DOXYGEN */
bogdanm 0:eff01767de02 153 void intern_softdevice_events_execute(void);
bogdanm 0:eff01767de02 154
bogdanm 0:eff01767de02 155 static __INLINE void softdevice_evt_get(void * p_event_data, uint16_t event_size)
bogdanm 0:eff01767de02 156 {
bogdanm 0:eff01767de02 157 APP_ERROR_CHECK_BOOL(event_size == 0);
bogdanm 0:eff01767de02 158 intern_softdevice_events_execute();
bogdanm 0:eff01767de02 159 }
bogdanm 0:eff01767de02 160
bogdanm 0:eff01767de02 161 static __INLINE uint32_t softdevice_evt_schedule(void)
bogdanm 0:eff01767de02 162 {
bogdanm 0:eff01767de02 163 return app_sched_event_put(NULL, 0, softdevice_evt_get);
bogdanm 0:eff01767de02 164 }
bogdanm 0:eff01767de02 165 /**@endcond */
bogdanm 0:eff01767de02 166
Rohit Grover 45:3c4df37ed83e 167 #ifdef __cplusplus
Rohit Grover 45:3c4df37ed83e 168 }
Rohit Grover 45:3c4df37ed83e 169 #endif // #ifdef __cplusplus
Rohit Grover 45:3c4df37ed83e 170
bogdanm 0:eff01767de02 171 #endif // SOFTDEVICE_HANDLER_H__
bogdanm 0:eff01767de02 172
bogdanm 0:eff01767de02 173 /** @} */