Initial release
Fork of nrf51-sdk by
Embed:
(wiki syntax)
Show/hide line numbers
nrf_sdm.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 @defgroup nrf_sdm_api SoftDevice Manager API 00034 @{ 00035 00036 @brief APIs for SoftDevice management. 00037 00038 */ 00039 00040 /* Header guard */ 00041 #ifndef NRF_SDM_H__ 00042 #define NRF_SDM_H__ 00043 00044 #include "nrf_svc.h" 00045 #include "nrf.h" 00046 #include "nrf_soc.h" 00047 #include "nrf_error_sdm.h" 00048 00049 /** @addtogroup NRF_SDM_DEFINES Defines 00050 * @{ */ 00051 00052 /** @brief SoftDevice Manager SVC Base number. */ 00053 #define SDM_SVC_BASE 0x10 00054 00055 /** @} */ 00056 00057 /** @brief Defines the SoftDevice Information Structure location (address) as an offset from 00058 the start of the softdevice (without MBR)*/ 00059 #define SOFTDEVICE_INFO_STRUCT_OFFSET (0x2000) 00060 00061 /** @brief Defines the usual size reserverd for the MBR when a softdevice is written to flash. 00062 This is the offset where the first byte of the softdevice hex file is written.*/ 00063 #define MBR_SIZE (0x1000) 00064 00065 /** @brief Defines the absolute Softdevice information structure location (address)*/ 00066 #define SOFTDEVICE_INFO_STRUCT_ADDRESS (SOFTDEVICE_INFO_STRUCT_OFFSET + MBR_SIZE) 00067 00068 /** @brief Defines the offset for Softdevice size value relative to Softdevice base address*/ 00069 #define SD_SIZE_OFFSET (SOFTDEVICE_INFO_STRUCT_OFFSET + 0x08) 00070 00071 /** @brief Defines the offset for FWID value relative to Softdevice base address*/ 00072 #define SD_FWID_OFFSET (SOFTDEVICE_INFO_STRUCT_OFFSET + 0x0C) 00073 00074 /** @brief Defines a macro for retreiving the actual Softdevice size value from a given base address 00075 use @ref MBR_SIZE when Softdevice is installed just above the MBR (the usual case)*/ 00076 #define SD_SIZE_GET(baseaddr) (*((uint32_t *) ((baseaddr) + SD_SIZE_OFFSET))) 00077 00078 /** @brief Defines a macro for retreiving the actual FWID value from a given base address 00079 use @ref MBR_SIZE when Softdevice is installed just above the MBR (the usual case)*/ 00080 #define SD_FWID_GET(baseaddr) ((*((uint32_t *) ((baseaddr) + SD_FWID_OFFSET))) & 0xFFFF) 00081 00082 00083 /** @addtogroup NRF_SDM_ENUMS Enumerations 00084 * @{ */ 00085 00086 /**@brief nRF SoftDevice Manager API SVC numbers. */ 00087 enum NRF_SD_SVCS 00088 { 00089 SD_SOFTDEVICE_ENABLE = SDM_SVC_BASE, /**< ::sd_softdevice_enable */ 00090 SD_SOFTDEVICE_DISABLE, /**< ::sd_softdevice_disable */ 00091 SD_SOFTDEVICE_IS_ENABLED, /**< ::sd_softdevice_is_enabled */ 00092 SD_SOFTDEVICE_VECTOR_TABLE_BASE_SET, /**< ::sd_softdevice_vector_table_base_set */ 00093 SVC_SDM_LAST /**< Placeholder for last SDM SVC */ 00094 }; 00095 00096 /**@brief Possible lfclk oscillator sources. */ 00097 enum NRF_CLOCK_LFCLKSRCS 00098 { 00099 NRF_CLOCK_LFCLKSRC_SYNTH_250_PPM, /**< LFCLK Synthesized from HFCLK. */ 00100 NRF_CLOCK_LFCLKSRC_XTAL_500_PPM, /**< LFCLK crystal oscillator 500 PPM accuracy. */ 00101 NRF_CLOCK_LFCLKSRC_XTAL_250_PPM, /**< LFCLK crystal oscillator 250 PPM accuracy. */ 00102 NRF_CLOCK_LFCLKSRC_XTAL_150_PPM, /**< LFCLK crystal oscillator 150 PPM accuracy. */ 00103 NRF_CLOCK_LFCLKSRC_XTAL_100_PPM, /**< LFCLK crystal oscillator 100 PPM accuracy. */ 00104 NRF_CLOCK_LFCLKSRC_XTAL_75_PPM, /**< LFCLK crystal oscillator 75 PPM accuracy. */ 00105 NRF_CLOCK_LFCLKSRC_XTAL_50_PPM, /**< LFCLK crystal oscillator 50 PPM accuracy. */ 00106 NRF_CLOCK_LFCLKSRC_XTAL_30_PPM, /**< LFCLK crystal oscillator 30 PPM accuracy. */ 00107 NRF_CLOCK_LFCLKSRC_XTAL_20_PPM, /**< LFCLK crystal oscillator 20 PPM accuracy. */ 00108 NRF_CLOCK_LFCLKSRC_RC_250_PPM_250MS_CALIBRATION, /**< LFCLK RC oscillator, 250ms calibration interval.*/ 00109 NRF_CLOCK_LFCLKSRC_RC_250_PPM_500MS_CALIBRATION, /**< LFCLK RC oscillator, 500ms calibration interval.*/ 00110 NRF_CLOCK_LFCLKSRC_RC_250_PPM_1000MS_CALIBRATION, /**< LFCLK RC oscillator, 1000ms calibration interval.*/ 00111 NRF_CLOCK_LFCLKSRC_RC_250_PPM_2000MS_CALIBRATION, /**< LFCLK RC oscillator, 2000ms calibration interval.*/ 00112 NRF_CLOCK_LFCLKSRC_RC_250_PPM_4000MS_CALIBRATION, /**< LFCLK RC oscillator, 4000ms calibration interval.*/ 00113 NRF_CLOCK_LFCLKSRC_RC_250_PPM_8000MS_CALIBRATION, /**< LFCLK RC oscillator, 8000ms calibration interval.*/ 00114 NRF_CLOCK_LFCLKSRC_RC_250_PPM_TEMP_1000MS_CALIBRATION, /**< LFCLK RC oscillator. Temperature checked every 1000ms, if changed above a threshold, a calibration is done.*/ 00115 NRF_CLOCK_LFCLKSRC_RC_250_PPM_TEMP_2000MS_CALIBRATION, /**< LFCLK RC oscillator. Temperature checked every 2000ms, if changed above a threshold, a calibration is done.*/ 00116 NRF_CLOCK_LFCLKSRC_RC_250_PPM_TEMP_4000MS_CALIBRATION, /**< LFCLK RC oscillator. Temperature checked every 4000ms, if changed above a threshold, a calibration is done.*/ 00117 NRF_CLOCK_LFCLKSRC_RC_250_PPM_TEMP_8000MS_CALIBRATION, /**< LFCLK RC oscillator. Temperature checked every 8000ms, if changed above a threshold, a calibration is done.*/ 00118 NRF_CLOCK_LFCLKSRC_RC_250_PPM_TEMP_16000MS_CALIBRATION, /**< LFCLK RC oscillator. Temperature checked every 16000ms, if changed above a threshold, a calibration is done.*/ 00119 }; 00120 00121 /** @} */ 00122 00123 /** @addtogroup NRF_SDM_TYPES Types 00124 * @{ */ 00125 00126 /**@brief Type representing lfclk oscillator source. */ 00127 typedef uint32_t nrf_clock_lfclksrc_t; 00128 00129 00130 /**@brief SoftDevice Assertion Handler type. 00131 * 00132 * When an unexpected error occurs within the SoftDevice it will call the SoftDevice assertion handler callback. 00133 * The protocol stack will be in an undefined state when this happens and the only way to recover will be to 00134 * perform a reset, using e.g. CMSIS NVIC_SystemReset(). 00135 * 00136 * @note This callback is executed in HardFault context, thus SVC functions cannot be called from the SoftDevice assert callback. 00137 * 00138 * @param[in] pc The program counter of the failed assert. 00139 * @param[in] line_number Line number where the assert failed. 00140 * @param[in] file_name File name where the assert failed. 00141 */ 00142 typedef void (*softdevice_assertion_handler_t)(uint32_t pc, uint16_t line_number, const uint8_t * p_file_name); 00143 00144 /** @} */ 00145 00146 /** @addtogroup NRF_SDM_FUNCTIONS Functions 00147 * @{ */ 00148 00149 /**@brief Enables the SoftDevice and by extension the protocol stack. 00150 * 00151 * Idempotent function to enable the SoftDevice. 00152 * 00153 * @note Some care must be taken if a low frequency clock source is already running when calling this function: 00154 * If the LF clock has a different source then the one currently running, it will be stopped. Then, the new 00155 * clock source will be started. 00156 * 00157 * @note This function has no effect when returning with an error. 00158 * 00159 * @post If return code is ::NRF_SUCCESS 00160 * - SoC library and protocol stack APIs are made available. 00161 * - A portion of RAM will be unavailable (see relevant SDS documentation). 00162 * - Some peripherals will be unavailable or available only through the SoC API (see relevant SDS documentation). 00163 * - Interrupts will not arrive from protected peripherals or interrupts. 00164 * - nrf_nvic_ functions must be used instead of CMSIS NVIC_ functions for reliable usage of the softdevice. 00165 * - Interrupt latency may be affected by the SoftDevice (see relevant SDS documentation). 00166 * - Chosen low frequency clock source will be running. 00167 * 00168 * @param clock_source Low frequency clock source and accuracy. (Note: In the case of XTAL source, the PPM accuracy of the chosen clock source must be greater than or equal to the actual characteristics of your XTAL clock). 00169 * @param assertion_handler Callback for SoftDevice assertions. 00170 * 00171 * @retval ::NRF_SUCCESS 00172 * @retval ::NRF_ERROR_INVALID_STATE SoftDevice is already enabled, and the clock source and assertion handler cannot be updated. 00173 * @retval ::NRF_ERROR_SDM_INCORRECT_INTERRUPT_CONFIGURATION SoftDeviceinterrupt is already enabled, or an enabled interrupt has an illegal priority level. 00174 * @retval ::NRF_ERROR_SDM_LFCLK_SOURCE_UNKNOWN Unknown low frequency clock source selected. 00175 */ 00176 SVCALL(SD_SOFTDEVICE_ENABLE, uint32_t, sd_softdevice_enable(nrf_clock_lfclksrc_t clock_source, softdevice_assertion_handler_t assertion_handler)); 00177 00178 /**@brief Disables the SoftDevice and by extension the protocol stack. 00179 * 00180 * Idempotent function to disable the SoftDevice. 00181 * 00182 * @post SoC library and protocol stack APIs are made unavailable. 00183 * @post All interrupts that was protected by the SoftDevice will be disabled and initialized to priority 0 (highest). 00184 * @post All peripherals used by the SoftDevice will be reset to default values. 00185 * @post All of RAM become available. 00186 * @post All interrupts are forwarded to the application. 00187 * @post LFCLK source chosen in ::sd_softdevice_enable will be left running. 00188 * 00189 * @retval ::NRF_SUCCESS 00190 */ 00191 SVCALL(SD_SOFTDEVICE_DISABLE, uint32_t, sd_softdevice_disable(void)); 00192 00193 /**@brief Check if the SoftDevice is enabled. 00194 * 00195 * @param[out] p_softdevice_enabled If the SoftDevice is enabled: 1 else 0. 00196 * 00197 * @retval ::NRF_SUCCESS 00198 */ 00199 SVCALL(SD_SOFTDEVICE_IS_ENABLED, uint32_t, sd_softdevice_is_enabled(uint8_t * p_softdevice_enabled)); 00200 00201 /**@brief Sets the base address of the interrupt vector table for interrupts forwarded from the SoftDevice 00202 * 00203 * This function is only intended to be called when a bootloader is enabled. 00204 * 00205 * @param[in] address The base address of the interrupt vector table for forwarded interrupts. 00206 00207 * @retval ::NRF_SUCCESS 00208 */ 00209 SVCALL(SD_SOFTDEVICE_VECTOR_TABLE_BASE_SET, uint32_t, sd_softdevice_vector_table_base_set(uint32_t address)); 00210 00211 /** @} */ 00212 00213 #endif // NRF_SDM_H__ 00214 00215 /** 00216 @} 00217 */
Generated on Tue Jul 12 2022 11:17:18 by 1.7.2