(5015f26)

Lifecycle Controller Device Interface Functions More...

#include <stdbool.h>
#include <stdint.h>
#include "sw/device/lib/base/macros.h"
#include "sw/device/lib/base/mmio.h"
#include "sw/device/lib/dif/dif_base.h"
#include "sw/device/lib/dif/autogen/dif_lc_ctrl_autogen.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_hw_rev_t
	A 32-bit hardware revision number. More...

struct	dif_lc_ctrl_device_id
	A 256-bit device id stored in OTP's hw_cfg0 partition. 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_t`s. More...

typedef enum dif_lc_ctrl_state	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_device_id	dif_lc_ctrl_device_id_t
	A 256-bit device id stored in OTP's hw_cfg0 partition.

Enumerations
enum	dif_lc_ctrl_status_code { kDifLcCtrlStatusCodeInitialized, kDifLcCtrlStatusCodeReady, kDifLcCtrlStatusExtClockSwitched, kDifLcCtrlStatusCodeSuccess, kDifLcCtrlStatusCodeTooManyTransitions, kDifLcCtrlStatusCodeInvalidTransition, kDifLcCtrlStatusCodeBadToken, kDifLcCtrlStatusCodeFlashRmaError, kDifLcCtrlStatusCodeOtpError, kDifLcCtrlStatusCodeCorrupt, kDifLcCtrlStatusCodeBusIntegError, kDifLcCtrlStatusCodeOtpPartError }
	A lifecycle controller status code. More...

