MCUXpresso SDK API Reference Manual  Rev. 0
NXP Semiconductors
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Secure Non-Volatile Storage High-Power

Overview

The MCUXpresso SDK provides a Peripheral driver for the Secure Non-Volatile Storage High-Power(SNVS-HP) module.

The SNVS_HP is in the chip's power-supply domain and thus receives the power along with the rest of the chip. The SNVS_HP provides an interface between the SNVS_LP and the rest of the system; there is no way to access the SNVS_LP registers except through the SNVS_HP. For access to the SNVS_LP registers, the SNVS_HP must be powered up. It uses a register access permission policy to determine whether the access to the particular registers is permitted.

SNVS_HP Driver Initialization and Configuration

SNVS_HP Driver Examples

Data Structures

struct  snvs_hp_rtc_datetime_t
 Structure is used to hold the date and time. More...
 
struct  snvs_hp_rtc_config_t
 SNVS config structure. More...
 

Macros

#define SNVS_MAKE_HP_SV_FLAG(x)   (1U << (SNVS_HPSVSR_SV0_SHIFT + (x)))
 Macro to make security violation flag. More...
 

Enumerations

enum  snvs_hp_interrupts_t {
  kSNVS_RTC_AlarmInterrupt = SNVS_HPCR_HPTA_EN_MASK,
  kSNVS_RTC_PeriodicInterrupt = SNVS_HPCR_PI_EN_MASK
}
 List of SNVS interrupts. More...
 
enum  snvs_hp_status_flags_t {
  kSNVS_RTC_AlarmInterruptFlag = SNVS_HPSR_HPTA_MASK,
  kSNVS_RTC_PeriodicInterruptFlag = SNVS_HPSR_PI_MASK,
  kSNVS_ZMK_ZeroFlag = (int)SNVS_HPSR_ZMK_ZERO_MASK,
  kSNVS_OTPMK_ZeroFlag = SNVS_HPSR_OTPMK_ZERO_MASK
}
 List of SNVS flags. More...
 
enum  snvs_hp_sv_status_flags_t {
  kSNVS_LP_ViolationFlag = SNVS_HPSVSR_SW_LPSV_MASK,
  kSNVS_ZMK_EccFailFlag = SNVS_HPSVSR_ZMK_ECC_FAIL_MASK,
  kSNVS_LP_SoftwareViolationFlag = SNVS_HPSVSR_SW_LPSV_MASK,
  kSNVS_FatalSoftwareViolationFlag = SNVS_HPSVSR_SW_FSV_MASK,
  kSNVS_SoftwareViolationFlag = SNVS_HPSVSR_SW_SV_MASK,
  kSNVS_Violation0Flag = SNVS_HPSVSR_SV0_MASK,
  kSNVS_Violation1Flag = SNVS_HPSVSR_SV1_MASK,
  kSNVS_Violation2Flag = SNVS_HPSVSR_SV2_MASK,
  kSNVS_Violation3Flag = SNVS_HPSVSR_SV3_MASK,
  kSNVS_Violation4Flag = SNVS_HPSVSR_SV4_MASK,
  kSNVS_Violation5Flag = SNVS_HPSVSR_SV5_MASK
}
 List of SNVS security violation flags. More...
 
enum  snvs_hp_ssm_state_t {
  kSNVS_SSMInit = 0x00,
  kSNVS_SSMHardFail = 0x01,
  kSNVS_SSMSoftFail = 0x03,
  kSNVS_SSMInitInter = 0x08,
  kSNVS_SSMCheck = 0x09,
  kSNVS_SSMNonSecure = 0x0B,
  kSNVS_SSMTrusted = 0x0D,
  kSNVS_SSMSecure = 0x0F
}
 

Functions

static void SNVS_HP_EnableMasterKeySelection (SNVS_Type *base, bool enable)
 Enable or disable master key selection. More...
 
static void SNVS_HP_ProgramZeroizableMasterKey (SNVS_Type *base)
 Trigger to program Zeroizable Master Key. More...
 
static void SNVS_HP_ChangeSSMState (SNVS_Type *base)
 Trigger SSM State Transition. More...
 
static void SNVS_HP_SetSoftwareFatalSecurityViolation (SNVS_Type *base)
 Trigger Software Fatal Security Violation. More...
 
static void SNVS_HP_SetSoftwareSecurityViolation (SNVS_Type *base)
 Trigger Software Security Violation. More...
 
