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