Software APIs
dif_csrng_shared.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_CSRNG_SHARED_H_
6#define OPENTITAN_SW_DEVICE_LIB_DIF_DIF_CSRNG_SHARED_H_
7
8#include "sw/device/lib/base/bitfield.h"
9#include "sw/device/lib/base/macros.h"
10#include "sw/device/lib/base/memory.h"
11#include "sw/device/lib/base/mmio.h"
12#include "sw/device/lib/dif/dif_base.h"
13#include "sw/device/lib/dif/dif_csrng.h"
14
15/**
16 * @file
17 * Private code shared between the CSRNG and EDN DIFs.
18 */
19
20enum {
21 /**
22 * CSRNG genbits buffer size in uint32_t words.
23 */
24 kCsrngGenBitsBufferSize = 4,
25};
26
27/**
28 * Supported CSRNG application commands.
29 * See https://docs.opentitan.org/hw/ip/csrng/doc/#command-header for
30 * details.
31 */
32typedef enum csrng_app_cmd_id {
33 kCsrngAppCmdInstantiate = 1,
34 kCsrngAppCmdReseed = 2,
35 kCsrngAppCmdGenerate = 3,
36 kCsrngAppCmdUpdate = 4,
37 kCsrngAppCmdUninstantiate = 5,
38} csrng_app_cmd_id_t;
39
40/**
41 * CSRNG application interface command header parameters.
42 */
43typedef struct csrng_app_cmd {
44 /**
45 * Application command.
46 */
47 csrng_app_cmd_id_t id;
48 /**
49 * Entropy source enable.
50 *
51 * Mapped to flag0 in the hardware command interface.
52 */
53 dif_csrng_entropy_src_toggle_t entropy_src_enable;
54 /**
55 * Seed material. Only used in `kCsrngAppCmdInstantiate`, `kCsrngAppCmdReseed`
56 * and `kCsrngAppCmdUpdate` commands.
57 */
58 const dif_csrng_seed_material_t *seed_material;
59 /**
60 * Generate length. Specified as number of 128bit blocks.
61 */
62 uint32_t generate_len;
63} csrng_app_cmd_t;
64
65/**
66 * This enum type contains all the different command types for
67 * csrng_send_cmd().
68 */
69typedef enum csrng_app_cmd_type {
70 /**
71 * Command issued directly to CSRNG.
72 */
73 kCsrngAppCmdTypeCsrng,
74 /**
75 * Command issued to CSRNG via the SW_CMD_REQ register of the EDN.
76 */
77 kCsrngAppCmdTypeEdnSw,
78 /**
79 * Command issued to CSRNG via the GENERATE_CMD register of the EDN.
80 * This type of command will be used in the auto mode of the EDN.
81 */
82 kCsrngAppCmdTypeEdnGen,
83 /**
84 * Command issued to CSRNG via the RESEED_CMD register of the EDN.
85 * This type of command will be used in the auto mode of the EDN.
86 */
87 kCsrngAppCmdTypeEdnRes,
88} csrng_app_cmd_type_t;
89
90/**
91 * Builds a CSRNG command header.
92 *
93 * Build a CSRNG command header following the CSRNG specification. The caller is
94 * responsible for verifying the correctness of the parameters passed into this
95 * function.
96 *
97 * @param id CSRNG command ID.
98 * @param entropy_src_enable Entropy source enable flag. Mapped to flag0 in the
99 * command header.
100 * @param cmd_len The overall command lend. It should be set to the number of
101 * seed material words, or zero.
102 * @param generate_len Number of 128bit blocks to request if the command ID is
103 * set to `kCsrngAppCmdGenerate`.
104 * @return CSRNG command header in `uint32_t` format.
105 */
106OT_WARN_UNUSED_RESULT
107uint32_t csrng_cmd_header_build(
108 csrng_app_cmd_id_t id, dif_csrng_entropy_src_toggle_t entropy_src_enable,
109 uint32_t cmd_len, uint32_t generate_len);
110
111/**
112 * Writes application command `cmd` to the CSRNG_CMD_REQ_REG register.
113 * Returns the result of the operation.
114 */
115OT_WARN_UNUSED_RESULT
116dif_result_t csrng_send_app_cmd(mmio_region_t base_addr,
117 csrng_app_cmd_type_t cmd_type,
118 csrng_app_cmd_t cmd);
119
120#endif // OPENTITAN_SW_DEVICE_LIB_DIF_DIF_CSRNG_SHARED_H_