Nordic Semiconductor / nrf51-sdk

Nordic nrf51 sdk sources. Mirrored from https://github.com/ARMmbed/nrf51-sdk.

Dependents:   nRF51822 nRF51822

source/nordic_sdk/components/softdevice/common/softdevice_handler/softdevice_handler.h@19:47192cb9def7, 2016-04-07 (annotated)

Committer:
vcoubard
Date:
Thu Apr 07 17:37:40 2016 +0100
Revision:
19:47192cb9def7
Parent:
10:233fefd8162b
Child:
20:a90c48eb1d30
Synchronized with git rev 9251259f

Author: Liyou Zhou

Copy over coresponding files from nordic-sdk 9.0.0

Who changed what in which revision?

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