enum	dif_lc_ctrl_state { kDifLcCtrlStateRaw, kDifLcCtrlStateTestUnlocked0, kDifLcCtrlStateTestLocked0, kDifLcCtrlStateTestUnlocked1, kDifLcCtrlStateTestLocked1, kDifLcCtrlStateTestUnlocked2, kDifLcCtrlStateTestLocked2, kDifLcCtrlStateTestUnlocked3, kDifLcCtrlStateTestLocked3, kDifLcCtrlStateTestUnlocked4, kDifLcCtrlStateTestLocked4, kDifLcCtrlStateTestUnlocked5, kDifLcCtrlStateTestLocked5, kDifLcCtrlStateTestUnlocked6, kDifLcCtrlStateTestLocked6, kDifLcCtrlStateTestUnlocked7, 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...

Functions
OT_WARN_UNUSED_RESULT dif_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...

OT_WARN_UNUSED_RESULT dif_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...

OT_WARN_UNUSED_RESULT dif_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...

OT_WARN_UNUSED_RESULT dif_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...

OT_WARN_UNUSED_RESULT dif_result_t	dif_lc_ctrl_get_hw_rev (const dif_lc_ctrl_t lc, dif_lc_ctrl_hw_rev_t hw_rev)
	Returns the hardware revision number reading from lifecycle controller's hardware revision register. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_lc_ctrl_get_device_id (const dif_lc_ctrl_t lc, dif_lc_ctrl_device_id_t device_id)
	Returns the current device id reading from lifecycle controller's device id registers. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_lc_ctrl_mutex_try_acquire (const dif_lc_ctrl_t *lc)
	Attempts to acquire the lifecycle controller's HW mutex. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_lc_ctrl_mutex_release (const dif_lc_ctrl_t *lc)
	Releases the lifecycle controller's HW mutex. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_lc_ctrl_configure (const dif_lc_ctrl_t lc, dif_lc_ctrl_state_t target_state, bool use_ext_clock, const dif_lc_ctrl_token_t token)
	Configures the lifecycle controller to perform a transition. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_lc_ctrl_transition (const dif_lc_ctrl_t *lc)
	Performs a lifecycle transition. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_lc_ctrl_set_otp_vendor_test_reg (const dif_lc_ctrl_t *lc, uint32_t settings)
	Writes settings to the vendor-specific OTP test control register. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_lc_ctrl_get_otp_vendor_test_reg (const dif_lc_ctrl_t lc, uint32_t settings)
	Reads settings from the vendor-specific OTP test control register. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_lc_ctrl_sw_mutex_lock (const dif_lc_ctrl_t *lc)
	Clears LC_CTRL_CLAIM_TRANSITION_IF_REGWEN to lock ability to claim mutex over TL-UL, effectively disabling SW-initiated lifecycle transitions. 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 275 of file dif_lc_ctrl.h.

Data Fields
uint8_t	data[128/8]

◆ dif_lc_ctrl_hw_rev_t

struct dif_lc_ctrl_hw_rev_t

A 32-bit hardware revision number.

Definition at line 282 of file dif_lc_ctrl.h.

Data Fields
uint16_t	product_id
uint8_t	revision_id
uint16_t	silicon_creator_id

◆ dif_lc_ctrl_device_id

struct dif_lc_ctrl_device_id

A 256-bit device id stored in OTP's hw_cfg0 partition.

Definition at line 291 of file dif_lc_ctrl.h.

Data Fields
uint32_t	data[256/32]

Typedef Documentation

◆ dif_lc_ctrl_state_t

typedef enum dif_lc_ctrl_state 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

typedef enum dif_lc_ctrl_status_code 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 98 of file dif_lc_ctrl.h.

Enumeration Type Documentation

◆ dif_lc_ctrl_id_state

enum 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 257 of file dif_lc_ctrl.h.

◆ dif_lc_ctrl_state

enum dif_lc_ctrl_state

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.
kDifLcCtrlStateTestLocked3	The third locked test state. All functions are disabled.
kDifLcCtrlStateTestUnlocked4	The fourth test state. Debug functions are enabled.
kDifLcCtrlStateTestLocked4	The fourth locked test state. All functions are disabled.
kDifLcCtrlStateTestUnlocked5	The fifth test state. Debug functions are enabled.
kDifLcCtrlStateTestLocked5	The fifth locked test state. All functions are disabled.
kDifLcCtrlStateTestUnlocked6	The sixth test state. Debug functions are enabled.
kDifLcCtrlStateTestLocked6	The sixth locked test state. All functions are disabled.
kDifLcCtrlStateTestUnlocked7	The seventh 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 107 of file dif_lc_ctrl.h.

◆ dif_lc_ctrl_status_code

enum dif_lc_ctrl_status_code

A lifecycle controller status code.

See dif_lc_ctrl_get_status().

Enumerator
kDifLcCtrlStatusCodeInitialized	Indicates that the controller has been successfully initialized.
kDifLcCtrlStatusCodeReady	Indicates that the controller has been successfully initialized and is ready to accept a life cycle transition command.
kDifLcCtrlStatusExtClockSwitched	Indicates that the clock manager has successfully switched to the external clock.
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.
kDifLcCtrlStatusCodeFlashRmaError	Indicates a flash RMA request error.
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.
kDifLcCtrlStatusCodeBusIntegError	Indicates a bus integrity error. This error will raise an alert.
kDifLcCtrlStatusCodeOtpPartError	Indicates an ECC error in the lifecycle OTP partition.

Definition at line 32 of file dif_lc_ctrl.h.

Function Documentation

◆ dif_lc_ctrl_configure()

OT_WARN_UNUSED_RESULT dif_result_t dif_lc_ctrl_configure	(	const dif_lc_ctrl_t *	lc,
		dif_lc_ctrl_state_t	target_state,
		bool	use_ext_clock,
		const dif_lc_ctrl_token_t *	token
	)

Configures the lifecycle controller to perform a transition.

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

Parameters

lc	A lifecycle handle.
state	The state to transition to.
use_ext_clock	Whether to use the external clock for the transition.
token	A token for unlocking the transition; may be null.

Returns: The result of the operation.

Definition at line 288 of file dif_lc_ctrl.c.

◆ dif_lc_ctrl_get_attempts()

OT_WARN_UNUSED_RESULT dif_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

	lc	A lifecycle handle.
[out]	count	Out-param for the number of attempts.

Returns: The result of the operation.

Definition at line 102 of file dif_lc_ctrl.c.

◆ dif_lc_ctrl_get_device_id()

OT_WARN_UNUSED_RESULT dif_result_t dif_lc_ctrl_get_device_id	(	const dif_lc_ctrl_t *	lc,
		dif_lc_ctrl_device_id_t *	device_id
	)

Returns the current device id reading from lifecycle controller's device id registers.

Parameters

	lc	A lifecycle handle.
[out]	device_id	Out-param for the device id.

Returns: The result of the operation.

Definition at line 235 of file dif_lc_ctrl.c.

◆ dif_lc_ctrl_get_hw_rev()

OT_WARN_UNUSED_RESULT dif_result_t dif_lc_ctrl_get_hw_rev	(	const dif_lc_ctrl_t *	lc,
		dif_lc_ctrl_hw_rev_t *	hw_rev
	)

Returns the hardware revision number reading from lifecycle controller's hardware revision register.

Parameters

	lc	A lifecycle handle.
[out]	hw_rev	Out-param for the hardware revision.

Returns: The result of the operation.

Definition at line 218 of file dif_lc_ctrl.c.

◆ dif_lc_ctrl_get_id_state()

OT_WARN_UNUSED_RESULT dif_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

