Software APIs
Data Structures | Typedefs | Enumerations | Functions
dif_lc_ctrl.h File Reference

(dcee03a)

Lifecycle Controller Device Interface Functions More...

#include <stdbool.h>
#include <stdint.h>
#include "sw/device/lib/base/mmio.h"
#include "sw/device/lib/dif/dif_warn_unused_result.h"

Go to the source code of this file.

Data Structures

struct  dif_lc_ctrl_token
 A 128-bit unlock token used for certain kinds of lifecycle transitions. More...
 
struct  dif_lc_ctrl_params
 Hardware instantiation parameters for a lifecycle controller. More...
 
struct  dif_lc_ctrl
 A handle to a lifecycle controller. More...
 

Typedefs

typedef enum dif_lc_ctrl_status_code dif_lc_ctrl_status_code_t
 A lifecycle controller status code. More...
 
typedef uint32_t dif_lc_ctrl_status_t
 A bit-vector of dif_lc_ctrl_status_code_ts. More...
 
typedef enum dif_lc_ctrl_state_t dif_lc_ctrl_state_t
 A lifecycle state. More...
 
typedef enum dif_lc_ctrl_id_state dif_lc_ctrl_id_state_t
 A personalization state, indicating whether the device has been successfully personalized.
 
typedef struct dif_lc_ctrl_token dif_lc_ctrl_token_t
 A 128-bit unlock token used for certain kinds of lifecycle transitions.
 
typedef struct dif_lc_ctrl_params dif_lc_ctrl_params_t
 Hardware instantiation parameters for a lifecycle controller. More...
 
typedef struct dif_lc_ctrl dif_lc_ctrl_t
 A handle to a lifecycle controller. More...
 
typedef enum dif_lc_ctrl_result dif_lc_ctrl_result_t
 The result of a lifecycle controller operation.
 
typedef enum dif_lc_ctrl_attempts_result dif_lc_ctrl_attempts_result_t
 The result of a lifecycle attempt counter operation.
 
typedef enum dif_lc_ctrl_mutex_result dif_lc_ctrl_mutex_result_t
 The result of a lifecycle controller operation involving the hardware mutex.
 
typedef enum dif_lc_ctrl_alert dif_lc_ctrl_alert_t
 An alert that can be raised by the hardware.
 

Enumerations

enum  dif_lc_ctrl_status_code {
  kDifLcCtrlStatusCodeReady,
  kDifLcCtrlStatusCodeSuccess,
  kDifLcCtrlStatusCodeTooManyTransitions,
  kDifLcCtrlStatusCodeInvalidTransition,
  kDifLcCtrlStatusCodeBadToken,
  kDifLcCtrlStatusCodeOtpError,
  kDifLcCtrlStatusCodeCorrupt
}
 A lifecycle controller status code. More...
 
enum  dif_lc_ctrl_state_t {
  kDifLcCtrlStateRaw,
  kDifLcCtrlStateTestUnlocked0,
  kDifLcCtrlStateTestLocked0,
  kDifLcCtrlStateTestUnlocked1,
  kDifLcCtrlStateTestLocked1,
  kDifLcCtrlStateTestUnlocked2,
  kDifLcCtrlStateTestLocked2,
  kDifLcCtrlStateTestUnlocked3,
  kDifLcCtrlStateDev,
  kDifLcCtrlStateProd,
  kDifLcCtrlStateProdEnd,
  kDifLcCtrlStateRma,
  kDifLcCtrlStateScrap,
  kDifLcCtrlStatePostTransition,
  kDifLcCtrlStateEscalate,
  kDifLcCtrlStateInvalid
}
 A lifecycle state. More...
 
enum  dif_lc_ctrl_id_state {
  kDifLcCtrlIdStateBlank,
  kDifLcCtrlIdStatePersonalized,
  kDifLcCtrlIdStateInvalid
}
 A personalization state, indicating whether the device has been successfully personalized. More...
 
