Software APIs
dif_otp_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#ifndef OPENTITAN_SW_DEVICE_LIB_DIF_DIF_OTP_CTRL_H_
5#define OPENTITAN_SW_DEVICE_LIB_DIF_DIF_OTP_CTRL_H_
6
7/**
8 * @file
9 * @brief <a href="/hw/top_earlgrey/ip_autogen/otp_ctrl/doc/">
10 * OTP Controller</a> Device Interface Functions
11 */
12
13#include <stdint.h>
14
18
19#include "sw/device/lib/dif/autogen/dif_otp_ctrl_autogen.h"
20
21// Header Extern Guard (so header can be used from C and C++)
22#ifdef __cplusplus
23extern "C" {
24#endif // __cplusplus
25
26/**
27 * A partition within OTP memory.
28 */
30 /**
31 * Vendor test partition.
32 *
33 * This is reserved for manufacturing smoke checks. The OTP wrapper
34 * control logic inside prim_otp is allowed to read/write to this
35 * region. ECC uncorrectable errors seen on the functional prim_otp
36 * interface will not lead to an alert for this partition.
37 * Instead, such errors will be reported as correctable ECC errors.
38 */
40 /**
41 * Software configuration partition.
42 *
43 * This is for device-specific calibration data, e.g, clock, LDO, RNG,
44 * and configuration settings set by the ROM.
45 */
47 /**
48 * Software configuration partition.
49 *
50 * This contains data that changes software behavior in the ROM, for
51 * example enabling defensive features in ROM or selecting failure
52 * modes if verification fails.
53 */
55#if defined(OPENTITAN_IS_EARLGREY)
56 /**
57 * This OTP partition is used to store four P-256 keys and four Sphincs+ keys.
58 *
59 * The partition requires 464
60 * bytes of software visible storage. The partition is
61 * locked at manufacturing time to protect against
62 * malicious write attempts.
63 */
64 kDifOtpCtrlPartitionRotCreatorAuthCodesign,
65 /**
66 * This OTP partition is used to capture the state of each key slot.
67 *
68 * Each key can be in one of the
69 * following states: BLANK, ENABLED, DISABLED. The
70 * encoded values are such that transitions between
71 * BLANK -> ENABLED -> DISABLED are possible without
72 * causing ECC errors (this is a mechanism similar to
73 * how we manage life cycle state transitions). The
74 * partition is left unlocked to allow STATE updates in
75 * the field. The ROM_EXT is required to lock access to
76 * the OTP Direct Access Interface to prevent DoS
77 * attacks from malicious code executing on Silicon
78 * Owner partitions. DAI write locking is available in
79 * EarlGrey.
80 */
81 kDifOtpCtrlPartitionRotCreatorAuthState,
82#elif defined(OPENTITAN_IS_DARJEELING)
83 /**
84 * SW managed asset ownership states partition.
85 *
86 * Multibit enable value for the tracking the asset ownership states.
87 * Note that the states can be written multiple times in a device lifetime.
88 * The values to be written are engineered in the same way as the LC_CTRL
89 * state encoding words so that the ECC encoding remains valid even after
90 * updating the values.
91 *
92 * The constants can be found in the lc_ctrl_state_pkg.sv package.
93 *
94 * The programming order has to adhere to:
95 *
96 * OWNERSHIP_ST_RAW (factory all-zero state) ->
97 * OWNERSHIP_ST_LOCKED0 ->
98 * OWNERSHIP_ST_RELEASED0 ->
99 * ...
100 * OWNERSHIP_ST_SCRAPPED
101 *
102 * Note that if there are less than 4 slots available the higher slot states
103 * become logically equivalent to OWNERSHIP_SCRAPPED (firmware has to handle
104 * this correctly).
105 */
106 kDifOtpCtrlPartitionOwnershipSlotState,
107 /**
108 * Software managed creator partition.
109 *
110 */
111 kDifOtpCtrlPartitionRotCreatorAuth,
112 /**
113 * Software managed owner slot 0 partition.
114 *
115 */
116 kDifOtpCtrlPartitionRotOwnerAuthSlot0,
117 /**
118 * Software managed owner slot 1 partition.
119 *
120 */
121 kDifOtpCtrlPartitionRotOwnerAuthSlot1,
122 /**
123 * Software managed platform integrator slot 0 partition.
124 *
125 */
126 kDifOtpCtrlPartitionPlatIntegAuthSlot0,
127 /**
128 * Software managed platform integrator slot 1 partition.
129 *
130 */
131 kDifOtpCtrlPartitionPlatIntegAuthSlot1,
132 /**
133 * Software managed platform owner slot 0 partition.
134 *
135 */
136 kDifOtpCtrlPartitionPlatOwnerAuthSlot0,
137 /**
138 * Software managed platform owner slot 1 partition.
139 *
140 */
141 kDifOtpCtrlPartitionPlatOwnerAuthSlot1,
142 /**
143 * Software managed platform owner slot 2 partition.
144 *
145 */
146 kDifOtpCtrlPartitionPlatOwnerAuthSlot2,
147 /**
148 * Software managed platform owner slot 3 partition.
149 *
150 */
151 kDifOtpCtrlPartitionPlatOwnerAuthSlot3,
152 /**
153 * Anti-replay protection Strike Counters partition.
154 *
155 */
156 kDifOtpCtrlPartitionExtNvm,
157 /**
158 * ROM Patch Code section.
159 *
160 * May contain multiple signed ROM2 patches.
161 */
162 kDifOtpCtrlPartitionRomPatch,
163#else
164#error "dif_otp_ctrl does not support this top"
165#endif
166 /**
167 * Hardware configuration 0 partition.
168 *
169 * This contains a device identifier and manufacturing state.
170 */
172 /**
173 * Hardware configuration 1 partition.
174 *
175 * This contains several hardware feature switches.
176 */
178 /**
179 * Secret partition 0.
180 *
181 * This contains TEST lifecycle unlock tokens.
182 */
184 /**
185 * Secret partition 1.
186 *
187 * This contains SRAM and flash scrambling keys.
188 */
190 /**
191 * Secret partition 2.
192 *
193 * This contains RMA unlock token, creator root key, and creator seed.
194 */
196 /**
197 * Secret partition 3.
198 *
199 * On Darjeeling, this contains the owner seed. On Earlgrey, this contains
200 * the field entropy.
201 */
203 /**
204 * Lifecycle partition.
205 *
206 * This contains lifecycle transition count and state. This partition
207 * cannot be locked since the life cycle state needs to advance to RMA
208 * in-field. Note that while this partition is not marked secret, it
209 * is not readable nor writeable via the DAI. Only the LC controller
210 * can access this partition, and even via the LC controller it is not
211 * possible to read the raw manufacturing life cycle state in encoded
212 * form, since that encoding is considered a netlist secret. The LC
213 * controller only exposes a decoded version of this state.
214 */
216
217 /**
218 * This is not a partition; rather, it represents the total number of
219 * partitions.
220 */
222
223 /**
224 * The following two are not partitions; rather they represent error codes
225 * that have a corresponding entry in dif_otp_ctrl_status_t.causes.
226 */
228 kDifOtpCtrlPartitionLciError,
229
230 /**
231 * This is not a partition; rather, it represents the total number of entries
232 * in dif_otp_ctrl_status_t.causes.
233 */
235
237
238/**
239 * Runtime configuration for OTP.
240 *
241 * This struct describes runtime information for one-time configuration of the
242 * hardware.
243 */
244typedef struct dif_otp_ctrl_config {
245 /**
246 * The timeout for an integrity or consistency check to succeed, in cycles.
247 *
248 * 100'000 is recommended as a minimum safe value.
249 */
251 /**
252 * A mask for the pseudo-random integrity check period.
253 *
254 * The value of this mask limits the period of the integrity check; when the
255 * pseudo-random period is computed, this mask is applied to limit it. For
256 * example, a value of 0x3'ffff would correspond to a maximum period of about
257 * 2.8s at 24MHz.
258 *
259 * A value of zero disables the check.
260 */
262 /**
263 * A mask for the pseudo-random consistency check period.
264 *
265 * The value of this mask limits the period of the consistency check; when the
266 * pseudo-random period is computed, this mask is applied to limit it. For
267 * example, a value of 0x3ff'ffff would correspond to a maximum period of
268 * about 716s at 24MHz.
269 *
270 * A value of zero disables the check.
271 */
274
275/**
276 * A hardware-level status code.
277 */
279 // Note that these enum variants are intended as bit indices, so
280 // their values should not be randomized.
281 /**
282 * Indicates that at least one partition raised an error.
283 */
285 /**
286 * Indicates an error occurred in the direct access interface.
287 */
289 /**
290 * Indicates an error occurred in the lifecycle interface.
291 */
293 /**
294 * Indicates that an integrity or consistency check has timed out.
295 *
296 * This error is unrecoverable.
297 */
299 /**
300 * Indicates that the LFSR that generates pseudo-random integrity and
301 * consistency checks is in a bad state.
302 *
303 * This error is unrecoverable.
304 */
306 /**
307 * Indicates that the scrambling hardware is in a bad state.
308 *
309 * This error is unrecoverable.
310 */
312 /**
313 * Indicates that the key derivation hardware is in a bad state.
314 *
315 * This error is unrecoverable.
316 */
318 /**
319 * Indicates a bus integrity error.
320 *
321 * This error will raise an alert.
322 */
324 /**
325 * Indicates that the direct access interface is idle.
326 */
328 /**
329 * Indicates that an integrity or consistency check is currently pending.
330 */
333
334/**
335 * A hardware-level error code, associated with a particular error defined in
336 * `dif_otp_ctrl_status_t`.
337 */
338typedef enum dif_otp_ctrl_error {
339 /**
340 * Indicates no error.
341 */
343 /**
344 * Indicates that an OTP macro command was invalid or did not
345 * complete successfully.
346 *
347 * This error indicates non-recoverable hardware malfunction.
348 */
350 /**
351 * Indicates a recoverable error during a read operation.
352 *
353 * A followup read should work as expected.
354 */
356 /**
357 * Indicates an unrecoverable error during a read operation.
358 *
359 * This error indicates non-recoverable hardware malfunction.
360 */
362 /**
363 * Indicates that the blank write check failed during a write operation.
364 */
366 /**
367 * Indicates a locked memory region was accessed.
368 */
370 /**
371 * Indicates a parity, integrity or consistency check failed in the buffer
372 * registers.
373 *
374 * This error indicates non-recoverable hardware malfunction.
375 */
377 /**
378 * Indicates that the FSM of the controller is in a bad state or that the
379 * controller's FSM has been moved into its terminal state due to escalation
380 * via the alert subsystem.
381 *
382 * This error indicates that the device has been glitched by an attacker.
383 */
386
387/**
388 * The overall status of the OTP controller.
389 *
390 * See `dif_otp_ctrl_get_status()`.
391 */
392typedef struct dif_otp_ctrl_status {
393 /**
394 * Currently active statuses, given as a bit vector. To check whether a
395 * particular status code was returned, write
396 *
397 * bool has_code = (status.codes >> kMyStatusCode) & 1;
398 *
399 * Note that it is possible to quickly check that the controller is idle and
400 * error-free by writing
401 *
402 * bool is_ok = status.codes == (1 << kDifOtpStatusCodeDaiIdle);
403 *
404 * Note this mapes to the "status" hw register.
405 */
406 uint32_t codes;
407 /**
408 * A list of root causes for each partition as well as for DAI and LCI.
409 * dif_otp_ctrl_partition_t can be used for indexing.
410 */
413
414/**
415 * Configures OTP with runtime information.
416 *
417 * This function should need to be called at most once for the lifetime of
418 * `otp`.
419 *
420 * @param otp An OTP handle.
421 * @param config Runtime configuration parameters.
422 * @return The result of the operation.
423 */
426 dif_otp_ctrl_config_t config);
427
428/**
429 * Runs an integrity check on the OTP hardware.
430 *
431 * This function can be used to trigger an integrity check independent of the
432 * pseudo-random hardware-generated checks.
433 *
434 * @param otp An OTP handle.
435 * @return The result of the operation.
436 */
439
440/**
441 * Runs a consistency check on the OTP hardware.
442 *
443 * This function can be used to trigger a consistency check independent of the
444 * pseudo-random hardware-generated checks.
445 *
446 * @param otp An OTP handle.
447 * @return The result of the operation.
448 */
451
452/**
453 * Locks out access to the direct access interface registers.
454 *
455 * This function is idempotent: calling it while functionality is locked will
456 * have no effect and return `kDifOk`.
457 *
458 * @param otp An OTP handle.
459 * @return The result of the operation.
460 */
463
464/**
465 * Checks whether access to the direct access interface is locked.
466 *
467 * Note that besides locking the DAI out until the next reset using the
468 * dif_otp_ctrl_dai_lock function, the DAI is also temporarily locked by the
469 * HW itself when it is busy processing a DAI command. In such a case, the
470 * kDifOtpCtrlStatusCodeDaiIdle status bit will be set to 0 as well.
471 *
472 * @param otp An OTP handle.
473 * @param[out] is_locked Out-param for the locked state.
474 * @return The result of the operation.
475 */
478 bool *is_locked);
479
480/**
481 * Locks out `dif_otp_ctrl_configure()` function.
482 *
483 * This function is idempotent: calling it while functionality is locked will
484 * have no effect and return `kDifOk`.
485 *
486 * @param otp An OTP handle.
487 * @return The result of the operation.
488 */
491
492/**
493 * Checks whether `dif_otp_ctrl_configure()` function is locked-out.
494 *
495 * @param otp An OTP handle.
496 * @param[out] is_locked Out-param for the locked state.
497 * @return The result of the operation.
498 */
501 bool *is_locked);
502
503/**
504 * Locks out `dif_otp_ctrl_check_*()` functions.
505 *
506 * This function is idempotent: calling it while functionality is locked will
507 * have no effect and return `kDifOk`.
508 *
509 * @param otp An OTP handle.
510 * @return The result of the operation.
511 */
514
515/**
516 * Checks whether the `dif_otp_ctrl_check_*()` functions are locked-out.
517 *
518 * @param otp An OTP handle.
519 * @param[out] is_locked Out-param for the locked state.
520 * @return The result of the operation.
521 */
524 bool *is_locked);
525
526/**
527 * Locks out reads to a SW partition.
528 *
529 * This function should only be called on SW partitions; doing otherwise will
530 * return an error.
531 *
532 * Note that this is distinct from the write-locking performed by calling
533 * `dif_otp_ctrl_dai_digest()`. In particular, the effects of this function will
534 * not persist past a system reset.
535 *
536 * This function is idempotent: calling it while functionality is locked will
537 * have no effect and return `kDifOk`.
538 *
539 * @param otp An OTP handle.
540 * @param partition The SW partition to lock.
541 * @return The result of the operation.
542 */
545 dif_otp_ctrl_partition_t partition);
546
547/**
548 * Checks whether reads to a SW partition are locked out.
549 *
550 * This function should only be called on SW partitions; doing otherwise will
551 * return an error.
552 *
553 * @param otp An OTP handle.
554 * @param partition the SW partition to check for locking.
555 * @param[out] is_locked Out-param for the locked state.
556 * @return The result of the operation.
557 */
560 dif_otp_ctrl_partition_t partition,
561 bool *is_locked);
562
563/**
564 * Gets the current status of the OTP controller.
565 *
566 * @param otp An OTP handle.
567 * @param[out] status Out-param for the controller's status.
568 * @return The result of the operation.
569 */
573
574/**
575 * Calculates a `relative_address` with respect to a `partition` start
576 * address.
577 *
578 * @param partition The partition to use to calculate the reference start
579 * address.
580 * @param abs_address Input address relative to the OTP memory start address.
581 * @param[out] relative_address The result relative address with respect to the
582 * `partition` start address.
583 * @return The result of the operation.
584 */
587 uint32_t abs_address,
588 uint32_t *relative_address);
589
590/**
591 * Schedules a read on the Direct Access Interface.
592 *
593 * Reads are performed relative to a partition; `address` should be given
594 * relative to the start of `partition`. An error is returned for out-of-bounds
595 * access.
596 *
597 * Furthermore, `address` must be well-aligned: it must be four-byte aligned for
598 * normal partitions and eight-byte-aligned for secret partitions. An error is
599 * returned for unaligned access.
600 *
601 * @param otp An OTP handle.
602 * @param partition The partition to read from.
603 * @param address A partition-relative address to read from.
604 * @return The result of the operation.
605 */
608 dif_otp_ctrl_partition_t partition,
609 uint32_t address);
610
611/**
612 * Gets the result of a completed 32-bit read operation on the Direct Access
613 * Interface.
614 *
615 * Whether this function or its 64-bit variant should be called is dependent on
616 * the most recent partition read from.
617 *
618 * @param otp An OTP handle.
619 * @param[out] value Out-param for the read value.
620 * @return The result of the operation.
621 */
624 uint32_t *value);
625
626/**
627 * Gets the result of a completed 64-bit read operation on the Direct Access
628 * Interface.
629 *
630 * Whether this function or its 32-bit variant should be called is dependent on
631 * the most recent partition read from.
632 *
633 * @param otp An OTP handle.
634 * @param[out] value Out-param for the read value.
635 * @return The result of the operation.
636 */
639 uint64_t *value);
640
641/**
642 * Schedules a 32-bit write on the Direct Access Interface.
643 *
644 * Writes are performed relative to a partition; `address` should be given
645 * relative to the start of `partition`. An error is returned for out-of-bounds
646 * access.
647 *
648 * Furthermore, `address` must be four-byte-aligned, and `partition` must not be
649 * a secret partition. An error is returned if neither condition is met.
650 *
651 * Note that this function cannot be used to program the digest at the end of a
652 * `SW` partition; `dif_otp_ctrl_dai_digest()` must be used instead.
653 *
654 * @param otp An OTP handle.
655 * @param partition The partition to program.
656 * @param address A partition-relative address to program.
657 * @param value The value to program into the OTP.
658 * @return The result of the operation.
659 */
662 dif_otp_ctrl_partition_t partition,
663 uint32_t address, uint32_t value);
664
665/**
666 * Schedules a 64-bit write on the Direct Access Interface.
667 *
668 * Writes are performed relative to a partition; `address` should be given
669 * relative to the start of `partition`. An error is returned for out-of-bounds
670 * access.
671 *
672 * Furthermore, `address` must be eight-byte-aligned, and `partition` must be
673 * a secret partition. An error is returned if neither condition is met.
674 *
675 * @param otp An OTP handle.
676 * @param partition The partition to program.
677 * @param address A partition-relative address to program.
678 * @param value The value to program into the OTP.
679 * @return The result of the operation.
680 */
683 dif_otp_ctrl_partition_t partition,
684 uint32_t address, uint64_t value);
685
686/**
687 * Schedules a hardware digest operation on the Direct Access Interface.
688 *
689 * **This operation will also lock writes for the given partition.**
690 *
691 * If `partition` is a SW partition, `digest` must be non-zero; if it is a
692 * partition with a hardware-managed digest, `digest` *must* be zero (since the
693 * digest will be generated by the hardware). An error is returned if either
694 * precondition is not met.
695 *
696 * This function does not work with the lifecycle state partition, and will
697 * return an error in that case.
698 *
699 * @param otp An OTP handle.
700 * @param partition The partition to digest and lock.
701 * @param digest The digest to program (for SW partitions).
702 * @return The result of the operation.
703 */
706 dif_otp_ctrl_partition_t partition,
707 uint64_t digest);
708
709/**
710 * Checks if the digest value for the given partition has been computed. Once a
711 * digest has been computed for a partition, the partition is write-locked
712 * (additionally, read-locked if the partition is secret).
713 *
714 * The lifecycle partition does not have a digest, and checking if this region
715 * has a computed digest will return an error.
716 *
717 * @param otp An OTP handle.
718 * @param partition The partition to check the digest of.
719 * @param[out] is_computed Indicates if the digest has been computed.
720 * @return The result of the operation.
721 */
724 dif_otp_ctrl_partition_t partition,
725 bool *is_computed);
726
727/**
728 * Gets the buffered digest value for the given partition.
729 *
730 * Note that this value is only updated when the device is reset; if the digest
731 * has not been computed yet, or has been computed but not since device reset,
732 * this function will return an error.
733 *
734 * The lifecycle partition does not have a digest and will result in an error
735 * being returned.
736 *
737 * @param otp An OTP handle.
738 * @param partition The partition to get a digest for.
739 * @param[out] digest Out-param for the digest.
740 * @return The result of the operation.
741 */
744 dif_otp_ctrl_partition_t partition,
745 uint64_t *digest);
746
747/**
748 * Performs a memory-mapped read of the given partition, if it supports them.
749 *
750 * In particular, this function will read `len` words, starting at `address`,
751 * relative to the start of `partition`.
752 *
753 * The same caveats for `dif_otp_ctrl_dai_read_start()` apply to `address`; in
754 * addition, `address + len` must also be in-range and must not overflow.
755 *
756 * This function will block until the read completes, unlike Direct Access
757 * Interface functions.
758 *
759 * @param otp An OTP handle.
760 * @param partition The partition to read from.
761 * @param address A partition-relative address to read from.
762 * @param[out] buf A buffer of words to write read values to.
763 * @param len The number of words to read.
764 * @return The result of the operation.
765 */
768 dif_otp_ctrl_partition_t partition,
769 uint32_t address, uint32_t *buf,
770 size_t len);
771
772#ifdef __cplusplus
773} // extern "C"
774#endif // __cplusplus
775
776#endif // OPENTITAN_SW_DEVICE_LIB_DIF_DIF_OTP_CTRL_H_