static snvs_hp_ssm_state_t SNVS_HP_GetSSMState (SNVS_Type *base)
 Get current SSM State. More...
 
static void SNVS_HP_ResetLP (SNVS_Type *base)
 Reset the SNVS LP section. More...
 
static uint32_t SNVS_HP_GetStatusFlags (SNVS_Type *base)
 Get the SNVS HP status flags. More...
 
static void SNVS_HP_ClearStatusFlags (SNVS_Type *base, uint32_t mask)
 Clear the SNVS HP status flags. More...
 
static uint32_t SNVS_HP_GetSecurityViolationStatusFlags (SNVS_Type *base)
 Get the SNVS HP security violation status flags. More...
 
static void SNVS_HP_ClearSecurityViolationStatusFlags (SNVS_Type *base, uint32_t mask)
 Clear the SNVS HP security violation status flags. More...
 

Driver version

#define FSL_SNVS_HP_DRIVER_VERSION   (MAKE_VERSION(2, 1, 4))
 Version 2.1.4.
 

Initialization and deinitialization

void SNVS_HP_Init (SNVS_Type *base)
 Initialize the SNVS. More...
 
void SNVS_HP_Deinit (SNVS_Type *base)
 Deinitialize the SNVS. More...
 
void SNVS_HP_RTC_Init (SNVS_Type *base, const snvs_hp_rtc_config_t *config)
 Ungates the SNVS clock and configures the peripheral for basic operation. More...
 
void SNVS_HP_RTC_Deinit (SNVS_Type *base)
 Stops the RTC and SRTC timers. More...
 
void SNVS_HP_RTC_GetDefaultConfig (snvs_hp_rtc_config_t *config)
 Fills in the SNVS config struct with the default settings. More...
 

Non secure RTC current Time & Alarm

status_t SNVS_HP_RTC_SetDatetime (SNVS_Type *base, const snvs_hp_rtc_datetime_t *datetime)
 Sets the SNVS RTC date and time according to the given time structure. More...
 
void SNVS_HP_RTC_GetDatetime (SNVS_Type *base, snvs_hp_rtc_datetime_t *datetime)
 Gets the SNVS RTC time and stores it in the given time structure. More...
 
status_t SNVS_HP_RTC_SetAlarm (SNVS_Type *base, const snvs_hp_rtc_datetime_t *alarmTime)
 Sets the SNVS RTC alarm time. More...
 
void SNVS_HP_RTC_GetAlarm (SNVS_Type *base, snvs_hp_rtc_datetime_t *datetime)
 Returns the SNVS RTC alarm time. More...
 
void SNVS_HP_RTC_TimeSynchronize (SNVS_Type *base)
 The function synchronizes RTC counter value with SRTC. More...
 

Interrupt Interface

static void SNVS_HP_RTC_EnableInterrupts (SNVS_Type *base, uint32_t mask)
 Enables the selected SNVS interrupts. More...
 
static void SNVS_HP_RTC_DisableInterrupts (SNVS_Type *base, uint32_t mask)
 Disables the selected SNVS interrupts. More...
 
uint32_t SNVS_HP_RTC_GetEnabledInterrupts (SNVS_Type *base)
 Gets the enabled SNVS interrupts. More...
 

Status Interface

uint32_t SNVS_HP_RTC_GetStatusFlags (SNVS_Type *base)
 Gets the SNVS status flags. More...
 
static void SNVS_HP_RTC_ClearStatusFlags (SNVS_Type *base, uint32_t mask)
 Clears the SNVS status flags. More...
 

Timer Start and Stop

static void SNVS_HP_RTC_StartTimer (SNVS_Type *base)
 Starts the SNVS RTC time counter. More...
 
static void SNVS_HP_RTC_StopTimer (SNVS_Type *base)
 Stops the SNVS RTC time counter. More...
 

High Assurance Counter (HAC)

static void SNVS_HP_EnableHighAssuranceCounter (SNVS_Type *base, bool enable)
 Enable or disable the High Assurance Counter (HAC) More...
 
static void SNVS_HP_StartHighAssuranceCounter (SNVS_Type *base, bool start)
 Start or stop the High Assurance Counter (HAC) More...
 
static void SNVS_HP_SetHighAssuranceCounterInitialValue (SNVS_Type *base, uint32_t value)
 Set the High Assurance Counter (HAC) initialize value. More...
 
static void SNVS_HP_LoadHighAssuranceCounter (SNVS_Type *base)
 Load the High Assurance Counter (HAC) More...
 
