diff options
Diffstat (limited to 'thirdparty/nRF5_SDK_15.0.0_a53641a/components/softdevice/common/nrf_sdh.h')
| -rw-r--r-- | thirdparty/nRF5_SDK_15.0.0_a53641a/components/softdevice/common/nrf_sdh.h | 305 |
1 files changed, 305 insertions, 0 deletions
diff --git a/thirdparty/nRF5_SDK_15.0.0_a53641a/components/softdevice/common/nrf_sdh.h b/thirdparty/nRF5_SDK_15.0.0_a53641a/components/softdevice/common/nrf_sdh.h new file mode 100644 index 0000000..a63e4cb --- /dev/null +++ b/thirdparty/nRF5_SDK_15.0.0_a53641a/components/softdevice/common/nrf_sdh.h @@ -0,0 +1,305 @@ +/** + * Copyright (c) 2017 - 2018, Nordic Semiconductor ASA + * + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without modification, + * are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, this + * list of conditions and the following disclaimer. + * + * 2. Redistributions in binary form, except as embedded into a Nordic + * Semiconductor ASA integrated circuit in a product or a software update for + * such product, must reproduce the above copyright notice, this list of + * conditions and the following disclaimer in the documentation and/or other + * materials provided with the distribution. + * + * 3. Neither the name of Nordic Semiconductor ASA nor the names of its + * contributors may be used to endorse or promote products derived from this + * software without specific prior written permission. + * + * 4. This software, with or without modification, must only be used with a + * Nordic Semiconductor ASA integrated circuit. + * + * 5. Any software provided in binary form under this license must not be reverse + * engineered, decompiled, modified and/or disassembled. + * + * THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA "AS IS" AND ANY EXPRESS + * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + * OF MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE + * DISCLAIMED. IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE + * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT + * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + * + */ + +/** @file + * + * @defgroup nrf_sdh SoftDevice Handler + * @{ + * @ingroup app_common + * @brief API for initializing and disabling the SoftDevice. + */ + +#ifndef NRF_SDH_H__ +#define NRF_SDH_H__ + +#include <stdbool.h> +#include "sdk_config.h" +#include "sdk_errors.h" +#include "nrf_section_iter.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @name Softdevice Handler dispatch models + * @{ + * @ingroup nrf_sdh */ + +/**@brief SoftDevice events are passed to the application from the interrupt context. */ +#define NRF_SDH_DISPATCH_MODEL_INTERRUPT 0 + +/**@brief SoftDevice events are passed to the application using @ref app_scheduler. + * + * @note @ref app_scheduler must be initialized before enabling the SoftDevice handler. + */ +#define NRF_SDH_DISPATCH_MODEL_APPSH 1 + +/**@brief SoftDevice events are polled manually using @ref nrf_sdh_evts_poll(). + * + * @note In this mode, a user application can also implement SD_EVT_IRQHandler() to receive a + * notification about incoming events. + */ +#define NRF_SDH_DISPATCH_MODEL_POLLING 2 + +/** @} */ + +/** + * @name SoftDevice Handler state change requests + * @{ + * @ingroup nrf_sdh */ + +/**@brief SoftDevice Handler state requests. */ +typedef enum +{ + NRF_SDH_EVT_ENABLE_REQUEST, //!< Request to enable the SoftDevice. + NRF_SDH_EVT_DISABLE_REQUEST, //!< Request to disable the SoftDevice. +} nrf_sdh_req_evt_t; + +/**@brief SoftDevice Handler state request handler. + * + * @retval true If ready for the SoftDevice to change state. + * @retval false If not ready for the SoftDevice to change state. + * If false is returned, the state change is aborted. + */ +typedef bool (*nrf_sdh_req_evt_handler_t)(nrf_sdh_req_evt_t request, void * p_context); + +/**@brief SoftDevice Handler state request observer. */ +typedef struct +{ + nrf_sdh_req_evt_handler_t handler; //!< Request handler. + void * p_context; //!< A parameter to the handler function. +} const nrf_sdh_req_observer_t; + +/**@brief Macro for registering a SoftDevice state change request observer. + * + * An observer of SoftDevice state change requests receives requests to change the state of the + * SoftDevice from enabled to disabled and vice versa. These requests may or may not be acknowledged + * by the observer, depending on the value returned by its request handler function. Thus, a + * request observer has the capability to defer the change of state of the SoftDevice. If it does + * so, it has the responsibility to call @ref nrf_sdh_request_continue when it is ready to let the + * SoftDevice change its state. If such capability is not necessary and you only need to be informed + * about changes of the SoftDevice state, use the @ref NRF_SDH_STATE_OBSERVER macro instead. + * + * @note This macro places the observer in a section named "sdh_req_observers". + * + * @param[in] _observer Name of the observer. + * @param[in] _prio Priority of the observer's event handler. + * The smaller the number, the higher the priority. + * @hideinitializer + */ +#define NRF_SDH_REQUEST_OBSERVER(_observer, _prio) \ +STATIC_ASSERT(NRF_SDH_ENABLED, "NRF_SDH_ENABLED not set!"); \ +STATIC_ASSERT(_prio < NRF_SDH_REQ_OBSERVER_PRIO_LEVELS, "Priority level unavailable."); \ +/*lint -esym(528,*_observer) -esym(529,*_observer) : Symbol not referenced. */ \ +NRF_SECTION_SET_ITEM_REGISTER(sdh_req_observers, _prio, nrf_sdh_req_observer_t const _observer) + +/** @} */ + +/** + * @name SoftDevice Handler state events + * @{ + * @ingroup nrf_sdh */ + +/**@brief SoftDevice Handler state events. */ +typedef enum +{ + NRF_SDH_EVT_STATE_ENABLE_PREPARE, //!< SoftDevice is going to be enabled. + NRF_SDH_EVT_STATE_ENABLED, //!< SoftDevice is enabled. + NRF_SDH_EVT_STATE_DISABLE_PREPARE, //!< SoftDevice is going to be disabled. + NRF_SDH_EVT_STATE_DISABLED, //!< SoftDevice is disabled. +} nrf_sdh_state_evt_t; + +/**@brief SoftDevice Handler state event handler. */ +typedef void (*nrf_sdh_state_evt_handler_t)(nrf_sdh_state_evt_t state, void * p_context); + +/**@brief SoftDevice Handler state observer. */ +typedef struct +{ + nrf_sdh_state_evt_handler_t handler; //!< State event handler. + void * p_context; //!< A parameter to the event handler. +} const nrf_sdh_state_observer_t; + +/**@brief Macro for registering a SoftDevice state observer. + * + * A SoftDevice state observer receives events when the SoftDevice state has changed or is + * about to change. These events are only meant to inform the state observer, which, contrary + * to a state change request observer, does not have the capability to defer the change of state. + * If such capability is required, use the @ref NRF_SDH_REQUEST_OBSERVER macro instead. + * + * This macro places the observer in a section named "sdh_state_observers". + * + * @param[in] _observer Name of the observer. + * @param[in] _prio Priority of the observer's event handler. + * The smaller the number, the higher the priority. + * @hideinitializer + */ +#define NRF_SDH_STATE_OBSERVER(_observer, _prio) \ +STATIC_ASSERT(NRF_SDH_ENABLED, "NRF_SDH_ENABLED not set!"); \ +STATIC_ASSERT(_prio < NRF_SDH_STATE_OBSERVER_PRIO_LEVELS, "Priority level unavailable."); \ +/*lint -esym(528,*_observer) -esym(529,*_observer) : Symbol not referenced. */ \ +NRF_SECTION_SET_ITEM_REGISTER(sdh_state_observers, _prio, static nrf_sdh_state_observer_t const _observer) + +/** @} */ + +/** + * @name SoftDevice stack events + * @{ + * @ingroup nrf_sdh */ + +/**@brief SoftDevice stack event handler. */ +typedef void (*nrf_sdh_stack_evt_handler_t)(void * p_evt); + +/**@brief SoftDevice stack event observer. */ +typedef struct +{ + nrf_sdh_stack_evt_handler_t handler; //!< SoftDevice event handler. + void * p_context; //!< A parameter to the event handler. +} const nrf_sdh_stack_observer_t; + +/**@brief Macro for registering a SoftDevice stack events observer. + * + * A SoftDevice stack event observer receives all events from the SoftDevice. These events can be + * either BLE, ANT, or SoC events. If you need to receive BLE, ANT, or SoC events separately, use the + * @ref NRF_SDH_BLE_OBSERVER, @ref NRF_SDH_ANT_OBSERVER, or @ref NRF_SDH_SOC_OBSERVER macros + * respectively. + * + * @note This macro places the observer in a section named "sdh_stack_observers". + * + * @param[in] _observer Name of the observer. + * @param[in] _prio Priority of the observer's event handler. + * The smaller the number, the higher the priority. + ** @hideinitializer + */ +#define NRF_SDH_STACK_OBSERVER(_observer, _prio) \ +STATIC_ASSERT(NRF_SDH_ENABLED, "NRF_SDH_ENABLED not set!"); \ +STATIC_ASSERT(_prio < NRF_SDH_STACK_OBSERVER_PRIO_LEVELS, "Priority level unavailable."); \ +/*lint -esym(528,*_observer) -esym(529,*_observer) : Symbol not referenced. */ \ +NRF_SECTION_SET_ITEM_REGISTER(sdh_stack_observers, _prio, static nrf_sdh_stack_observer_t const _observer) + +/** @} */ + +/**@brief Function for requesting to enable the SoftDevice. + * + * This function issues a @ref NRF_SDH_EVT_ENABLE_REQUEST request to all observers that + * were registered using the @ref NRF_SDH_REQUEST_OBSERVER macro. The observers may or + * may not acknowledge the request. If all observers acknowledge the request, the + * SoftDevice will be enabled. Otherwise, the process will be stopped and the observers + * that did not acknowledge have the responsibility to restart it by calling + * @ref nrf_sdh_request_continue when they are ready for the SoftDevice to change state. + * + * @retval NRF_SUCCESS The process is started. + * @retval NRF_ERROR_INVALID_STATE The SoftDevice is already enabled. + */ +ret_code_t nrf_sdh_enable_request(void); + + +/**@brief Function for requesting to disable the SoftDevice. + * + * This function issues a @ref NRF_SDH_EVT_DISABLE_REQUEST request to all observers that + * were registered using the @ref NRF_SDH_REQUEST_OBSERVER macro. The observers may or + * may not acknowledge the request. If all observers acknowledge the request, the + * SoftDevice will be disabled. Otherwise, the process will be stopped and the observers + * that did not acknowledge have the responsibility to restart it by calling + * @ref nrf_sdh_request_continue when they are ready for the SoftDevice to change state. + * + * @retval NRF_SUCCESS The process is started. + * @retval NRF_ERROR_INVALID_STATE The SoftDevice is already disabled. + */ +ret_code_t nrf_sdh_disable_request(void); + + +/**@brief Function for restarting the SoftDevice Enable/Disable process. + * + * Modules which did not acknowledge a @ref NRF_SDH_EVT_ENABLE_REQUEST or + * @ref NRF_SDH_EVT_DISABLE_REQUEST request must call this function to restart the + * SoftDevice state change process. + * + * @retval NRF_SUCCESS The process is restarted. + * @retval NRF_ERROR_INVALID_STATE No state change request was pending. + */ +ret_code_t nrf_sdh_request_continue(void); + + +/**@brief Function for retrieving the SoftDevice state. + * + * @retval true If the SoftDevice is enabled. + * @retval false If the SoftDevice is disabled. + */ +bool nrf_sdh_is_enabled(void); + + +/**@brief Function for stopping the incoming stack events. + * + * This function disables the SoftDevice interrupt. To resume polling for events, + * call @ref nrf_sdh_resume. + */ +void nrf_sdh_suspend(void); + + +/**@brief Function for resuming polling incoming events from the SoftDevice. */ +void nrf_sdh_resume(void); + + +/**@brief Function for retrieving the information about the module state. + * + * @retval true The SoftDevice handler is paused, and it will not fetch events from the stack. + * @retval false The SoftDevice handler is running, and it will fetch and dispatch events from + * the stack to the registered stack observers. + */ +bool nrf_sdh_is_suspended(void); + + +/**@brief Function for polling stack events from the SoftDevice. + * + * The events are passed to the application using the registered event handlers. + * + * @note @ref NRF_SDH_DISPATCH_MODEL_POLLING must be selected to use this function. + */ +void nrf_sdh_evts_poll(void); + + +#ifdef __cplusplus +} +#endif + +#endif // NRF_SDH_H__ + +/** @} */ |