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