Software APIs
lifecycle.h
1// Copyright lowRISC contributors (OpenTitan project).
2// Licensed under the Apache License, Version 2.0, see LICENSE for details.
3// SPDX-License-Identifier: Apache-2.0
4
5#ifndef OPENTITAN_SW_DEVICE_SILICON_CREATOR_LIB_DRIVERS_LIFECYCLE_H_
6#define OPENTITAN_SW_DEVICE_SILICON_CREATOR_LIB_DRIVERS_LIFECYCLE_H_
7
8#include <stdint.h>
9
12
13#ifdef __cplusplus
14extern "C" {
15#endif
16
17/**
18 * Lifecycle states.
19 *
20 * This is a condensed version of the 24 possible life cycle states where
21 * TEST_UNLOCKED_* states are mapped to `kLcStateTest` and invalid states where
22 * CPU execution is disabled are omitted.
23 *
24 * Encoding generated with
25 * $ ./util/design/sparse-fsm-encode.py -d 6 -m 5 -n 32 \
26 * -s 2447090565 --language=c
27 *
28 * Minimum Hamming distance: 13
29 * Maximum Hamming distance: 19
30 * Minimum Hamming weight: 15
31 * Maximum Hamming weight: 20
32 */
33typedef enum lifecycle_state {
34 /**
35 * Unlocked test state where debug functions are enabled.
36 *
37 * Corresponds to TEST_UNLOCKED_* life cycle states.
38 */
39 kLcStateTest = 0xb2865fbb,
40 /**
41 * Development life cycle state where limited debug functionality is
42 * available.
43 */
44 kLcStateDev = 0x0b5a75e0,
45 /**
46 * Production life cycle state.
47 */
48 kLcStateProd = 0x65f2520f,
49 /**
50 * Same as PROD, but transition into RMA is not possible from this state.
51 */
52 kLcStateProdEnd = 0x91b9b68a,
53 /**
54 * RMA life cycle state.
55 */
56 kLcStateRma = 0xcf8cfaab,
57} lifecycle_state_t;
58
59enum {
60 /**
61 * Size of the device identifier in words.
62 */
63 kLifecycleDeviceIdNumWords = 8,
64};
65
66/**
67 * 256-bit device identifier that is stored in the `HW_CFG0` partition in OTP.
68 */
69typedef struct lifecycle_device_id {
70 uint32_t device_id[kLifecycleDeviceIdNumWords];
71} lifecycle_device_id_t;
72
73/**
74 * Hardware revision.
75 *
76 * Consists of a 16-bit silicon creator ID,
77 * a 16-bit product ID and an 8bit revision ID.
78 */
79typedef struct lifecycle_hw_rev {
80 uint16_t silicon_creator_id;
81 uint16_t product_id;
82 uint8_t revision_id;
83} lifecycle_hw_rev_t;
84
85/**
86 * Get the life cycle state.
87 *
88 * This function checks the value read from the hardware and returns a
89 * `life_cycle_state_t`. See `life_cyle_state_t` for more details.
90 *
91 * @return Life cycle state.
92 */
94lifecycle_state_t lifecycle_state_get(void);
95
96/**
97 * Check if the device is in prod state.
98 *
99 * Warning: This function also returns false when LCS is invalid.
100 *
101 * @return `kHardenedBoolTrue` if the device is in prod state.
102 */
104hardened_bool_t lifecycle_is_prod(void);
105
106/**
107 * Get the unprocessed life cycle state value read from the hardware.
108 *
109 * This function directly returns the `uint32_t` value read from the hardware.
110 *
111 * @return Life cycle state.
112 */
114uint32_t lifecycle_raw_state_get(void);
115
116/**
117 * Get the device identifier.
118 *
119 * @param[out] device_id 256-bit device identifier that is stored in the
120 * `HW_CFG0` partition in OTP.
121 */
122void lifecycle_device_id_get(lifecycle_device_id_t *device_id);
123
124/**
125 * Get the hardware revision.
126 *
127 * @param[out] hw_rev Hardware revision.
128 */
129void lifecycle_hw_rev_get(lifecycle_hw_rev_t *hw_rev);
130
131/**
132 * Determine if the device identification number subfield of the Device Id is
133 * equal to the supplied DIN.
134 *
135 * @returns kHardenedBoolTrue if equal, kHardenedBoolFalse if not equal.
136 */
137hardened_bool_t lifecycle_din_eq(lifecycle_device_id_t *id, uint32_t *din);
138
139#ifdef __cplusplus
140}
141#endif
142#endif // OPENTITAN_SW_DEVICE_SILICON_CREATOR_LIB_DRIVERS_LIFECYCLE_H_