enum  dif_lc_ctrl_result {
  kDifLcCtrlOk = 0,
  kDifLcCtrlError = 1,
  kDifLcCtrlBadArg = 2
}
 The result of a lifecycle controller operation. More...
 
enum  dif_lc_ctrl_attempts_result {
  kDifLcCtrlAttemptsOk = kDifLcCtrlOk,
  kDifLcCtrlAttemptsError = kDifLcCtrlError,
  kDifLcCtrlAttemptsBadArg = kDifLcCtrlBadArg,
  kDifLcCtrlAttemptsTooMany
}
 The result of a lifecycle attempt counter operation. More...
 
enum  dif_lc_ctrl_mutex_result {
  kDifLcCtrlMutexOk = kDifLcCtrlOk,
  kDifLcCtrlMutexError = kDifLcCtrlError,
  kDifLcCtrlMutexBadArg = kDifLcCtrlBadArg,
  kDifLcCtrlMutexAlreadyTaken = 3
}
 The result of a lifecycle controller operation involving the hardware mutex. More...
 
enum  dif_lc_ctrl_alert {
  kDifLcCtrlAlertOtp,
  kDifLcCtrlAlertCorrupt
}
 An alert that can be raised by the hardware. More...
 

Functions

DIF_WARN_UNUSED_RESULT dif_lc_ctrl_result_t dif_lc_ctrl_init (dif_lc_ctrl_params_t params, dif_lc_ctrl_t *lc)
 Creates a new handle for the lifecycle controller. More...
 
DIF_WARN_UNUSED_RESULT dif_lc_ctrl_result_t dif_lc_ctrl_get_state (const dif_lc_ctrl_t *lc, dif_lc_ctrl_state_t *state)
 Returns the current state of the lifecycle controller. More...
 
DIF_WARN_UNUSED_RESULT dif_lc_ctrl_attempts_result_t dif_lc_ctrl_get_attempts (const dif_lc_ctrl_t *lc, uint8_t *count)
 Returns the number of lifecycle transitions that this device has attempted, up to 16. More...
 
DIF_WARN_UNUSED_RESULT dif_lc_ctrl_result_t dif_lc_ctrl_get_status (const dif_lc_ctrl_t *lc, dif_lc_ctrl_status_t *status)
 Returns the current status of the lifecycle controller. More...
 
DIF_WARN_UNUSED_RESULT dif_lc_ctrl_result_t dif_lc_ctrl_get_id_state (const dif_lc_ctrl_t *lc, dif_lc_ctrl_id_state_t *state)
 Returns the current personalization state of the lifecycle controller. More...
 
DIF_WARN_UNUSED_RESULT dif_lc_ctrl_result_t dif_lc_ctrl_alert_force (const dif_lc_ctrl_t *lc, dif_lc_ctrl_alert_t alert)
 Forces a particular alert, causing it to be escalated as if the hardware had raised it. More...
 
DIF_WARN_UNUSED_RESULT dif_lc_ctrl_mutex_result_t dif_lc_ctrl_mutex_try_acquire (const dif_lc_ctrl_t *lc)
 Attempts to acquire the lifecycle controller's HW mutex. More...
 
DIF_WARN_UNUSED_RESULT dif_lc_ctrl_mutex_result_t dif_lc_ctrl_mutex_release (const dif_lc_ctrl_t *lc)
 Releases the lifecycle controller's HW mutex. More...
 
DIF_WARN_UNUSED_RESULT dif_lc_ctrl_mutex_result_t dif_lc_ctrl_transition (const dif_lc_ctrl_t *lc, dif_lc_ctrl_state_t state, const dif_lc_ctrl_token_t *token)
 Performs a lifecycle transition. More...
 

Detailed Description

Lifecycle Controller Device Interface Functions

Definition in file dif_lc_ctrl.h.


Data Structure Documentation

◆ dif_lc_ctrl_token

struct dif_lc_ctrl_token