static uint32_t SNVS_HP_GetHighAssuranceCounter (SNVS_Type *base)
 Get the current High Assurance Counter (HAC) value. More...
 
static void SNVS_HP_ClearHighAssuranceCounter (SNVS_Type *base)
 Clear the High Assurance Counter (HAC) More...
 
static void SNVS_HP_LockHighAssuranceCounter (SNVS_Type *base)
 Lock the High Assurance Counter (HAC) More...
 

Data Structure Documentation

struct snvs_hp_rtc_datetime_t

Data Fields

uint16_t year
 Range from 1970 to 2099. More...
 
uint8_t month
 Range from 1 to 12. More...
 
uint8_t day
 Range from 1 to 31 (depending on month). More...
 
uint8_t hour
 Range from 0 to 23. More...
 
uint8_t minute
 Range from 0 to 59. More...
 
uint8_t second
 Range from 0 to 59. More...
 

Field Documentation

uint16_t snvs_hp_rtc_datetime_t::year
uint8_t snvs_hp_rtc_datetime_t::month
uint8_t snvs_hp_rtc_datetime_t::day
uint8_t snvs_hp_rtc_datetime_t::hour
uint8_t snvs_hp_rtc_datetime_t::minute
uint8_t snvs_hp_rtc_datetime_t::second
struct snvs_hp_rtc_config_t

This structure holds the configuration settings for the SNVS peripheral. To initialize this structure to reasonable defaults, call the SNVS_GetDefaultConfig() function and pass a pointer to your config structure instance.

The config struct can be made const so it resides in flash

Data Fields

bool rtcCalEnable
 true: RTC calibration mechanism is enabled; false:No calibration is used
 
uint32_t rtcCalValue
 Defines signed calibration value for nonsecure RTC; This is a 5-bit 2's complement value, range from -16 to +15.
 
uint32_t periodicInterruptFreq
 Defines frequency of the periodic interrupt; Range from 0 to 15.
 

Macro Definition Documentation

#define SNVS_MAKE_HP_SV_FLAG (   x)    (1U << (SNVS_HPSVSR_SV0_SHIFT + (x)))

Macro help to make security violation flag kSNVS_Violation0Flag to kSNVS_Violation5Flag, For example, SNVS_MAKE_HP_SV_FLAG(0) is kSNVS_Violation0Flag.

Enumeration Type Documentation

Enumerator
kSNVS_RTC_AlarmInterrupt 

RTC time alarm.

kSNVS_RTC_PeriodicInterrupt 

RTC periodic interrupt.

Enumerator
kSNVS_RTC_AlarmInterruptFlag 

RTC time alarm flag.

kSNVS_RTC_PeriodicInterruptFlag 

RTC periodic interrupt flag.

kSNVS_ZMK_ZeroFlag 

The ZMK is zero.

kSNVS_OTPMK_ZeroFlag 

The OTPMK is zero.

Enumerator
kSNVS_LP_ViolationFlag 

Low Power section Security Violation.

kSNVS_ZMK_EccFailFlag 

Zeroizable Master Key Error Correcting Code Check Failure.

kSNVS_LP_SoftwareViolationFlag 

LP Software Security Violation.

kSNVS_FatalSoftwareViolationFlag 

Software Fatal Security Violation.

kSNVS_SoftwareViolationFlag 

Software Security Violation.

kSNVS_Violation0Flag 

Security Violation 0.

kSNVS_Violation1Flag 

Security Violation 1.

kSNVS_Violation2Flag 

Security Violation 2.

kSNVS_Violation3Flag 

Security Violation 3.

kSNVS_Violation4Flag 

Security Violation 4.

kSNVS_Violation5Flag 

Security Violation 5.

Enumerator
kSNVS_SSMInit 

Init.

kSNVS_SSMHardFail 

Hard Fail.

kSNVS_SSMSoftFail 

Soft Fail.

kSNVS_SSMInitInter 

Init Intermediate (transition state between Init and Check)

kSNVS_SSMCheck 

Check.

kSNVS_SSMNonSecure 

Non-Secure.

kSNVS_SSMTrusted 

Trusted.

kSNVS_SSMSecure 

Secure.

Function Documentation

