Software APIs
usb_testutils_diags.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_USB_TESTUTILS_DIAGS_H_
6 #define OPENTITAN_SW_DEVICE_LIB_TESTING_USB_TESTUTILS_DIAGS_H_
7 #include "sw/device/lib/arch/device.h"
8 #include "sw/device/lib/runtime/print.h"
9 
10 // Diagnostic, testing and performance measurements utilities for verification
11 // of usbdev and development of the usb_testutils support software; the
12 // requirements of this software are peculiar in that the USBDPI model used in
13 // top-level requires packet responses very promptly, so the introduction of
14 // logging/tracing code can substantially alter behavior and cause malfunction
15 //
16 // Employ faster memory copying routines to/from the packet buffer
17 // (the standard dif_usbdev_buffer_write/read functionality should normally be
18 // employed, but it is inefficient; the replacement routines better model the
19 // attainable performance)
20 #ifndef USBUTILS_MEM_FASTER
21 #define USBUTILS_MEM_FASTER 1
22 #endif
23 
24 // Implement low-impact tracing of software execution, permitting the software
25 // and hardware behavior to be married, hopefully without modifying the
26 // behavior/performance, particularly in top-level simulation
27 #define USBUTILS_FUNCTION_POINTS 0
28 
29 // Record the function points to a memory buffer instead, for use where test
30 // hardware is unavailable, eg. FPGA builds
31 #define USBUTILS_FUNCPT_USE_BUFFER 0
32 
33 #if USBUTILS_MEM_FASTER
34 #include "sw/device/lib/base/mmio.h"
35 #endif
36 
37 #if USBUTILS_FUNCTION_POINTS
38 // For access to ibex_mcycle_read()
39 #include "sw/device/lib/runtime/ibex.h"
40 
41 // Function point file numbers
42 // (used to index filename table in usb_testutils_diags.c)
43 #define USBUTILS_FUNCPT_FILE_DIF_USBDEV 0x01U
44 #define USBUTILS_FUNCPT_FILE_USB_TESTUTILS 0x02U
45 #define USBUTILS_FUNCPT_FILE_USB_CONTROLEP 0x03U
46 #define USBUTILS_FUNCPT_FILE_USB_SIMPLESER 0x04U
47 #define USBUTILS_FUNCPT_FILE_USBDEV_TEST 0x05U
48 #define USBUTILS_FUNCPT_FILE_USBDEV_STRM_TEST 0x06U
49 
50 #define USBUTILS_FUNCPT_LOG_ENTRIES 0x1000U
51 #define USBUTILS_FUNCPT_LOG_SIZE (USBUTILS_FUNCPT_LOG_ENTRIES * 4U)
52 
53 #define USBUTILS_FUNCPT_ENTRY_SIGNATURE 0xAA55FF99U
54 /**
55  * Entry in function point stream
56  */
57 typedef struct {
58  uint32_t sig;
59  uint32_t time;
60  uint32_t file_point;
61  uint32_t data;
62 } funcpt_entry_t;
63 
64 #if USBUTILS_FUNCPT_USE_BUFFER
65 // Record function points to RAM buffer for deferred reporting, eg. FPGA
66 #define USBUTILS_FUNCPT(pt, d) \
67  { \
68  unsigned idx = usbutils_fpt_next; \
69  usbutils_fpt_next = \
70  (idx >= USBUTILS_FUNCPT_LOG_SIZE - 4U) ? 0U : (idx + 4U); \
71  functpt_enttry_t *e = (functpt_enttry_t *)&usbutils_fpt_log[idx]; \
72  e->sig = USBUTILS_FUNCPT_ENTRY_SIGNATURE; \
73  e->time = (uint32_t)ibex_mcycle_read(); \
74  e->file_point = (USBUTILS_FUNCPT_FILE << 16) | pt; \
75  e->data = (d); \
76  }
77 
78 extern volatile unsigned usbutils_fpt_next;
79 extern uint32_t usbutils_fpt_log[];
80 #else
81 // Emit function points to special address for waveform viewing in simulation
82 // (this is the address used by DV simulation for logging output)
83 #define USBUTILS_FUNCPT(pt, d) \
84  { \
85  volatile uint32_t *log_hw = (uint32_t *)0x411f0084u; \
86  uint32_t time = (uint32_t)ibex_mcycle_read(); \
87  *log_hw = USBUTILS_FUNCPT_ENTRY_SIGNATURE; \
88  *log_hw = time; \
89  *log_hw = (USBUTILS_FUNCPT_FILE << 16) | (pt); \
90  *log_hw = (d); \
91  }
92 #endif
93 
94 /**
95  * Report the contents of the function point log
96  */
97 void usbutils_funcpt_report(void);
98 #else
99 // Omit function point tracing
100 #define USBUTILS_FUNCPT(pt, d)
101 #endif
102 
103 // For investigation of usbdev performance characteristics
104 #if USBUTILS_MEM_FASTER
105 /**
106  * Performant copying routine from usbdev packet buffer (MMIO)
107  *
108  * @param base MMIO base address
109  * @param offset MMIO word offset
110  * @param dest Buffer to receive data
111  * @param len Number of bytes to be copied
112  */
113 void usbutils_memcpy_from_mmio32(mmio_region_t base, uint32_t offset,
114  void *dest, size_t len);
115 /**
116  * Performant copying routine to usbdev packet buffer (MMIO)
117  *
118  * @param base MMIO base address
119  * @param offset MMIO word offset
120  * @param src Data to be copied
121  * @param len Number of bytes to be copied
122  */
123 void usbutils_memcpy_to_mmio32(mmio_region_t base, uint32_t offset,
124  const void *src, size_t len);
125 #endif
126 
127 // Used for tracing what is going on. This may impact timing which is critical
128 // when simulating with the USB DPI module.
129 #define USBUTILS_ENABLE_TRC 0
130 
131 // Prompt the user for intervention if we're not running in simulation;
132 // logging within simulation can be time-consuming and induce failures.
133 #define USBUTILS_USER_PROMPT(...) \
134  do { \
135  if (kDeviceType != kDeviceSimDV && kDeviceType != kDeviceSimVerilator) { \
136  LOG_INFO(__VA_ARGS__); \
137  } \
138  } while (false)
139 
140 #if USBUTILS_ENABLE_TRC
141 #if 0
142 // May be useful on FPGA CW310
143 #include "sw/device/lib/runtime/log.h"
144 #define TRC_S(s) LOG_INFO("%s", s)
145 #define TRC_I(i, b) LOG_INFO("0x%x", i)
146 #define TRC_C(c) LOG_INFO("%c", c)
147 #else
148 // Very low impact, for use in t-l simulation
149 #define USBDIAGS_LOG_EMIT(d) (*((volatile uint32_t *)0x411f0084u) = (d))
150 
151 #define TRC_S(s) usbutils_log_text(s)
152 #define TRC_I(i, b) USBDIAGS_LOG_EMIT(i)
153 #define TRC_C(c) USBDIAGS_LOG_EMIT(0xcc000000u | (uint16_t)c)
154 
155 // Faster string logging to minimise impact upon timing
156 inline void usbutils_log_text(const char *s) {
157  while (*s) {
158  USBDIAGS_LOG_EMIT(*s);
159  s++;
160  }
161 }
162 #endif
163 #else
164 #define TRC_S(s)
165 #define TRC_I(i, b)
166 #define TRC_C(c)
167 #endif
168 
169 #endif // OPENTITAN_SW_DEVICE_LIB_TESTING_USB_TESTUTILS_DIAGS_H_
Return to OpenTitan Documentation