Software APIs
dif_rom_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_ROM_CTRL_H_
6#define OPENTITAN_SW_DEVICE_LIB_DIF_DIF_ROM_CTRL_H_
7
8/**
9 * @file
10 * @brief <a href="/hw/ip/rom_ctrl/doc/">ROM Controller</a> Device Interface
11 * Functions
12 */
13
14#include <stdint.h>
15
16#include "rom_ctrl_regs.h" // Generated.
17#include "sw/device/lib/dif/autogen/dif_rom_ctrl_autogen.h"
18
19#ifdef __cplusplus
20extern "C" {
21#endif // __cplusplus
22
23/**
24 * A fatal alert cause error.
25 *
26 * See also: `dif_rom_ctrl_fatal_alert_causes_t`.
27 */
28typedef enum dif_rom_ctrl_fatal_alert_cause {
29 /**
30 * No error has occured.
31 */
32 kDifRomCtrlFatalAlertCauseNoError = 0,
33 /**
34 * Set on a fatal error detected by the ROM checker.
35 */
36 kDifRomCtrlFatalAlertCauseCheckerError =
37 ROM_CTRL_FATAL_ALERT_CAUSE_CHECKER_ERROR_BIT,
38 /**
39 * Set on an integrity error from the register interface.
40 */
41 kDifRomCtrlFatalAlertCauseIntegrityError =
42 ROM_CTRL_FATAL_ALERT_CAUSE_INTEGRITY_ERROR_BIT,
43} dif_rom_ctrl_fatal_alert_cause_t;
44
45/**
46 * A set of fatal alert cause errors.
47 */
48typedef uint32_t dif_rom_ctrl_fatal_alert_causes_t;
49
50/**
51 * A typed representation of the ROM digest.
52 */
53typedef struct dif_rom_ctrl_digest {
54 uint32_t digest[ROM_CTRL_DIGEST_MULTIREG_COUNT];
55} dif_rom_ctrl_digest_t;
56
57/**
58 * Reads the fatal alert cause bits of the ROM Controller.
59 *
60 * @param rom_ctrl A ROM Controller handle.
61 * @return The result of the operation.
62 */
63OT_WARN_UNUSED_RESULT
64dif_result_t dif_rom_ctrl_get_fatal_alert_cause(
65 const dif_rom_ctrl_t *rom_ctrl,
66 dif_rom_ctrl_fatal_alert_causes_t *alert_causes);
67
68/**
69 * Reads the (KMAC computed) ROM digest.
70 *
71 * @param rom_ctrl A ROM Controller handle.
72 * @param digest KMAC digest of ROM.
73 * @return The result of the operation.
74 */
75OT_WARN_UNUSED_RESULT
76dif_result_t dif_rom_ctrl_get_digest(const dif_rom_ctrl_t *rom_ctrl,
77 dif_rom_ctrl_digest_t *digest);
78
79/**
80 * Reads the expected ROM digest contained in the top eight words of ROM.
81 *
82 * @param rom_ctrl A ROM Controller handle.
83 * @param expected_digest Expected KMAC digest of ROM.
84 * @return The result of the operation.
85 */
86OT_WARN_UNUSED_RESULT
87dif_result_t dif_rom_ctrl_get_expected_digest(
88 const dif_rom_ctrl_t *rom_ctrl, dif_rom_ctrl_digest_t *expected_digest);
89
90#ifdef __cplusplus
91} // extern "C"
92#endif // __cplusplus
93
94#endif // OPENTITAN_SW_DEVICE_LIB_DIF_DIF_ROM_CTRL_H_