Initial release
Fork of nrf51-sdk by
Embed:
(wiki syntax)
Show/hide line numbers
softdevice_handler.h
Go to the documentation of this file.
00001 /* 00002 * Copyright (c) Nordic Semiconductor ASA 00003 * All rights reserved. 00004 * 00005 * Redistribution and use in source and binary forms, with or without modification, 00006 * are permitted provided that the following conditions are met: 00007 * 00008 * 1. Redistributions of source code must retain the above copyright notice, this 00009 * list of conditions and the following disclaimer. 00010 * 00011 * 2. Redistributions in binary form must reproduce the above copyright notice, this 00012 * list of conditions and the following disclaimer in the documentation and/or 00013 * other materials provided with the distribution. 00014 * 00015 * 3. Neither the name of Nordic Semiconductor ASA nor the names of other 00016 * contributors to this software may be used to endorse or promote products 00017 * derived from this software without specific prior written permission. 00018 * 00019 * 00020 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 00021 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 00022 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 00023 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR 00024 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 00025 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 00026 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON 00027 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 00028 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 00029 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 00030 * 00031 */ 00032 00033 /** @file 00034 * 00035 * @defgroup softdevice_handler SoftDevice Event Handler 00036 * @{ 00037 * @ingroup app_common 00038 * @brief API for initializing and disabling the SoftDevice 00039 * 00040 * @details This API contains the functions and defines exposed by the @ref lib_softdevice_handler. 00041 * For more information on the library and how the application should use it, please refer 00042 * @ref lib_softdevice_handler. 00043 * 00044 * @note Use the USE_SCHEDULER parameter of the SOFTDEVICE_HANDLER_INIT() macro to select if 00045 * the @ref app_scheduler is to be used or not. 00046 * 00047 * @note Even if the scheduler is not used, softdevice_handler.h will include app_scheduler.h. 00048 * So when compiling, app_scheduler.h must be available in one of the compiler include 00049 * paths. 00050 */ 00051 00052 #ifndef SOFTDEVICE_HANDLER_H__ 00053 #define SOFTDEVICE_HANDLER_H__ 00054 00055 #include <stdlib.h> 00056 #include "nordic_common.h" 00057 #include "nrf_sdm.h" 00058 #include "app_error.h " 00059 #include "app_util.h " 00060 #include "ble_stack_handler_types.h " 00061 #include "ant_stack_handler_types.h " 00062 00063 #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. */ 00064 #define SYS_EVT_MSG_BUF_SIZE sizeof(uint32_t) /**< Size of System (SOC) event message buffer. */ 00065 00066 /**@brief Type of function for passing events from the stack handler module to the scheduler. */ 00067 typedef uint32_t (*softdevice_evt_schedule_func_t) (void); 00068 00069 /**@brief Application System (SOC) event handler type. */ 00070 typedef void (*sys_evt_handler_t) (uint32_t evt_id); 00071 00072 00073 /**@brief Macro for initializing the stack event handler. 00074 * 00075 * @details It will handle dimensioning and allocation of the memory buffer required for reading 00076 * events from the stack, making sure the buffer is correctly aligned. It will also 00077 * connect the stack event handler to the scheduler/RTOS (if specified). 00078 * 00079 * @param[in] CLOCK_SOURCE Low frequency clock source and accuracy (type nrf_clock_lfclksrc_t, 00080 * see sd_softdevice_enable() for details). 00081 * @param[in] EVT_HANDLER scheduler/RTOS event handler function. 00082 * 00083 * @note Since this macro allocates a buffer, it must only be called once (it is OK to call it 00084 * several times as long as it is from the same location, that is to do a 00085 * reinitialization). 00086 */ 00087 /*lint -emacro(506, SOFTDEVICE_HANDLER_INIT) */ /* Suppress "Constant value Boolean */ 00088 #define SOFTDEVICE_HANDLER_INIT(CLOCK_SOURCE, \ 00089 EVT_HANDLER) \ 00090 do \ 00091 { \ 00092 static uint32_t BLE_EVT_BUFFER[CEIL_DIV(BLE_STACK_EVT_MSG_BUF_SIZE, sizeof(uint32_t))]; \ 00093 uint32_t ERR_CODE; \ 00094 ERR_CODE = softdevice_handler_init((CLOCK_SOURCE), \ 00095 BLE_EVT_BUFFER, \ 00096 sizeof(BLE_EVT_BUFFER), \ 00097 EVT_HANDLER); \ 00098 APP_ERROR_CHECK(ERR_CODE); \ 00099 } while (0) 00100 00101 /** 00102 * @brief Function for retrieving the information about SD state 00103 * 00104 * The information about current state of softdevice. 00105 * @retval false SD is not initialized and SD commands should not be called. 00106 * @retval true SD is already initialized 00107 */ 00108 bool softdevice_handler_isEnabled(void); 00109 00110 /**@brief Function for initializing the stack handler module. 00111 * 00112 * @details Enables the SoftDevice and the stack event interrupt handler. 00113 * 00114 * @note This function must be called before calling any function in the SoftDevice API. 00115 * 00116 * @note Normally initialization should be done using the SOFTDEVICE_HANDLER_INIT() macro, 00117 * as that will both allocate the event buffer, and also align the buffer correctly. 00118 * 00119 * @param[in] clock_source Low frequency clock source to be used by the SoftDevice. 00120 * @param[in] p_ble_evt_buffer Buffer for holding one BLE stack event. Since heap is not being 00121 * used, this buffer must be provided by the application. The 00122 * buffer must be large enough to hold the biggest stack event the 00123 * application is supposed to handle. The buffer must be aligned to 00124 * a 4 byte boundary. This parameter is unused if BLE stack support 00125 * is not required. 00126 * @param[in] ble_evt_buffer_size Size of SoftDevice BLE event buffer. This parameter is unused if 00127 * BLE stack support is not required. 00128 * @param[in] evt_schedule_func Function for passing events to the scheduler. Point to 00129 * ble_ant_stack_evt_schedule() to connect to the scheduler. 00130 * Set to NULL to make the stack handler module call the event 00131 * handler directly from the stack event interrupt handler. 00132 * 00133 * @retval NRF_SUCCESS Successful initialization. 00134 * @retval NRF_ERROR_INVALID_PARAM Invalid parameter (buffer not aligned to a 4 byte 00135 * boundary) or NULL. 00136 */ 00137 uint32_t softdevice_handler_init(nrf_clock_lfclksrc_t clock_source, 00138 void * p_ble_evt_buffer, 00139 uint16_t ble_evt_buffer_size, 00140 softdevice_evt_schedule_func_t evt_schedule_func); 00141 00142 00143 /**@brief Function for disabling the SoftDevice. 00144 * 00145 * @details This function will disable the SoftDevice. It will also update the internal state 00146 * of this module. 00147 */ 00148 uint32_t softdevice_handler_sd_disable(void); 00149 00150 00151 /**@brief Function for registering for System (SOC) events. 00152 * 00153 * @details The application should use this function to register for receiving System (SOC) 00154 * events from the SoftDevice. If the application does not call this function, then any 00155 * System (SOC) events that may be generated by the SoftDevice will NOT be fetched. Once 00156 * the application has registered for the events, it is not possible to possible to 00157 * cancel the registration. However, it is possible to register a different function for 00158 * handling the events at any point of time. 00159 * 00160 * @param[in] sys_evt_handler Function to be called for each received System (SOC) event. 00161 * 00162 * @retval NRF_SUCCESS Successful registration. 00163 * @retval NRF_ERROR_NULL Null pointer provided as input. 00164 */ 00165 uint32_t softdevice_sys_evt_handler_set(sys_evt_handler_t sys_evt_handler); 00166 00167 00168 // Functions for connecting the Stack Event Handler to the scheduler: 00169 /**@cond NO_DOXYGEN */ 00170 void intern_softdevice_events_execute(void); 00171 00172 00173 /**@endcond */ 00174 00175 #endif // SOFTDEVICE_HANDLER_H__ 00176 00177 /** @} */
Generated on Tue Jul 12 2022 11:17:19 by 1.7.2