void SNVS_HP_Init ( SNVS_Type *  base)
Note
This API should be called at the beginning of the application using the SNVS driver.
Parameters
baseSNVS peripheral base address
void SNVS_HP_Deinit ( SNVS_Type *  base)
Parameters
baseSNVS peripheral base address
void SNVS_HP_RTC_Init ( SNVS_Type *  base,
const snvs_hp_rtc_config_t config 
)
Note
This API should be called at the beginning of the application using the SNVS driver.
Parameters
baseSNVS peripheral base address
configPointer to the user's SNVS configuration structure.
void SNVS_HP_RTC_Deinit ( SNVS_Type *  base)
Parameters
baseSNVS peripheral base address
void SNVS_HP_RTC_GetDefaultConfig ( snvs_hp_rtc_config_t config)

The default values are as follows.

* config->rtccalenable = false;
* config->rtccalvalue = 0U;
* config->PIFreq = 0U;
*
Parameters
configPointer to the user's SNVS configuration structure.
status_t SNVS_HP_RTC_SetDatetime ( SNVS_Type *  base,
const snvs_hp_rtc_datetime_t datetime 
)
Parameters
baseSNVS peripheral base address
datetimePointer to the structure where the date and time details are stored.
Returns
kStatus_Success: Success in setting the time and starting the SNVS RTC kStatus_InvalidArgument: Error because the datetime format is incorrect
void SNVS_HP_RTC_GetDatetime ( SNVS_Type *  base,
snvs_hp_rtc_datetime_t datetime 
)
Parameters
baseSNVS peripheral base address
datetimePointer to the structure where the date and time details are stored.
status_t SNVS_HP_RTC_SetAlarm ( SNVS_Type *  base,
const snvs_hp_rtc_datetime_t alarmTime 
)

The function sets the RTC alarm. It also checks whether the specified alarm time is greater than the present time. If not, the function does not set the alarm and returns an error.

Parameters
baseSNVS peripheral base address
alarmTimePointer to the structure where the alarm time is stored.
Returns
kStatus_Success: success in setting the SNVS RTC alarm kStatus_InvalidArgument: Error because the alarm datetime format is incorrect kStatus_Fail: Error because the alarm time has already passed
void SNVS_HP_RTC_GetAlarm ( SNVS_Type *  base,
snvs_hp_rtc_datetime_t datetime 
)
Parameters
baseSNVS peripheral base address
datetimePointer to the structure where the alarm date and time details are stored.
void SNVS_HP_RTC_TimeSynchronize ( SNVS_Type *  base)
Parameters
baseSNVS peripheral base address
static void SNVS_HP_RTC_EnableInterrupts ( SNVS_Type *  base,
uint32_t  mask 
)
inlinestatic
Parameters
baseSNVS peripheral base address
maskThe interrupts to enable. This is a logical OR of members of the enumeration ::snvs_interrupt_enable_t
static void SNVS_HP_RTC_DisableInterrupts ( SNVS_Type *  base,
uint32_t  mask 
)
inlinestatic
Parameters
baseSNVS peripheral base address
maskThe interrupts to enable. This is a logical OR of members of the enumeration ::snvs_interrupt_enable_t
uint32_t SNVS_HP_RTC_GetEnabledInterrupts ( SNVS_Type *  base)
Parameters
baseSNVS peripheral base address
Returns
The enabled interrupts. This is the logical OR of members of the enumeration ::snvs_interrupt_enable_t
uint32_t SNVS_HP_RTC_GetStatusFlags ( SNVS_Type *  base)
Parameters
baseSNVS peripheral base address
Returns
The status flags. This is the logical OR of members of the enumeration ::snvs_status_flags_t
static void SNVS_HP_RTC_ClearStatusFlags ( SNVS_Type *  base,
uint32_t  mask 
)
inlinestatic
Parameters
baseSNVS peripheral base address
maskThe status flags to clear. This is a logical OR of members of the enumeration ::snvs_status_flags_t
static void SNVS_HP_RTC_StartTimer ( SNVS_Type *  base)
inlinestatic
Parameters
baseSNVS peripheral base address
static void SNVS_HP_RTC_StopTimer ( SNVS_Type *  base)
inlinestatic
Parameters
baseSNVS peripheral base address
static void SNVS_HP_EnableMasterKeySelection ( SNVS_Type *  base,
bool  enable 
)
inlinestatic
Parameters
baseSNVS peripheral base address
enablePass true to enable, false to disable.
static void SNVS_HP_ProgramZeroizableMasterKey ( SNVS_Type *  base)
inlinestatic
Parameters
baseSNVS peripheral base address
enablePass true to enable, false to disable.
static void SNVS_HP_ChangeSSMState ( SNVS_Type *  base)
inlinestatic