A 128-bit unlock token used for certain kinds of lifecycle transitions.

Definition at line 200 of file dif_lc_ctrl.h.

Data Fields
uint8_t data[128/8]

◆ dif_lc_ctrl_params

struct dif_lc_ctrl_params

Hardware instantiation parameters for a lifecycle controller.

This struct describes information about the underlying hardware that is not determined until the hardware design is used as part of a top-level design.

Definition at line 211 of file dif_lc_ctrl.h.

Data Fields
mmio_region_t base_addr The base address for the lifecycle controller hardware registers.

◆ dif_lc_ctrl

struct dif_lc_ctrl

A handle to a lifecycle controller.

This type should be treated as opaque by users.

Definition at line 223 of file dif_lc_ctrl.h.

Data Fields
dif_lc_ctrl_params_t params

Typedef Documentation

◆ dif_lc_ctrl_params_t

Hardware instantiation parameters for a lifecycle controller.

This struct describes information about the underlying hardware that is not determined until the hardware design is used as part of a top-level design.

◆ dif_lc_ctrl_state_t

A lifecycle state.

This enum represents all states that the lifecycle state register can be in; some of these do not correspond to "real" lifecycle states, and cannot be transitioned to.

◆ dif_lc_ctrl_status_code_t

A lifecycle controller status code.

See dif_lc_ctrl_get_status().

◆ dif_lc_ctrl_status_t

typedef uint32_t dif_lc_ctrl_status_t

A bit-vector of dif_lc_ctrl_status_code_ts.

Whether a particular status is contained in this vector can be discovered by using it as a bit index: bitfield_bit32_read(status, status_code);.

Definition at line 71 of file dif_lc_ctrl.h.

◆ dif_lc_ctrl_t

typedef struct dif_lc_ctrl dif_lc_ctrl_t

A handle to a lifecycle controller.

This type should be treated as opaque by users.

Enumeration Type Documentation

◆ dif_lc_ctrl_alert

An alert that can be raised by the hardware.

Enumerator
kDifLcCtrlAlertOtp 

The alert triggered by a kDifLcCtrlStatusCodeOtpError.

kDifLcCtrlAlertCorrupt 

The alert triggered by a kDifLcCtrlStatusCodeCorrupt.

Definition at line 304 of file dif_lc_ctrl.h.

◆ dif_lc_ctrl_attempts_result

The result of a lifecycle attempt counter operation.

Enumerator
kDifLcCtrlAttemptsOk 

Indicates that the operation succeeded.

kDifLcCtrlAttemptsError 

Indicates some unspecified failure.

kDifLcCtrlAttemptsBadArg 

Indicates that some parameter passed into a function failed a precondition.

When this value is returned, no hardware operations occurred.

kDifLcCtrlAttemptsTooMany 

Indicates that too many lifecycle transitions have occurred, such that the hardware can no longer keep a count.

Definition at line 251 of file dif_lc_ctrl.h.

◆ dif_lc_ctrl_id_state

A personalization state, indicating whether the device has been successfully personalized.

Enumerator
kDifLcCtrlIdStateBlank 

Indicates that the device has not yet been personalized.

kDifLcCtrlIdStatePersonalized 

Indicates that the device has been personalized.

kDifLcCtrlIdStateInvalid 

Indicates that the personalization state is corrupt.

Definition at line 182 of file dif_lc_ctrl.h.

◆ dif_lc_ctrl_mutex_result

The result of a lifecycle controller operation involving the hardware mutex.

Enumerator
kDifLcCtrlMutexOk 

Indicates that the operation succeeded.

kDifLcCtrlMutexError 

Indicates some unspecified failure.

kDifLcCtrlMutexBadArg 

Indicates that some parameter passed into a function failed a precondition.

When this value is returned, no hardware operations occurred.

kDifLcCtrlMutexAlreadyTaken 

Indicates that a mutex-guarded operation failed because someone (other than software) is holding it.

