nrf_soc.h

00001 /* Copyright (c) 2011 Nordic Semiconductor. All Rights Reserved.
00002  *
00003  * The information contained herein is confidential property of Nordic Semiconductor. The use,
00004  * copying, transfer or disclosure of such information is prohibited except by express written
00005  * agreement with Nordic Semiconductor.
00006  *
00007  */
00008  
00009 /**
00010   @defgroup nrf_soc_api SoC Library API
00011   @{
00012   
00013   @brief APIs for the SoC library.
00014   
00015 */
00016 
00017 #ifndef NRF_SOC_H__
00018 #define NRF_SOC_H__
00019 
00020 #include <stdint.h>
00021 #include <stdbool.h>
00022 #include "nordic_global.h"
00023 #include "nrf_svc.h"
00024 #include "nrf51.h"
00025 #include "nrf51_bitfields.h"
00026 #include "nrf_error_soc.h"
00027 
00028 /** @addtogroup NRF_SOC_DEFINES Defines
00029  * @{ */
00030 
00031 /**@brief The number of the lowest SVC number reserved for the SoC library. */
00032 #define SOC_SVC_BASE 0x20
00033 
00034 /**@brief Guranteed time for application to process radio inactive notification. */
00035 #define NRF_RADIO_NOTIFICATION_INACTIVE_GUARANTEED_TIME_US   (62)
00036 
00037 #define SOC_ECB_KEY_LENGTH                   (16)                       /**< ECB key length. */
00038 #define SOC_ECB_CLEARTEXT_LENGTH             (16)                       /**< ECB cleartext length. */
00039 #define SOC_ECB_CIPHERTEXT_LENGTH            (SOC_ECB_CLEARTEXT_LENGTH) /**< ECB ciphertext length. */
00040 
00041 #define SD_EVT_IRQn                   (SWI2_IRQn)       /**< SoftDevice Event IRQ number. Used for both protocol events and SoC events. */
00042 #define SD_EVT_IRQHandler             (SWI2_IRQHandler) /**< SoftDevice Event IRQ handler. Used for both protocol events and SoC events. */
00043 #define RADIO_NOTIFICATION_IRQn       (SWI1_IRQn)       /**< The radio notification IRQ number. */
00044 #define RADIO_NOTIFICATION_IRQHandler (SWI1_IRQHandler) /**< The radio notification IRQ handler. */
00045 
00046 /** @} */
00047 
00048 /** @addtogroup NRF_SOC_TYPES Types
00049  * @{ */
00050 
00051 /**@brief The SVC numbers used by the SVC functions in the SoC library. */
00052 enum NRF_SOC_SVCS
00053 {
00054   SD_MUTEX_NEW = SOC_SVC_BASE,
00055   SD_MUTEX_ACQUIRE,
00056   SD_MUTEX_RELEASE,
00057   SD_NVIC_ENABLEIRQ,
00058   SD_NVIC_DISABLEIRQ,
00059   SD_NVIC_GETPENDINGIRQ,
00060   SD_NVIC_SETPENDINGIRQ,
00061   SD_NVIC_CLEARPENDINGIRQ,
00062   SD_NVIC_SETPRIORITY,
00063   SD_NVIC_GETPRIORITY,
00064   SD_NVIC_SYSTEMRESET,
00065   SD_NVIC_CRITICAL_REGION_ENTER,
00066   SD_NVIC_CRITICAL_REGION_EXIT,
00067   SD_RAND_APPLICATION_POOL_CAPACITY,
00068   SD_RAND_APPLICATION_BYTES_AVAILABLE,
00069   SD_RAND_APPLICATION_GET_VECTOR,
00070   SD_POWER_MODE_SET,
00071   SD_POWER_SYSTEM_OFF,
00072   SD_POWER_RESET_REASON_GET,
00073   SD_POWER_RESET_REASON_CLR,
00074   SD_POWER_POF_ENABLE,
00075   SD_POWER_POF_THRESHOLD_SET,
00076   SD_POWER_RAMON_SET,
00077   SD_POWER_RAMON_CLR,
00078   SD_POWER_RAMON_GET,
00079   SD_POWER_GPREGRET_SET,
00080   SD_POWER_GPREGRET_CLR,
00081   SD_POWER_GPREGRET_GET,
00082   SD_POWER_DCDC_MODE_SET,
00083   SD_APP_EVT_WAIT,
00084   SD_CLOCK_HFCLK_REQUEST,
00085   SD_CLOCK_HFCLK_RELEASE,
00086   SD_CLOCK_HFCLK_IS_RUNNING,
00087   SD_PPI_CHANNEL_ENABLE_GET,
00088   SD_PPI_CHANNEL_ENABLE_SET,
00089   SD_PPI_CHANNEL_ENABLE_CLR,
00090   SD_PPI_CHANNEL_ASSIGN,
00091   SD_PPI_GROUP_TASK_ENABLE,
00092   SD_PPI_GROUP_TASK_DISABLE,
00093   SD_PPI_GROUP_ASSIGN,
00094   SD_PPI_GROUP_GET,
00095   SD_RADIO_NOTIFICATION_CFG_SET,
00096   SD_ECB_BLOCK_ENCRYPT,
00097   SD_RESERVED1,
00098   SD_RESERVED2,
00099   SD_RESERVED3,
00100   SD_EVT_GET,
00101   SD_TEMP_GET,
00102   SD_FLASH_ERASE_PAGE,
00103   SD_FLASH_WRITE,
00104   SD_FLASH_PROTECT,
00105   SVC_SOC_LAST
00106 };
00107 
00108 /**@brief Possible values of a ::nrf_mutex_t. */
00109 enum NRF_MUTEX_VALUES
00110 {
00111   NRF_MUTEX_FREE,
00112   NRF_MUTEX_TAKEN
00113 };
00114 
00115 /**@brief Possible values of ::nrf_app_irq_priority_t. */
00116 enum NRF_APP_PRIORITIES
00117 {
00118   NRF_APP_PRIORITY_HIGH = 1,
00119   NRF_APP_PRIORITY_LOW = 3
00120 };
00121 
00122 /**@brief Possible values of ::nrf_power_mode_t. */
00123 enum NRF_POWER_MODES
00124 {
00125   NRF_POWER_MODE_CONSTLAT,  /**< Constant latency mode. See power management in the reference manual. */
00126   NRF_POWER_MODE_LOWPWR     /**< Low power mode. See power management in the reference manual. */
00127 };
00128 
00129 
00130 /**@brief Possible values of ::nrf_power_failure_threshold_t */
00131 enum NRF_POWER_THRESHOLDS
00132 {
00133   NRF_POWER_THRESHOLD_V21,  /**< 2.1 Volts power failure threshold. */
00134   NRF_POWER_THRESHOLD_V23,  /**< 2.3 Volts power failure threshold. */
00135   NRF_POWER_THRESHOLD_V25,  /**< 2.5 Volts power failure threshold. */ 
00136   NRF_POWER_THRESHOLD_V27   /**< 2.7 Volts power failure threshold. */
00137 };
00138 
00139 
00140 /**@brief Possible values of ::nrf_power_dcdc_mode_t. */
00141 enum NRF_POWER_DCDC_MODES
00142 {
00143   NRF_POWER_DCDC_MODE_OFF,          /**< The DCDC is always off. */
00144   NRF_POWER_DCDC_MODE_ON,           /**< The DCDC is always on. */
00145   NRF_POWER_DCDC_MODE_AUTOMATIC     /**< The DCDC is automatically managed. */
00146 };
00147 
00148 /**@brief Possible values of ::nrf_radio_notification_distance_t. */
00149 enum NRF_RADIO_NOTIFICATION_DISTANCES
00150 {
00151   NRF_RADIO_NOTIFICATION_DISTANCE_NONE = 0, /**< The event does not have a notification. */
00152   NRF_RADIO_NOTIFICATION_DISTANCE_800US,    /**< The distance from the active notification to start of radio activity. */
00153   NRF_RADIO_NOTIFICATION_DISTANCE_1740US,   /**< The distance from the active notification to start of radio activity. */
00154   NRF_RADIO_NOTIFICATION_DISTANCE_2680US,   /**< The distance from the active notification to start of radio activity. */
00155   NRF_RADIO_NOTIFICATION_DISTANCE_3620US,   /**< The distance from the active notification to start of radio activity. */
00156   NRF_RADIO_NOTIFICATION_DISTANCE_4560US,   /**< The distance from the active notification to start of radio activity. */
00157   NRF_RADIO_NOTIFICATION_DISTANCE_5500US    /**< The distance from the active notification to start of radio activity. */
00158 };
00159 
00160 
00161 /**@brief Possible values of ::nrf_radio_notification_type_t. */
00162 enum NRF_RADIO_NOTIFICATION_TYPES
00163 {
00164   NRF_RADIO_NOTIFICATION_TYPE_NONE = 0,        /**< The event does not have a radio notification signal. */
00165   NRF_RADIO_NOTIFICATION_TYPE_INT_ON_ACTIVE,   /**< Using interrupt for notification when the radio will be enabled. */
00166   NRF_RADIO_NOTIFICATION_TYPE_INT_ON_INACTIVE, /**< Using interrupt for notification when the radio has been disabled. */
00167   NRF_RADIO_NOTIFICATION_TYPE_INT_ON_BOTH,     /**< Using interrupt for notification both when the radio will be enabled and disabled. */
00168 };
00169 
00170 /**@brief SoC Events. */
00171 enum NRF_SOC_EVTS
00172 {
00173   NRF_EVT_HFCLKSTARTED,                       /**< Event indicating that the HFCLK has started. */
00174   NRF_EVT_POWER_FAILURE_WARNING,              /**< Event indicating that a power failure warning has occurred. */
00175   NRF_EVT_FLASH_OPERATION_SUCCESS,            /**< Event indicating that the ongoing flash operation has completed successfully. */
00176   NRF_EVT_FLASH_OPERATION_ERROR,              /**< Event indicating that the ongoing flash operation has timed out with an error. */
00177   NRF_EVT_RESERVED1,
00178   NRF_EVT_RESERVED2,
00179   NRF_EVT_RESERVED3,
00180   NRF_EVT_RESERVED4,
00181   NRF_EVT_RESERVED5,
00182   NRF_EVT_NUMBER_OF_EVTS
00183 };
00184 
00185 /** @} */
00186 
00187 /** @addtogroup NRF_SOC_TYPES Types
00188  * @{ */
00189 
00190 /**@brief Represents a mutex for use with the nrf_mutex functions.
00191  * @note Accessing the value directly is not safe, use the mutex functions!
00192  */
00193 typedef volatile uint8_t nrf_mutex_t;
00194 
00195 /**@brief The interrupt priorities available to the application while the softdevice is active. */
00196 typedef uint8_t nrf_app_irq_priority_t;
00197 
00198 /**@brief Represents a power mode, used in power mode functions */
00199 typedef uint8_t nrf_power_mode_t;
00200 
00201 /**@brief Represents a power failure threshold value. */
00202 typedef uint8_t nrf_power_failure_threshold_t;
00203 
00204 /**@brief Represents a DCDC mode value. */
00205 typedef uint32_t nrf_power_dcdc_mode_t;
00206 
00207 /**@brief Radio notification distances. */
00208 typedef uint8_t nrf_radio_notification_distance_t;
00209 
00210 /**@brief Radio notification types. */
00211 typedef uint8_t nrf_radio_notification_type_t;
00212 
00213 
00214 /**@brief AES ECB data structure */
00215 typedef struct
00216 {
00217   uint8_t key[SOC_ECB_KEY_LENGTH];                /**< Encryption key. */
00218   uint8_t cleartext[SOC_ECB_CLEARTEXT_LENGTH];    /**< Clear Text data. */
00219   uint8_t ciphertext[SOC_ECB_CIPHERTEXT_LENGTH];  /**< Cipher Text data. */
00220 } nrf_ecb_hal_data_t;
00221 
00222 /** @} */
00223 
00224 /** @addtogroup NRF_SOC_FUNCTIONS Functions
00225  * @{ */
00226 
00227 /**@brief Initialize a mutex.
00228  *
00229  * @param[in] p_mutex Pointer to the mutex to initialize.
00230  *
00231  * @retval ::NRF_SUCCESS
00232  */
00233 SVCALL(SD_MUTEX_NEW, uint32_t, sd_mutex_new(nrf_mutex_t * p_mutex));
00234 
00235 /**@brief Attempt to acquire a mutex.
00236  *
00237  * @param[in] p_mutex Pointer to the mutex to acquire.
00238  *
00239  * @retval ::NRF_SUCCESS The mutex was successfully acquired.
00240  * @retval ::NRF_ERROR_SOC_MUTEX_ALREADY_TAKEN The mutex could not be acquired.
00241  */
00242 SVCALL(SD_MUTEX_ACQUIRE, uint32_t, sd_mutex_acquire(nrf_mutex_t * p_mutex));
00243 
00244 /**@brief Release a mutex.
00245  *
00246  * @param[in] p_mutex Pointer to the mutex to release.
00247  *
00248  * @retval ::NRF_SUCCESS
00249  */
00250 SVCALL(SD_MUTEX_RELEASE, uint32_t, sd_mutex_release(nrf_mutex_t * p_mutex));
00251 
00252 /**@brief Enable External Interrupt.
00253  * @note Corresponds to NVIC_EnableIRQ in CMSIS.
00254  *
00255  * @pre{IRQn is valid and not reserved by the stack}
00256  *
00257  * @param[in] IRQn See the NVIC_EnableIRQ documentation in CMSIS.
00258  *
00259  * @retval ::NRF_SUCCESS The interrupt was enabled.
00260  * @retval ::NRF_ERROR_SOC_NVIC_INTERRUPT_NOT_AVAILABLE The interrupt is not available for the application.
00261  * @retval ::NRF_ERROR_SOC_NVIC_INTERRUPT_PRIORITY_NOT_ALLOWED The interrupt has a priority not available for the application.
00262  */
00263 SVCALL(SD_NVIC_ENABLEIRQ, uint32_t, sd_nvic_EnableIRQ(IRQn_Type IRQn));
00264 
00265 /**@brief  Disable External Interrupt.
00266  * @note Corresponds to NVIC_DisableIRQ in CMSIS.
00267  *
00268  * @pre{IRQn is valid and not reserved by the stack}
00269  *
00270  * @param[in] IRQn See the NVIC_DisableIRQ documentation in CMSIS
00271  *
00272  * @retval ::NRF_SUCCESS The interrupt was disabled.
00273  * @retval ::NRF_ERROR_SOC_NVIC_INTERRUPT_NOT_AVAILABLE The interrupt is not available for the application.
00274  */
00275 SVCALL(SD_NVIC_DISABLEIRQ, uint32_t, sd_nvic_DisableIRQ(IRQn_Type IRQn));
00276 
00277 /**@brief  Get Pending Interrupt.
00278  * @note Corresponds to NVIC_GetPendingIRQ in CMSIS.
00279  *
00280  * @pre{IRQn is valid and not reserved by the stack}
00281  *
00282  * @param[in]   IRQn          See the NVIC_GetPendingIRQ documentation in CMSIS.
00283  * @param[out]  p_pending_irq Return value from NVIC_GetPendingIRQ.
00284  *
00285  * @retval ::NRF_SUCCESS The interrupt is available for the application.
00286  * @retval ::NRF_ERROR_SOC_NVIC_INTERRUPT_NOT_AVAILABLE IRQn is not available for the application.
00287  */
00288 SVCALL(SD_NVIC_GETPENDINGIRQ, uint32_t, sd_nvic_GetPendingIRQ(IRQn_Type IRQn, uint32_t * p_pending_irq));
00289 
00290 /**@brief  Set Pending Interrupt.
00291  * @note Corresponds to NVIC_SetPendingIRQ in CMSIS.
00292  *
00293  * @pre{IRQn is valid and not reserved by the stack}
00294  *
00295  * @param[in] IRQn See the NVIC_SetPendingIRQ documentation in CMSIS.
00296  *
00297  * @retval ::NRF_SUCCESS The interrupt is set pending.
00298  * @retval ::NRF_ERROR_SOC_NVIC_INTERRUPT_NOT_AVAILABLE IRQn is not available for the application.
00299  */
00300 SVCALL(SD_NVIC_SETPENDINGIRQ, uint32_t, sd_nvic_SetPendingIRQ(IRQn_Type IRQn));
00301 
00302 /**@brief  Clear Pending Interrupt.
00303  * @note Corresponds to NVIC_ClearPendingIRQ in CMSIS.
00304  *
00305  * @pre{IRQn is valid and not reserved by the stack}
00306  *
00307  * @param[in] IRQn See the NVIC_ClearPendingIRQ documentation in CMSIS.
00308  *
00309  * @retval ::NRF_SUCCESS The interrupt pending flag is cleared.
00310  * @retval ::NRF_ERROR_SOC_NVIC_INTERRUPT_NOT_AVAILABLE IRQn is not available for the application.
00311  */
00312 SVCALL(SD_NVIC_CLEARPENDINGIRQ, uint32_t, sd_nvic_ClearPendingIRQ(IRQn_Type IRQn));
00313 
00314 /**@brief Set Interrupt Priority.
00315  * @note Corresponds to NVIC_SetPriority in CMSIS.
00316  *
00317  * @pre{IRQn is valid and not reserved by the stack}
00318  * @pre{priority is valid and not reserved by the stack}
00319  *
00320  * @param[in] IRQn      See the NVIC_SetPriority documentation in CMSIS.
00321  * @param[in] priority  A valid IRQ priority for use by the application.
00322  *
00323  * @retval ::NRF_SUCCESS The interrupt and priority level is available for the application.
00324  * @retval ::NRF_ERROR_SOC_NVIC_INTERRUPT_NOT_AVAILABLE IRQn is not available for the application.
00325  * @retval ::NRF_ERROR_SOC_NVIC_INTERRUPT_PRIORITY_NOT_ALLOWED The interrupt priority is not available for the application.
00326  */
00327 SVCALL(SD_NVIC_SETPRIORITY, uint32_t, sd_nvic_SetPriority(IRQn_Type IRQn, nrf_app_irq_priority_t priority));
00328 
00329 /**@brief Get Interrupt Priority.
00330  * @note Corresponds to NVIC_GetPriority in CMSIS.
00331  *
00332  * @pre{IRQn is valid and not reserved by the stack}
00333  *
00334  * @param[in]  IRQn         See the NVIC_GetPriority documentation in CMSIS.
00335  * @param[out] p_priority   Return value from NVIC_GetPriority.
00336  *
00337  * @retval ::NRF_SUCCESS The interrupt priority is returned in p_priority.
00338  * @retval ::NRF_ERROR_SOC_NVIC_INTERRUPT_NOT_AVAILABLE - IRQn is not available for the application.
00339  */
00340 SVCALL(SD_NVIC_GETPRIORITY, uint32_t, sd_nvic_GetPriority(IRQn_Type IRQn, nrf_app_irq_priority_t * p_priority));
00341 
00342 /**@brief System Reset.
00343  * @note Corresponds to NVIC_SystemReset in CMSIS.
00344  *
00345  * @retval ::NRF_ERROR_SOC_NVIC_SHOULD_NOT_RETURN
00346  */
00347 SVCALL(SD_NVIC_SYSTEMRESET, uint32_t, sd_nvic_SystemReset(void));
00348 
00349 /**@brief Enters critical region.
00350  *
00351  * @post Application interrupts will be disabled.
00352  * @sa sd_nvic_critical_region_exit
00353  *
00354  * @param[out]  p_is_nested_critical_region  1: If in a nested critical region.
00355  *                                           0: Otherwise.
00356  *
00357  * @retval ::NRF_SUCCESS
00358  */
00359 SVCALL(SD_NVIC_CRITICAL_REGION_ENTER, uint32_t, sd_nvic_critical_region_enter(uint8_t * p_is_nested_critical_region));
00360 
00361 /**@brief Exit critical region.
00362  *
00363  * @pre Application has entered a critical region using ::sd_nvic_critical_region_enter.
00364  * @post If not in a nested critical region, the application interrupts will restored to the state before ::sd_nvic_critical_region_enter was called. 
00365  *
00366  * @param[in] is_nested_critical_region If this is set to 1, the critical region won't be exited. @sa sd_nvic_critical_region_enter.
00367  *
00368  * @retval ::NRF_SUCCESS
00369  */
00370 SVCALL(SD_NVIC_CRITICAL_REGION_EXIT, uint32_t, sd_nvic_critical_region_exit(uint8_t is_nested_critical_region));
00371 
00372 /**@brief Query the capacity of the application random pool.
00373  *
00374  * @param[out] p_pool_capacity The capacity of the pool.
00375  *
00376  * @retval ::NRF_SUCCESS
00377  */
00378 SVCALL(SD_RAND_APPLICATION_POOL_CAPACITY, uint32_t, sd_rand_application_pool_capacity_get(uint8_t * p_pool_capacity));
00379 
00380 /**@brief Get number of random bytes available to the application.
00381  *
00382  * @param[out] p_bytes_available The number of bytes currently available in the pool.
00383  *
00384  * @retval ::NRF_SUCCESS
00385  */
00386 SVCALL(SD_RAND_APPLICATION_BYTES_AVAILABLE, uint32_t, sd_rand_application_bytes_available_get(uint8_t * p_bytes_available));
00387 
00388 /**@brief Get random bytes from the application pool.
00389 
00390   @param[out]  p_buff  Pointer to unit8_t buffer for storing the bytes.
00391   @param[in]   length  Number of bytes to take from pool and place in p_buff.
00392 
00393   @retval ::NRF_SUCCESS The requested bytes were written to p_buff.
00394   @retval ::NRF_ERROR_SOC_RAND_NOT_ENOUGH_VALUES No bytes were written to the buffer, because there were not enough bytes available.
00395 */
00396 SVCALL(SD_RAND_APPLICATION_GET_VECTOR, uint32_t, sd_rand_application_vector_get(uint8_t * p_buff, uint8_t length));
00397 
00398 /**@brief Gets the reset reason register. 
00399  *
00400  * @param[out]  p_reset_reason  Contents of the NRF_POWER->RESETREAS register.
00401  *
00402  * @retval ::NRF_SUCCESS
00403  */
00404 SVCALL(SD_POWER_RESET_REASON_GET, uint32_t, sd_power_reset_reason_get(uint32_t * p_reset_reason));
00405 
00406 /**@brief Clears the bits of the reset reason register. 
00407  *
00408  * @param[in] reset_reason_clr_msk Contains the bits to clear from the reset reason register.
00409  *
00410  * @retval ::NRF_SUCCESS
00411  */
00412 SVCALL(SD_POWER_RESET_REASON_CLR, uint32_t, sd_power_reset_reason_clr(uint32_t reset_reason_clr_msk));
00413 
00414 /**@brief Sets the power mode when in CPU sleep.
00415  *
00416  * @param[in] power_mode The power mode to use when in CPU sleep. @sa sd_app_evt_wait
00417  *
00418  * @retval ::NRF_SUCCESS The power mode was set.
00419  * @retval ::NRF_ERROR_SOC_POWER_MODE_UNKNOWN The power mode was unknown.
00420  */
00421 SVCALL(SD_POWER_MODE_SET, uint32_t, sd_power_mode_set(nrf_power_mode_t power_mode));
00422 
00423 /**@brief Puts the chip in System OFF mode. 
00424  *
00425  * @retval ::NRF_ERROR_SOC_POWER_OFF_SHOULD_NOT_RETURN
00426  */
00427 SVCALL(SD_POWER_SYSTEM_OFF, uint32_t, sd_power_system_off(void));
00428 
00429 /**@brief Enables or disables the power-fail comparator.
00430  *
00431  * Enabling this will give a softdevice event (NRF_EVT_POWER_FAILURE_WARNING) when the power failure warning occurs.
00432  * The event can be retrieved with sd_evt_get();
00433  *
00434  * @param[in] pof_enable    True if the power-fail comparator should be enabled, false if it should be disabled.
00435  *
00436  * @retval ::NRF_SUCCESS
00437  */
00438 SVCALL(SD_POWER_POF_ENABLE, uint32_t, sd_power_pof_enable(uint8_t pof_enable));
00439 
00440 /**@brief Sets the power-fail threshold value.
00441  *
00442  * @param[in] threshold The power-fail threshold value to use.
00443  *
00444  * @retval ::NRF_SUCCESS The power failure threshold was set.
00445  * @retval ::NRF_ERROR_SOC_POWER_POF_THRESHOLD_UNKNOWN The power failure threshold is unknown.
00446  */
00447 SVCALL(SD_POWER_POF_THRESHOLD_SET, uint32_t, sd_power_pof_threshold_set(nrf_power_failure_threshold_t threshold));
00448 
00449 /**@brief Sets bits in the NRF_POWER->RAMON register.
00450  *
00451  * @param[in] ramon Contains the bits needed to be set in the NRF_POWER->RAMON register.
00452  *
00453  * @retval ::NRF_SUCCESS
00454  */
00455 SVCALL(SD_POWER_RAMON_SET, uint32_t, sd_power_ramon_set(uint32_t ramon));
00456 
00457 /** @brief Clears bits in the NRF_POWER->RAMON register.
00458  *
00459  * @param ramon Contains the bits needed to be cleared in the NRF_POWER->RAMON register.
00460  *
00461  * @retval ::NRF_SUCCESS
00462  */
00463 SVCALL(SD_POWER_RAMON_CLR, uint32_t, sd_power_ramon_clr(uint32_t ramon));
00464 
00465 /**@brief Get contents of NRF_POWER->RAMON register, indicates power status of ram blocks.
00466  *
00467  * @param[out] p_ramon Content of NRF_POWER->RAMON register.
00468  *
00469  * @retval ::NRF_SUCCESS
00470  */
00471 SVCALL(SD_POWER_RAMON_GET, uint32_t, sd_power_ramon_get(uint32_t * p_ramon));
00472 
00473 /**@brief Set bits in the NRF_POWER->GPREGRET register.
00474  *
00475  * @param[in] gpregret_msk Bits to be set in the GPREGRET register.
00476  *
00477  * @retval ::NRF_SUCCESS
00478  */
00479 SVCALL(SD_POWER_GPREGRET_SET, uint32_t, sd_power_gpregret_set(uint32_t gpregret_msk));
00480 
00481 /**@brief Clear bits in the NRF_POWER->GPREGRET register.
00482  *
00483  * @param[in] gpregret_msk Bits to be clear in the GPREGRET register.
00484  *
00485  * @retval ::NRF_SUCCESS
00486  */
00487 SVCALL(SD_POWER_GPREGRET_CLR, uint32_t, sd_power_gpregret_clr(uint32_t gpregret_msk));
00488 
00489 /**@brief Get contents of the NRF_POWER->GPREGRET register.
00490  *
00491  * @param[out] p_gpregret Contents of the GPREGRET register.
00492  *
00493  * @retval ::NRF_SUCCESS
00494  */
00495 SVCALL(SD_POWER_GPREGRET_GET, uint32_t, sd_power_gpregret_get(uint32_t *p_gpregret));
00496 
00497 /**@brief Sets the DCDC mode.
00498  *
00499  * Depending on the internal state of the SoftDevice, the mode change may not happen immediately.
00500  * The DCDC mode switch will be blocked when occurring in close proximity to radio transmissions. When
00501  * the radio transmission is done, the last mode will be used.
00502  *
00503  * @param[in] dcdc_mode The mode of the DCDC.
00504  *
00505  * @retval ::NRF_SUCCESS
00506  * @retval ::NRF_ERROR_INVALID_PARAM The DCDC mode is invalid.
00507  */
00508 SVCALL(SD_POWER_DCDC_MODE_SET, uint32_t, sd_power_dcdc_mode_set(nrf_power_dcdc_mode_t dcdc_mode));
00509 
00510 /**@brief Request the high frequency crystal oscillator.
00511  *
00512  * Will start the high frequency crystal oscillator, the startup time of the crystal varies
00513  * and the ::sd_clock_hfclk_is_running function can be polled to check if it has started.
00514  *
00515  * @see sd_clock_hfclk_is_running
00516  * @see sd_clock_hfclk_release
00517  *
00518  * @retval ::NRF_SUCCESS
00519  */
00520 SVCALL(SD_CLOCK_HFCLK_REQUEST, uint32_t, sd_clock_hfclk_request(void));
00521 
00522 /**@brief Releases the high frequency crystal oscillator.
00523  *
00524  * Will stop the high frequency crystal oscillator, this happens immediately.
00525  *
00526  * @see sd_clock_hfclk_is_running
00527  * @see sd_clock_hfclk_request
00528  *
00529  * @retval ::NRF_SUCCESS
00530  */
00531 SVCALL(SD_CLOCK_HFCLK_RELEASE, uint32_t, sd_clock_hfclk_release(void));
00532 
00533 /**@brief Checks if the high frequency crystal oscillator is running.
00534  *
00535  * @see sd_clock_hfclk_request
00536  * @see sd_clock_hfclk_release
00537  *
00538  * @param[out] p_is_running 1 if the external crystal oscillator is running, 0 if not.
00539  *
00540  * @retval ::NRF_SUCCESS
00541  */
00542 SVCALL(SD_CLOCK_HFCLK_IS_RUNNING, uint32_t, sd_clock_hfclk_is_running(uint32_t * p_is_running));
00543 
00544 /**@brief Waits for an application event.
00545  * 
00546  * An application event is either an application interrupt or a pended interrupt when the
00547  * interrupt is disabled. When the interrupt is enabled it will be taken immediately since
00548  * this function will wait in thread mode, then the execution will return in the application's
00549  * main thread. When an interrupt is disabled and gets pended it will return to the application's 
00550  * thread main. The application must ensure that the pended flag is cleared using 
00551  * ::sd_nvic_ClearPendingIRQ in order to sleep using this function. This is only necessary for
00552  * disabled interrupts, as the interrupt handler will clear the pending flag automatically for
00553  * enabled interrupts.
00554  *
00555  * In order to wake up from disabled interrupts, the SEVONPEND flag has to be set in the Cortex-M0
00556  * System Control Register (SCR). @sa CMSIS_SCB
00557  *
00558  * @note If an application interrupt has happened since the last time sd_app_evt_wait was
00559  *       called this function will return immediately and not go to sleep. This is to avoid race
00560  *       conditions that can occur when a flag is updated in the interrupt handler and processed
00561  *       in the main loop.
00562  *
00563  * @post An application interrupt has happened or a interrupt pending flag is set.
00564  *
00565  * @retval ::NRF_SUCCESS
00566  */
00567 SVCALL(SD_APP_EVT_WAIT, uint32_t, sd_app_evt_wait(void));
00568 
00569 /**@brief Get PPI channel enable register contents.
00570  *
00571  * @param[out] p_channel_enable The contents of the PPI CHEN register.
00572  *
00573  * @retval ::NRF_SUCCESS
00574  */
00575 SVCALL(SD_PPI_CHANNEL_ENABLE_GET, uint32_t, sd_ppi_channel_enable_get(uint32_t * p_channel_enable));
00576 
00577 /**@brief Set PPI channel enable register.
00578  *
00579  * @param[in] channel_enable_set_msk Mask containing the bits to set in the PPI CHEN register.
00580  *
00581  * @retval ::NRF_SUCCESS
00582  */
00583 SVCALL(SD_PPI_CHANNEL_ENABLE_SET, uint32_t, sd_ppi_channel_enable_set(uint32_t channel_enable_set_msk));
00584 
00585 /**@brief Clear PPI channel enable register.
00586  *
00587  * @param[in] channel_enable_clr_msk Mask containing the bits to clear in the PPI CHEN register.
00588  *
00589  * @retval ::NRF_SUCCESS
00590  */
00591 SVCALL(SD_PPI_CHANNEL_ENABLE_CLR, uint32_t, sd_ppi_channel_enable_clr(uint32_t channel_enable_clr_msk));
00592 
00593 /**@brief Assign endpoints to a PPI channel.
00594  *
00595  * @param[in] channel_num Number of the PPI channel to assign.
00596  * @param[in] evt_endpoint Event endpoint of the PPI channel.
00597  * @param[in] task_endpoint Task endpoint of the PPI channel.
00598  *
00599  * @retval ::NRF_ERROR_SOC_PPI_INVALID_CHANNEL The channel number is invalid.
00600  * @retval ::NRF_SUCCESS
00601  */
00602 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));
00603 
00604 /**@brief Task to enable a channel group.
00605  *
00606  * @param[in] group_num Number of the channel group.
00607  *
00608  * @retval ::NRF_ERROR_SOC_PPI_INVALID_GROUP The group number is invalid
00609  * @retval ::NRF_SUCCESS
00610  */
00611 SVCALL(SD_PPI_GROUP_TASK_ENABLE, uint32_t, sd_ppi_group_task_enable(uint8_t group_num));
00612 
00613 /**@brief Task to disable a channel group.
00614  *
00615  * @param[in] group_num Number of the PPI group.
00616  *
00617  * @retval ::NRF_ERROR_SOC_PPI_INVALID_GROUP The group number is invalid.
00618  * @retval ::NRF_SUCCESS
00619  */
00620 SVCALL(SD_PPI_GROUP_TASK_DISABLE, uint32_t, sd_ppi_group_task_disable(uint8_t group_num));
00621 
00622 /**@brief Assign PPI channels to a channel group.
00623  *
00624  * @param[in] group_num Number of the channel group.
00625  * @param[in] channel_msk Mask of the channels to assign to the group.
00626  *
00627  * @retval ::NRF_ERROR_SOC_PPI_INVALID_GROUP The group number is invalid.
00628  * @retval ::NRF_SUCCESS
00629  */
00630 SVCALL(SD_PPI_GROUP_ASSIGN, uint32_t, sd_ppi_group_assign(uint8_t group_num, uint32_t channel_msk));
00631 
00632 /**@brief Gets the PPI channels of a channel group.
00633  *
00634  * @param[in]   group_num Number of the channel group.
00635  * @param[out]  p_channel_msk Mask of the channels assigned to the group.
00636  *
00637  * @retval ::NRF_ERROR_SOC_PPI_INVALID_GROUP The group number is invalid.
00638  * @retval ::NRF_SUCCESS
00639  */
00640 SVCALL(SD_PPI_GROUP_GET, uint32_t, sd_ppi_group_get(uint8_t group_num, uint32_t * p_channel_msk));
00641 
00642 /**@brief Configures the Radio Notification signal.
00643  *
00644  * @note
00645  *      - The notification signal latency depends on the interrupt priority settings of SWI used
00646  *        for notification signal.
00647  *      - In the period between the ACTIVE signal and the start of the Radio Event, the SoftDevice
00648  *        will interrupt the application to do Radio Event preparation.
00649  *      - Using the Radio Notification feature may limit the bandwidth, as the SoftDevice may have
00650  *        to shorten the connection events to have time for the Radio Notification signals.
00651  *
00652  * @param[in]  type      Type of notification signal.
00653  *                       @ref NRF_RADIO_NOTIFICATION_TYPE_NONE shall be used to turn off radio
00654  *                       notification. Using @ref NRF_RADIO_NOTIFICATION_DISTANCE_NONE is
00655  *                       recommended (but not required) to be used with
00656  *                       @ref NRF_RADIO_NOTIFICATION_TYPE_NONE.
00657  *
00658  * @param[in]  distance  Distance between the notification signal and start of radio activity.
00659  *                       This parameter is ignored when @ref NRF_RADIO_NOTIFICATION_TYPE_NONE or 
00660  *                       @ref NRF_RADIO_NOTIFICATION_TYPE_INT_ON_INACTIVE is used.
00661  *
00662  * @retval ::NRF_ERROR_INVALID_PARAM The group number is invalid.
00663  * @retval ::NRF_SUCCESS
00664  */
00665 SVCALL(SD_RADIO_NOTIFICATION_CFG_SET, uint32_t, sd_radio_notification_cfg_set(nrf_radio_notification_type_t type, nrf_radio_notification_distance_t distance));
00666 
00667 /**@brief Encrypts a block according to the specified parameters.
00668  *
00669  * 128-bit AES encryption.
00670  *
00671  * @param[in, out] p_ecb_data Pointer to the ECB parameters' struct (two input
00672  *                            parameters and one output parameter).
00673  *
00674  * @retval ::NRF_SUCCESS
00675  */
00676 SVCALL(SD_ECB_BLOCK_ENCRYPT, uint32_t, sd_ecb_block_encrypt(nrf_ecb_hal_data_t * p_ecb_data));
00677 
00678 /**@brief Gets any pending events generated by the SoC API.
00679  *
00680  * The application should keep calling this function to get events, until ::NRF_ERROR_NOT_FOUND is returned.
00681  *
00682  * @param[out] p_evt_id Set to one of the values in @ref NRF_SOC_EVTS, if any events are pending.
00683  *
00684  * @retval ::NRF_SUCCESS An event was pending. The event id is written in the p_evt_id parameter.
00685  * @retval ::NRF_ERROR_NOT_FOUND No pending events. 
00686  */
00687 SVCALL(SD_EVT_GET, uint32_t, sd_evt_get(uint32_t * p_evt_id));
00688 
00689 /**@brief Get the temperature measured on the chip
00690  * 
00691  * This function will block until the temperature measurement is done.
00692  * It takes around 50us from call to return.
00693  *
00694  * @note Pan #28 in PAN-028 v 1.6 "Negative measured values are not represented correctly" is corrected by this function.
00695  *
00696  * @param[out] p_temp Result of temperature measurement. Die temperature in 0.25 degrees celsius.
00697  *
00698  * @retval ::NRF_SUCCESS A temperature measurement was done, and the temperature was written to temp
00699  */
00700 SVCALL(SD_TEMP_GET, uint32_t, sd_temp_get(int32_t * p_temp));
00701 
00702 /**@brief Flash Write
00703  *
00704  * Commands to write a buffer to flash
00705  *
00706  * This call initiates the flash access command, and its completion will be communicated to the
00707  * application with exactly one of the following events:
00708  *      - NRF_EVT_FLASH_OPERATION_SUCCESS - The command was successfully completed.
00709  *      - NRF_EVT_FLASH_OPERATION_ERROR   - The command could not be started.
00710  *
00711  * @note
00712  *      - This call takes control over the radio and the CPU during flash erase and write to make sure that
00713  *        they will not interfere with the flash access. This means that all interrupts will be blocked
00714  *        for a predictable time (depending on the NVMC specification in nRF51 Series Reference Manual
00715  *        and the command parameters).
00716  *
00717  *
00718  * @param[in]  p_dst Pointer to start of flash location to be written.
00719  * @param[in]  p_src Pointer to buffer with data to be written
00720  * @param[in]  size  Number of 32-bit words to write. Maximum size is 256 32bit words.
00721  *
00722  * @retval ::NRF_ERROR_INVALID_ADDR   Tried to write to a non existing flash address, or p_dst or p_src was unaligned.
00723  * @retval ::NRF_ERROR_BUSY           The previous command has not yet completed.
00724  * @retval ::NRF_ERROR_INVALID_LENGTH Size was 0, or more than 256 words.
00725  * @retval ::NRF_ERROR_FORBIDDEN      Tried to write to or read from protected location.
00726  * @retval ::NRF_SUCCESS              The command was accepted.
00727  */
00728 SVCALL(SD_FLASH_WRITE, uint32_t, sd_flash_write(uint32_t * const p_dst, uint32_t const * const p_src, uint32_t size));
00729 
00730 
00731 /**@brief Flash Erase page
00732  *
00733  * Commands to erase a flash page
00734  *
00735  * This call initiates the flash access command, and its completion will be communicated to the
00736  * application with exactly one of the following events:
00737  *      - NRF_EVT_FLASH_OPERATION_SUCCESS - The command was successfully completed.
00738  *      - NRF_EVT_FLASH_OPERATION_ERROR   - The command could not be started.
00739  *
00740  * @note
00741  *      - This call takes control over the radio and the CPU during flash erase and write to make sure that
00742  *        they will not interfere with the flash access. This means that all interrupts will be blocked
00743  *        for a predictable time (depending on the NVMC specification in nRF51 Series Reference Manual
00744  *        and the command parameters).
00745  *
00746  *
00747  * @param[in]  page_number Pagenumber of the page to erase
00748  * @retval ::NRF_ERROR_INTERNAL      If a new session could not be opened due to an internal error.
00749  * @retval ::NRF_ERROR_INVALID_ADDR  Tried to erase to a non existing flash page.
00750  * @retval ::NRF_ERROR_BUSY          The previous command has not yet completed.
00751  * @retval ::NRF_ERROR_FORBIDDEN     Tried to erase a protected page.
00752  * @retval ::NRF_SUCCESS             The command was accepted.
00753  */
00754 SVCALL(SD_FLASH_ERASE_PAGE, uint32_t, sd_flash_page_erase(uint32_t page_number));
00755 
00756 
00757 /**@brief Flash Protection set
00758  *
00759  * Commands to set the flash protection registers PROTENSETx
00760  *
00761  * @note To read the values in PROTENSETx you can read them directly. They are only write-protected.
00762  *
00763  * @param[in]  protenset0 Value to be written to PROTENSET0
00764  * @param[in]  protenset1 Value to be written to PROTENSET1
00765  *
00766  * @retval ::NRF_ERROR_FORBIDDEN Tried to protect the SoftDevice
00767  * @retval ::NRF_SUCCESS Values successfully written to PROTENSETx
00768  */
00769 SVCALL(SD_FLASH_PROTECT, uint32_t, sd_flash_protect(uint32_t protenset0, uint32_t protenset1));
00770 
00771 
00772 /** @} */
00773 
00774 #endif // NRF_SOC_H__
00775 
00776 /**
00777   @}
00778  */