mbed official / mbed

The official Mbed 2 C/C++ SDK provides the software platform and libraries to build your applications.

Dependents:   hello SerialTestv11 SerialTestv12 Sierpinski ... more

mbed 2

This is the mbed 2 library. If you'd like to learn about Mbed OS please see the mbed-os docs.

TARGET_TY51822R3/TOOLCHAIN_IAR/softdevice_handler.h@171:3a7713b1edbc, 2018-11-08 (annotated)

Committer:
AnnaBridge
Date:
Thu Nov 08 11:45:42 2018 +0000
Revision:
171:3a7713b1edbc
Parent:
TARGET_TY51822R3/TARGET_NORDIC/TARGET_NRF5x/TARGET_SDK_11/softdevice/common/softdevice_handler/softdevice_handler.h@169:a7c7b631e539 
mbed library. Release version 164

Who changed what in which revision?

UserRevisionLine numberNew contents of line
AnnaBridge 143:86740a56073b 1 /*
AnnaBridge 143:86740a56073b 2 * Copyright (c) 2013 Nordic Semiconductor ASA
AnnaBridge 143:86740a56073b 3 * All rights reserved.
AnnaBridge 143:86740a56073b 4 *
AnnaBridge 143:86740a56073b 5 * Redistribution and use in source and binary forms, with or without modification,
AnnaBridge 143:86740a56073b 6 * are permitted provided that the following conditions are met:
AnnaBridge 143:86740a56073b 7 *
AnnaBridge 143:86740a56073b 8 * 1. Redistributions of source code must retain the above copyright notice, this list
AnnaBridge 143:86740a56073b 9 * of conditions and the following disclaimer.
AnnaBridge 143:86740a56073b 10 *
AnnaBridge 143:86740a56073b 11 * 2. Redistributions in binary form, except as embedded into a Nordic Semiconductor ASA
AnnaBridge 143:86740a56073b 12 * integrated circuit in a product or a software update for such product, must reproduce
AnnaBridge 143:86740a56073b 13 * the above copyright notice, this list of conditions and the following disclaimer in
AnnaBridge 143:86740a56073b 14 * the documentation and/or other materials provided with the distribution.
AnnaBridge 143:86740a56073b 15 *
AnnaBridge 143:86740a56073b 16 * 3. Neither the name of Nordic Semiconductor ASA nor the names of its contributors may be
AnnaBridge 143:86740a56073b 17 * used to endorse or promote products derived from this software without specific prior
AnnaBridge 143:86740a56073b 18 * written permission.
AnnaBridge 143:86740a56073b 19 *
AnnaBridge 143:86740a56073b 20 * 4. This software, with or without modification, must only be used with a
AnnaBridge 143:86740a56073b 21 * Nordic Semiconductor ASA integrated circuit.
AnnaBridge 143:86740a56073b 22 *
AnnaBridge 143:86740a56073b 23 * 5. Any software provided in binary or object form under this license must not be reverse
AnnaBridge 143:86740a56073b 24 * engineered, decompiled, modified and/or disassembled.
AnnaBridge 143:86740a56073b 25 *
AnnaBridge 143:86740a56073b 26 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
AnnaBridge 143:86740a56073b 27 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
AnnaBridge 143:86740a56073b 28 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
AnnaBridge 143:86740a56073b 29 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
AnnaBridge 143:86740a56073b 30 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
AnnaBridge 143:86740a56073b 31 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
AnnaBridge 143:86740a56073b 32 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
AnnaBridge 143:86740a56073b 33 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
AnnaBridge 143:86740a56073b 34 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
AnnaBridge 143:86740a56073b 35 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
AnnaBridge 143:86740a56073b 36 *
AnnaBridge 143:86740a56073b 37 */
AnnaBridge 143:86740a56073b 38
AnnaBridge 143:86740a56073b 39
AnnaBridge 143:86740a56073b 40 /** @file
AnnaBridge 143:86740a56073b 41 *
AnnaBridge 143:86740a56073b 42 * @defgroup softdevice_handler SoftDevice Event Handler
AnnaBridge 143:86740a56073b 43 * @{
AnnaBridge 143:86740a56073b 44 * @ingroup app_common
AnnaBridge 143:86740a56073b 45 * @brief API for initializing and disabling the SoftDevice
AnnaBridge 143:86740a56073b 46 *
AnnaBridge 143:86740a56073b 47 * @details This API contains the functions and defines exposed by the @ref lib_softdevice_handler.
AnnaBridge 143:86740a56073b 48 * For more information on the library and how the application should use it, please refer
AnnaBridge 143:86740a56073b 49 * @ref lib_softdevice_handler.
AnnaBridge 143:86740a56073b 50 *
AnnaBridge 143:86740a56073b 51 * @note Use the USE_SCHEDULER parameter of the SOFTDEVICE_HANDLER_INIT() macro to select if
AnnaBridge 143:86740a56073b 52 * the @ref app_scheduler is to be used or not.
AnnaBridge 143:86740a56073b 53 *
AnnaBridge 143:86740a56073b 54 * @note Even if the scheduler is not used, softdevice_handler.h will include app_scheduler.h.
AnnaBridge 143:86740a56073b 55 * So when compiling, app_scheduler.h must be available in one of the compiler include
AnnaBridge 143:86740a56073b 56 * paths.
AnnaBridge 143:86740a56073b 57 */
AnnaBridge 143:86740a56073b 58
AnnaBridge 143:86740a56073b 59 #ifndef SOFTDEVICE_HANDLER_H__
AnnaBridge 143:86740a56073b 60 #define SOFTDEVICE_HANDLER_H__
AnnaBridge 143:86740a56073b 61
AnnaBridge 143:86740a56073b 62 #include <stdlib.h>
AnnaBridge 143:86740a56073b 63 #include "nordic_common.h"
AnnaBridge 143:86740a56073b 64 #include "nrf_sdm.h"
AnnaBridge 143:86740a56073b 65 #include "app_error.h"
AnnaBridge 143:86740a56073b 66 #include "app_util.h"
AnnaBridge 143:86740a56073b 67 #include "ble_stack_handler_types.h"
AnnaBridge 143:86740a56073b 68 #include "ant_stack_handler_types.h"
AnnaBridge 143:86740a56073b 69 #if defined(BLE_STACK_SUPPORT_REQD)
AnnaBridge 143:86740a56073b 70 #include "nrf_ble.h"
AnnaBridge 143:86740a56073b 71 #endif
AnnaBridge 143:86740a56073b 72 #include "app_ram_base.h"
AnnaBridge 143:86740a56073b 73 #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. */
AnnaBridge 143:86740a56073b 74 #define SYS_EVT_MSG_BUF_SIZE sizeof(uint32_t) /**< Size of System (SOC) event message buffer. */
AnnaBridge 143:86740a56073b 75
AnnaBridge 143:86740a56073b 76
AnnaBridge 143:86740a56073b 77 #define CHECK_RAM_START_ADDR_INTERN(CENTRAL_LINK_COUNT, PERIPHERAL_LINK_COUNT) \
AnnaBridge 143:86740a56073b 78 do{ \
AnnaBridge 143:86740a56073b 79 uint32_t app_ram_start_addr = APP_RAM_BASE_CENTRAL_LINKS_##CENTRAL_LINK_COUNT##_PERIPH_LINKS_##PERIPHERAL_LINK_COUNT##_SEC_COUNT_0_MID_BW; \
AnnaBridge 143:86740a56073b 80 err_code = sd_check_ram_start(app_ram_start_addr); \
AnnaBridge 143:86740a56073b 81 APP_ERROR_CHECK(err_code); \
AnnaBridge 143:86740a56073b 82 } while (0)
AnnaBridge 143:86740a56073b 83
AnnaBridge 143:86740a56073b 84 /** @brief Macro for checking the RAM requirement of the SoftDevice */
AnnaBridge 143:86740a56073b 85 #define CHECK_RAM_START_ADDR(C_LINK_CNT, P_LINK_CNT) CHECK_RAM_START_ADDR_INTERN(C_LINK_CNT, P_LINK_CNT)
AnnaBridge 143:86740a56073b 86
AnnaBridge 143:86740a56073b 87
AnnaBridge 143:86740a56073b 88 /**@brief Function for checking the RAM requirement of the SoftDevice.
AnnaBridge 143:86740a56073b 89 *
AnnaBridge 143:86740a56073b 90 * @details Call this function to check if the project settings have the correct RAM start address in respect to what the SoftDevice requires.
AnnaBridge 143:86740a56073b 91 *
AnnaBridge 143:86740a56073b 92 * @note This function is called using the CHECK_RAM_START_ADDR_INTERN macro and should not be called directly.
AnnaBridge 143:86740a56073b 93 */
AnnaBridge 143:86740a56073b 94 uint32_t sd_check_ram_start(uint32_t sd_req_ram_start);
AnnaBridge 143:86740a56073b 95
AnnaBridge 143:86740a56073b 96 /**@brief Type of function for passing events from the stack handler module to the scheduler. */
AnnaBridge 143:86740a56073b 97 typedef uint32_t (*softdevice_evt_schedule_func_t) (void);
AnnaBridge 143:86740a56073b 98
AnnaBridge 143:86740a56073b 99 /**@brief Application System (SOC) event handler type. */
AnnaBridge 143:86740a56073b 100 typedef void (*sys_evt_handler_t) (uint32_t evt_id);
AnnaBridge 143:86740a56073b 101
AnnaBridge 143:86740a56073b 102
AnnaBridge 143:86740a56073b 103 /**@brief Macro for initializing the stack event handler.
AnnaBridge 143:86740a56073b 104 *
AnnaBridge 143:86740a56073b 105 * @details It will handle dimensioning and allocation of the memory buffer required for reading
AnnaBridge 143:86740a56073b 106 * events from the stack, making sure the buffer is correctly aligned. It will also
AnnaBridge 143:86740a56073b 107 * connect the stack event handler to the scheduler/RTOS (if specified).
AnnaBridge 143:86740a56073b 108 *
AnnaBridge 143:86740a56073b 109 * @param[in] CLOCK_SOURCE Low frequency clock source and accuracy (type nrf_clock_lf_cfg_t_t,
AnnaBridge 143:86740a56073b 110 * see sd_softdevice_enable() for details).
AnnaBridge 143:86740a56073b 111 * @param[in] EVT_HANDLER scheduler/RTOS event handler function.
AnnaBridge 143:86740a56073b 112 *
AnnaBridge 143:86740a56073b 113 * @note Since this macro allocates a buffer, it must only be called once (it is OK to call it
AnnaBridge 143:86740a56073b 114 * several times as long as it is from the same location, that is to do a
AnnaBridge 143:86740a56073b 115 * reinitialization).
AnnaBridge 143:86740a56073b 116 */
AnnaBridge 143:86740a56073b 117 /*lint -emacro(506, SOFTDEVICE_HANDLER_INIT) */ /* Suppress "Constant value Boolean */
AnnaBridge 143:86740a56073b 118 #define SOFTDEVICE_HANDLER_INIT(CLOCK_SOURCE, \
AnnaBridge 143:86740a56073b 119 EVT_HANDLER) \
AnnaBridge 143:86740a56073b 120 do \
AnnaBridge 143:86740a56073b 121 { \
AnnaBridge 143:86740a56073b 122 static uint32_t BLE_EVT_BUFFER[CEIL_DIV(BLE_STACK_EVT_MSG_BUF_SIZE, sizeof(uint32_t))]; \
AnnaBridge 143:86740a56073b 123 uint32_t ERR_CODE; \
AnnaBridge 143:86740a56073b 124 ERR_CODE = softdevice_handler_init((CLOCK_SOURCE), \
AnnaBridge 143:86740a56073b 125 BLE_EVT_BUFFER, \
AnnaBridge 143:86740a56073b 126 sizeof(BLE_EVT_BUFFER), \
AnnaBridge 143:86740a56073b 127 EVT_HANDLER); \
AnnaBridge 143:86740a56073b 128 APP_ERROR_CHECK(ERR_CODE); \
AnnaBridge 143:86740a56073b 129 } while (0)
AnnaBridge 143:86740a56073b 130
AnnaBridge 143:86740a56073b 131 /**
AnnaBridge 143:86740a56073b 132 * @brief Function for retrieving the information about SD state
AnnaBridge 143:86740a56073b 133 *
AnnaBridge 143:86740a56073b 134 * The information about current state of softdevice.
AnnaBridge 143:86740a56073b 135 * @retval false SD is not initialized and SD commands should not be called.
AnnaBridge 143:86740a56073b 136 * @retval true SD is already initialized
AnnaBridge 143:86740a56073b 137 */
AnnaBridge 143:86740a56073b 138 bool softdevice_handler_isEnabled(void);
AnnaBridge 143:86740a56073b 139
AnnaBridge 143:86740a56073b 140 /**@brief Function for initializing the stack handler module.
AnnaBridge 143:86740a56073b 141 *
AnnaBridge 143:86740a56073b 142 * @details Enables the SoftDevice and the stack event interrupt handler.
AnnaBridge 143:86740a56073b 143 *
AnnaBridge 143:86740a56073b 144 * @note This function must be called before calling any function in the SoftDevice API.
AnnaBridge 143:86740a56073b 145 *
AnnaBridge 143:86740a56073b 146 * @note Normally initialization should be done using the SOFTDEVICE_HANDLER_INIT() macro,
AnnaBridge 143:86740a56073b 147 * as that will both allocate the event buffer, and also align the buffer correctly.
AnnaBridge 143:86740a56073b 148 *
AnnaBridge 143:86740a56073b 149 * @param[in] p_clock_lf_cfg Low frequency clock source to be used by the SoftDevice.
AnnaBridge 143:86740a56073b 150 * @param[in] p_ble_evt_buffer Buffer for holding one BLE stack event. Since heap is not being
AnnaBridge 143:86740a56073b 151 * used, this buffer must be provided by the application. The
AnnaBridge 143:86740a56073b 152 * buffer must be large enough to hold the biggest stack event the
AnnaBridge 143:86740a56073b 153 * application is supposed to handle. The buffer must be aligned to
AnnaBridge 143:86740a56073b 154 * a 4 byte boundary. This parameter is unused if BLE stack support
AnnaBridge 143:86740a56073b 155 * is not required.
AnnaBridge 143:86740a56073b 156 * @param[in] ble_evt_buffer_size Size of SoftDevice BLE event buffer. This parameter is unused if
AnnaBridge 143:86740a56073b 157 * BLE stack support is not required.
AnnaBridge 143:86740a56073b 158 * @param[in] evt_schedule_func Function for passing events to the scheduler. Point to
AnnaBridge 143:86740a56073b 159 * ble_ant_stack_evt_schedule() to connect to the scheduler.
AnnaBridge 143:86740a56073b 160 * Set to NULL to make the stack handler module call the event
AnnaBridge 143:86740a56073b 161 * handler directly from the stack event interrupt handler.
AnnaBridge 143:86740a56073b 162 *
AnnaBridge 143:86740a56073b 163 * @retval NRF_SUCCESS Successful initialization.
AnnaBridge 143:86740a56073b 164 * @retval NRF_ERROR_INVALID_PARAM Invalid parameter (buffer not aligned to a 4 byte
AnnaBridge 143:86740a56073b 165 * boundary) or NULL.
AnnaBridge 143:86740a56073b 166 */
AnnaBridge 143:86740a56073b 167 uint32_t softdevice_handler_init(nrf_clock_lf_cfg_t * p_clock_lf_cfg,
AnnaBridge 143:86740a56073b 168 void * p_ble_evt_buffer,
AnnaBridge 143:86740a56073b 169 uint16_t ble_evt_buffer_size,
AnnaBridge 143:86740a56073b 170 softdevice_evt_schedule_func_t evt_schedule_func);
AnnaBridge 143:86740a56073b 171
AnnaBridge 143:86740a56073b 172
AnnaBridge 143:86740a56073b 173 /**@brief Function for disabling the SoftDevice.
AnnaBridge 143:86740a56073b 174 *
AnnaBridge 143:86740a56073b 175 * @details This function will disable the SoftDevice. It will also update the internal state
AnnaBridge 143:86740a56073b 176 * of this module.
AnnaBridge 143:86740a56073b 177 */
AnnaBridge 143:86740a56073b 178 uint32_t softdevice_handler_sd_disable(void);
AnnaBridge 143:86740a56073b 179
AnnaBridge 143:86740a56073b 180
AnnaBridge 143:86740a56073b 181 /**@brief Function for registering for System (SOC) events.
AnnaBridge 143:86740a56073b 182 *
AnnaBridge 143:86740a56073b 183 * @details The application should use this function to register for receiving System (SOC)
AnnaBridge 143:86740a56073b 184 * events from the SoftDevice. If the application does not call this function, then any
AnnaBridge 143:86740a56073b 185 * System (SOC) events that may be generated by the SoftDevice will NOT be fetched. Once
AnnaBridge 143:86740a56073b 186 * the application has registered for the events, it is not possible to possible to
AnnaBridge 143:86740a56073b 187 * cancel the registration. However, it is possible to register a different function for
AnnaBridge 143:86740a56073b 188 * handling the events at any point of time.
AnnaBridge 143:86740a56073b 189 *
AnnaBridge 143:86740a56073b 190 * @param[in] sys_evt_handler Function to be called for each received System (SOC) event.
AnnaBridge 143:86740a56073b 191 *
AnnaBridge 143:86740a56073b 192 * @retval NRF_SUCCESS Successful registration.
AnnaBridge 143:86740a56073b 193 * @retval NRF_ERROR_NULL Null pointer provided as input.
AnnaBridge 143:86740a56073b 194 */
AnnaBridge 143:86740a56073b 195 uint32_t softdevice_sys_evt_handler_set(sys_evt_handler_t sys_evt_handler);
AnnaBridge 143:86740a56073b 196
AnnaBridge 143:86740a56073b 197 #if defined(BLE_STACK_SUPPORT_REQD)
AnnaBridge 143:86740a56073b 198 /**@brief Function for fetching the default enable parameters for the SoftDevice.
AnnaBridge 143:86740a56073b 199 *
AnnaBridge 143:86740a56073b 200 * @details The default enable parameters will work for most projects in the SDK.
AnnaBridge 143:86740a56073b 201 * They are not optimized with regards to RAM use. This function is meant as a way to abstract the
AnnaBridge 143:86740a56073b 202 * details of p_ble_enable_params needed by @ref softdevice_enable. You might want to tweak
AnnaBridge 143:86740a56073b 203 * the struct returned by this function or fill in the entire ble_enable_params_t
AnnaBridge 143:86740a56073b 204 * instead of fetching it from this function.
AnnaBridge 143:86740a56073b 205 *
AnnaBridge 143:86740a56073b 206 * @param[in] central_links_count Number of central links used by the application.
AnnaBridge 143:86740a56073b 207 * @param[in] periph_links_count Number of peripheral links used by the application.
AnnaBridge 143:86740a56073b 208 * @param[out] p_ble_enable_params Default ble_enable_params_t to be used by @ref softdevice_enable.
AnnaBridge 143:86740a56073b 209 *
AnnaBridge 143:86740a56073b 210 * @retval NRF_SUCCESS If the operation was successful.
AnnaBridge 143:86740a56073b 211 */
AnnaBridge 143:86740a56073b 212 uint32_t softdevice_enable_get_default_config(uint8_t central_links_count,
AnnaBridge 143:86740a56073b 213 uint8_t periph_links_count,
AnnaBridge 143:86740a56073b 214 ble_enable_params_t * p_ble_enable_params);
AnnaBridge 143:86740a56073b 215
AnnaBridge 143:86740a56073b 216 /**@brief Function for enabling the SoftDevice.
AnnaBridge 143:86740a56073b 217 *
AnnaBridge 143:86740a56073b 218 * @details This function calls the @ref sd_ble_enable SVC call. It has been abstracted to give
AnnaBridge 143:86740a56073b 219 * feedback on the app_ram_base. If the app_ram_base is too low, this function will
AnnaBridge 143:86740a56073b 220 * return an error. Using a app_ram_base that is too high will not fail, but will
AnnaBridge 143:86740a56073b 221 * result in RAM that is never used. If the DEBUG macro is enabled, this
AnnaBridge 143:86740a56073b 222 * function will provide the correct app_ram_base as mandated by the SoftDevice.
AnnaBridge 143:86740a56073b 223 * This is useful to tweak the RAM use of your application.
AnnaBridge 143:86740a56073b 224 *
AnnaBridge 143:86740a56073b 225 * @param[in] p_ble_enable_params Parameters for configuring links and bandwidths.
AnnaBridge 143:86740a56073b 226 *
AnnaBridge 143:86740a56073b 227 * @retval NRF_SUCCESS If the operation was successful.
AnnaBridge 143:86740a56073b 228 */
AnnaBridge 143:86740a56073b 229 uint32_t softdevice_enable(ble_enable_params_t * p_ble_enable_params);
AnnaBridge 143:86740a56073b 230 #endif //BLE_STACK_SUPPORT_REQD
AnnaBridge 143:86740a56073b 231 // Functions for connecting the Stack Event Handler to the scheduler:
AnnaBridge 143:86740a56073b 232 /**@cond NO_DOXYGEN */
AnnaBridge 143:86740a56073b 233 void intern_softdevice_events_execute(void);
AnnaBridge 143:86740a56073b 234
AnnaBridge 143:86740a56073b 235 #define softdevice_handler_is_enabled softdevice_handler_isEnabled
AnnaBridge 143:86740a56073b 236 /**@endcond */
AnnaBridge 143:86740a56073b 237
AnnaBridge 143:86740a56073b 238 #endif // SOFTDEVICE_HANDLER_H__
AnnaBridge 143:86740a56073b 239
AnnaBridge 143:86740a56073b 240 /** @} */