Definition at line 277 of file dif_lc_ctrl.h.

◆ dif_lc_ctrl_result

The result of a lifecycle controller operation.

Enumerator
kDifLcCtrlOk 

Indicates that the operation succeeded.

kDifLcCtrlError 

Indicates some unspecified failure.

kDifLcCtrlBadArg 

Indicates that some parameter passed into a function failed a precondition.

When this value is returned, no hardware operations occurred.

Definition at line 230 of file dif_lc_ctrl.h.

◆ dif_lc_ctrl_state_t

A lifecycle state.

This enum represents all states that the lifecycle state register can be in; some of these do not correspond to "real" lifecycle states, and cannot be transitioned to.

Enumerator
kDifLcCtrlStateRaw 

The initial post-manufacture state.

All functions are disabled.

kDifLcCtrlStateTestUnlocked0 

The zeroth test state.

Debug functions are enabled.

kDifLcCtrlStateTestLocked0 

The zeroth locked test state.

All functions are disabled.

kDifLcCtrlStateTestUnlocked1 

The first test state.

Debug functions are enabled.

kDifLcCtrlStateTestLocked1 

The first locked test state.

All functions are disabled.

kDifLcCtrlStateTestUnlocked2 

The second test state.

Debug functions are enabled.

kDifLcCtrlStateTestLocked2 

The second locked test state.

All functions are disabled.

kDifLcCtrlStateTestUnlocked3 

The third test state.

Debug functions are enabled.

kDifLcCtrlStateDev 

The development state.

Some debug functions are enabled.

kDifLcCtrlStateProd 

The main production state.

No debug functions are enabled.

kDifLcCtrlStateProdEnd 

The EOL production state.

Same as Prod, except Rma cannot be transitioned to.

kDifLcCtrlStateRma 

RMA manufacturer analysis state.

kDifLcCtrlStateScrap 

The scrap EOL state.

Cannot be transitioned from; all functions are disabled.

kDifLcCtrlStatePostTransition 

State entered immediately after a transition occurs.

Not a real state.

kDifLcCtrlStateEscalate 

State entered immediately after an alert is raised.

Not a real state.

kDifLcCtrlStateInvalid 

Indicates that the encoded lifecycle is invalid.

Not a real state.

Definition at line 80 of file dif_lc_ctrl.h.

◆ dif_lc_ctrl_status_code

A lifecycle controller status code.

See dif_lc_ctrl_get_status().

Enumerator
kDifLcCtrlStatusCodeReady 

Indicates that the controller has been successfully initialized.

kDifLcCtrlStatusCodeSuccess 

Indicates that the last lifecycle transition succeeded.

kDifLcCtrlStatusCodeTooManyTransitions 

Indicates that too many hardware transitions have occurred, and the hardware will not transition the lifecycle any further.

kDifLcCtrlStatusCodeInvalidTransition 

Indicates that an invalid lifecycle transition was attempted.

kDifLcCtrlStatusCodeBadToken 

Indicates that a bad token was supplied for conditional transition.

kDifLcCtrlStatusCodeOtpError 

Indicates an error during an OTP operation.

This error will raise an alert.

kDifLcCtrlStatusCodeCorrupt 

Indicates an error in the controller's internal state.

This error will raise an alert.

Definition at line 29 of file dif_lc_ctrl.h.

Function Documentation

◆ dif_lc_ctrl_alert_force()

DIF_WARN_UNUSED_RESULT dif_lc_ctrl_result_t dif_lc_ctrl_alert_force ( const dif_lc_ctrl_t lc,
dif_lc_ctrl_alert_t  alert 
)

Forces a particular alert, causing it to be escalated as if the hardware had raised it.

Parameters
lcA lifecycle handle.
alertThe alert to force.
Returns
The result of the operation.

Definition at line 179 of file dif_lc_ctrl.c.

◆ dif_lc_ctrl_get_attempts()

