nrf_soc.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  *   4. This software must only be used in a processor manufactured by Nordic
00020  *   Semiconductor ASA, or in a processor manufactured by a third party that
00021  *   is used in combination with a processor manufactured by Nordic Semiconductor.
00022  * 
00023  * 
00024  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
00025  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
00026  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
00027  * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
00028  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
00029  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
00030  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
00031  * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
00032  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00033  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00034  * 
00035  */ 
00036 /**
00037  * @defgroup nrf_soc_api SoC Library API
00038  * @{
00039  * 
00040  * @brief APIs for the SoC library.
00041  * 
00042  */
00043 
00044 #ifndef NRF_SOC_H__
00045 #define NRF_SOC_H__
00046 
00047 #include <stdint.h>
00048 #include <stdbool.h>
00049 #include "nrf_svc.h"
00050 #include "nrf.h"
00051 
00052 #include "nrf_error_soc.h"
00053 
00054 #ifdef __cplusplus
00055 extern "C" {
00056 #endif
00057 
00058 /**@addtogroup NRF_SOC_DEFINES Defines
00059  * @{ */
00060 
00061 /**@brief The number of the lowest SVC number reserved for the SoC library. */
00062 #define SOC_SVC_BASE               (0x20)
00063 #define SOC_SVC_BASE_NOT_AVAILABLE (0x2B)
00064 
00065 /**@brief Guranteed time for application to process radio inactive notification. */
00066 #define NRF_RADIO_NOTIFICATION_INACTIVE_GUARANTEED_TIME_US  (62)
00067 
00068 /**@brief The minimum allowed timeslot extension time. */
00069 #define NRF_RADIO_MINIMUM_TIMESLOT_LENGTH_EXTENSION_TIME_US (200)
00070 
00071 #define SOC_ECB_KEY_LENGTH                (16)                       /**< ECB key length. */
00072 #define SOC_ECB_CLEARTEXT_LENGTH          (16)                       /**< ECB cleartext length. */
00073 #define SOC_ECB_CIPHERTEXT_LENGTH         (SOC_ECB_CLEARTEXT_LENGTH) /**< ECB ciphertext length. */
00074 
00075 #ifdef NRF51
00076 #define SD_EVT_IRQn                       (SWI2_IRQn)        /**< SoftDevice Event IRQ number. Used for both protocol events and SoC events. */
00077 #define SD_EVT_IRQHandler                 (SWI2_IRQHandler)  /**< SoftDevice Event IRQ handler. Used for both protocol events and SoC events. */
00078 #define RADIO_NOTIFICATION_IRQn           (SWI1_IRQn)        /**< The radio notification IRQ number. */
00079 #define RADIO_NOTIFICATION_IRQHandler     (SWI1_IRQHandler)  /**< The radio notification IRQ handler. */
00080 #endif
00081 #ifdef NRF52
00082 #define SD_EVT_IRQn                       (SWI2_EGU2_IRQn)        /**< SoftDevice Event IRQ number. Used for both protocol events and SoC events. */
00083 #define SD_EVT_IRQHandler                 (SWI2_EGU2_IRQHandler)  /**< SoftDevice Event IRQ handler. Used for both protocol events and SoC events. */
00084 #define RADIO_NOTIFICATION_IRQn           (SWI1_EGU1_IRQn)        /**< The radio notification IRQ number. */
00085 #define RADIO_NOTIFICATION_IRQHandler     (SWI1_EGU1_IRQHandler)  /**< The radio notification IRQ handler. */
00086 #endif
00087 
00088 #define NRF_RADIO_LENGTH_MIN_US           (100)               /**< The shortest allowed radio timeslot, in microseconds. */
00089 #define NRF_RADIO_LENGTH_MAX_US           (100000)            /**< The longest allowed radio timeslot, in microseconds. */
00090 
00091 #define NRF_RADIO_DISTANCE_MAX_US         (128000000UL - 1UL) /**< The longest timeslot distance, in microseconds, allowed for the distance parameter (see @ref nrf_radio_request_normal_t) in the request. */
00092 
00093 #define NRF_RADIO_EARLIEST_TIMEOUT_MAX_US (128000000UL - 1UL) /**< The longest timeout, in microseconds, allowed when requesting the earliest possible timeslot. */
00094 
00095 #define NRF_RADIO_START_JITTER_US         (2)                 /**< The maximum jitter in @ref NRF_RADIO_CALLBACK_SIGNAL_TYPE_START relative to the requested start time. */
00096 
00097 /**@} */
00098 
00099 /**@addtogroup NRF_SOC_ENUMS Enumerations
00100  * @{ */
00101 
00102 /**@brief The SVC numbers used by the SVC functions in the SoC library. */
00103 enum NRF_SOC_SVCS
00104 {
00105   SD_PPI_CHANNEL_ENABLE_GET = SOC_SVC_BASE,
00106   SD_PPI_CHANNEL_ENABLE_SET,
00107   SD_PPI_CHANNEL_ENABLE_CLR,
00108   SD_PPI_CHANNEL_ASSIGN,
00109   SD_PPI_GROUP_TASK_ENABLE,
00110   SD_PPI_GROUP_TASK_DISABLE,
00111   SD_PPI_GROUP_ASSIGN,
00112   SD_PPI_GROUP_GET,
00113   SD_FLASH_PAGE_ERASE,
00114   SD_FLASH_WRITE,
00115   SD_FLASH_PROTECT,
00116   SD_MUTEX_NEW = SOC_SVC_BASE_NOT_AVAILABLE,
00117   SD_MUTEX_ACQUIRE,
00118   SD_MUTEX_RELEASE,
00119   SD_RFU_1,
00120   SD_RFU_2,
00121   SD_RFU_3,
00122   SD_RFU_4,
00123   SD_RFU_5,
00124   SD_RFU_6,
00125   SD_RFU_7,
00126   SD_RFU_8,
00127   SD_RFU_9,
00128   SD_RFU_10,
00129   SD_RAND_APPLICATION_POOL_CAPACITY_GET,
00130   SD_RAND_APPLICATION_BYTES_AVAILABLE_GET,
00131   SD_RAND_APPLICATION_VECTOR_GET,
00132   SD_POWER_MODE_SET,
00133   SD_POWER_SYSTEM_OFF,
00134   SD_POWER_RESET_REASON_GET,
00135   SD_POWER_RESET_REASON_CLR,
00136   SD_POWER_POF_ENABLE,
00137   SD_POWER_POF_THRESHOLD_SET,
00138   SD_POWER_RAMON_SET,
00139   SD_POWER_RAMON_CLR,
00140   SD_POWER_RAMON_GET,
00141   SD_POWER_GPREGRET_SET,
00142   SD_POWER_GPREGRET_CLR,
00143   SD_POWER_GPREGRET_GET,
00144   SD_POWER_DCDC_MODE_SET,
00145   SD_APP_EVT_WAIT,
00146   SD_CLOCK_HFCLK_REQUEST,
00147   SD_CLOCK_HFCLK_RELEASE,
00148   SD_CLOCK_HFCLK_IS_RUNNING,
00149   SD_RADIO_NOTIFICATION_CFG_SET,
00150   SD_ECB_BLOCK_ENCRYPT,
00151   SD_ECB_BLOCKS_ENCRYPT,
00152   SD_RADIO_SESSION_OPEN,
00153   SD_RADIO_SESSION_CLOSE,
00154   SD_RADIO_REQUEST,
00155   SD_EVT_GET,
00156   SD_TEMP_GET,
00157   SVC_SOC_LAST
00158 };
00159 
00160 /**@brief Possible values of a ::nrf_mutex_t. */
00161 enum NRF_MUTEX_VALUES
00162 {
00163   NRF_MUTEX_FREE,
00164   NRF_MUTEX_TAKEN
00165 };
00166 
00167 /**@brief Power modes. */
00168 enum NRF_POWER_MODES
00169 {
00170   NRF_POWER_MODE_CONSTLAT,  /**< Constant latency mode. See power management in the reference manual. */
00171   NRF_POWER_MODE_LOWPWR     /**< Low power mode. See power management in the reference manual. */
00172 };
00173 
00174 
00175 /**@brief Power failure thresholds */
00176 enum NRF_POWER_THRESHOLDS
00177 {
00178   NRF_POWER_THRESHOLD_V21,  /**< 2.1 Volts power failure threshold. */
00179   NRF_POWER_THRESHOLD_V23,  /**< 2.3 Volts power failure threshold. */
00180   NRF_POWER_THRESHOLD_V25,  /**< 2.5 Volts power failure threshold. */ 
00181   NRF_POWER_THRESHOLD_V27   /**< 2.7 Volts power failure threshold. */
00182 };
00183 
00184 
00185 /**@brief DC/DC converter modes. */
00186 enum NRF_POWER_DCDC_MODES
00187 {
00188   NRF_POWER_DCDC_DISABLE,          /**< The DCDC is disabled. */
00189   NRF_POWER_DCDC_ENABLE            /**< The DCDC is enabled.  */
00190 };
00191 
00192 /**@brief Radio notification distances. */
00193 enum NRF_RADIO_NOTIFICATION_DISTANCES
00194 {
00195   NRF_RADIO_NOTIFICATION_DISTANCE_NONE = 0, /**< The event does not have a notification. */
00196   NRF_RADIO_NOTIFICATION_DISTANCE_800US,    /**< The distance from the active notification to start of radio activity. */
00197   NRF_RADIO_NOTIFICATION_DISTANCE_1740US,   /**< The distance from the active notification to start of radio activity. */
00198   NRF_RADIO_NOTIFICATION_DISTANCE_2680US,   /**< The distance from the active notification to start of radio activity. */
00199   NRF_RADIO_NOTIFICATION_DISTANCE_3620US,   /**< The distance from the active notification to start of radio activity. */
00200   NRF_RADIO_NOTIFICATION_DISTANCE_4560US,   /**< The distance from the active notification to start of radio activity. */
00201   NRF_RADIO_NOTIFICATION_DISTANCE_5500US    /**< The distance from the active notification to start of radio activity. */
00202 };
00203 
00204 
00205 /**@brief Radio notification types. */
00206 enum NRF_RADIO_NOTIFICATION_TYPES
00207 {
00208   NRF_RADIO_NOTIFICATION_TYPE_NONE = 0,        /**< The event does not have a radio notification signal. */
00209   NRF_RADIO_NOTIFICATION_TYPE_INT_ON_ACTIVE,   /**< Using interrupt for notification when the radio will be enabled. */
00210   NRF_RADIO_NOTIFICATION_TYPE_INT_ON_INACTIVE, /**< Using interrupt for notification when the radio has been disabled. */
00211   NRF_RADIO_NOTIFICATION_TYPE_INT_ON_BOTH,     /**< Using interrupt for notification both when the radio will be enabled and disabled. */
00212 };
00213 
00214 /**@brief The Radio signal callback types. */
00215 enum NRF_RADIO_CALLBACK_SIGNAL_TYPE
00216 {
00217   NRF_RADIO_CALLBACK_SIGNAL_TYPE_START,             /**< This signal indicates the start of the radio timeslot. */
00218   NRF_RADIO_CALLBACK_SIGNAL_TYPE_TIMER0,            /**< This signal indicates the NRF_TIMER0 interrupt. */
00219   NRF_RADIO_CALLBACK_SIGNAL_TYPE_RADIO,             /**< This signal indicates the NRF_RADIO interrupt. */
00220   NRF_RADIO_CALLBACK_SIGNAL_TYPE_EXTEND_FAILED,     /**< This signal indicates extend action failed. */
00221   NRF_RADIO_CALLBACK_SIGNAL_TYPE_EXTEND_SUCCEEDED   /**< This signal indicates extend action succeeded. */
00222 };
00223 
00224 /**@brief The actions requested by the signal callback.
00225  *
00226  *  This code gives the SOC instructions about what action to take when the signal callback has
00227  *  returned.
00228  */
00229 enum NRF_RADIO_SIGNAL_CALLBACK_ACTION
00230 {
00231   NRF_RADIO_SIGNAL_CALLBACK_ACTION_NONE,            /**< Return without action. */
00232   NRF_RADIO_SIGNAL_CALLBACK_ACTION_EXTEND,          /**< Request an extension of the current timeslot (maximum execution time for this action is when the extension succeeded). */
00233   NRF_RADIO_SIGNAL_CALLBACK_ACTION_END,             /**< End the current radio timeslot. */
00234   NRF_RADIO_SIGNAL_CALLBACK_ACTION_REQUEST_AND_END  /**< Request a new radio timeslot and end the current timeslot. */
00235 };
00236 
00237 /**@brief Radio timeslot high frequency clock source configuration. */
00238 enum NRF_RADIO_HFCLK_CFG
00239 {
00240   NRF_RADIO_HFCLK_CFG_XTAL_GUARANTEED, /**< The SoftDevice will guarantee that the high frequency clock source is the
00241                                            external crystal for the whole duration of the timeslot. This should be the
00242                                            preferred option for events that use the radio or require high timing accuracy. */
00243   NRF_RADIO_HFCLK_CFG_NO_GUARANTEE    /**< This configuration allows for earlier and tighter scheduling of timeslots.
00244                                            The RC oscillator may be the clock source in part or for the whole duration of the timeslot.
00245                                            The RC oscillator's accuracy must therefore be taken into consideration.
00246                                            @note If the application will use the radio peripheral in timeslots with this configuration,
00247                                            it must make sure that the crystal is running and stable before starting the radio. */
00248 };
00249 
00250 /**@brief Radio timeslot priorities. */
00251 enum NRF_RADIO_PRIORITY
00252 {
00253   NRF_RADIO_PRIORITY_HIGH,                          /**< High (equal priority as the normal connection priority of the SoftDevice stack(s)). */
00254   NRF_RADIO_PRIORITY_NORMAL,                        /**< Normal (equal priority as the priority of secondary activites of the SoftDevice stack(s)). */
00255 };
00256 
00257 /**@brief Radio timeslot request type. */
00258 enum NRF_RADIO_REQUEST_TYPE
00259 {
00260   NRF_RADIO_REQ_TYPE_EARLIEST,                      /**< Request radio timeslot as early as possible. This should always be used for the first request in a session. */
00261   NRF_RADIO_REQ_TYPE_NORMAL                         /**< Normal radio timeslot request. */
00262 };
00263 
00264 /**@brief SoC Events. */
00265 enum NRF_SOC_EVTS
00266 {
00267   NRF_EVT_HFCLKSTARTED,                         /**< Event indicating that the HFCLK has started. */
00268   NRF_EVT_POWER_FAILURE_WARNING,                /**< Event indicating that a power failure warning has occurred. */
00269   NRF_EVT_FLASH_OPERATION_SUCCESS,              /**< Event indicating that the ongoing flash operation has completed successfully. */
00270   NRF_EVT_FLASH_OPERATION_ERROR,                /**< Event indicating that the ongoing flash operation has timed out with an error. */
00271   NRF_EVT_RADIO_BLOCKED,                        /**< Event indicating that a radio timeslot was blocked. */
00272   NRF_EVT_RADIO_CANCELED,                       /**< Event indicating that a radio timeslot was canceled by SoftDevice. */
00273   NRF_EVT_RADIO_SIGNAL_CALLBACK_INVALID_RETURN, /**< Event indicating that a radio timeslot signal callback handler return was invalid. */
00274   NRF_EVT_RADIO_SESSION_IDLE,                   /**< Event indicating that a radio timeslot session is idle. */
00275   NRF_EVT_RADIO_SESSION_CLOSED,                 /**< Event indicating that a radio timeslot session is closed. */
00276   NRF_EVT_NUMBER_OF_EVTS
00277 };
00278 
00279 /**@} */
00280 
00281 
00282 /**@addtogroup NRF_SOC_STRUCTURES Structures
00283  * @{ */
00284 
00285 /**@brief Represents a mutex for use with the nrf_mutex functions.
00286  * @note Accessing the value directly is not safe, use the mutex functions!
00287  */
00288 typedef volatile uint8_t nrf_mutex_t;
00289 
00290 /**@brief Parameters for a request for a timeslot as early as possible. */
00291 typedef struct
00292 {
00293   uint8_t       hfclk;                              /**< High frequency clock source, see @ref NRF_RADIO_HFCLK_CFG. */
00294   uint8_t       priority;                           /**< The radio timeslot priority, see @ref NRF_RADIO_PRIORITY. */
00295   uint32_t      length_us;                          /**< The radio timeslot length (in the range 100 to 100,000] microseconds). */
00296   uint32_t      timeout_us;                         /**< Longest acceptable delay until the start of the requested timeslot (up to @ref NRF_RADIO_EARLIEST_TIMEOUT_MAX_US microseconds). */
00297 } nrf_radio_request_earliest_t;
00298 
00299 /**@brief Parameters for a normal radio timeslot request. */
00300 typedef struct
00301 {
00302   uint8_t       hfclk;                              /**< High frequency clock source, see @ref NRF_RADIO_HFCLK_CFG. */
00303   uint8_t       priority;                           /**< The radio timeslot priority, see @ref NRF_RADIO_PRIORITY. */
00304   uint32_t      distance_us;                        /**< Distance from the start of the previous radio timeslot (up to @ref NRF_RADIO_DISTANCE_MAX_US microseconds). */
00305   uint32_t      length_us;                          /**< The radio timeslot length (in the range [100..100,000] microseconds). */
00306 } nrf_radio_request_normal_t;
00307 
00308 /**@brief Radio timeslot request parameters. */
00309 typedef struct
00310 {
00311   uint8_t                         request_type;     /**< Type of request, see @ref NRF_RADIO_REQUEST_TYPE. */
00312   union
00313   {
00314     nrf_radio_request_earliest_t  earliest;         /**< Parameters for requesting a radio timeslot as early as possible. */
00315     nrf_radio_request_normal_t    normal;           /**< Parameters for requesting a normal radio timeslot. */
00316   } params;
00317 } nrf_radio_request_t;
00318 
00319 /**@brief Return parameters of the radio timeslot signal callback. */
00320 typedef struct
00321 {
00322   uint8_t               callback_action;            /**< The action requested by the application when returning from the signal callback, see @ref NRF_RADIO_SIGNAL_CALLBACK_ACTION. */
00323   union
00324   {
00325     struct
00326     {
00327       nrf_radio_request_t * p_next;                 /**< The request parameters for the next radio timeslot. */
00328     } request;                                      /**< Additional parameters for return_code @ref NRF_RADIO_SIGNAL_CALLBACK_ACTION_REQUEST_AND_END. */
00329     struct
00330     {
00331       uint32_t              length_us;              /**< Requested extension of the radio timeslot duration (microseconds) (for minimum time see @ref NRF_RADIO_MINIMUM_TIMESLOT_LENGTH_EXTENSION_TIME_US). */
00332     } extend;                                       /**< Additional parameters for return_code @ref NRF_RADIO_SIGNAL_CALLBACK_ACTION_EXTEND. */
00333   } params;
00334 } nrf_radio_signal_callback_return_param_t;
00335 
00336 /**@brief The radio timeslot signal callback type.
00337  *
00338  * @note In case of invalid return parameters, the radio timeslot will automatically end
00339  *       immediately after returning from the signal callback and the
00340  *       @ref NRF_EVT_RADIO_SIGNAL_CALLBACK_INVALID_RETURN event will be sent.
00341  * @note The returned struct pointer must remain valid after the signal callback
00342  *       function returns. For instance, this means that it must not point to a stack variable.
00343  *
00344  * @param[in] signal_type Type of signal, see @ref NRF_RADIO_CALLBACK_SIGNAL_TYPE.
00345  *
00346  * @return Pointer to structure containing action requested by the application.
00347  */
00348 typedef nrf_radio_signal_callback_return_param_t * (*nrf_radio_signal_callback_t) (uint8_t signal_type);
00349 
00350 /**@brief AES ECB parameter typedefs */
00351 typedef uint8_t soc_ecb_key_t[SOC_ECB_KEY_LENGTH];
00352 typedef uint8_t soc_ecb_cleartext_t[SOC_ECB_CLEARTEXT_LENGTH];
00353 typedef uint8_t soc_ecb_ciphertext_t[SOC_ECB_CIPHERTEXT_LENGTH];
00354 
00355 /**@brief AES ECB data structure */
00356 typedef struct
00357 {
00358   soc_ecb_key_t        key;            /**< Encryption key. */
00359   soc_ecb_cleartext_t  cleartext;      /**< Cleartext data. */
00360   soc_ecb_ciphertext_t ciphertext;     /**< Ciphertext data. */
00361 } nrf_ecb_hal_data_t;
00362 
00363 /**@brief AES ECB block. Used to provide multiple blocks in a single call
00364           to @ref sd_ecb_blocks_encrypt.*/
00365 typedef struct
00366 {
00367   soc_ecb_key_t*        p_key;           /**< Pointer to the Encryption key. */
00368   soc_ecb_cleartext_t*  p_cleartext;     /**< Pointer to the Cleartext data. */
00369   soc_ecb_ciphertext_t* p_ciphertext;    /**< Pointer to the Ciphertext data. */
00370 } nrf_ecb_hal_data_block_t;
00371 
00372 /**@} */
00373 
00374 /**@addtogroup NRF_SOC_FUNCTIONS Functions
00375  * @{ */
00376 
00377 /**@brief Initialize a mutex.
00378  *
00379  * @param[in] p_mutex Pointer to the mutex to initialize.
00380  *
00381  * @retval ::NRF_SUCCESS
00382  */
00383 SVCALL(SD_MUTEX_NEW, uint32_t, sd_mutex_new(nrf_mutex_t * p_mutex));
00384 
00385 /**@brief Attempt to acquire a mutex.
00386  *
00387  * @param[in] p_mutex Pointer to the mutex to acquire.
00388  *
00389  * @retval ::NRF_SUCCESS The mutex was successfully acquired.
00390  * @retval ::NRF_ERROR_SOC_MUTEX_ALREADY_TAKEN The mutex could not be acquired.
00391  */
00392 SVCALL(SD_MUTEX_ACQUIRE, uint32_t, sd_mutex_acquire(nrf_mutex_t * p_mutex));
00393 
00394 /**@brief Release a mutex.
00395  *
00396  * @param[in] p_mutex Pointer to the mutex to release.
00397  *
00398  * @retval ::NRF_SUCCESS
00399  */
00400 SVCALL(SD_MUTEX_RELEASE, uint32_t, sd_mutex_release(nrf_mutex_t * p_mutex));
00401 
00402 /**@brief Query the capacity of the application random pool.
00403  *
00404  * @param[out] p_pool_capacity The capacity of the pool.
00405  *
00406  * @retval ::NRF_SUCCESS
00407  */
00408 SVCALL(SD_RAND_APPLICATION_POOL_CAPACITY_GET, uint32_t, sd_rand_application_pool_capacity_get(uint8_t * p_pool_capacity));
00409 
00410 /**@brief Get number of random bytes available to the application.
00411  *
00412  * @param[out] p_bytes_available The number of bytes currently available in the pool.
00413  *
00414  * @retval ::NRF_SUCCESS
00415  */
00416 SVCALL(SD_RAND_APPLICATION_BYTES_AVAILABLE_GET, uint32_t, sd_rand_application_bytes_available_get(uint8_t * p_bytes_available));
00417 
00418 /**@brief Get random bytes from the application pool.
00419  *
00420  * @param[out]  p_buff  Pointer to unit8_t buffer for storing the bytes.
00421  * @param[in]   length  Number of bytes to take from pool and place in p_buff.
00422  *
00423  * @retval ::NRF_SUCCESS The requested bytes were written to p_buff.
00424  * @retval ::NRF_ERROR_SOC_RAND_NOT_ENOUGH_VALUES No bytes were written to the buffer, because there were not enough bytes available.
00425 */
00426 SVCALL(SD_RAND_APPLICATION_VECTOR_GET, uint32_t, sd_rand_application_vector_get(uint8_t * p_buff, uint8_t length));
00427 
00428 /**@brief Gets the reset reason register. 
00429  *
00430  * @param[out]  p_reset_reason  Contents of the NRF_POWER->RESETREAS register.
00431  *
00432  * @retval ::NRF_SUCCESS
00433  */
00434 SVCALL(SD_POWER_RESET_REASON_GET, uint32_t, sd_power_reset_reason_get(uint32_t * p_reset_reason));
00435 
00436 /**@brief Clears the bits of the reset reason register. 
00437  *
00438  * @param[in] reset_reason_clr_msk Contains the bits to clear from the reset reason register.
00439  *
00440  * @retval ::NRF_SUCCESS
00441  */
00442 SVCALL(SD_POWER_RESET_REASON_CLR, uint32_t, sd_power_reset_reason_clr(uint32_t reset_reason_clr_msk));
00443 
00444 /**@brief Sets the power mode when in CPU sleep.
00445  *
00446  * @param[in] power_mode The power mode to use when in CPU sleep, see @ref NRF_POWER_MODES. @sa sd_app_evt_wait
00447  *
00448  * @retval ::NRF_SUCCESS The power mode was set.
00449  * @retval ::NRF_ERROR_SOC_POWER_MODE_UNKNOWN The power mode was unknown.
00450  */
00451 SVCALL(SD_POWER_MODE_SET, uint32_t, sd_power_mode_set(uint8_t power_mode));
00452 
00453 /**@brief Puts the chip in System OFF mode. 
00454  *
00455  * @retval ::NRF_ERROR_SOC_POWER_OFF_SHOULD_NOT_RETURN
00456  */
00457 SVCALL(SD_POWER_SYSTEM_OFF, uint32_t, sd_power_system_off(void));
00458 
00459 /**@brief Enables or disables the power-fail comparator.
00460  *
00461  * Enabling this will give a softdevice event (NRF_EVT_POWER_FAILURE_WARNING) when the power failure warning occurs.
00462  * The event can be retrieved with sd_evt_get();
00463  *
00464  * @param[in] pof_enable    True if the power-fail comparator should be enabled, false if it should be disabled.
00465  *
00466  * @retval ::NRF_SUCCESS
00467  */
00468 SVCALL(SD_POWER_POF_ENABLE, uint32_t, sd_power_pof_enable(uint8_t pof_enable));
00469 
00470 /**@brief Sets the power-fail threshold value.
00471  *
00472  * @param[in] threshold The power-fail threshold value to use, see @ref NRF_POWER_THRESHOLDS.
00473  *
00474  * @retval ::NRF_SUCCESS The power failure threshold was set.
00475  * @retval ::NRF_ERROR_SOC_POWER_POF_THRESHOLD_UNKNOWN The power failure threshold is unknown.
00476  */
00477 SVCALL(SD_POWER_POF_THRESHOLD_SET, uint32_t, sd_power_pof_threshold_set(uint8_t threshold));
00478 
00479 /**@brief Sets bits in the NRF_POWER->RAMON register.
00480  *
00481  * @param[in] ramon Contains the bits needed to be set in the NRF_POWER->RAMON register.
00482  *
00483  * @retval ::NRF_SUCCESS
00484  */
00485 SVCALL(SD_POWER_RAMON_SET, uint32_t, sd_power_ramon_set(uint32_t ramon));
00486 
00487 /**@brief Clears bits in the NRF_POWER->RAMON register.
00488  *
00489  * @param ramon Contains the bits needed to be cleared in the NRF_POWER->RAMON register.
00490  *
00491  * @retval ::NRF_SUCCESS
00492  */
00493 SVCALL(SD_POWER_RAMON_CLR, uint32_t, sd_power_ramon_clr(uint32_t ramon));
00494 
00495 /**@brief Get contents of NRF_POWER->RAMON register, indicates power status of ram blocks.
00496  *
00497  * @param[out] p_ramon Content of NRF_POWER->RAMON register.
00498  *
00499  * @retval ::NRF_SUCCESS
00500  */
00501 SVCALL(SD_POWER_RAMON_GET, uint32_t, sd_power_ramon_get(uint32_t * p_ramon));
00502 
00503 /**@brief Set bits in the NRF_POWER->GPREGRET register.
00504  *
00505  * @param[in] gpregret_msk Bits to be set in the GPREGRET register.
00506  *
00507  * @retval ::NRF_SUCCESS
00508  */
00509 SVCALL(SD_POWER_GPREGRET_SET, uint32_t, sd_power_gpregret_set(uint32_t gpregret_msk));
00510 
00511 /**@brief Clear bits in the NRF_POWER->GPREGRET register.
00512  *
00513  * @param[in] gpregret_msk Bits to be clear in the GPREGRET register.
00514  *
00515  * @retval ::NRF_SUCCESS
00516  */
00517 SVCALL(SD_POWER_GPREGRET_CLR, uint32_t, sd_power_gpregret_clr(uint32_t gpregret_msk));
00518 
00519 /**@brief Get contents of the NRF_POWER->GPREGRET register.
00520  *
00521  * @param[out] p_gpregret Contents of the GPREGRET register.
00522  *
00523  * @retval ::NRF_SUCCESS
00524  */
00525 SVCALL(SD_POWER_GPREGRET_GET, uint32_t, sd_power_gpregret_get(uint32_t *p_gpregret));
00526 
00527 /**@brief Sets the DCDC mode.
00528  *
00529  * Enable or disable the DCDC peripheral.
00530  *
00531  * @param[in] dcdc_mode The mode of the DCDC, see @ref NRF_POWER_DCDC_MODES.
00532  *
00533  * @retval ::NRF_SUCCESS
00534  * @retval ::NRF_ERROR_INVALID_PARAM The DCDC mode is invalid.
00535  */
00536 SVCALL(SD_POWER_DCDC_MODE_SET, uint32_t, sd_power_dcdc_mode_set(uint8_t dcdc_mode));
00537 
00538 /**@brief Request the high frequency crystal oscillator.
00539  *
00540  * Will start the high frequency crystal oscillator, the startup time of the crystal varies
00541  * and the ::sd_clock_hfclk_is_running function can be polled to check if it has started.
00542  *
00543  * @see sd_clock_hfclk_is_running
00544  * @see sd_clock_hfclk_release
00545  *
00546  * @retval ::NRF_SUCCESS
00547  */
00548 SVCALL(SD_CLOCK_HFCLK_REQUEST, uint32_t, sd_clock_hfclk_request(void));
00549 
00550 /**@brief Releases the high frequency crystal oscillator.
00551  *
00552  * Will stop the high frequency crystal oscillator, this happens immediately.
00553  *
00554  * @see sd_clock_hfclk_is_running
00555  * @see sd_clock_hfclk_request
00556  *
00557  * @retval ::NRF_SUCCESS
00558  */
00559 SVCALL(SD_CLOCK_HFCLK_RELEASE, uint32_t, sd_clock_hfclk_release(void));
00560 
00561 /**@brief Checks if the high frequency crystal oscillator is running.
00562  *
00563  * @see sd_clock_hfclk_request
00564  * @see sd_clock_hfclk_release
00565  *
00566  * @param[out] p_is_running 1 if the external crystal oscillator is running, 0 if not.
00567  *
00568  * @retval ::NRF_SUCCESS
00569  */
00570 SVCALL(SD_CLOCK_HFCLK_IS_RUNNING, uint32_t, sd_clock_hfclk_is_running(uint32_t * p_is_running));
00571 
00572 /**@brief Waits for an application event.
00573  * 
00574  * An application event is either an application interrupt or a pended interrupt when the
00575  * interrupt is disabled. When the interrupt is enabled it will be taken immediately since
00576  * this function will wait in thread mode, then the execution will return in the application's
00577  * main thread. When an interrupt is disabled and gets pended it will return to the application's 
00578  * thread main. The application must ensure that the pended flag is cleared using 
00579  * ::sd_nvic_ClearPendingIRQ in order to sleep using this function. This is only necessary for
00580  * disabled interrupts, as the interrupt handler will clear the pending flag automatically for
00581  * enabled interrupts.
00582  *
00583  * In order to wake up from disabled interrupts, the SEVONPEND flag has to be set in the Cortex-M0
00584  * System Control Register (SCR). @sa CMSIS_SCB
00585  *
00586  * @note If an application interrupt has happened since the last time sd_app_evt_wait was
00587  *       called this function will return immediately and not go to sleep. This is to avoid race
00588  *       conditions that can occur when a flag is updated in the interrupt handler and processed
00589  *       in the main loop.
00590  *
00591  * @post An application interrupt has happened or a interrupt pending flag is set.
00592  *
00593  * @retval ::NRF_SUCCESS
00594  */
00595 SVCALL(SD_APP_EVT_WAIT, uint32_t, sd_app_evt_wait(void));
00596 
00597 /**@brief Get PPI channel enable register contents.
00598  *
00599  * @param[out] p_channel_enable The contents of the PPI CHEN register.
00600  *
00601  * @retval ::NRF_SUCCESS
00602  */
00603 SVCALL(SD_PPI_CHANNEL_ENABLE_GET, uint32_t, sd_ppi_channel_enable_get(uint32_t * p_channel_enable));
00604 
00605 /**@brief Set PPI channel enable register.
00606  *
00607  * @param[in] channel_enable_set_msk Mask containing the bits to set in the PPI CHEN register.
00608  *
00609  * @retval ::NRF_SUCCESS
00610  */
00611 SVCALL(SD_PPI_CHANNEL_ENABLE_SET, uint32_t, sd_ppi_channel_enable_set(uint32_t channel_enable_set_msk));
00612 
00613 /**@brief Clear PPI channel enable register.
00614  *
00615  * @param[in] channel_enable_clr_msk Mask containing the bits to clear in the PPI CHEN register.
00616  *
00617  * @retval ::NRF_SUCCESS
00618  */
00619 SVCALL(SD_PPI_CHANNEL_ENABLE_CLR, uint32_t, sd_ppi_channel_enable_clr(uint32_t channel_enable_clr_msk));
00620 
00621 /**@brief Assign endpoints to a PPI channel.
00622  *
00623  * @param[in] channel_num Number of the PPI channel to assign.
00624  * @param[in] evt_endpoint Event endpoint of the PPI channel.
00625  * @param[in] task_endpoint Task endpoint of the PPI channel.
00626  *
00627  * @retval ::NRF_ERROR_SOC_PPI_INVALID_CHANNEL The channel number is invalid.
00628  * @retval ::NRF_SUCCESS
00629  */
00630 SVCALL(SD_PPI_CHANNEL_ASSIGN, uint32_t, sd_ppi_channel_assign(uint8_t channel_num, const volatile void * evt_endpoint, const volatile void * task_endpoint));
00631 
00632 /**@brief Task to enable a channel group.
00633  *
00634  * @param[in] group_num Number of the channel group.
00635  *
00636  * @retval ::NRF_ERROR_SOC_PPI_INVALID_GROUP The group number is invalid
00637  * @retval ::NRF_SUCCESS
00638  */
00639 SVCALL(SD_PPI_GROUP_TASK_ENABLE, uint32_t, sd_ppi_group_task_enable(uint8_t group_num));
00640 
00641 /**@brief Task to disable a channel group.
00642  *
00643  * @param[in] group_num Number of the PPI group.
00644  *
00645  * @retval ::NRF_ERROR_SOC_PPI_INVALID_GROUP The group number is invalid.
00646  * @retval ::NRF_SUCCESS
00647  */
00648 SVCALL(SD_PPI_GROUP_TASK_DISABLE, uint32_t, sd_ppi_group_task_disable(uint8_t group_num));
00649 
00650 /**@brief Assign PPI channels to a channel group.
00651  *
00652  * @param[in] group_num Number of the channel group.
00653  * @param[in] channel_msk Mask of the channels to assign to the group.
00654  *
00655  * @retval ::NRF_ERROR_SOC_PPI_INVALID_GROUP The group number is invalid.
00656  * @retval ::NRF_SUCCESS
00657  */
00658 SVCALL(SD_PPI_GROUP_ASSIGN, uint32_t, sd_ppi_group_assign(uint8_t group_num, uint32_t channel_msk));
00659 
00660 /**@brief Gets the PPI channels of a channel group.
00661  *
00662  * @param[in]   group_num Number of the channel group.
00663  * @param[out]  p_channel_msk Mask of the channels assigned to the group.
00664  *
00665  * @retval ::NRF_ERROR_SOC_PPI_INVALID_GROUP The group number is invalid.
00666  * @retval ::NRF_SUCCESS
00667  */
00668 SVCALL(SD_PPI_GROUP_GET, uint32_t, sd_ppi_group_get(uint8_t group_num, uint32_t * p_channel_msk));
00669 
00670 /**@brief Configures the Radio Notification signal.
00671  *
00672  * @note
00673  *      - The notification signal latency depends on the interrupt priority settings of SWI used
00674  *        for notification signal.
00675  *      - To ensure that the radio notification signal behaves in a consistent way, always 
00676  *        configure radio notifications when there is no protocol stack or other SoftDevice 
00677  *        activity in progress. It is recommended that the radio notification signal is 
00678  *        configured directly after the SoftDevice has been enabled.
00679  *      - In the period between the ACTIVE signal and the start of the Radio Event, the SoftDevice
00680  *        will interrupt the application to do Radio Event preparation.
00681  *      - Using the Radio Notification feature may limit the bandwidth, as the SoftDevice may have
00682  *        to shorten the connection events to have time for the Radio Notification signals.
00683  *
00684  * @param[in]  type      Type of notification signal, see @ref NRF_RADIO_NOTIFICATION_TYPES.
00685  *                       @ref NRF_RADIO_NOTIFICATION_TYPE_NONE shall be used to turn off radio
00686  *                       notification. Using @ref NRF_RADIO_NOTIFICATION_DISTANCE_NONE is
00687  *                       recommended (but not required) to be used with
00688  *                       @ref NRF_RADIO_NOTIFICATION_TYPE_NONE.
00689  *
00690  * @param[in]  distance  Distance between the notification signal and start of radio activity, see @ref NRF_RADIO_NOTIFICATION_DISTANCES.
00691  *                       This parameter is ignored when @ref NRF_RADIO_NOTIFICATION_TYPE_NONE or 
00692  *                       @ref NRF_RADIO_NOTIFICATION_TYPE_INT_ON_INACTIVE is used. 
00693  *
00694  * @retval ::NRF_ERROR_INVALID_PARAM The group number is invalid.
00695  * @retval ::NRF_SUCCESS
00696  */
00697 SVCALL(SD_RADIO_NOTIFICATION_CFG_SET, uint32_t, sd_radio_notification_cfg_set(uint8_t type, uint8_t distance));
00698 
00699 /**@brief Encrypts a block according to the specified parameters.
00700  *
00701  * 128-bit AES encryption.
00702  *
00703  * @note:
00704  *    - The application may set the SEVONPEND bit in the SCR to 1 to make the SoftDevice sleep while
00705  *      the ECB is running. The SEVONPEND bit should only be cleared (set to 0) from application
00706  *      main or low interrupt level.
00707  *
00708  * @param[in, out] p_ecb_data Pointer to the ECB parameters' struct (two input
00709  *                            parameters and one output parameter).
00710  *
00711  * @retval ::NRF_SUCCESS
00712  */
00713 SVCALL(SD_ECB_BLOCK_ENCRYPT, uint32_t, sd_ecb_block_encrypt(nrf_ecb_hal_data_t * p_ecb_data));
00714 
00715 /**@brief Encrypts multiple data blocks provided as an array of data block structures.
00716  *
00717  * @details: Performs 128-bit AES encryption on multiple data blocks
00718  *
00719  * @note:
00720  *    - The application may set the SEVONPEND bit in the SCR to 1 to make the SoftDevice sleep while
00721  *      the ECB is running. The SEVONPEND bit should only be cleared (set to 0) from application
00722  *      main or low interrupt level.
00723  *
00724  * @param[in]     block_count     Count of blocks in the p_data_blocks array.
00725  * @param[in,out] p_data_blocks   Pointer to the first entry in a contiguous array of
00726  *                                @ref nrf_ecb_hal_data_block_t structures.
00727  *
00728  * @retval ::NRF_SUCCESS
00729  */
00730 SVCALL(SD_ECB_BLOCKS_ENCRYPT, uint32_t, sd_ecb_blocks_encrypt(uint8_t block_count, nrf_ecb_hal_data_block_t * p_data_blocks));
00731 
00732 /**@brief Gets any pending events generated by the SoC API.
00733  *
00734  * The application should keep calling this function to get events, until ::NRF_ERROR_NOT_FOUND is returned.
00735  *
00736  * @param[out] p_evt_id Set to one of the values in @ref NRF_SOC_EVTS, if any events are pending.
00737  *
00738  * @retval ::NRF_SUCCESS An event was pending. The event id is written in the p_evt_id parameter.
00739  * @retval ::NRF_ERROR_NOT_FOUND No pending events. 
00740  */
00741 SVCALL(SD_EVT_GET, uint32_t, sd_evt_get(uint32_t * p_evt_id));
00742 
00743 /**@brief Get the temperature measured on the chip
00744  * 
00745  * This function will block until the temperature measurement is done.
00746  * It takes around 50us from call to return.
00747  *
00748  * @param[out] p_temp Result of temperature measurement. Die temperature in 0.25 degrees celsius.
00749  *
00750  * @retval ::NRF_SUCCESS A temperature measurement was done, and the temperature was written to temp
00751  */
00752 SVCALL(SD_TEMP_GET, uint32_t, sd_temp_get(int32_t * p_temp));
00753 
00754 /**@brief Flash Write
00755 *
00756 * Commands to write a buffer to flash
00757 *
00758 * If the SoftDevice is enabled:
00759 *  This call initiates the flash access command, and its completion will be communicated to the
00760 *  application with exactly one of the following events:
00761 *      - @ref NRF_EVT_FLASH_OPERATION_SUCCESS - The command was successfully completed.
00762 *      - @ref NRF_EVT_FLASH_OPERATION_ERROR   - The command could not be started.
00763 *
00764 * If the SoftDevice is not enabled no event will be generated, and this call will return @ref NRF_SUCCESS when the 
00765  * write has been completed
00766 *
00767 * @note
00768 *      - This call takes control over the radio and the CPU during flash erase and write to make sure that
00769 *        they will not interfere with the flash access. This means that all interrupts will be blocked
00770 *        for a predictable time (depending on the NVMC specification in nRF51 Series Reference Manual
00771 *        and the command parameters).
00772 *
00773 *
00774 * @param[in]  p_dst Pointer to start of flash location to be written.
00775 * @param[in]  p_src Pointer to buffer with data to be written.
00776 * @param[in]  size  Number of 32-bit words to write. Maximum size is 256 32-bit words for nRF51 and 1024 for nRF52.
00777 *
00778 * @retval ::NRF_ERROR_INVALID_ADDR   Tried to write to a non existing flash address, or p_dst or p_src was unaligned.
00779 * @retval ::NRF_ERROR_BUSY           The previous command has not yet completed.
00780 * @retval ::NRF_ERROR_INVALID_LENGTH Size was 0, or higher than the maximum allowed size.
00781 * @retval ::NRF_ERROR_FORBIDDEN      Tried to write to or read from protected location.
00782 * @retval ::NRF_SUCCESS              The command was accepted.
00783 */
00784 SVCALL(SD_FLASH_WRITE, uint32_t, sd_flash_write(uint32_t * const p_dst, uint32_t const * const p_src, uint32_t size));
00785 
00786 
00787 /**@brief Flash Erase page
00788 *
00789 * Commands to erase a flash page
00790 * If the SoftDevice is enabled:
00791 *  This call initiates the flash access command, and its completion will be communicated to the
00792 *  application with exactly one of the following events:
00793 *      - @ref NRF_EVT_FLASH_OPERATION_SUCCESS - The command was successfully completed.
00794 *      - @ref NRF_EVT_FLASH_OPERATION_ERROR   - The command could not be started.
00795 *
00796 * If the SoftDevice is not enabled no event will be generated, and this call will return @ref NRF_SUCCESS when the 
00797 * erase has been completed
00798 *
00799 * @note
00800 *      - This call takes control over the radio and the CPU during flash erase and write to make sure that
00801 *        they will not interfere with the flash access. This means that all interrupts will be blocked
00802 *        for a predictable time (depending on the NVMC specification in nRF51 Series Reference Manual
00803 *        and the command parameters).
00804 *
00805 *
00806 * @param[in]  page_number Pagenumber of the page to erase
00807 * @retval ::NRF_ERROR_INTERNAL      If a new session could not be opened due to an internal error.
00808 * @retval ::NRF_ERROR_INVALID_ADDR  Tried to erase to a non existing flash page.
00809 * @retval ::NRF_ERROR_BUSY          The previous command has not yet completed.
00810 * @retval ::NRF_ERROR_FORBIDDEN     Tried to erase a protected page.
00811 * @retval ::NRF_SUCCESS             The command was accepted.
00812 */
00813 SVCALL(SD_FLASH_PAGE_ERASE, uint32_t, sd_flash_page_erase(uint32_t page_number));
00814 
00815 
00816 /**@brief Flash Protection set
00817  *
00818  * Commands to set the flash protection configuration registers.
00819    On nRF51 this sets the PROTENSETx registers of the MPU peripheral.
00820    On nRF52 this sets the CONFIGx registers of the BPROT peripheral.
00821  *
00822  * @note To read the values read them directly. They are only write-protected.
00823  *
00824  * @param[in]  block_cfg0 Value to be written to the configuration register.
00825  * @param[in]  block_cfg1 Value to be written to the configuration register.
00826  * @param[in]  block_cfg2 Value to be written to the configuration register (ignored on nRF51).
00827  * @param[in]  block_cfg3 Value to be written to the configuration register (ignored on nRF51).
00828  *
00829  * @retval ::NRF_ERROR_FORBIDDEN Tried to protect the SoftDevice.
00830  * @retval ::NRF_SUCCESS Values successfully written to configuration registers.
00831  */
00832 SVCALL(SD_FLASH_PROTECT, uint32_t, sd_flash_protect(uint32_t block_cfg0, uint32_t block_cfg1, uint32_t block_cfg2, uint32_t block_cfg3));
00833 
00834 /**@brief Opens a session for radio timeslot requests.
00835  *
00836  * @note Only one session can be open at a time.
00837  * @note p_radio_signal_callback(@ref NRF_RADIO_CALLBACK_SIGNAL_TYPE_START) will be called when the radio timeslot
00838  *       starts. From this point the NRF_RADIO and NRF_TIMER0 peripherals can be freely accessed
00839  *       by the application.
00840  * @note p_radio_signal_callback(@ref NRF_RADIO_CALLBACK_SIGNAL_TYPE_TIMER0) is called whenever the NRF_TIMER0
00841  *       interrupt occurs.
00842  * @note p_radio_signal_callback(@ref NRF_RADIO_CALLBACK_SIGNAL_TYPE_RADIO) is called whenever the NRF_RADIO
00843  *       interrupt occurs.
00844  * @note p_radio_signal_callback() will be called at ARM interrupt priority level 0. This
00845  *       implies that none of the sd_* API calls can be used from p_radio_signal_callback().
00846  *
00847  * @param[in] p_radio_signal_callback The signal callback.
00848  *
00849  * @retval ::NRF_ERROR_INVALID_ADDR p_radio_signal_callback is an invalid function pointer.
00850  * @retval ::NRF_ERROR_BUSY If session cannot be opened.
00851  * @retval ::NRF_ERROR_INTERNAL If a new session could not be opened due to an internal error.
00852  * @retval ::NRF_SUCCESS Otherwise.
00853  */
00854  SVCALL(SD_RADIO_SESSION_OPEN, uint32_t, sd_radio_session_open(nrf_radio_signal_callback_t p_radio_signal_callback));
00855 
00856 /**@brief Closes a session for radio timeslot requests.
00857  *
00858  * @note Any current radio timeslot will be finished before the session is closed.
00859  * @note If a radio timeslot is scheduled when the session is closed, it will be canceled.
00860  * @note The application cannot consider the session closed until the @ref NRF_EVT_RADIO_SESSION_CLOSED
00861  *       event is received.
00862  *
00863  * @retval ::NRF_ERROR_FORBIDDEN If session not opened.
00864  * @retval ::NRF_ERROR_BUSY If session is currently being closed.
00865  * @retval ::NRF_SUCCESS Otherwise.
00866  */
00867  SVCALL(SD_RADIO_SESSION_CLOSE, uint32_t, sd_radio_session_close(void));
00868 
00869 /**@brief Requests a radio timeslot.
00870  *
00871  * @note The request type is determined by p_request->request_type, and can be one of @ref NRF_RADIO_REQ_TYPE_EARLIEST
00872  *       and @ref NRF_RADIO_REQ_TYPE_NORMAL. The first request in a session must always be of type @ref NRF_RADIO_REQ_TYPE_EARLIEST.
00873  * @note For a normal request (@ref NRF_RADIO_REQ_TYPE_NORMAL), the start time of a radio timeslot is specified by
00874  *       p_request->distance_us and is given relative to the start of the previous timeslot. 
00875  * @note A too small p_request->distance_us will lead to a @ref NRF_EVT_RADIO_BLOCKED event.
00876  * @note Timeslots scheduled too close will lead to a @ref NRF_EVT_RADIO_BLOCKED event.
00877  * @note See the SoftDevice Specification for more on radio timeslot scheduling, distances and lengths.
00878  * @note If an opportunity for the first radio timeslot is not found before 100ms after the call to this
00879  *       function, it is not scheduled, and instead a @ref NRF_EVT_RADIO_BLOCKED event is sent.
00880  *       The application may then try to schedule the first radio timeslot again.
00881  * @note Successful requests will result in nrf_radio_signal_callback_t(@ref NRF_RADIO_CALLBACK_SIGNAL_TYPE_START).
00882  *       Unsuccessful requests will result in a @ref NRF_EVT_RADIO_BLOCKED event, see @ref NRF_SOC_EVTS.
00883  * @note The jitter in the start time of the radio timeslots is +/- @ref NRF_RADIO_START_JITTER_US us.
00884  * @note The nrf_radio_signal_callback_t(@ref NRF_RADIO_CALLBACK_SIGNAL_TYPE_START) call has a latency relative to the
00885  *       specified radio timeslot start, but this does not affect the actual start time of the timeslot.
00886  * @note NRF_TIMER0 is reset at the start of the radio timeslot, and is clocked at 1MHz from the high frequency
00887  *       (16 MHz) clock source. If p_request->hfclk_force_xtal is true, the high frequency clock is 
00888  *       guaranteed to be clocked from the external crystal.
00889  * @note The SoftDevice will neither access the NRF_RADIO peripheral nor the NRF_TIMER0 peripheral
00890  *       during the radio timeslot.
00891  *
00892  * @param[in] p_request Pointer to the request parameters.
00893  *
00894  * @retval ::NRF_ERROR_FORBIDDEN If session not opened or the session is not IDLE.
00895  * @retval ::NRF_ERROR_INVALID_ADDR If the p_request pointer is invalid.
00896  * @retval ::NRF_ERROR_INVALID_PARAM If the parameters of p_request are not valid.
00897  * @retval ::NRF_SUCCESS Otherwise.
00898  */
00899  SVCALL(SD_RADIO_REQUEST, uint32_t, sd_radio_request(nrf_radio_request_t * p_request ));
00900 
00901 /**@} */
00902 
00903 #ifdef __cplusplus
00904 }
00905 #endif
00906 #endif // NRF_SOC_H__
00907 
00908 /**@} */
00909