Software APIs
sw
device
lib
dif
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
// DO NOT EDIT THIS FILE DIRECTLY.
5
// It has been generated with ./util/design/gen-otp-mmap.py
6
7
#ifndef OPENTITAN_SW_DEVICE_LIB_DIF_DIF_OTP_CTRL_H_
8
#define OPENTITAN_SW_DEVICE_LIB_DIF_DIF_OTP_CTRL_H_
9
10
/**
11
* @file
12
* @brief <a href="/hw/ip/otp_ctrl/doc/">OTP Controller</a> Device Interface
13
* Functions
14
*/
15
16
#include <
stdint.h
>
17
18
#include "
sw/device/lib/base/macros.h
"
19
#include "
sw/device/lib/base/mmio.h
"
20
#include "
sw/device/lib/dif/dif_base.h
"
21
22
#include "
sw/device/lib/dif/autogen/dif_otp_ctrl_autogen.h
"
23
24
// Header Extern Guard (so header can be used from C and C++)
25
#ifdef __cplusplus
26
extern
"C"
{
27
#endif // __cplusplus
28
29
/**
30
* A partition within OTP memory.
31
*/
32
typedef
enum
dif_otp_ctrl_partition
{
33
/**
34
* Vendor test partition.
35
*
36
* This is reserved for manufacturing smoke checks. The OTP wrapper
37
* control logic inside prim_otp is allowed to read/write to this
38
* region. ECC uncorrectable errors seen on the functional prim_otp
39
* interface will not lead to an alert for this partition.
40
* Instead, such errors will be reported as correctable ECC errors.
41
*/
42
kDifOtpCtrlPartitionVendorTest
,
43
/**
44
* Software configuration partition.
45
*
46
* This is for device-specific calibration data. For example, clock,
47
* LDO, RNG.
48
*/
49
kDifOtpCtrlPartitionCreatorSwCfg
,
50
/**
51
* Software configuration partition.
52
*
53
* This contains data that changes software behavior in the ROM, for
54
* example enabling defensive features in ROM or selecting failure
55
* modes if verification fails.
56
*/
57
kDifOtpCtrlPartitionOwnerSwCfg
,
58
/**
59
* This OTP partition is used to store four P-256 keys and four Sphincs+ keys.
60
*
61
* The partition requires 464
62
* bytes of software visible storage. The partition is
63
* locked at manufacturing time to protect against
64
* malicious write attempts.
65
*/
66
kDifOtpCtrlPartitionRotCreatorAuthCodesign
,
67
/**
68
* This OTP partition is used to capture the state of each key slot.
69
*
70
* Each key can be in one of the
71
* following states: BLANK, ENABLED, DISABLED. The
72
* encoded values are such that transitions between
73
* BLANK -> ENABLED -> DISABLED are possible without
74
* causing ECC errors (this is a mechanism similar to
75
* how we manage life cycle state transitions). The
76
* partition is left unlocked to allow STATE updates in
77
* the field. The ROM_EXT is required to lock access to
78
* the OTP Direct Access Interface to prevent DoS
79
* attacks from malicious code executing on Silicon
80
* Owner partitions. DAI write locking is available in
81
* EarlGrey.
82
*/
83
kDifOtpCtrlPartitionRotCreatorAuthState
,
84
/**
85
* Hardware configuration 0 partition.
86
*
87
* This contains
88
* - DEVICE_ID: Unique device identifier.
89
* - MANUF_STATE: Vector for capturing the manufacturing status.
90
*/
91
kDifOtpCtrlPartitionHwCfg0
,
92
/**
93
* Hardware configuration 1 partition.
94
*
95
* This contains
96
* - EN_SRAM_IFETCH: Enable / disable execute from SRAM CSR switch.
97
* - EN_CSRNG_SW_APP_READ: This input efuse is used to enable access to the
98
* NIST internal state per instance.
99
* - DIS_RV_DM_LATE_DEBUG: Setting this to true bypasses the late debug
100
* enablement of RV_DM in the DEV life cycle state.
101
*/
102
kDifOtpCtrlPartitionHwCfg1
,
103
/**
104
* Secret partition 0.
105
*
106
* This contains TEST lifecycle unlock tokens.
107
*/
108
kDifOtpCtrlPartitionSecret0
,
109
/**
110
* Secret partition 1.
111
*
112
* This contains SRAM and flash scrambling keys.
113
*/
114
kDifOtpCtrlPartitionSecret1
,
115
/**
116
* Secret partition 2.
117
*
118
* This contains RMA unlock token, creator root key, and creator seed.
119
*/
120
kDifOtpCtrlPartitionSecret2
,
121
/**
122
* Lifecycle partition.
123
*
124
* This contains lifecycle transition count and state. This partition
125
* cannot be locked since the life cycle state needs to advance to RMA
126
* in-field. Note that while this partition is not marked secret, it
127
* is not readable nor writeable via the DAI. Only the LC controller
128
* can access this partition, and even via the LC controller it is not
129
* possible to read the raw manufacturing life cycle state in encoded
130
* form, since that encoding is considered a netlist secret. The LC
131
* controller only exposes a decoded version of this state.
132
*/
133
kDifOtpCtrlPartitionLifeCycle
,
134
}
dif_otp_ctrl_partition_t
;
135
136
/**
137
* Runtime configuration for OTP.
138
*
139
* This struct describes runtime information for one-time configuration of the
140
* hardware.
141
*/
142
typedef
struct
dif_otp_ctrl_config
{
143
/**
144
* The timeout for an integrity or consistency check to succeed, in cycles.
145
*
146
* 100'000 is recommended as a minimum safe value.
147
*/
148
uint32_t
check_timeout
;
149
/**
150
* A mask for the pseudo-random integrity check period.
151
*
152
* The value of this mask limits the period of the integrity check; when the
153
* pseudo-random period is computed, this mask is applied to limit it. For
154
* example, a value of 0x3'ffff would correspond to a maximum period of about
155
* 2.8s at 24MHz.
156
*
157
* A value of zero disables the check.
158
*/
159
uint32_t
integrity_period_mask
;
160
/**
161
* A mask for the pseudo-random consistency check period.
162
*
163
* The value of this mask limits the period of the consistency check; when the
164
* pseudo-random period is computed, this mask is applied to limit it. For
165
* example, a value of 0x3ff'ffff would correspond to a maximum period of
166
* about 716s at 24MHz.
167
*
168
* A value of zero disables the check.
169
*/
170
uint32_t
consistency_period_mask
;
171
}
dif_otp_ctrl_config_t
;
172
173
/**
174
* A hardware-level status code.
175
*/
176
typedef
enum
dif_otp_ctrl_status_code
{
177
// NOTE: This enum's API *requires* that all "error"-like codes (that is,
178
// those which have associated cause registers) be a prefix of the enum
179
// values.
180
//
181
// Note furthermore that these enum variants are intended as bit indices, so
182
// their values should not be randomized.
183
/**
184
* Indicates an error occurred in the `VendorTest` partition.
185
*/
186
kDifOtpCtrlStatusCodeVendorTestError
= 0,
187
/**
188
* Indicates an error occurred in the `CreatorSwCfg` partition.
189
*/
190
kDifOtpCtrlStatusCodeCreatorSwCfgError
,
191
/**
192
* Indicates an error occurred in the `OwnerSwCfg` partition.
193
*/
194
kDifOtpCtrlStatusCodeOwnerSwCfgError
,
195
/**
196
* Indicates an error occurred in the `RotCreatorAuthCodesign` partition.
197
*/
198
kDifOtpCtrlStatusCodeRotCreatorAuthCodesignError
,
199
/**
200
* Indicates an error occurred in the `RotCreatorAuthState` partition.
201
*/
202
kDifOtpCtrlStatusCodeRotCreatorAuthStateError
,
203
/**
204
* Indicates an error occurred in the `HwCfg0` partition.
205
*/
206
kDifOtpCtrlStatusCodeHwCfg0Error
,
207
/**
208
* Indicates an error occurred in the `HwCfg1` partition.
209
*/
210
kDifOtpCtrlStatusCodeHwCfg1Error
,
211
/**
212
* Indicates an error occurred in the `Secret0` partition.
213
*/
214
kDifOtpCtrlStatusCodeSecret0Error
,
215
/**
216
* Indicates an error occurred in the `Secret1` partition.
217
*/
218
kDifOtpCtrlStatusCodeSecret1Error
,
219
/**
220
* Indicates an error occurred in the `Secret2` partition.
221
*/
222
kDifOtpCtrlStatusCodeSecret2Error
,
223
/**
224
* Indicates an error occurred in the `LifeCycle` partition.
225
*/
226
kDifOtpCtrlStatusCodeLifeCycleError
,
227
/**
228
* Indicates an error occurred in the direct access interface.
229
*/
230
kDifOtpCtrlStatusCodeDaiError
,
231
/**
232
* Indicates an error occurred in the lifecycle interface.
233
*/
234
kDifOtpCtrlStatusCodeLciError
,
235
/**
236
* This is not a status code; rather, it represents the last error code which
237
* has a corresponding "cause" register.
238
*
239
* See `dif_otp_ctrl_status_t` for information on how to use this.
240
*/
241
kDifOtpCtrlStatusCodeHasCauseLast
=
kDifOtpCtrlStatusCodeLciError
,
242
/**
243
* Indicates that an integrity or consistency check has timed out.
244
*
245
* This error is unrecoverable.
246
*/
247
kDifOtpCtrlStatusCodeTimeoutError
,
248
/**
249
* Indicates that the LFSR that generates pseudo-random integrity and
250
* consistency checks is in a bad state.
251
*
252
* This error is unrecoverable.
253
*/
254
kDifOtpCtrlStatusCodeLfsrError
,
255
/**
256
* Indicates that the scrambling hardware is in a bad state.
257
*
258
* This error is unrecoverable.
259
*/
260
kDifOtpCtrlStatusCodeScramblingError
,
261
/**
262
* Indicates that the key derivation hardware is in a bad state.
263
*
264
* This error is unrecoverable.
265
*/
266
kDifOtpCtrlStatusCodeKdfError
,
267
/**
268
* Indicates a bus integrity error.
269
*
270
* This error will raise an alert.
271
*/
272
kDifOtpCtrlStatusCodeBusIntegError
,
273
/**
274
* Indicates that the direct access interface is idle.
275
*/
276
kDifOtpCtrlStatusCodeDaiIdle
,
277
/**
278
* Indicates that an integrity or consistency check is currently pending.
279
*/
280
kDifOtpCtrlStatusCodeCheckPending
,
281
}
dif_otp_ctrl_status_code_t
;
282
283
/**
284
* A hardware-level error code, associated with a particular error defined in
285
* `dif_otp_ctrl_status_t`.
286
*/
287
typedef
enum
dif_otp_ctrl_error
{
288
/**
289
* Indicates no error.
290
*/
291
kDifOtpCtrlErrorOk
,
292
/**
293
* Indicates that an OTP macro command was invalid or did not
294
* complete successfully.
295
*
296
* This error indicates non-recoverable hardware malfunction.
297
*/
298
kDifOtpCtrlErrorMacroUnspecified
,
299
/**
300
* Indicates a recoverable error during a read operation.
301
*
302
* A followup read should work as expected.
303
*/
304
kDifOtpCtrlErrorMacroRecoverableRead
,
305
/**
306
* Indicates an unrecoverable error during a read operation.
307
*
308
* This error indicates non-recoverable hardware malfunction.
309
*/
310
kDifOtpCtrlErrorMacroUnrecoverableRead
,
311
/**
312
* Indicates that the blank write check failed during a write operation.
313
*/
314
kDifOtpCtrlErrorMacroBlankCheckFailed
,
315
/**
316
* Indicates a locked memory region was accessed.
317
*/
318
kDifOtpCtrlErrorLockedAccess
,
319
/**
320
* Indicates a parity, integrity or consistency check failed in the buffer
321
* registers.
322
*
323
* This error indicates non-recoverable hardware malfunction.
324
*/
325
kDifOtpCtrlErrorBackgroundCheckFailed
,
326
/**
327
* Indicates that the FSM of the controller is in a bad state or that the
328
* controller's FSM has been moved into its terminal state due to escalation
329
* via the alert subsystem.
330
*
331
* This error indicates that the device has been glitched by an attacker.
332
*/
333
kDifOtpCtrlErrorFsmBadState
,
334
}
dif_otp_ctrl_error_t
;
335
336
/**
337
* The overall status of the OTP controller.
338
*
339
* See `dif_otp_ctrl_get_status()`.
340
*/
341
typedef
struct
dif_otp_ctrl_status
{
342
/**
343
* Currently active statuses, given as a bit vector. To check whether a
344
* particular status code was returned, write
345
*
346
* bool has_code = (status.codes >> kMyStatusCode) & 1;
347
*
348
* Note that it is possible to quickly check that the controller is idle and
349
* error-free by writing
350
*
351
* bool is_ok = status.codes == (1 << kDifOtpStatusCodeDaiIdle);
352
*/
353
uint32_t
codes
;
354
/**
355
* A list of root causes for each error status code.
356
*
357
* If the error status code `error` is present in `codes`, and
358
* `error <= kDifOtpCtrlStatusCodeHasCauseLast`, then `causes[error]`
359
* will contain its root cause.
360
*/
361
dif_otp_ctrl_error_t
causes
[
kDifOtpCtrlStatusCodeHasCauseLast
+ 1];
362
}
dif_otp_ctrl_status_t
;
363
364
/**
365
* Configures OTP with runtime information.
366
*
367
* This function should need to be called at most once for the lifetime of
368
* `otp`.
369
*
370
* @param otp An OTP handle.
371
* @param config Runtime configuration parameters.
372
* @return The result of the operation.
373
*/
374
OT_WARN_UNUSED_RESULT
375
dif_result_t
dif_otp_ctrl_configure
(
const
dif_otp_ctrl_t
*otp,
376
dif_otp_ctrl_config_t
config);
377
378
/**
379
* Runs an integrity check on the OTP hardware.
380
*
381
* This function can be used to trigger an integrity check independent of the
382
* pseudo-random hardware-generated checks.
383
*
384
* @param otp An OTP handle.
385
* @return The result of the operation.
386
*/
387
OT_WARN_UNUSED_RESULT
388
dif_result_t
dif_otp_ctrl_check_integrity
(
const
dif_otp_ctrl_t
*otp);
389
390
/**
391
* Runs a consistency check on the OTP hardware.
392
*
393
* This function can be used to trigger a consistency check independent of the
394
* pseudo-random hardware-generated checks.
395
*
396
* @param otp An OTP handle.
397
* @return The result of the operation.
398
*/
399
OT_WARN_UNUSED_RESULT
400
dif_result_t
dif_otp_ctrl_check_consistency
(
const
dif_otp_ctrl_t
*otp);
401
402
/**
403
* Locks out access to the direct access interface registers.
404
*
405
* This function is idempotent: calling it while functionality is locked will
406
* have no effect and return `kDifOk`.
407
*
408
* @param otp An OTP handle.
409
* @return The result of the operation.
410
*/
411
OT_WARN_UNUSED_RESULT
412
dif_result_t
dif_otp_ctrl_lock_dai
(
const
dif_otp_ctrl_t
*otp);
413
414
/**
415
* Checks whether access to the direct access interface is locked.
416
*
417
* Note that besides locking the DAI out until the next reset using the
418
* dif_otp_ctrl_lock_dai function, the DAI is also temporarily locked by the
419
* HW itself when it is busy processing a DAI command. In such a case, the
420
* kDifOtpCtrlStatusCodeDaiIdle status bit will be set to 0 as well.
421
*
422
* @param otp An OTP handle.
423
* @param[out] is_locked Out-param for the locked state.
424
* @return The result of the operation.
425
*/
426
OT_WARN_UNUSED_RESULT
427
dif_result_t
dif_otp_ctrl_dai_is_locked
(
const
dif_otp_ctrl_t
*otp,
428
bool
*is_locked);
429
430
/**
431
* Locks out `dif_otp_ctrl_configure()` function.
432
*
433
* This function is idempotent: calling it while functionality is locked will
434
* have no effect and return `kDifOk`.
435
*
436
* @param otp An OTP handle.
437
* @return The result of the operation.
438
*/
439
OT_WARN_UNUSED_RESULT
440
dif_result_t
dif_otp_ctrl_lock_config
(
const
dif_otp_ctrl_t
*otp);
441
442
/**
443
* Checks whether `dif_otp_ctrl_configure()` function is locked-out.
444
*
445
* @param otp An OTP handle.
446
* @param[out] is_locked Out-param for the locked state.
447
* @return The result of the operation.
448
*/
449
OT_WARN_UNUSED_RESULT
450
dif_result_t
dif_otp_ctrl_config_is_locked
(
const
dif_otp_ctrl_t
*otp,
451
bool
*is_locked);
452
453
/**
454
* Locks out `dif_otp_ctrl_check_*()` functions.
455
*
456
* This function is idempotent: calling it while functionality is locked will
457
* have no effect and return `kDifOk`.
458
*
459
* @param otp An OTP handle.
460
* @return The result of the operation.
461
*/
462
OT_WARN_UNUSED_RESULT
463
dif_result_t
dif_otp_ctrl_lock_check_trigger
(
const
dif_otp_ctrl_t
*otp);
464
465
/**
466
* Checks whether the `dif_otp_ctrl_check_*()` functions are locked-out.
467
*
468
* @param otp An OTP handle.
469
* @param[out] is_locked Out-param for the locked state.
470
* @return The result of the operation.
471
*/
472
OT_WARN_UNUSED_RESULT
473
dif_result_t
dif_otp_ctrl_check_trigger_is_locked
(
const
dif_otp_ctrl_t
*otp,
474
bool
*is_locked);
475
476
/**
477
* Locks out reads to a SW partition.
478
*
479
* This function should only be called on SW partitions; doing otherwise will
480
* return an error.
481
*
482
* Note that this is distinct from the write-locking performed by calling
483
* `dif_otp_ctrl_dai_digest()`. In particular, the effects of this function will
484
* not persist past a system reset.
485
*
486
* This function is idempotent: calling it while functionality is locked will
487
* have no effect and return `kDifOk`.
488
*
489
* @param otp An OTP handle.
490
* @param partition The SW partition to lock.
491
* @return The result of the operation.
492
*/
493
OT_WARN_UNUSED_RESULT
494
dif_result_t
dif_otp_ctrl_lock_reading
(
const
dif_otp_ctrl_t
*otp,
495
dif_otp_ctrl_partition_t
partition);
496
497
/**
498
* Checks whether reads to a SW partition are locked out.
499
*
500
* This function should only be called on SW partitions; doing otherwise will
501
* return an error.
502
*
503
* @param otp An OTP handle.
504
* @param partition the SW partition to check for locking.
505
* @param[out] is_locked Out-param for the locked state.
506
* @return The result of the operation.
507
*/
508
OT_WARN_UNUSED_RESULT
509
dif_result_t
dif_otp_ctrl_reading_is_locked
(
const
dif_otp_ctrl_t
*otp,
510
dif_otp_ctrl_partition_t
partition,
511
bool
*is_locked);
512
513
/**
514
* Gets the current status of the OTP controller.
515
*
516
* @param otp An OTP handle.
517
* @param[out] status Out-param for the controller's status.
518
* @return The result of the operation.
519
*/
520
OT_WARN_UNUSED_RESULT
521
dif_result_t
dif_otp_ctrl_get_status
(
const
dif_otp_ctrl_t
*otp,
522
dif_otp_ctrl_status_t
*
status
);
523
524
/**
525
* Calculates a `relative_address` with respect to a `partition` start
526
* address.
527
*
528
* @param partition The partition to use to calculate the reference start
529
* address.
530
* @param abs_address Input address relative to the OTP memory start address.
531
* @param[out] relative_address The result relative address with respect to the
532
* `partition` start address.
533
* @return The result of the operation.
534
*/
535
OT_WARN_UNUSED_RESULT
536
dif_result_t
dif_otp_ctrl_relative_address
(
dif_otp_ctrl_partition_t
partition,
537
uint32_t abs_address,
538
uint32_t *relative_address);
539
540
/**
541
* Schedules a read on the Direct Access Interface.
542
*
543
* Reads are performed relative to a partition; `address` should be given
544
* relative to the start of `partition`. An error is returned for out-of-bounds
545
* access.
546
*
547
* Furthermore, `address` must be well-aligned: it must be four-byte aligned for
548
* normal partitions and eight-byte-aligned for secret partitions. An error is
549
* returned for unaligned access.
550
*
551
* @param otp An OTP handle.
552
* @param partition The partition to read from.
553
* @param address A partition-relative address to read from.
554
* @return The result of the operation.
555
*/
556
OT_WARN_UNUSED_RESULT
557
dif_result_t
dif_otp_ctrl_dai_read_start
(
const
dif_otp_ctrl_t
*otp,
558
dif_otp_ctrl_partition_t
partition,
559
uint32_t address);
560
561
/**
562
* Gets the result of a completed 32-bit read operation on the Direct Access
563
* Interface.
564
*
565
* Whether this function or its 64-bit variant should be called is dependent on
566
* the most recent partition read from.
567
*
568
* @param otp An OTP handle.
569
* @param[out] value Out-param for the read value.
570
* @return The result of the operation.
571
*/
572
OT_WARN_UNUSED_RESULT
573
dif_result_t
dif_otp_ctrl_dai_read32_end
(
const
dif_otp_ctrl_t
*otp,
574
uint32_t *value);
575
576
/**
577
* Gets the result of a completed 64-bit read operation on the Direct Access
578
* Interface.
579
*
580
* Whether this function or its 32-bit variant should be called is dependent on
581
* the most recent partition read from.
582
*
583
* @param otp An OTP handle.
584
* @param[out] value Out-param for the read value.
585
* @return The result of the operation.
586
*/
587
OT_WARN_UNUSED_RESULT
588
dif_result_t
dif_otp_ctrl_dai_read64_end
(
const
dif_otp_ctrl_t
*otp,
589
uint64_t *value);
590
591
/**
592
* Schedules a 32-bit write on the Direct Access Interface.
593
*
594
* Writes are performed relative to a partition; `address` should be given
595
* relative to the start of `partition`. An error is returned for out-of-bounds
596
* access.
597
*
598
* Furthermore, `address` must be four-byte-aligned, and `partition` must not be
599
* a secret partition. An error is returned if neither condition is met.
600
*
601
* Note that this function cannot be used to program the digest at the end of a
602
* `SW` partition; `dif_otp_ctrl_dai_digest()` must be used instead.
603
*
604
* @param otp An OTP handle.
605
* @param partition The partition to program.
606
* @param address A partition-relative address to program.
607
* @param value The value to program into the OTP.
608
* @return The result of the operation.
609
*/
610
OT_WARN_UNUSED_RESULT
611
dif_result_t
dif_otp_ctrl_dai_program32
(
const
dif_otp_ctrl_t
*otp,
612
dif_otp_ctrl_partition_t
partition,
613
uint32_t address, uint32_t value);
614
615
/**
616
* Schedules a 64-bit write on the Direct Access Interface.
617
*
618
* Writes are performed relative to a partition; `address` should be given
619
* relative to the start of `partition`. An error is returned for out-of-bounds
620
* access.
621
*
622
* Furthermore, `address` must be eight-byte-aligned, and `partition` must be
623
* a secret partition. An error is returned if neither condition is met.
624
*
625
* @param otp An OTP handle.
626
* @param partition The partition to program.
627
* @param address A partition-relative address to program.
628
* @param value The value to program into the OTP.
629
* @return The result of the operation.
630
*/
631
OT_WARN_UNUSED_RESULT
632
dif_result_t
dif_otp_ctrl_dai_program64
(
const
dif_otp_ctrl_t
*otp,
633
dif_otp_ctrl_partition_t
partition,
634
uint32_t address, uint64_t value);
635
636
/**
637
* Schedules a hardware digest operation on the Direct Access Interface.
638
*
639
* **This operation will also lock writes for the given partition.**
640
*
641
* If `partition` is a SW partition, `digest` must be non-zero; if it is a
642
* partition with a hardware-managed digest, `digest` *must* be zero (since the
643
* digest will be generated by the hardware). An error is returned if either
644
* precondition is not met.
645
*
646
* This function does not work with the lifecycle state partition, and will
647
* return an error in that case.
648
*
649
* @param otp An OTP handle.
650
* @param partition The partition to digest and lock.
651
* @param digest The digest to program (for SW partitions).
652
* @return The result of the operation.
653
*/
654
OT_WARN_UNUSED_RESULT
655
dif_result_t
dif_otp_ctrl_dai_digest
(
const
dif_otp_ctrl_t
*otp,
656
dif_otp_ctrl_partition_t
partition,
657
uint64_t digest);
658
659
/**
660
* Checks if the digest value for the given partition has been computed. Once a
661
* digest has been computed for a partition, the partition is write-locked
662
* (additionally, read-locked if the partition is secret).
663
*
664
* The lifecycle partition does not have a digest, and checking if this region
665
* has a computed digest will return an error.
666
*
667
* @param otp An OTP handle.
668
* @param partition The partition to check the digest of.
669
* @param[out] is_computed Indicates if the digest has been computed.
670
* @return The result of the operation.
671
*/
672
OT_WARN_UNUSED_RESULT
673
dif_result_t
dif_otp_ctrl_is_digest_computed
(
const
dif_otp_ctrl_t
*otp,
674
dif_otp_ctrl_partition_t
partition,
675
bool
*is_computed);
676
677
/**
678
* Gets the buffered digest value for the given partition.
679
*
680
* Note that this value is only updated when the device is reset; if the digest
681
* has not been computed yet, or has been computed but not since device reset,
682
* this function will return an error.
683
*
684
* The lifecycle partition does not have a digest and will result in an error
685
* being returned.
686
*
687
* @param otp An OTP handle.
688
* @param partition The partition to get a digest for.
689
* @param[out] digest Out-param for the digest.
690
* @return The result of the operation.
691
*/
692
OT_WARN_UNUSED_RESULT
693
dif_result_t
dif_otp_ctrl_get_digest
(
const
dif_otp_ctrl_t
*otp,
694
dif_otp_ctrl_partition_t
partition,
695
uint64_t *digest);
696
697
/**
698
* Performs a memory-mapped read of the given partition, if it supports them.
699
*
700
* In particular, this function will read `len` words, starting at `address`,
701
* relative to the start of `partition`.
702
*
703
* The same caveats for `dif_otp_ctrl_dai_read_start()` apply to `address`; in
704
* addition, `address + len` must also be in-range and must not overflow.
705
*
706
* This function will block until the read completes, unlike Direct Access
707
* Interface functions.
708
*
709
* @param otp An OTP handle.
710
* @param partition The partition to read from.
711
* @param address A partition-relative address to read from.
712
* @param[out] buf A buffer of words to write read values to.
713
* @param len The number of words to read.
714
* @return The result of the operation.
715
*/
716
OT_WARN_UNUSED_RESULT
717
dif_result_t
dif_otp_ctrl_read_blocking
(
const
dif_otp_ctrl_t
*otp,
718
dif_otp_ctrl_partition_t
partition,
719
uint32_t address, uint32_t *buf,
720
size_t
len);
721
722
#ifdef __cplusplus
723
}
// extern "C"
724
#endif // __cplusplus
725
726
#endif // OPENTITAN_SW_DEVICE_LIB_DIF_DIF_OTP_CTRL_H_
Return to
OpenTitan Documentation