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