	lc	A lifecycle handle.
[out]	state	Out-param for the controller's personalization state.

Returns: The result of the operation.

Definition at line 193 of file dif_lc_ctrl.c.

◆ dif_lc_ctrl_get_otp_vendor_test_reg()

OT_WARN_UNUSED_RESULT dif_result_t dif_lc_ctrl_get_otp_vendor_test_reg	(	const dif_lc_ctrl_t *	lc,
		uint32_t *	settings
	)

Reads settings from the vendor-specific OTP test control register.

This returns kDifUnavailable if the mutex has not been acquired.

Parameters

lc	A lifecycle handle.
settings	Output parameter for the settings.

Returns: The result of the operation.

Definition at line 436 of file dif_lc_ctrl.c.

◆ dif_lc_ctrl_get_state()

OT_WARN_UNUSED_RESULT dif_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

	lc	A lifecycle handle.
[out]	state	Out-param for the controller's state.

Returns: The result of the operation.

Definition at line 13 of file dif_lc_ctrl.c.

◆ dif_lc_ctrl_get_status()

OT_WARN_UNUSED_RESULT dif_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

	lc	A lifecycle handle.
[out]	status	Out-param for the controller's status.

Returns: The result of the operation.

Definition at line 119 of file dif_lc_ctrl.c.

◆ dif_lc_ctrl_mutex_release()

OT_WARN_UNUSED_RESULT dif_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

lc	A lifecycle handle.

Returns: The result of the operation.

Definition at line 271 of file dif_lc_ctrl.c.

◆ dif_lc_ctrl_mutex_try_acquire()

OT_WARN_UNUSED_RESULT dif_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

lc	A lifecycle handle.

Returns: The result of the operation.

Definition at line 247 of file dif_lc_ctrl.c.

◆ dif_lc_ctrl_set_otp_vendor_test_reg()

OT_WARN_UNUSED_RESULT dif_result_t dif_lc_ctrl_set_otp_vendor_test_reg	(	const dif_lc_ctrl_t *	lc,
		uint32_t	settings
	)

Writes settings to the vendor-specific OTP test control register.

This returns kDifUnavailable if the mutex has not been acquired.

Parameters

lc	A lifecycle handle.
settings	The settings to write to the register.

Returns: The result of the operation.

Definition at line 418 of file dif_lc_ctrl.c.

◆ dif_lc_ctrl_sw_mutex_lock()

OT_WARN_UNUSED_RESULT dif_result_t dif_lc_ctrl_sw_mutex_lock ( const dif_lc_ctrl_t * lc )

Clears LC_CTRL_CLAIM_TRANSITION_IF_REGWEN to lock ability to claim mutex over TL-UL, effectively disabling SW-initiated lifecycle transitions.

Parameters

lc	A lifecycle handle.

Returns: The result of the operation.

Definition at line 454 of file dif_lc_ctrl.c.

◆ dif_lc_ctrl_transition()

OT_WARN_UNUSED_RESULT dif_result_t dif_lc_ctrl_transition ( const dif_lc_ctrl_t * lc )

Performs a lifecycle transition.

Parameters

lc	A lifecycle handle.

Returns: The result of the operation.

Definition at line 402 of file dif_lc_ctrl.c.

(5015f26)

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ dif_lc_ctrl_token

◆ dif_lc_ctrl_hw_rev_t

◆ dif_lc_ctrl_device_id

Typedef Documentation

◆ dif_lc_ctrl_state_t

◆ dif_lc_ctrl_status_code_t

◆ dif_lc_ctrl_status_t

Enumeration Type Documentation

◆ dif_lc_ctrl_id_state

◆ dif_lc_ctrl_state

◆ dif_lc_ctrl_status_code

Function Documentation

◆ dif_lc_ctrl_configure()

◆ dif_lc_ctrl_get_attempts()

◆ dif_lc_ctrl_get_device_id()

◆ dif_lc_ctrl_get_hw_rev()

◆ dif_lc_ctrl_get_id_state()

◆ dif_lc_ctrl_get_otp_vendor_test_reg()

◆ dif_lc_ctrl_get_state()

◆ dif_lc_ctrl_get_status()

◆ dif_lc_ctrl_mutex_release()

◆ dif_lc_ctrl_mutex_try_acquire()

◆ dif_lc_ctrl_set_otp_vendor_test_reg()

◆ dif_lc_ctrl_sw_mutex_lock()

◆ dif_lc_ctrl_transition()