Cefn Hoile / nRF51822

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Dependencies:   nrf51-sdk

Dependents:   microbit-dal

Fork of nRF51822 by Lancaster University

source/nordic-sdk/components/softdevice/common/softdevice_handler/softdevice_handler.h@497:4b09b9115685, 2015-12-02 (annotated)

Committer:
rgrover1
Date:
Wed Dec 02 10:32:51 2015 +0000
Revision:
497:4b09b9115685
Parent:
431:95158d6d493f
Child:
498:d72c7e78ee13
Synchronized with git rev af14327c

Author: Liyou Zhou

Change folder structure to fit new sdk

Reverted some unnecessary changes.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
rgrover1 371:8f7d2137727a 1 /*
rgrover1 371:8f7d2137727a 2 * Copyright (c) Nordic Semiconductor ASA
rgrover1 371:8f7d2137727a 3 * All rights reserved.
rgrover1 371:8f7d2137727a 4 *
rgrover1 371:8f7d2137727a 5 * Redistribution and use in source and binary forms, with or without modification,
rgrover1 371:8f7d2137727a 6 * are permitted provided that the following conditions are met:
rgrover1 371:8f7d2137727a 7 *
rgrover1 371:8f7d2137727a 8 * 1. Redistributions of source code must retain the above copyright notice, this
rgrover1 371:8f7d2137727a 9 * list of conditions and the following disclaimer.
rgrover1 371:8f7d2137727a 10 *
rgrover1 371:8f7d2137727a 11 * 2. Redistributions in binary form must reproduce the above copyright notice, this
rgrover1 371:8f7d2137727a 12 * list of conditions and the following disclaimer in the documentation and/or
rgrover1 371:8f7d2137727a 13 * other materials provided with the distribution.
rgrover1 371:8f7d2137727a 14 *
rgrover1 371:8f7d2137727a 15 * 3. Neither the name of Nordic Semiconductor ASA nor the names of other
rgrover1 371:8f7d2137727a 16 * contributors to this software may be used to endorse or promote products
rgrover1 371:8f7d2137727a 17 * derived from this software without specific prior written permission.
rgrover1 371:8f7d2137727a 18 *
rgrover1 371:8f7d2137727a 19 *
rgrover1 371:8f7d2137727a 20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
rgrover1 371:8f7d2137727a 21 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
rgrover1 371:8f7d2137727a 22 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
rgrover1 371:8f7d2137727a 23 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
rgrover1 371:8f7d2137727a 24 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
rgrover1 371:8f7d2137727a 25 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
rgrover1 371:8f7d2137727a 26 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
rgrover1 371:8f7d2137727a 27 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
rgrover1 371:8f7d2137727a 28 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
rgrover1 371:8f7d2137727a 29 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
rgrover1 371:8f7d2137727a 30 *
rgrover1 371:8f7d2137727a 31 */
rgrover1 371:8f7d2137727a 32
rgrover1 371:8f7d2137727a 33 /** @file
rgrover1 371:8f7d2137727a 34 *
rgrover1 371:8f7d2137727a 35 * @defgroup softdevice_handler SoftDevice Event Handler
rgrover1 371:8f7d2137727a 36 * @{
rgrover1 371:8f7d2137727a 37 * @ingroup app_common
rgrover1 371:8f7d2137727a 38 * @brief API for initializing and disabling the SoftDevice
rgrover1 371:8f7d2137727a 39 *
rgrover1 371:8f7d2137727a 40 * @details This API contains the functions and defines exposed by the @ref lib_softdevice_handler.
rgrover1 371:8f7d2137727a 41 * For more information on the library and how the application should use it, please refer
rgrover1 371:8f7d2137727a 42 * @ref lib_softdevice_handler.
rgrover1 371:8f7d2137727a 43 *
rgrover1 371:8f7d2137727a 44 * @note Use the USE_SCHEDULER parameter of the SOFTDEVICE_HANDLER_INIT() macro to select if
rgrover1 371:8f7d2137727a 45 * the @ref app_scheduler is to be used or not.
rgrover1 371:8f7d2137727a 46 *
rgrover1 371:8f7d2137727a 47 * @note Even if the scheduler is not used, softdevice_handler.h will include app_scheduler.h.
rgrover1 371:8f7d2137727a 48 * So when compiling, app_scheduler.h must be available in one of the compiler include
rgrover1 371:8f7d2137727a 49 * paths.
rgrover1 371:8f7d2137727a 50 */
rgrover1 371:8f7d2137727a 51
rgrover1 371:8f7d2137727a 52 #ifndef SOFTDEVICE_HANDLER_H__
rgrover1 371:8f7d2137727a 53 #define SOFTDEVICE_HANDLER_H__
rgrover1 371:8f7d2137727a 54
rgrover1 371:8f7d2137727a 55 #include <stdlib.h>
rgrover1 371:8f7d2137727a 56 #include "nordic_common.h"
rgrover1 371:8f7d2137727a 57 #include "nrf_sdm.h"
rgrover1 371:8f7d2137727a 58 #include "app_error.h"
rgrover1 371:8f7d2137727a 59 #include "app_util.h"
rgrover1 371:8f7d2137727a 60 #include "ble_stack_handler_types.h"
rgrover1 371:8f7d2137727a 61 #include "ant_stack_handler_types.h"
rgrover1 371:8f7d2137727a 62
rgrover1 371:8f7d2137727a 63 #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. */
rgrover1 371:8f7d2137727a 64 #define SYS_EVT_MSG_BUF_SIZE sizeof(uint32_t) /**< Size of System (SOC) event message buffer. */
rgrover1 371:8f7d2137727a 65
rgrover1 371:8f7d2137727a 66 /**@brief Type of function for passing events from the stack handler module to the scheduler. */
rgrover1 371:8f7d2137727a 67 typedef uint32_t (*softdevice_evt_schedule_func_t) (void);
rgrover1 371:8f7d2137727a 68
rgrover1 371:8f7d2137727a 69 /**@brief Application System (SOC) event handler type. */
rgrover1 371:8f7d2137727a 70 typedef void (*sys_evt_handler_t) (uint32_t evt_id);
rgrover1 371:8f7d2137727a 71
rgrover1 371:8f7d2137727a 72
rgrover1 371:8f7d2137727a 73 /**@brief Macro for initializing the stack event handler.
rgrover1 371:8f7d2137727a 74 *
rgrover1 371:8f7d2137727a 75 * @details It will handle dimensioning and allocation of the memory buffer required for reading
rgrover1 371:8f7d2137727a 76 * events from the stack, making sure the buffer is correctly aligned. It will also
rgrover1 371:8f7d2137727a 77 * connect the stack event handler to the scheduler/RTOS (if specified).
rgrover1 371:8f7d2137727a 78 *
rgrover1 371:8f7d2137727a 79 * @param[in] CLOCK_SOURCE Low frequency clock source and accuracy (type nrf_clock_lfclksrc_t,
rgrover1 371:8f7d2137727a 80 * see sd_softdevice_enable() for details).
rgrover1 371:8f7d2137727a 81 * @param[in] EVT_HANDLER scheduler/RTOS event handler function.
rgrover1 371:8f7d2137727a 82 *
rgrover1 371:8f7d2137727a 83 * @note Since this macro allocates a buffer, it must only be called once (it is OK to call it
rgrover1 371:8f7d2137727a 84 * several times as long as it is from the same location, that is to do a
rgrover1 371:8f7d2137727a 85 * reinitialization).
rgrover1 371:8f7d2137727a 86 */
rgrover1 371:8f7d2137727a 87 /*lint -emacro(506, SOFTDEVICE_HANDLER_INIT) */ /* Suppress "Constant value Boolean */
rgrover1 497:4b09b9115685 88 #define SOFTDEVICE_HANDLER_INIT(CLOCK_SOURCE, \
rgrover1 497:4b09b9115685 89 EVT_HANDLER) \
rgrover1 371:8f7d2137727a 90 do \
rgrover1 371:8f7d2137727a 91 { \
rgrover1 371:8f7d2137727a 92 static uint32_t BLE_EVT_BUFFER[CEIL_DIV(BLE_STACK_EVT_MSG_BUF_SIZE, sizeof(uint32_t))]; \
rgrover1 371:8f7d2137727a 93 uint32_t ERR_CODE; \
rgrover1 371:8f7d2137727a 94 ERR_CODE = softdevice_handler_init((CLOCK_SOURCE), \
rgrover1 371:8f7d2137727a 95 BLE_EVT_BUFFER, \
rgrover1 371:8f7d2137727a 96 sizeof(BLE_EVT_BUFFER), \
rgrover1 431:95158d6d493f 97 EVT_HANDLER); \
rgrover1 371:8f7d2137727a 98 APP_ERROR_CHECK(ERR_CODE); \
rgrover1 371:8f7d2137727a 99 } while (0)
rgrover1 371:8f7d2137727a 100
rgrover1 371:8f7d2137727a 101
rgrover1 371:8f7d2137727a 102 /**@brief Function for initializing the stack handler module.
rgrover1 371:8f7d2137727a 103 *
rgrover1 371:8f7d2137727a 104 * @details Enables the SoftDevice and the stack event interrupt handler.
rgrover1 371:8f7d2137727a 105 *
rgrover1 371:8f7d2137727a 106 * @note This function must be called before calling any function in the SoftDevice API.
rgrover1 371:8f7d2137727a 107 *
rgrover1 371:8f7d2137727a 108 * @note Normally initialization should be done using the SOFTDEVICE_HANDLER_INIT() macro,
rgrover1 371:8f7d2137727a 109 * as that will both allocate the event buffer, and also align the buffer correctly.
rgrover1 371:8f7d2137727a 110 *
rgrover1 371:8f7d2137727a 111 * @param[in] clock_source Low frequency clock source to be used by the SoftDevice.
rgrover1 371:8f7d2137727a 112 * @param[in] p_ble_evt_buffer Buffer for holding one BLE stack event. Since heap is not being
rgrover1 371:8f7d2137727a 113 * used, this buffer must be provided by the application. The
rgrover1 371:8f7d2137727a 114 * buffer must be large enough to hold the biggest stack event the
rgrover1 371:8f7d2137727a 115 * application is supposed to handle. The buffer must be aligned to
rgrover1 431:95158d6d493f 116 * a 4 byte boundary. This parameter is unused if BLE stack support
rgrover1 371:8f7d2137727a 117 * is not required.
rgrover1 371:8f7d2137727a 118 * @param[in] ble_evt_buffer_size Size of SoftDevice BLE event buffer. This parameter is unused if
rgrover1 371:8f7d2137727a 119 * BLE stack support is not required.
rgrover1 371:8f7d2137727a 120 * @param[in] evt_schedule_func Function for passing events to the scheduler. Point to
rgrover1 371:8f7d2137727a 121 * ble_ant_stack_evt_schedule() to connect to the scheduler.
rgrover1 371:8f7d2137727a 122 * Set to NULL to make the stack handler module call the event
rgrover1 371:8f7d2137727a 123 * handler directly from the stack event interrupt handler.
rgrover1 371:8f7d2137727a 124 *
rgrover1 371:8f7d2137727a 125 * @retval NRF_SUCCESS Successful initialization.
rgrover1 371:8f7d2137727a 126 * @retval NRF_ERROR_INVALID_PARAM Invalid parameter (buffer not aligned to a 4 byte
rgrover1 371:8f7d2137727a 127 * boundary) or NULL.
rgrover1 371:8f7d2137727a 128 */
rgrover1 371:8f7d2137727a 129 uint32_t softdevice_handler_init(nrf_clock_lfclksrc_t clock_source,
rgrover1 371:8f7d2137727a 130 void * p_ble_evt_buffer,
rgrover1 371:8f7d2137727a 131 uint16_t ble_evt_buffer_size,
rgrover1 371:8f7d2137727a 132 softdevice_evt_schedule_func_t evt_schedule_func);
rgrover1 371:8f7d2137727a 133
rgrover1 371:8f7d2137727a 134
rgrover1 371:8f7d2137727a 135 /**@brief Function for disabling the SoftDevice.
rgrover1 371:8f7d2137727a 136 *
rgrover1 371:8f7d2137727a 137 * @details This function will disable the SoftDevice. It will also update the internal state
rgrover1 371:8f7d2137727a 138 * of this module.
rgrover1 371:8f7d2137727a 139 */
rgrover1 371:8f7d2137727a 140 uint32_t softdevice_handler_sd_disable(void);
rgrover1 371:8f7d2137727a 141
rgrover1 371:8f7d2137727a 142
rgrover1 371:8f7d2137727a 143 /**@brief Function for registering for System (SOC) events.
rgrover1 371:8f7d2137727a 144 *
rgrover1 371:8f7d2137727a 145 * @details The application should use this function to register for receiving System (SOC)
rgrover1 371:8f7d2137727a 146 * events from the SoftDevice. If the application does not call this function, then any
rgrover1 371:8f7d2137727a 147 * System (SOC) events that may be generated by the SoftDevice will NOT be fetched. Once
rgrover1 371:8f7d2137727a 148 * the application has registered for the events, it is not possible to possible to
rgrover1 371:8f7d2137727a 149 * cancel the registration. However, it is possible to register a different function for
rgrover1 371:8f7d2137727a 150 * handling the events at any point of time.
rgrover1 371:8f7d2137727a 151 *
rgrover1 371:8f7d2137727a 152 * @param[in] sys_evt_handler Function to be called for each received System (SOC) event.
rgrover1 371:8f7d2137727a 153 *
rgrover1 371:8f7d2137727a 154 * @retval NRF_SUCCESS Successful registration.
rgrover1 371:8f7d2137727a 155 * @retval NRF_ERROR_NULL Null pointer provided as input.
rgrover1 371:8f7d2137727a 156 */
rgrover1 371:8f7d2137727a 157 uint32_t softdevice_sys_evt_handler_set(sys_evt_handler_t sys_evt_handler);
rgrover1 371:8f7d2137727a 158
rgrover1 371:8f7d2137727a 159
rgrover1 371:8f7d2137727a 160 // Functions for connecting the Stack Event Handler to the scheduler:
rgrover1 371:8f7d2137727a 161 /**@cond NO_DOXYGEN */
rgrover1 371:8f7d2137727a 162 void intern_softdevice_events_execute(void);
rgrover1 371:8f7d2137727a 163
rgrover1 371:8f7d2137727a 164
rgrover1 371:8f7d2137727a 165 /**@endcond */
rgrover1 371:8f7d2137727a 166
rgrover1 371:8f7d2137727a 167 #endif // SOFTDEVICE_HANDLER_H__
rgrover1 371:8f7d2137727a 168
rgrover1 371:8f7d2137727a 169 /** @} */