Trigger state transition of the system security monitor (SSM). It results only the following transitions of the SSM:

  • Check State -> Non-Secure (when Non-Secure Boot and not in Fab Configuration)
  • Check State –> Trusted (when Secure Boot or in Fab Configuration )
  • Trusted State –> Secure
  • Secure State –> Trusted
  • Soft Fail –> Non-Secure
Parameters
baseSNVS peripheral base address
static void SNVS_HP_SetSoftwareFatalSecurityViolation ( SNVS_Type *  base)
inlinestatic

The result SSM state transition is:

  • Check State -> Soft Fail
  • Non-Secure State -> Soft Fail
  • Trusted State -> Soft Fail
  • Secure State -> Soft Fail
Parameters
baseSNVS peripheral base address
static void SNVS_HP_SetSoftwareSecurityViolation ( SNVS_Type *  base)
inlinestatic

The result SSM state transition is:

  • Check -> Non-Secure
  • Trusted -> Soft Fail
  • Secure -> Soft Fail
Parameters
baseSNVS peripheral base address
static snvs_hp_ssm_state_t SNVS_HP_GetSSMState ( SNVS_Type *  base)
inlinestatic
Parameters
baseSNVS peripheral base address
Returns
Current SSM state
static void SNVS_HP_ResetLP ( SNVS_Type *  base)
inlinestatic

Reset the LP section except SRTC and Time alarm.

Parameters
baseSNVS peripheral base address
static void SNVS_HP_EnableHighAssuranceCounter ( SNVS_Type *  base,
bool  enable 
)
inlinestatic
Parameters
baseSNVS peripheral base address
enablePass true to enable, false to disable.
static void SNVS_HP_StartHighAssuranceCounter ( SNVS_Type *  base,
bool  start 
)
inlinestatic
Parameters
baseSNVS peripheral base address
startPass true to start, false to stop.
static void SNVS_HP_SetHighAssuranceCounterInitialValue ( SNVS_Type *  base,
uint32_t  value 
)
inlinestatic
Parameters
baseSNVS peripheral base address
valueThe initial value to set.
static void SNVS_HP_LoadHighAssuranceCounter ( SNVS_Type *  base)
inlinestatic

This function loads the HAC initialize value to counter register.

Parameters
baseSNVS peripheral base address
static uint32_t SNVS_HP_GetHighAssuranceCounter ( SNVS_Type *  base)
inlinestatic
Parameters
baseSNVS peripheral base address
Returns
HAC currnet value.
static void SNVS_HP_ClearHighAssuranceCounter ( SNVS_Type *  base)
inlinestatic

This function can be called in a functional or soft fail state. When the HAC is enabled:

  • If the HAC is cleared in the soft fail state, the SSM transitions to the hard fail state immediately;
  • If the HAC is cleared in functional state, the SSM will transition to hard fail immediately after transitioning to soft fail.
Parameters
baseSNVS peripheral base address
static void SNVS_HP_LockHighAssuranceCounter ( SNVS_Type *  base)
inlinestatic

Once locked, the HAC initialize value could not be changed, the HAC enable status could not be changed. This could only be unlocked by system reset.

Parameters
baseSNVS peripheral base address
static uint32_t SNVS_HP_GetStatusFlags ( SNVS_Type *  base)
inlinestatic

The flags are returned as the OR'ed value of snvs_hp_sgtatus_flags_t.

Parameters
baseSNVS peripheral base address
Returns
The OR'ed value of status flags.
static void SNVS_HP_ClearStatusFlags ( SNVS_Type *  base,
uint32_t  mask 
)
inlinestatic

The flags to clear are passed in as the OR'ed value of snvs_hp_status_flags_t. Only these flags could be cleared using this API.

Parameters
baseSNVS peripheral base address
maskOR'ed value of the flags to clear.
static uint32_t SNVS_HP_GetSecurityViolationStatusFlags ( SNVS_Type *  base)
inlinestatic

The flags are returned as the OR'ed value of snvs_hp_sv_status_flags_t.

Parameters
baseSNVS peripheral base address
Returns
The OR'ed value of security violation status flags.
static void SNVS_HP_ClearSecurityViolationStatusFlags ( SNVS_Type *  base,
uint32_t  mask 
)
inlinestatic

The flags to clear are passed in as the OR'ed value of snvs_hp_sv_status_flags_t. Only these flags could be cleared using this API.

Parameters
baseSNVS peripheral base address
maskOR'ed value of the flags to clear.