softdevice_handler.h

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 #ifdef __cplusplus
00064 extern "C" {
00065 #endif // #ifdef __cplusplus
00066 
00067 #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. */
00068 #define SYS_EVT_MSG_BUF_SIZE            sizeof(uint32_t)                                  /**< Size of System (SOC) event message buffer. */
00069 
00070 /**@brief Type of function for passing events from the stack handler module to the scheduler. */
00071 typedef uint32_t (*softdevice_evt_schedule_func_t) (void);
00072 
00073 /**@brief Application System (SOC) event handler type. */
00074 typedef void (*sys_evt_handler_t) (uint32_t evt_id);
00075 
00076 
00077 /**@brief     Macro for initializing the stack event handler.
00078  *
00079  * @details   It will handle dimensioning and allocation of the memory buffer required for reading
00080  *            events from the stack, making sure the buffer is correctly aligned. It will also
00081  *            connect the stack event handler to the scheduler/RTOS (if specified).
00082  *
00083  * @param[in] CLOCK_SOURCE     Low frequency clock source and accuracy (type nrf_clock_lfclksrc_t,
00084  *                             see sd_softdevice_enable() for details).
00085  * @param[in] EVT_HANDLER      scheduler/RTOS event handler function.
00086  *
00087  * @note      Since this macro allocates a buffer, it must only be called once (it is OK to call it
00088  *            several times as long as it is from the same location, that is to do a
00089  *            reinitialization).
00090  */
00091 /*lint -emacro(506, SOFTDEVICE_HANDLER_INIT) */ /* Suppress "Constant value Boolean */
00092 #define SOFTDEVICE_HANDLER_INIT(CLOCK_SOURCE, EVT_HANDLER)                                         \
00093     do                                                                                             \
00094     {                                                                                              \
00095         static uint32_t BLE_EVT_BUFFER[CEIL_DIV(BLE_STACK_EVT_MSG_BUF_SIZE, sizeof(uint32_t))];    \
00096         uint32_t ERR_CODE;                                                                         \
00097         ERR_CODE = softdevice_handler_init((CLOCK_SOURCE),                                         \
00098                                            BLE_EVT_BUFFER,                                         \
00099                                            sizeof(BLE_EVT_BUFFER),                                 \
00100                                            EVT_HANDLER);                                           \
00101         APP_ERROR_CHECK(ERR_CODE);                                                                 \
00102     } while (0)
00103 
00104 
00105 /**@brief      Function for initializing the stack handler module.
00106  *
00107  * @details    Enables the SoftDevice and the stack event interrupt handler.
00108  *
00109  * @note       This function must be called before calling any function in the SoftDevice API.
00110  *
00111  * @note       Normally initialization should be done using the SOFTDEVICE_HANDLER_INIT() macro,
00112  *             as that will both allocate the event buffer, and also align the buffer correctly.
00113  *
00114  * @param[in]  clock_source        Low frequency clock source to be used by the SoftDevice.
00115  * @param[in]  p_ble_evt_buffer    Buffer for holding one BLE stack event. Since heap is not being
00116  *                                 used, this buffer must be provided by the application. The
00117  *                                 buffer must be large enough to hold the biggest stack event the
00118  *                                 application is supposed to handle. The buffer must be aligned to
00119  *                                 a 4 byte boundary. This parameter is unused if BLE stack support
00120  *                                 is not required.
00121  * @param[in]  ble_evt_buffer_size Size of SoftDevice BLE event buffer. This parameter is unused if
00122  *                                 BLE stack support is not required.
00123  * @param[in]  evt_schedule_func   Function for passing events to the scheduler. Point to
00124  *                                 ble_ant_stack_evt_schedule() to connect to the scheduler.
00125  *                                 Set to NULL to make the stack handler module call the event
00126  *                                 handler directly from the stack event interrupt handler.
00127  *
00128  * @retval     NRF_SUCCESS               Successful initialization.
00129  * @retval     NRF_ERROR_INVALID_PARAM   Invalid parameter (buffer not aligned to a 4 byte
00130  *                                       boundary) or NULL.
00131  */
00132 uint32_t softdevice_handler_init(nrf_clock_lfclksrc_t              clock_source,
00133                                  void *                            p_ble_evt_buffer,
00134                                  uint16_t                          ble_evt_buffer_size,
00135                                  softdevice_evt_schedule_func_t    evt_schedule_func);
00136 
00137 
00138 /**@brief     Function for disabling the SoftDevice.
00139  *
00140  * @details   This function will disable the SoftDevice. It will also update the internal state
00141  *            of this module.
00142  */
00143 uint32_t softdevice_handler_sd_disable(void);
00144 
00145 
00146 /**@brief     Function for registering for System (SOC) events.
00147  *
00148  * @details   The application should use this function to register for receiving System (SOC)
00149  *            events from the SoftDevice. If the application does not call this function, then any
00150  *            System (SOC) events that may be generated by the SoftDevice will NOT be fetched. Once
00151  *            the application has registered for the events, it is not possible to  possible to
00152  *            cancel the registration. However, it is possible to register a different function for
00153  *            handling the events at any point of time.
00154  *
00155  * @param[in] sys_evt_handler Function to be called for each received System (SOC) event.
00156  *
00157  * @retval    NRF_SUCCESS     Successful registration.
00158  * @retval    NRF_ERROR_NULL  Null pointer provided as input.
00159  */
00160 uint32_t softdevice_sys_evt_handler_set(sys_evt_handler_t sys_evt_handler);
00161 
00162 
00163 // Functions for connecting the Stack Event Handler to the scheduler:
00164 /**@cond NO_DOXYGEN */
00165 void intern_softdevice_events_execute(void);
00166 
00167 
00168 /**@endcond */
00169 
00170 #ifdef __cplusplus
00171 }
00172 #endif // #ifdef __cplusplus
00173 
00174 #endif // SOFTDEVICE_HANDLER_H__
00175 
00176 /** @} */