DIF_WARN_UNUSED_RESULT dif_lc_ctrl_attempts_result_t dif_lc_ctrl_get_attempts ( const dif_lc_ctrl_t lc,
uint8_t *  count 
)

Returns the number of lifecycle transitions that this device has attempted, up to 16.

Parameters
lcA lifecycle handle.
[out]countOut-param for the number of attempts.
Returns
The result of the operation.

Definition at line 86 of file dif_lc_ctrl.c.

◆ dif_lc_ctrl_get_id_state()

DIF_WARN_UNUSED_RESULT dif_lc_ctrl_result_t dif_lc_ctrl_get_id_state ( const dif_lc_ctrl_t lc,
dif_lc_ctrl_id_state_t state 
)

Returns the current personalization state of the lifecycle controller.

Parameters
lcA lifecycle handle.
[out]stateOut-param for the controller's personalization state.
Returns
The result of the operation.

Definition at line 154 of file dif_lc_ctrl.c.

◆ dif_lc_ctrl_get_state()

DIF_WARN_UNUSED_RESULT dif_lc_ctrl_result_t dif_lc_ctrl_get_state ( const dif_lc_ctrl_t lc,
dif_lc_ctrl_state_t state 
)

Returns the current state of the lifecycle controller.

Parameters
lcA lifecycle handle.
[out]stateOut-param for the controller's state.
Returns
The result of the operation.

Definition at line 20 of file dif_lc_ctrl.c.

◆ dif_lc_ctrl_get_status()

DIF_WARN_UNUSED_RESULT dif_lc_ctrl_result_t dif_lc_ctrl_get_status ( const dif_lc_ctrl_t lc,
dif_lc_ctrl_status_t status 
)

Returns the current status of the lifecycle controller.

Parameters
lcA lifecycle handle.
[out]statusOut-param for the controller's status.
Returns
The result of the operation.

Definition at line 104 of file dif_lc_ctrl.c.

◆ dif_lc_ctrl_init()

Creates a new handle for the lifecycle controller.

This function does not actuate the hardware.

Parameters
paramsHardware instantiation parameters.
[out]lcOut param for the initialized handle.
Returns
The result of the operation.

Definition at line 10 of file dif_lc_ctrl.c.

◆ dif_lc_ctrl_mutex_release()

DIF_WARN_UNUSED_RESULT dif_lc_ctrl_mutex_result_t dif_lc_ctrl_mutex_release ( const dif_lc_ctrl_t lc)

Releases the lifecycle controller's HW mutex.

Calls to this function must be sequenced with successful calls to dif_lc_ctrl_mutex_try_acquire().

Parameters
lcA lifecycle handle.
Returns
The result of the operation.

Definition at line 222 of file dif_lc_ctrl.c.

◆ dif_lc_ctrl_mutex_try_acquire()

DIF_WARN_UNUSED_RESULT dif_lc_ctrl_mutex_result_t dif_lc_ctrl_mutex_try_acquire ( const dif_lc_ctrl_t lc)

Attempts to acquire the lifecycle controller's HW mutex.

Returns kDifLcCtrlMutexHeld if acquisition fails. It is recommended to call this function in a busy loop to acquire the mutex.

Parameters
lcA lifecycle handle.
Returns
The result of the operation.

Definition at line 203 of file dif_lc_ctrl.c.

◆ dif_lc_ctrl_transition()

DIF_WARN_UNUSED_RESULT dif_lc_ctrl_mutex_result_t dif_lc_ctrl_transition ( const dif_lc_ctrl_t lc,
dif_lc_ctrl_state_t  state,
const dif_lc_ctrl_token_t token 
)

Performs a lifecycle transition.

Note that not all transitions require an unlock token; in that case, NULL should be passed as the token.

Parameters
lcA lifecycle handle.
stateThe state to transition to.
tokenA token for unlocking the transition; may be null.
Returns
The result of the operation.

Definition at line 239 of file dif_lc_ctrl.c.