softdevice_handler.h

00001 /* Copyright (c) 2013 Nordic Semiconductor. All Rights Reserved.
00002  *
00003  * The information contained herein is property of Nordic Semiconductor ASA.
00004  * Terms and conditions of usage are described in detail in NORDIC
00005  * SEMICONDUCTOR STANDARD SOFTWARE LICENSE AGREEMENT.
00006  *
00007  * Licensees are granted free, non-transferable use of the information. NO
00008  * WARRANTY of ANY KIND is provided. This heading must NOT be removed from
00009  * the file.
00010  *
00011  */
00012 
00013 /** @file
00014  *
00015  * @defgroup softdevice_handler SoftDevice Event Handler
00016  * @{
00017  * @ingroup  app_common
00018  * @brief    API for initializing and disabling the SoftDevice
00019  *
00020  * @details  This API contains the functions and defines exposed by the @ref lib_softdevice_handler.
00021  *           For more information on the library and how the application should use it, please refer
00022  *           @ref lib_softdevice_handler.
00023  *
00024  * @note     Use the USE_SCHEDULER parameter of the SOFTDEVICE_HANDLER_INIT() macro to select if
00025  *           the @ref app_scheduler is to be used or not.
00026  *
00027  * @note     Even if the scheduler is not used, softdevice_handler.h will include app_scheduler.h.
00028  *           So when compiling, app_scheduler.h must be available in one of the compiler include
00029  *           paths.
00030  */
00031 
00032 #ifndef SOFTDEVICE_HANDLER_H__
00033 #define SOFTDEVICE_HANDLER_H__
00034 
00035 #include <stdlib.h>
00036 #include "nordic_global.h"
00037 #include "nrf_sdm.h"
00038 #include "app_error.h "
00039 #include "app_scheduler.h "
00040 #include "app_util.h "
00041 #include "ble_stack_handler_types.h "
00042 #include "ant_stack_handler_types.h "
00043 
00044 #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. */
00045 #define SYS_EVT_MSG_BUF_SIZE            sizeof(uint32_t)                                  /**< Size of System (SOC) event message buffer. */
00046 
00047 /**@brief Type of function for passing events from the stack handler module to the scheduler. */
00048 typedef uint32_t (*softdevice_evt_schedule_func_t) (void);
00049 
00050 /**@brief Application System (SOC) event handler type. */
00051 typedef void (*sys_evt_handler_t) (uint32_t evt_id);
00052 
00053 
00054 /**@brief     Macro for initializing the stack event handler.
00055  *
00056  * @details   It will handle dimensioning and allocation of the memory buffer required for reading
00057  *            events from the stack, making sure the buffer is correctly aligned. It will also
00058  *            connect the stack event handler to the scheduler (if specified).
00059  *
00060  * @param[in] CLOCK_SOURCE     Low frequency clock source and accuracy (type nrf_clock_lfclksrc_t,
00061  *                             see sd_softdevice_enable() for details).
00062  * @param[in] USE_SCHEDULER    TRUE if the application is using the event scheduler, FALSE
00063  *                             otherwise.
00064  *
00065  * @note      Since this macro allocates a buffer, it must only be called once (it is OK to call it
00066  *            several times as long as it is from the same location, that is to do a
00067  *            reinitialization).
00068  */
00069 /*lint -emacro(506, SOFTDEVICE_HANDLER_INIT) */ /* Suppress "Constant value Boolean */
00070 #define SOFTDEVICE_HANDLER_INIT(CLOCK_SOURCE,                                                      \
00071                                 USE_SCHEDULER)                                                     \
00072     do                                                                                             \
00073     {                                                                                              \
00074         static uint32_t EVT_BUFFER[CEIL_DIV(MAX(                                                   \
00075                                                 MAX(BLE_STACK_EVT_MSG_BUF_SIZE,                    \
00076                                                     ANT_STACK_EVT_STRUCT_SIZE),                    \
00077                                                 SYS_EVT_MSG_BUF_SIZE                               \
00078                                                ),                                                  \
00079                                             sizeof(uint32_t))];                                    \
00080         uint32_t ERR_CODE;                                                                         \
00081         ERR_CODE = softdevice_handler_init((CLOCK_SOURCE),                                         \
00082                                            EVT_BUFFER,                                             \
00083                                            sizeof(EVT_BUFFER),                                     \
00084                                            (USE_SCHEDULER) ? softdevice_evt_schedule : NULL);      \
00085         APP_ERROR_CHECK(ERR_CODE);                                                                 \
00086     } while (0)
00087 
00088 
00089 /**@brief      Function for initializing the stack handler module.
00090  *
00091  * @details    Enables the SoftDevice and the stack event interrupt handler.
00092  *
00093  * @note       This function must be called before calling any function in the SoftDevice API.
00094  *
00095  * @note       Normally initialization should be done using the SOFTDEVICE_HANDLER_INIT() macro,
00096  *             as that will both allocate the event buffer, and also align the buffer correctly.
00097  *
00098  * @param[in]  clock_source        Low frequency clock source to be used by the SoftDevice.
00099  * @param[in]  p_evt_buffer        Buffer for holding one stack event. Since heap is not being
00100  *                                 used, this buffer must be provided by the application. The
00101  *                                 buffer must be large enough to hold the biggest stack event the
00102  *                                 application is supposed to handle. The buffer must be aligned to
00103  *                                 a 4 byte boundary. This parameter is unused if neither BLE nor
00104  *                                 ANT stack support is required.
00105  * @param[in]  evt_buffer_size     Size of SoftDevice event buffer. This parameter is unused if
00106  *                                 BLE stack support is not required.
00107  * @param[in]  evt_schedule_func   Function for passing events to the scheduler. Point to
00108  *                                 ble_ant_stack_evt_schedule() to connect to the scheduler.
00109  *                                 Set to NULL to make the stack handler module call the event
00110  *                                 handler directly from the stack event interrupt handler.
00111  *
00112  * @retval     NRF_SUCCESS               Successful initialization.
00113  * @retval     NRF_ERROR_INVALID_PARAM   Invalid parameter (buffer not aligned to a 4 byte
00114  *                                       boundary) or NULL.
00115  */
00116 uint32_t softdevice_handler_init(nrf_clock_lfclksrc_t              clock_source,
00117                                  void *                            p_evt_buffer,
00118                                  uint16_t                          evt_buffer_size,
00119                                  softdevice_evt_schedule_func_t    evt_schedule_func);
00120 
00121 
00122 /**@brief     Function for disabling the SoftDevice.
00123  *
00124  * @details   This function will disable the SoftDevice. It will also update the internal state
00125  *            of this module.
00126  */
00127 uint32_t softdevice_handler_sd_disable(void);
00128 
00129 
00130 /**@brief     Function for registering for System (SOC) events.
00131  *
00132  * @details   The application should use this function to register for receiving System (SOC)
00133  *            events from the SoftDevice. If the application does not call this function, then any
00134  *            System (SOC) events that may be generated by the SoftDevice will NOT be fetched. Once
00135  *            the application has registered for the events, it is not possible to  possible to
00136  *            cancel the registration. However, it is possible to register a different function for
00137  *            handling the events at any point of time.
00138  *
00139  * @param[in] sys_evt_handler Function to be called for each received System (SOC) event.
00140  *
00141  * @retval    NRF_SUCCESS     Successful registration.
00142  * @retval    NRF_ERROR_NULL  Null pointer provided as input.
00143  */
00144 uint32_t softdevice_sys_evt_handler_set(sys_evt_handler_t sys_evt_handler);
00145 
00146 
00147 // Functions for connecting the Stack Event Handler to the scheduler:
00148 /**@cond NO_DOXYGEN */
00149 void intern_softdevice_events_execute(void);
00150 
00151 static __INLINE void softdevice_evt_get(void * p_event_data, uint16_t event_size)
00152 {
00153     APP_ERROR_CHECK_BOOL(event_size == 0);
00154     intern_softdevice_events_execute();
00155 }
00156 
00157 static __INLINE uint32_t softdevice_evt_schedule(void)
00158 {
00159     return app_sched_event_put(NULL, 0, softdevice_evt_get);
00160 }
00161 /**@endcond */
00162 
00163 #endif // SOFTDEVICE_HANDLER_H__
00164 
00165 /** @} */