Software APIs
status.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_TESTING_TEST_FRAMEWORK_STATUS_H_
6#define OPENTITAN_SW_DEVICE_LIB_TESTING_TEST_FRAMEWORK_STATUS_H_
7
8/**
9 * Indicates the status of the software running on the CPU, from a testing
10 * perspective.
11 *
12 * It is useful to track the current status of the test SW executing on the CPU
13 * as a signal the helps aid in debug.
14 *
15 * The values set to these literals is arbitrary and do not possess any special
16 * meaning (other than being hex 'words'). They are chosen to be 16-bits wide.
17 * The upper 16-bits are reserved for future use.
18 */
19typedef enum test_status {
20 /**
21 * Indicates that the CPU has started executing the test_rom code.
22 *
23 * Writing this value to #device_test_status_address() must not stop
24 * simulation of the current device.
25 */
26 kTestStatusInBootRom = 0xb090, // 'bogo', BOotrom GO
27
28 /**
29 * Indicates that the CPU has seen ROM_EXEC_EN = 0 and will now stop
30 * execution.
31 *
32 * Writing this value to #device_test_status_address() must not stop
33 * simulation of the current device.
34 */
35 kTestStatusInBootRomHalt = 0xb057, // 'bost', BOotrom STop
36
37 /**
38 * Indicates that the CPU has started executing the test code.
39 *
40 * Writing this value to #device_test_status_address() must not stop
41 * simulation of the current device.
42 */
43 kTestStatusInTest = 0x4354, // 'test'
44
45 /**
46 * Indicates that the CPU is in the WFI state.
47 *
48 * Writing this value to #device_test_status_address() must not stop
49 * simulation of the current device.
50 */
51 kTestStatusInWfi = 0x1d1e, // 'idle'
52
53 /**
54 * This indicates that the test has passed. This is a terminal state. Any code
55 * appearing after this value is set is unreachable.
56 *
57 * Writing this value to #device_test_status_address() may stop simulation of
58 * the current device.
59 */
60 kTestStatusPassed = 0x900d, // 'good'
61
62 /**
63 * This indicates that the test has failed. This is a terminal state. Any code
64 * appearing after this value is set is unreachable.
65 *
66 * Writing this value to #device_test_status_address() may stop simulation of
67 * the current device.
68 */
69 kTestStatusFailed = 0xbaad // 'baad'
70} test_status_t;
71
72/**
73 * This signals the status of the software test with `test_status` value.
74 *
75 * It is mandatory for tests to indicate whether they passed or failed using
76 * this function with #kTestStatusPassed and #kTestStatusFailed.
77 *
78 * In simulated testing (Verilator, DV), this function writes `test_status` to
79 * a specific address, which may cause the simulation to end.
80 *
81 * In environments with a null #device_test_status_address(), this logs a
82 * message for terminal states and calls abort. Otherwise, the function returns
83 * safely.
84 *
85 * @param test_status current status of the test.
86 */
87void test_status_set(test_status_t test_status);
88
89#endif // OPENTITAN_SW_DEVICE_LIB_TESTING_TEST_FRAMEWORK_STATUS_H_