Mustahsin Chowdhury / nRF51822

Nordic stack and drivers for the mbed BLE API

Fork of nRF51822 by Nordic Semiconductor

TARGET_MCU_NRF51822/sdk/source/softdevice/common/softdevice_handler/softdevice_handler.h@640:c90ae1400bf2, 2016-09-14 (annotated)

Committer:
Vincent Coubard
Date:
Wed Sep 14 14:39:43 2016 +0100
Revision:
640:c90ae1400bf2
Sync with bdab10dc0f90748b6989c8b577771bb403ca6bd8 from ARMmbed/mbed-os.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Vincent Coubard 640:c90ae1400bf2 1 /*
Vincent Coubard 640:c90ae1400bf2 2 * Copyright (c) Nordic Semiconductor ASA
Vincent Coubard 640:c90ae1400bf2 3 * All rights reserved.
Vincent Coubard 640:c90ae1400bf2 4 *
Vincent Coubard 640:c90ae1400bf2 5 * Redistribution and use in source and binary forms, with or without modification,
Vincent Coubard 640:c90ae1400bf2 6 * are permitted provided that the following conditions are met:
Vincent Coubard 640:c90ae1400bf2 7 *
Vincent Coubard 640:c90ae1400bf2 8 * 1. Redistributions of source code must retain the above copyright notice, this
Vincent Coubard 640:c90ae1400bf2 9 * list of conditions and the following disclaimer.
Vincent Coubard 640:c90ae1400bf2 10 *
Vincent Coubard 640:c90ae1400bf2 11 * 2. Redistributions in binary form must reproduce the above copyright notice, this
Vincent Coubard 640:c90ae1400bf2 12 * list of conditions and the following disclaimer in the documentation and/or
Vincent Coubard 640:c90ae1400bf2 13 * other materials provided with the distribution.
Vincent Coubard 640:c90ae1400bf2 14 *
Vincent Coubard 640:c90ae1400bf2 15 * 3. Neither the name of Nordic Semiconductor ASA nor the names of other
Vincent Coubard 640:c90ae1400bf2 16 * contributors to this software may be used to endorse or promote products
Vincent Coubard 640:c90ae1400bf2 17 * derived from this software without specific prior written permission.
Vincent Coubard 640:c90ae1400bf2 18 *
Vincent Coubard 640:c90ae1400bf2 19 *
Vincent Coubard 640:c90ae1400bf2 20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
Vincent Coubard 640:c90ae1400bf2 21 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
Vincent Coubard 640:c90ae1400bf2 22 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
Vincent Coubard 640:c90ae1400bf2 23 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
Vincent Coubard 640:c90ae1400bf2 24 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
Vincent Coubard 640:c90ae1400bf2 25 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
Vincent Coubard 640:c90ae1400bf2 26 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
Vincent Coubard 640:c90ae1400bf2 27 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
Vincent Coubard 640:c90ae1400bf2 28 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
Vincent Coubard 640:c90ae1400bf2 29 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Vincent Coubard 640:c90ae1400bf2 30 *
Vincent Coubard 640:c90ae1400bf2 31 */
Vincent Coubard 640:c90ae1400bf2 32
Vincent Coubard 640:c90ae1400bf2 33 /** @file
Vincent Coubard 640:c90ae1400bf2 34 *
Vincent Coubard 640:c90ae1400bf2 35 * @defgroup softdevice_handler SoftDevice Event Handler
Vincent Coubard 640:c90ae1400bf2 36 * @{
Vincent Coubard 640:c90ae1400bf2 37 * @ingroup app_common
Vincent Coubard 640:c90ae1400bf2 38 * @brief API for initializing and disabling the SoftDevice
Vincent Coubard 640:c90ae1400bf2 39 *
Vincent Coubard 640:c90ae1400bf2 40 * @details This API contains the functions and defines exposed by the @ref lib_softdevice_handler.
Vincent Coubard 640:c90ae1400bf2 41 * For more information on the library and how the application should use it, please refer
Vincent Coubard 640:c90ae1400bf2 42 * @ref lib_softdevice_handler.
Vincent Coubard 640:c90ae1400bf2 43 *
Vincent Coubard 640:c90ae1400bf2 44 * @note Use the USE_SCHEDULER parameter of the SOFTDEVICE_HANDLER_INIT() macro to select if
Vincent Coubard 640:c90ae1400bf2 45 * the @ref app_scheduler is to be used or not.
Vincent Coubard 640:c90ae1400bf2 46 *
Vincent Coubard 640:c90ae1400bf2 47 * @note Even if the scheduler is not used, softdevice_handler.h will include app_scheduler.h.
Vincent Coubard 640:c90ae1400bf2 48 * So when compiling, app_scheduler.h must be available in one of the compiler include
Vincent Coubard 640:c90ae1400bf2 49 * paths.
Vincent Coubard 640:c90ae1400bf2 50 */
Vincent Coubard 640:c90ae1400bf2 51
Vincent Coubard 640:c90ae1400bf2 52 #ifndef SOFTDEVICE_HANDLER_H__
Vincent Coubard 640:c90ae1400bf2 53 #define SOFTDEVICE_HANDLER_H__
Vincent Coubard 640:c90ae1400bf2 54
Vincent Coubard 640:c90ae1400bf2 55 #include <stdlib.h>
Vincent Coubard 640:c90ae1400bf2 56 #include "nordic_common.h"
Vincent Coubard 640:c90ae1400bf2 57 #include "nrf_sdm.h"
Vincent Coubard 640:c90ae1400bf2 58 #include "app_error.h"
Vincent Coubard 640:c90ae1400bf2 59 #include "app_util.h"
Vincent Coubard 640:c90ae1400bf2 60 #include "ble_stack_handler_types.h"
Vincent Coubard 640:c90ae1400bf2 61 #include "ant_stack_handler_types.h"
Vincent Coubard 640:c90ae1400bf2 62
Vincent Coubard 640:c90ae1400bf2 63 #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 640:c90ae1400bf2 64 #define SYS_EVT_MSG_BUF_SIZE sizeof(uint32_t) /**< Size of System (SOC) event message buffer. */
Vincent Coubard 640:c90ae1400bf2 65
Vincent Coubard 640:c90ae1400bf2 66 /**@brief Type of function for passing events from the stack handler module to the scheduler. */
Vincent Coubard 640:c90ae1400bf2 67 typedef uint32_t (*softdevice_evt_schedule_func_t) (void);
Vincent Coubard 640:c90ae1400bf2 68
Vincent Coubard 640:c90ae1400bf2 69 /**@brief Application System (SOC) event handler type. */
Vincent Coubard 640:c90ae1400bf2 70 typedef void (*sys_evt_handler_t) (uint32_t evt_id);
Vincent Coubard 640:c90ae1400bf2 71
Vincent Coubard 640:c90ae1400bf2 72
Vincent Coubard 640:c90ae1400bf2 73 /**@brief Macro for initializing the stack event handler.
Vincent Coubard 640:c90ae1400bf2 74 *
Vincent Coubard 640:c90ae1400bf2 75 * @details It will handle dimensioning and allocation of the memory buffer required for reading
Vincent Coubard 640:c90ae1400bf2 76 * events from the stack, making sure the buffer is correctly aligned. It will also
Vincent Coubard 640:c90ae1400bf2 77 * connect the stack event handler to the scheduler/RTOS (if specified).
Vincent Coubard 640:c90ae1400bf2 78 *
Vincent Coubard 640:c90ae1400bf2 79 * @param[in] CLOCK_SOURCE Low frequency clock source and accuracy (type nrf_clock_lfclksrc_t,
Vincent Coubard 640:c90ae1400bf2 80 * see sd_softdevice_enable() for details).
Vincent Coubard 640:c90ae1400bf2 81 * @param[in] EVT_HANDLER scheduler/RTOS event handler function.
Vincent Coubard 640:c90ae1400bf2 82 *
Vincent Coubard 640:c90ae1400bf2 83 * @note Since this macro allocates a buffer, it must only be called once (it is OK to call it
Vincent Coubard 640:c90ae1400bf2 84 * several times as long as it is from the same location, that is to do a
Vincent Coubard 640:c90ae1400bf2 85 * reinitialization).
Vincent Coubard 640:c90ae1400bf2 86 */
Vincent Coubard 640:c90ae1400bf2 87 /*lint -emacro(506, SOFTDEVICE_HANDLER_INIT) */ /* Suppress "Constant value Boolean */
Vincent Coubard 640:c90ae1400bf2 88 #define SOFTDEVICE_HANDLER_INIT(CLOCK_SOURCE, \
Vincent Coubard 640:c90ae1400bf2 89 EVT_HANDLER) \
Vincent Coubard 640:c90ae1400bf2 90 do \
Vincent Coubard 640:c90ae1400bf2 91 { \
Vincent Coubard 640:c90ae1400bf2 92 static uint32_t BLE_EVT_BUFFER[CEIL_DIV(BLE_STACK_EVT_MSG_BUF_SIZE, sizeof(uint32_t))]; \
Vincent Coubard 640:c90ae1400bf2 93 uint32_t ERR_CODE; \
Vincent Coubard 640:c90ae1400bf2 94 ERR_CODE = softdevice_handler_init((CLOCK_SOURCE), \
Vincent Coubard 640:c90ae1400bf2 95 BLE_EVT_BUFFER, \
Vincent Coubard 640:c90ae1400bf2 96 sizeof(BLE_EVT_BUFFER), \
Vincent Coubard 640:c90ae1400bf2 97 EVT_HANDLER); \
Vincent Coubard 640:c90ae1400bf2 98 APP_ERROR_CHECK(ERR_CODE); \
Vincent Coubard 640:c90ae1400bf2 99 } while (0)
Vincent Coubard 640:c90ae1400bf2 100
Vincent Coubard 640:c90ae1400bf2 101 /**
Vincent Coubard 640:c90ae1400bf2 102 * @brief Function for retrieving the information about SD state
Vincent Coubard 640:c90ae1400bf2 103 *
Vincent Coubard 640:c90ae1400bf2 104 * The information about current state of softdevice.
Vincent Coubard 640:c90ae1400bf2 105 * @retval false SD is not initialized and SD commands should not be called.
Vincent Coubard 640:c90ae1400bf2 106 * @retval true SD is already initialized
Vincent Coubard 640:c90ae1400bf2 107 */
Vincent Coubard 640:c90ae1400bf2 108 bool softdevice_handler_isEnabled(void);
Vincent Coubard 640:c90ae1400bf2 109
Vincent Coubard 640:c90ae1400bf2 110 /**@brief Function for initializing the stack handler module.
Vincent Coubard 640:c90ae1400bf2 111 *
Vincent Coubard 640:c90ae1400bf2 112 * @details Enables the SoftDevice and the stack event interrupt handler.
Vincent Coubard 640:c90ae1400bf2 113 *
Vincent Coubard 640:c90ae1400bf2 114 * @note This function must be called before calling any function in the SoftDevice API.
Vincent Coubard 640:c90ae1400bf2 115 *
Vincent Coubard 640:c90ae1400bf2 116 * @note Normally initialization should be done using the SOFTDEVICE_HANDLER_INIT() macro,
Vincent Coubard 640:c90ae1400bf2 117 * as that will both allocate the event buffer, and also align the buffer correctly.
Vincent Coubard 640:c90ae1400bf2 118 *
Vincent Coubard 640:c90ae1400bf2 119 * @param[in] clock_source Low frequency clock source to be used by the SoftDevice.
Vincent Coubard 640:c90ae1400bf2 120 * @param[in] p_ble_evt_buffer Buffer for holding one BLE stack event. Since heap is not being
Vincent Coubard 640:c90ae1400bf2 121 * used, this buffer must be provided by the application. The
Vincent Coubard 640:c90ae1400bf2 122 * buffer must be large enough to hold the biggest stack event the
Vincent Coubard 640:c90ae1400bf2 123 * application is supposed to handle. The buffer must be aligned to
Vincent Coubard 640:c90ae1400bf2 124 * a 4 byte boundary. This parameter is unused if BLE stack support
Vincent Coubard 640:c90ae1400bf2 125 * is not required.
Vincent Coubard 640:c90ae1400bf2 126 * @param[in] ble_evt_buffer_size Size of SoftDevice BLE event buffer. This parameter is unused if
Vincent Coubard 640:c90ae1400bf2 127 * BLE stack support is not required.
Vincent Coubard 640:c90ae1400bf2 128 * @param[in] evt_schedule_func Function for passing events to the scheduler. Point to
Vincent Coubard 640:c90ae1400bf2 129 * ble_ant_stack_evt_schedule() to connect to the scheduler.
Vincent Coubard 640:c90ae1400bf2 130 * Set to NULL to make the stack handler module call the event
Vincent Coubard 640:c90ae1400bf2 131 * handler directly from the stack event interrupt handler.
Vincent Coubard 640:c90ae1400bf2 132 *
Vincent Coubard 640:c90ae1400bf2 133 * @retval NRF_SUCCESS Successful initialization.
Vincent Coubard 640:c90ae1400bf2 134 * @retval NRF_ERROR_INVALID_PARAM Invalid parameter (buffer not aligned to a 4 byte
Vincent Coubard 640:c90ae1400bf2 135 * boundary) or NULL.
Vincent Coubard 640:c90ae1400bf2 136 */
Vincent Coubard 640:c90ae1400bf2 137 uint32_t softdevice_handler_init(nrf_clock_lfclksrc_t clock_source,
Vincent Coubard 640:c90ae1400bf2 138 void * p_ble_evt_buffer,
Vincent Coubard 640:c90ae1400bf2 139 uint16_t ble_evt_buffer_size,
Vincent Coubard 640:c90ae1400bf2 140 softdevice_evt_schedule_func_t evt_schedule_func);
Vincent Coubard 640:c90ae1400bf2 141
Vincent Coubard 640:c90ae1400bf2 142
Vincent Coubard 640:c90ae1400bf2 143 /**@brief Function for disabling the SoftDevice.
Vincent Coubard 640:c90ae1400bf2 144 *
Vincent Coubard 640:c90ae1400bf2 145 * @details This function will disable the SoftDevice. It will also update the internal state
Vincent Coubard 640:c90ae1400bf2 146 * of this module.
Vincent Coubard 640:c90ae1400bf2 147 */
Vincent Coubard 640:c90ae1400bf2 148 uint32_t softdevice_handler_sd_disable(void);
Vincent Coubard 640:c90ae1400bf2 149
Vincent Coubard 640:c90ae1400bf2 150
Vincent Coubard 640:c90ae1400bf2 151 /**@brief Function for registering for System (SOC) events.
Vincent Coubard 640:c90ae1400bf2 152 *
Vincent Coubard 640:c90ae1400bf2 153 * @details The application should use this function to register for receiving System (SOC)
Vincent Coubard 640:c90ae1400bf2 154 * events from the SoftDevice. If the application does not call this function, then any
Vincent Coubard 640:c90ae1400bf2 155 * System (SOC) events that may be generated by the SoftDevice will NOT be fetched. Once
Vincent Coubard 640:c90ae1400bf2 156 * the application has registered for the events, it is not possible to possible to
Vincent Coubard 640:c90ae1400bf2 157 * cancel the registration. However, it is possible to register a different function for
Vincent Coubard 640:c90ae1400bf2 158 * handling the events at any point of time.
Vincent Coubard 640:c90ae1400bf2 159 *
Vincent Coubard 640:c90ae1400bf2 160 * @param[in] sys_evt_handler Function to be called for each received System (SOC) event.
Vincent Coubard 640:c90ae1400bf2 161 *
Vincent Coubard 640:c90ae1400bf2 162 * @retval NRF_SUCCESS Successful registration.
Vincent Coubard 640:c90ae1400bf2 163 * @retval NRF_ERROR_NULL Null pointer provided as input.
Vincent Coubard 640:c90ae1400bf2 164 */
Vincent Coubard 640:c90ae1400bf2 165 uint32_t softdevice_sys_evt_handler_set(sys_evt_handler_t sys_evt_handler);
Vincent Coubard 640:c90ae1400bf2 166
Vincent Coubard 640:c90ae1400bf2 167
Vincent Coubard 640:c90ae1400bf2 168 // Functions for connecting the Stack Event Handler to the scheduler:
Vincent Coubard 640:c90ae1400bf2 169 /**@cond NO_DOXYGEN */
Vincent Coubard 640:c90ae1400bf2 170 void intern_softdevice_events_execute(void);
Vincent Coubard 640:c90ae1400bf2 171
Vincent Coubard 640:c90ae1400bf2 172
Vincent Coubard 640:c90ae1400bf2 173 /**@endcond */
Vincent Coubard 640:c90ae1400bf2 174
Vincent Coubard 640:c90ae1400bf2 175 #endif // SOFTDEVICE_HANDLER_H__
Vincent Coubard 640:c90ae1400bf2 176
Vincent Coubard 640:c90ae1400bf2 177 /** @} */