Software APIs
boot_log.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_BOOT_LOG_H_
6 #define OPENTITAN_SW_DEVICE_SILICON_CREATOR_LIB_BOOT_LOG_H_
7 
8 #include <stdint.h>
9 
10 #include "sw/device/lib/base/macros.h"
11 #include "sw/device/silicon_creator/lib/boot_data.h"
12 #include "sw/device/silicon_creator/lib/chip_info.h"
13 #include "sw/device/silicon_creator/lib/drivers/hmac.h"
14 #include "sw/device/silicon_creator/lib/error.h"
15 #include "sw/device/silicon_creator/lib/nonce.h"
16 #include "sw/device/silicon_creator/lib/ownership/datatypes.h"
17 
18 #ifdef __cplusplus
19 extern "C" {
20 #endif
21 
22 /**
23  * The boot_log encodes information about how the chip booted.
24  */
25 typedef struct boot_log {
26  /** Digest to indicate validity of the boot_log. */
27  hmac_digest_t digest;
28  /** Identifier (`BLOG`). */
29  uint32_t identifier;
30  /** Chip version (from the ROM). */
31  chip_info_scm_revision_t chip_version;
32  /** Which ROM_EXT slot booted (boot_slot_t). */
33  uint32_t rom_ext_slot;
34  /** ROM_EXT major version number. */
35  uint32_t rom_ext_major;
36  /** ROM_EXT minor version number. */
37  uint32_t rom_ext_minor;
38  /** ROM_EXT size in flash. */
39  uint32_t rom_ext_size;
40  /** ROM_EXT nonce for challenge/response boot_svc commands. */
41  nonce_t rom_ext_nonce;
42  /** Which BL0 slot booted (boot_slot_t). */
43  uint32_t bl0_slot;
44  /** Chip ownership state. */
45  uint32_t ownership_state;
46  /** Number of ownership transfers this chip has had. */
47  uint32_t ownership_transfers;
48  /** Minimum security version permitted for ROM_EXT payloads. */
49  uint32_t rom_ext_min_sec_ver;
50  /** Minimum security version permitted for application payloads. */
51  uint32_t bl0_min_sec_ver;
52  /** Primary BL0 slot. */
53  uint32_t primary_bl0_slot;
54  /** Whether the RET-RAM was initialized on this boot (hardened_bool_t). */
55  uint32_t retention_ram_initialized;
56  /** Pad to 128 bytes. */
57  uint32_t reserved[8];
58 } boot_log_t;
59 
60 OT_ASSERT_MEMBER_OFFSET(boot_log_t, digest, 0);
61 OT_ASSERT_MEMBER_OFFSET(boot_log_t, identifier, 32);
62 OT_ASSERT_MEMBER_OFFSET(boot_log_t, chip_version, 36);
63 OT_ASSERT_MEMBER_OFFSET(boot_log_t, rom_ext_slot, 44);
64 OT_ASSERT_MEMBER_OFFSET(boot_log_t, rom_ext_major, 48);
65 OT_ASSERT_MEMBER_OFFSET(boot_log_t, rom_ext_minor, 52);
66 OT_ASSERT_MEMBER_OFFSET(boot_log_t, rom_ext_size, 56);
67 OT_ASSERT_MEMBER_OFFSET(boot_log_t, rom_ext_nonce, 60);
68 OT_ASSERT_MEMBER_OFFSET(boot_log_t, bl0_slot, 68);
69 OT_ASSERT_MEMBER_OFFSET(boot_log_t, ownership_state, 72);
70 OT_ASSERT_MEMBER_OFFSET(boot_log_t, ownership_transfers, 76);
71 OT_ASSERT_MEMBER_OFFSET(boot_log_t, rom_ext_min_sec_ver, 80);
72 OT_ASSERT_MEMBER_OFFSET(boot_log_t, bl0_min_sec_ver, 84);
73 OT_ASSERT_MEMBER_OFFSET(boot_log_t, primary_bl0_slot, 88);
74 OT_ASSERT_MEMBER_OFFSET(boot_log_t, retention_ram_initialized, 92);
75 OT_ASSERT_MEMBER_OFFSET(boot_log_t, reserved, 96);
76 
77 enum {
78  /**
79  * Boot log identifier value (ASCII "BLOG").
80  */
81  kBootLogIdentifier = 0x474f4c42,
82 };
83 
84 /**
85  * Updates the digest of the boot_log.
86  *
87  * This function computes the digest over all fields of the boot_log_t struct
88  * (except digest) and updates the digest field. The digest must be the first
89  * member of the struct.
90  *
91  * @param boot_log A buffer that holds the boot_log.
92  */
93 void boot_log_digest_update(boot_log_t *boot_log);
94 
95 /**
96  * Checks whether a boot_log entry is valid.
97  *
98  * This function checks the `identifier` and `digest` fields of the given
99  * `boot_log`.
100  *
101  * @param boot_log A buffer that holds the boot_log.
102  * @return Whether the digest and identifier of the `boot_log` are valid.
103  */
104 OT_WARN_UNUSED_RESULT
105 rom_error_t boot_log_check(const boot_log_t *boot_log);
106 
107 /**
108  * Check the boot_log and initialize it if not yet initialized.
109  *
110  * @param boot_log A buffer that holds the boot_log.
111  * @param rom_ext_slot The current ROM_EXT slot.
112  * @param info A pointer to the chip_info_t structure in ROM.
113  */
114 void boot_log_check_or_init(boot_log_t *boot_log, uint32_t rom_ext_slot,
115  const chip_info_t *info);
116 
117 #ifdef __cplusplus
118 }
119 #endif
120 
121 #endif // OPENTITAN_SW_DEVICE_SILICON_CREATOR_LIB_BOOT_LOG_H_
Return to OpenTitan Documentation