owner-nrf52sdk/nRF5_SDK_15.2.0/components/softdevice/common/nrf_sdh.h

/**
 * 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__

/** @} */