Software APIs
device.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_ARCH_DEVICE_H_
6#define OPENTITAN_SW_DEVICE_LIB_ARCH_DEVICE_H_
7
8#include <stdbool.h>
9#include <stdint.h>
10
12
13#ifdef __cplusplus
14extern "C" {
15#endif // __cplusplus
16
17/**
18 * @file
19 * @brief This header contains declarations of device-specific information.
20 *
21 * This header contains "device-specific" declarations, i.e., information that
22 * all devices are known to provide, but which is specific to the particular
23 * choice of platform, which can range from a software simulation, like
24 * Verilator or a DV testbench, to real harware, like an FPGA or ASIC.
25 *
26 * Definitions for these symbols can be found in other files in this directory,
27 * which should be linked in depending on which platform an executable is
28 * intended for.
29 */
30
31/**
32 * A `device_type_t` represents a particular device type for which
33 * device-specific symbols are available.
34 */
35typedef enum device_type {
36 /**
37 * Represents "DV", i.e. running the test in a DV simulation testbench.
38 *
39 * DISCLAIMER: it is important this value remains assigned to 0, as it is
40 * implicitly checked in the `test_rom_start.S` assembly code to determine
41 * whether or not to initialize SRAM.
42 */
44 /**
45 * Represents the "Verilator" device, i.e., a synthesis of the OpenTitan
46 * design by Verilator into C++.
47 */
49 /**
50 * Represents the "ChipWhisperer CW310 FPGA" device, i.e., the particular
51 * FPGA board blessed for OpenTitan development, containing a Xilinx FPGA.
52 */
54 /**
55 * Represents the "ChipWhisperer CW305 FPGA" device, i.e., the smaller FPGA
56 * development board with SCA capability, containing a Xilinx FPGA.
57 */
59 /**
60 * Represents the "ChipWhisperer CW340 FPGA" device, i.e., the particular
61 * FPGA board blessed for OpenTitan development, containing a Xilinx FPGA.
62 */
64 /**
65 * Represents the "Silicon" device, i.e., an instantiation of OpenTitan in
66 * Silicon.
67 */
69 /**
70 * Represents the "QEMU" device, i.e. an emulation of OpenTitan written
71 * independently of the RTL.
72 */
75
76/**
77 * Indicates the device that this program has been linked for.
78 *
79 * This can be used, for example, for conditioning an operation on the precise
80 * device type.
81 */
82extern const device_type_t kDeviceType;
83
84/**
85 * The CPU clock frequency of the device, in hertz.
86 * This is the operating clock for the main processing host.
87 */
88extern const uint64_t kClockFreqCpuHz;
89
90/**
91 * The peripheral clock frequency of the device, in hertz.
92 * This is the operating clock used by timers, uarts,
93 * other peripheral interfaces.
94 */
95extern const uint64_t kClockFreqPeripheralHz;
96
97/**
98 * The high-speed peripheral clock frequency of the device, in hertz.
99 * This is the operating clock used by the spi host
100 */
101extern const uint64_t kClockFreqHiSpeedPeripheralHz;
102
103/**
104 * The USB clock frequency of the device, in hertz.
105 * This is the operating clock used by the USB phy interface and USB's software
106 * interface.
107 */
108extern const uint64_t kClockFreqUsbHz;
109
110/**
111 * The always on clock frequency of the device, in hertz.
112 * This is the operating clock used by the always on timer,
113 * power manager and other peripherals that continue to
114 * operate after the device is in sleep state.
115 */
116extern const uint64_t kClockFreqAonHz;
117
118/**
119 * The baudrate of the UART peripheral (if such a thing is present).
120 */
121extern const uint64_t kUartBaudrate;
122
123/**
124 * A helper macro to calculate NCO values.
125 * NOTE: the left shift value is dependent on the UART hardware.
126 * The NCO width is 16 bits and the NCO calculates a 16x oversampling clock.
127 * If uart baud rate is 1.5Mbps and IO is 24Mhz, NCO is 0x10000, which is over
128 * the NCO width, use NCO = 0xffff for this case since the error is tolerable.
129 * Refer to #4263
130 */
131#define CALCULATE_UART_NCO_(baudrate, peripheral_clock) \
132 (baudrate == 1500000 && peripheral_clock == 24000000) \
133 ? 0xffff \
134 : (uint32_t)(((uint64_t)(baudrate) << (16 + 4)) / (peripheral_clock))
135
136#define CALCULATE_UART_NCO(baudrate, peripheral_clock) \
137 CALCULATE_UART_NCO_(baudrate, peripheral_clock) < 0x10000 \
138 ? CALCULATE_UART_NCO_(baudrate, peripheral_clock) \
139 : 0;
140
141/**
142 * The pre-calculated UART NCO value based on the Baudrate and Peripheral clock.
143 */
144extern const uint32_t kUartNCOValue;
145
146/**
147 * Additional pre-calculated UART NCO values. If the pre-calculated value is
148 * zero, then the corresponding baudrate is not supported.
149 */
150extern const uint32_t kUartBaud115K;
151extern const uint32_t kUartBaud230K;
152extern const uint32_t kUartBaud460K;
153extern const uint32_t kUartBaud921K;
154extern const uint32_t kUartBaud1M33;
155extern const uint32_t kUartBaud1M50;
156
157/**
158 * Helper macro to calculate the time it takes to transmit the entire UART TX
159 * FIFO in CPU cycles.
160 *
161 * This macro assumes 10 bits per byte (no parity bits) and a 128 byte deep TX
162 * FIFO.
163 */
164#define CALCULATE_UART_TX_FIFO_CPU_CYCLES(baud_rate_, cpu_freq_, fifo_depth_) \
165 ((cpu_freq_)*10 * (fifo_depth_) / (baud_rate_))
166
167/**
168 * Helper macro to calculate the maximum duration of the AST initialization
169 * check poll in CPU cycles.
170 *
171 * This macro assumes that the desired duration is 100us.
172 */
173#define CALCULATE_AST_CHECK_POLL_CPU_CYCLES(cpu_freq_) \
174 ((cpu_freq_)*100 / 1000000)
175
176/**
177 * Maximum duration of the AST initialization check poll in CPU cycles. This
178 * number depends on `kClockFreqCpuHz` and the resulting duration must be 100us.
179 */
180extern const uint32_t kAstCheckPollCpuCycles;
181
182/**
183 * An address to write to report test status.
184 *
185 * If this is zero, there is no address to write to report test status.
186 *
187 * Depending on the simulation environment and the value written to this
188 * address, the simulation may stop.
189 *
190 * @see #test_status_set
191 */
192uintptr_t device_test_status_address(void);
193
194/**
195 * An address to write use for UART logging bypass
196 *
197 * If this is zero, there is no address to write to bypass UART logging.
198 *
199 * @see #LOG
200 */
201uintptr_t device_log_bypass_uart_address(void);
202
203/**
204 * A platform-specific function to convert microseconds to cpu cycles.
205 *
206 * This is primarily used for spin waits that use the cpu cycle counters.
207 * For platforms with clock periods slower than 1 us this will round up.
208 */
210uint64_t to_cpu_cycles(uint64_t usec);
211
212/**
213 * Prints the FPGA version.
214 *
215 * This function is a NOP unless we are building for an FPGA.
216 */
218
219#ifdef __cplusplus
220} // extern "C"
221#endif // __cplusplus
222
223#endif // OPENTITAN_SW_DEVICE_LIB_ARCH_DEVICE_H_