Software APIs
dif_lc_ctrl.h
Go to the documentation of this file.
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_LIB_DIF_DIF_LC_CTRL_H_
6#define OPENTITAN_SW_DEVICE_LIB_DIF_DIF_LC_CTRL_H_
7
8/**
9 * @file
10 * @brief <a href="/hw/ip/lc_ctrl/doc/">Lifecycle Controller</a> Device
11 * Interface Functions
12 */
13
14#include <stdbool.h>
15#include <stdint.h>
16
20
21#include "sw/device/lib/dif/autogen/dif_lc_ctrl_autogen.h"
22
23#ifdef __cplusplus
24extern "C" {
25#endif // __cplusplus
26
27/**
28 * A lifecycle controller status code.
29 *
30 * See `dif_lc_ctrl_get_status()`.
31 */
33 /**
34 * Indicates that the controller has been successfully initialized.
35 */
37 /**
38 * Indicates that the controller has been successfully initialized
39 * and is ready to accept a life cycle transition command.
40 */
42 /**
43 * Indicates that the clock manager has successfully switched to the
44 * external clock.
45 */
47 /**
48 * Indicates that the last lifecycle transition succeeded.
49 */
51 /**
52 * Indicates that too many hardware transitions have occurred, and the
53 * hardware will not transition the lifecycle any further.
54 */
56 /**
57 * Indicates that an invalid lifecycle transition was attempted.
58 */
60 /**
61 * Indicates that a bad token was supplied for conditional transition.
62 */
64 /**
65 * Indicates a flash RMA request error.
66 */
68 /**
69 * Indicates an error during an OTP operation.
70 *
71 * This error will raise an alert.
72 */
74 /**
75 * Indicates an error in the controller's internal state.
76 *
77 * This error will raise an alert.
78 */
80 /**
81 * Indicates a bus integrity error.
82 *
83 * This error will raise an alert.
84 */
86 /**
87 * Indicates an ECC error in the lifecycle OTP partition.
88 */
91
92/**
93 * A bit-vector of `dif_lc_ctrl_status_code_t`s.
94 *
95 * Whether a particular status is contained in this vector can be discovered by
96 * using it as a bit index: `bitfield_bit32_read(status, status_code);`.
97 */
98typedef uint32_t dif_lc_ctrl_status_t;
99
100/**
101 * A lifecycle state.
102 *
103 * This enum represents all states that the lifecycle state register can be in;
104 * some of these do not correspond to "real" lifecycle states, and cannot be
105 * transitioned to.
106 */
107typedef enum dif_lc_ctrl_state {
108 /**
109 * The initial post-manufacture state.
110 *
111 * All functions are disabled.
112 */
114 /**
115 * The zeroth test state.
116 *
117 * Debug functions are enabled.
118 */
120 /**
121 * The zeroth locked test state.
122 *
123 * All functions are disabled.
124 */
126 /**
127 * The first test state.
128 *
129 * Debug functions are enabled.
130 */
132 /**
133 * The first locked test state.
134 *
135 * All functions are disabled.
136 */
138 /**
139 * The second test state.
140 *
141 * Debug functions are enabled.
142 */
144 /**
145 * The second locked test state.
146 *
147 * All functions are disabled.
148 */
150 /**
151 * The third test state.
152 *
153 * Debug functions are enabled.
154 */
156 /**
157 * The third locked test state.
158 *
159 * All functions are disabled.
160 */
162 /**
163 * The fourth test state.
164 *
165 * Debug functions are enabled.
166 */
168 /**
169 * The fourth locked test state.
170 *
171 * All functions are disabled.
172 */
174 /**
175 * The fifth test state.
176 *
177 * Debug functions are enabled.
178 */
180 /**
181 * The fifth locked test state.
182 *
183 * All functions are disabled.
184 */
186 /**
187 * The sixth test state.
188 *
189 * Debug functions are enabled.
190 */
192 /**
193 * The sixth locked test state.
194 *
195 * All functions are disabled.
196 */
198 /**
199 * The seventh test state.
200 *
201 * Debug functions are enabled.
202 */
204 /**
205 * The development state.
206 *
207 * Some debug functions are enabled.
208 */
210 /**
211 * The main production state.
212 *
213 * No debug functions are enabled.
214 */
216 /**
217 * The EOL production state.
218 *
219 * Same as Prod, except Rma cannot be transitioned to.
220 */
222 /**
223 * RMA manufacturer analysis state.
224 */
226 /**
227 * The scrap EOL state.
228 *
229 * Cannot be transitioned from; all functions are disabled.
230 */
232
233 /**
234 * State entered immediately after a transition occurs.
235 *
236 * Not a real state.
237 */
239 /**
240 * State entered immediately after an alert is raised.
241 *
242 * Not a real state.
243 */
245 /**
246 * Indicates that the encoded lifecycle is invalid.
247 *
248 * Not a real state.
249 */
252
253/**
254 * A personalization state, indicating whether the device has been successfully
255 * personalized.
256 */
258 /**
259 * Indicates that the device has not yet been personalized.
260 */
262 /**
263 * Indicates that the device has been personalized.
264 */
266 /**
267 * Indicates that the personalization state is corrupt.
268 */
271
272/**
273 * A 128-bit unlock token used for certain kinds of lifecycle transitions.
274 */
275typedef struct dif_lc_ctrl_token {
276 uint8_t data[128 / 8];
278
279/**
280 * A 32-bit hardware revision number.
281 */
282typedef struct {
283 uint16_t silicon_creator_id;
284 uint16_t product_id;
285 uint8_t revision_id;
287
288/**
289 * A 256-bit device id stored in OTP's hw_cfg0 partition.
290 */
291typedef struct dif_lc_ctrl_device_id {
292 uint32_t data[256 / 32];
294
295/**
296 * Returns the current state of the lifecycle controller.
297 *
298 * @param lc A lifecycle handle.
299 * @param[out] state Out-param for the controller's state.
300 * @return The result of the operation.
301 */
304 dif_lc_ctrl_state_t *state);
305
306/**
307 * Returns the number of lifecycle transitions that this device has attempted,
308 * up to 16.
309 *
310 * @param lc A lifecycle handle.
311 * @param[out] count Out-param for the number of attempts.
312 * @return The result of the operation.
313 */
315dif_result_t dif_lc_ctrl_get_attempts(const dif_lc_ctrl_t *lc, uint8_t *count);
316
317/**
318 * Returns the current status of the lifecycle controller.
319 *
320 * @param lc A lifecycle handle.
321 * @param[out] status Out-param for the controller's status.
322 * @return The result of the operation.
323 */
327
328/**
329 * Returns the current personalization state of the lifecycle controller.
330 *
331 * @param lc A lifecycle handle.
332 * @param[out] state Out-param for the controller's personalization state.
333 * @return The result of the operation.
334 */
338
339/**
340 * Returns the hardware revision number reading from lifecycle controller's
341 * hardware revision register.
342 *
343 * @param lc A lifecycle handle.
344 * @param[out] hw_rev Out-param for the hardware revision.
345 * @return The result of the operation.
346 */
349 dif_lc_ctrl_hw_rev_t *hw_rev);
350
351/**
352 * Returns the current device id reading from lifecycle controller's device id
353 * registers.
354 *
355 * @param lc A lifecycle handle.
356 * @param[out] device_id Out-param for the device id.
357 * @return The result of the operation.
358 */
361 dif_lc_ctrl_device_id_t *device_id);
362
363/**
364 * Attempts to acquire the lifecycle controller's HW mutex.
365 *
366 * Returns `kDifLcCtrlMutexHeld` if acquisition fails. It is recommended to
367 * call this function in a busy loop to acquire the mutex.
368 *
369 * @param lc A lifecycle handle.
370 * @return The result of the operation.
371 */
372// Open Q: do we want to be checking REGWEN for all operations dependent on the
373// mutex?
376
377/**
378 * Releases the lifecycle controller's HW mutex.
379 *
380 * Calls to this function must be sequenced with successful calls to
381 * `dif_lc_ctrl_mutex_try_acquire()`.
382 *
383 * @param lc A lifecycle handle.
384 * @return The result of the operation.
385 */
388
389/**
390 * Configures the lifecycle controller to perform a transition.
391 *
392 * Note that not all transitions require an unlock token; in that case, NULL
393 * should be passed as the token.
394 *
395 * @param lc A lifecycle handle.
396 * @param state The state to transition to.
397 * @param use_ext_clock Whether to use the external clock for the transition.
398 * @param token A token for unlocking the transition; may be null.
399 * @return The result of the operation.
400 */
403 dif_lc_ctrl_state_t target_state,
404 bool use_ext_clock,
405 const dif_lc_ctrl_token_t *token);
406
407/**
408 * Performs a lifecycle transition.
409 *
410 * @param lc A lifecycle handle.
411 * @return The result of the operation.
412 */
415
416/**
417 * Writes settings to the vendor-specific OTP test control register.
418 *
419 * This returns `kDifUnavailable` if the mutex has not been acquired.
420 *
421 * @param lc A lifecycle handle.
422 * @param settings The settings to write to the register.
423 * @return The result of the operation.
424 */
427 uint32_t settings);
428
429/**
430 * Reads settings from the vendor-specific OTP test control register.
431 *
432 * This returns `kDifUnavailable` if the mutex has not been acquired.
433 *
434 * @param lc A lifecycle handle.
435 * @param settings Output parameter for the settings.
436 * @return The result of the operation.
437 */
440 uint32_t *settings);
441
442/**
443 * Clears LC_CTRL_CLAIM_TRANSITION_IF_REGWEN to lock ability to claim mutex over
444 * TL-UL, effectively disabling SW-initiated lifecycle transitions.
445 *
446 * @param lc A lifecycle handle.
447 * @return The result of the operation.
448 */
451
452#ifdef __cplusplus
453} // extern "C"
454#endif // __cplusplus
455
456#endif // OPENTITAN_SW_DEVICE_LIB_DIF_DIF_LC_CTRL_H_