[sw] Convert Delimiters to Backticks in Comments
This updates existing code to follow the new guidance about backticks
in software code. This should be a non-functional change.
Signed-off-by: Sam Elliott <selliott@lowrisc.org>
diff --git a/sw/device/boot_rom/bootstrap.h b/sw/device/boot_rom/bootstrap.h
index 997a5cc..580ae5e 100644
--- a/sw/device/boot_rom/bootstrap.h
+++ b/sw/device/boot_rom/bootstrap.h
@@ -12,7 +12,7 @@
*
* The payload is expected to be split into frames as defined in
* bootstrap_msgs.h. Frames are processed in consecutive number, with
- * |frame_num| in frame_hdr_t expected to increase monotonically.
+ * `frame_num` in frame_hdr_t expected to increase monotonically.
*
* The last frame must be ord with FRAME_EOF_MARKER to signal the end of
* payload transmission.
diff --git a/sw/device/boot_rom/bootstrap_msgs.h b/sw/device/boot_rom/bootstrap_msgs.h
index 80010eb..a1d1a7a 100644
--- a/sw/device/boot_rom/bootstrap_msgs.h
+++ b/sw/device/boot_rom/bootstrap_msgs.h
@@ -11,7 +11,7 @@
#define FRAME_NO(k) ((k)&0xffffff)
typedef struct {
- /* SHA2 of the entire frame_t message starting at the |frame_num| offset. */
+ /* SHA2 of the entire frame_t message starting at the `frame_num` offset. */
uint32_t hash[8];
/* Frame number starting at 0. The last frame should be ord with
diff --git a/sw/device/boot_rom/rom_crt.S b/sw/device/boot_rom/rom_crt.S
index 6713de5..543d8b5 100644
--- a/sw/device/boot_rom/rom_crt.S
+++ b/sw/device/boot_rom/rom_crt.S
@@ -14,7 +14,7 @@
* Entry point after reset. This symbol is jumped to from the handler
* for IRQ 0x80.
*
- * Sets up the stack, then jumps to |_start|.
+ * Sets up the stack, then jumps to `_start`.
*/
_reset_start:
.globl _reset_start
@@ -61,21 +61,21 @@
la gp, __global_pointer$
.option pop
- // Explicit fall-through to |_start|.
+ // Explicit fall-through to `_start`.
/**
* Callable entry point for the boot rom.
*
- * Currently, this zeroes the |.bss| section, copies initial data to
- * |.data|, and then jumps to the program entry point.
+ * Currently, this zeroes the `.bss` section, copies initial data to
+ * `.data`, and then jumps to the program entry point.
*/
_start:
.globl _start
- // Zero out the |.bss| segment.
+ // Zero out the `.bss` segment.
//
- // We use |t0| and |t1| to represent the start and end pointers
- // of |.bss|.
+ // We use `t0` and `t1` to represent the start and end pointers
+ // of `.bss`.
la t0, _bss_start
la t1, _bss_end
bge t0, t1, bss_zero_loop_end
@@ -85,11 +85,11 @@
ble t0, t1, bss_zero_loop
bss_zero_loop_end:
- // Initialize the |.data| segment from the |.idata| segment.
+ // Initialize the `.data` segment from the `.idata` segment.
//
- // We use |t0| and |t1| to represent the start and end pointers
- // of |.data|, |t2| to represent the start pointer of |.idata|
- // (which has the same length as |.data|) and |t3| is a scratch
+ // We use `t0` and `t1` to represent the start and end pointers
+ // of `.data`, `t2` to represent the start pointer of `.idata`
+ // (which has the same length as `.data`) and `t3` is a scratch
// register for the copy.
la t0, _data_start
la t1, _data_end
diff --git a/sw/device/examples/hello_usbdev/hello_usbdev.c b/sw/device/examples/hello_usbdev/hello_usbdev.c
index 8a0f305..bb23b05 100644
--- a/sw/device/examples/hello_usbdev/hello_usbdev.c
+++ b/sw/device/examples/hello_usbdev/hello_usbdev.c
@@ -46,7 +46,7 @@
static usb_ss_ctx_t simple_serial1;
/**
- * Makes |c| into a printable character, replacing it with |replacement|
+ * Makes `c` into a printable character, replacing it with `replacement`
* as necessary.
*/
static char make_printable(char c, char replacement) {
@@ -96,9 +96,9 @@
demo_gpio_startup(&gpio);
- // Call |usbdev_init| here so that DPI will not start until the
+ // Call `usbdev_init` here so that DPI will not start until the
// simulation has finished all of the printing, which takes a while
- // if |--trace| was passed in.
+ // if `--trace` was passed in.
usbdev_init(&usbdev);
usb_controlep_init(&usbdev_control, &usbdev, 0, config_descriptors,
sizeof(config_descriptors));
diff --git a/sw/device/exts/common/flash_crt.S b/sw/device/exts/common/flash_crt.S
index 0ffac3b..0157e2d 100644
--- a/sw/device/exts/common/flash_crt.S
+++ b/sw/device/exts/common/flash_crt.S
@@ -15,7 +15,7 @@
/**
* Callable entry point for flash.
*
- * This sets up the stack, zeroes |.bss|, and sets up |.data|.
+ * This sets up the stack, zeroes `.bss`, and sets up `.data`.
* It then jumps into main.
*/
_start:
@@ -36,10 +36,10 @@
la t0, _vectors_start
csrw mtvec, t0
- // Zero out the |.bss| segment.
+ // Zero out the `.bss` segment.
//
- // We use |t0| and |t1| to represent the start and end pointers
- // of |.bss|.
+ // We use `t0` and `t1` to represent the start and end pointers
+ // of `.bss`.
la t0, _bss_start
la t1, _bss_end
bge t0, t1, bss_zero_loop_end
@@ -49,11 +49,11 @@
ble t0, t1, bss_zero_loop
bss_zero_loop_end:
- // Initialize the |.data| segment from the |.idata| segment.
+ // Initialize the `.data` segment from the `.idata` segment.
//
- // We use |t0| and |t1| to represent the start and end pointers
- // of |.data|, |t2| to represent the start pointer of |.idata|
- // (which has the same length as |.data|) and |t3| is a scratch
+ // We use `t0` and `t1` to represent the start and end pointers
+ // of `.data`, `t2` to represent the start pointer of `.idata`
+ // (which has the same length as `.data`) and `t3` is a scratch
// register for the copy.
la t0, _data_start
la t1, _data_end
@@ -68,7 +68,7 @@
data_copy_loop_end:
// Jump into the C program entry point. This is your standard
- // C |main()|, so we need to pass dummy values for |argc| and |argv|.
+ // C `main()`, so we need to pass dummy values for `argc` and `argv`.
li a0, 0x0 // argc = 0
li a1, 0x0 // argv = NULL
call main
diff --git a/sw/device/lib/arch/device.h b/sw/device/lib/arch/device.h
index d15d33f..b56a774 100644
--- a/sw/device/lib/arch/device.h
+++ b/sw/device/lib/arch/device.h
@@ -19,7 +19,7 @@
*/
/**
- * A |device_type_t| represents a particular device type for which
+ * A `device_type_t` represents a particular device type for which
* device-specific symbols are available.
*/
typedef enum device_type {
diff --git a/sw/device/lib/base/freestanding/stddef.h b/sw/device/lib/base/freestanding/stddef.h
index 2667f66..8878696 100644
--- a/sw/device/lib/base/freestanding/stddef.h
+++ b/sw/device/lib/base/freestanding/stddef.h
@@ -18,7 +18,7 @@
// GCC's built-in defines do not include a type with the maximum alignment, but
// does include a define with the maximum alignment value. Since the only
-// requirement of |max_align_t| is that it be some type such that its alignment
+// requirement of `max_align_t` is that it be some type such that its alignment
// is maximal, we simply use a one-byte struct whose alignment is forced to be
// the maximum.
typedef struct { alignas(__BIGGEST_ALIGNMENT__) uint8_t __nonce; } max_align_t;
diff --git a/sw/device/lib/base/freestanding/stdint.h b/sw/device/lib/base/freestanding/stdint.h
index 2c618a8..14b102b 100644
--- a/sw/device/lib/base/freestanding/stdint.h
+++ b/sw/device/lib/base/freestanding/stdint.h
@@ -10,10 +10,10 @@
* This header is specified in detail in S7.20 the same.
*
* Actual limit values below are defined as:
- * - Unsigned MAXs are defined as the |0xff..ffU| all-ones representation.
- * - Signed MINs are defined as |0x80..00| all-zeroes-but-the-last
+ * - Unsigned MAXs are defined as the `0xff..ffU` all-ones representation.
+ * - Signed MINs are defined as `0x80..00` all-zeroes-but-the-last
* representation.
- * - Unsigned MAXs are defined as |0x7f..ff| all-ones-but-the-last
+ * - Unsigned MAXs are defined as `0x7f..ff` all-ones-but-the-last
* representation.
* These shorthands are correct for two's complement and the ones least likely
* to get a mistake in.
diff --git a/sw/device/lib/base/log.c b/sw/device/lib/base/log.c
index d8c7d82..143590c 100644
--- a/sw/device/lib/base/log.c
+++ b/sw/device/lib/base/log.c
@@ -24,12 +24,12 @@
}
/**
- * Logs |format| and the values that following to stdout.
+ * Logs `format` and the values that following to stdout.
*
* @param severity the log severity.
* @param file_name a constant string referring to the file in which the log
* occured.
- * @param line a line number from |file_name|.
+ * @param line a line number from `file_name`.
* @param format a format string, as described in print.h. This must be a string
* literal.
* @param ... format parameters matching the format string.
@@ -61,7 +61,7 @@
}
/**
- * Logs |format| and the values that following in an efficient, DV-testbench
+ * Logs `format` and the values that following in an efficient, DV-testbench
* specific way.
*
* @param severity the log severity.
@@ -71,4 +71,4 @@
*/
void base_log_internal_dv(log_severity_t severity, const char *format, ...) {
// Do nothing, for now.
-}
\ No newline at end of file
+}
diff --git a/sw/device/lib/base/log.h b/sw/device/lib/base/log.h
index c824bb9..349b954 100644
--- a/sw/device/lib/base/log.h
+++ b/sw/device/lib/base/log.h
@@ -42,7 +42,7 @@
* of C specifier syntax supported.
*
* The precise mechanism for logging is dependent on the target device. On core
- * devices, like Verilator, logs are printed using whatever |stdout| is set to
+ * devices, like Verilator, logs are printed using whatever `stdout` is set to
* in print.h. DV testbenches may use an alternative, more efficient mechanism.
* In DV mode, some format specifiers may be unsupported, such as %s.
*/
@@ -75,22 +75,22 @@
*
* Prefer to use a LOG function with a specified severity, instead.
*
- * @param severity a severity of type |log_severity_t|.
+ * @param severity a severity of type `log_severity_t`.
* @param format a format string, as described in print.h. This must be a string
* literal.
* @param ... format parameters matching the format string.
*/
// Currently, this simply prints directly to printf. In the future, when
-// we begin supporting DV testbenches, we can include an |if| statement here
-// that detects that using |device.h| and switches to the cheaper "dump args
+// we begin supporting DV testbenches, we can include an `if` statement here
+// that detects that using `device.h` and switches to the cheaper "dump args
// for post process formatting" function.
//
// NOTE: the ##__VA_ARGS__ syntax below is a GCC/Clang extension, while
// "" foo "" is a common C idiom to assert that a macro parameter is a string.
#define LOG(severity, format, ...) \
do { \
- /* The |false| below will eventually be replaced with a device.h \
- function |device_is_dv()| or similar, which determines if the \
+ /* The `false` below will eventually be replaced with a device.h \
+ function `device_is_dv()` or similar, which determines if the \
current device is a DV testbench. */ \
if (false) { \
base_log_internal_dv(severity, "" format "", ##__VA_ARGS__); \
@@ -103,7 +103,7 @@
/**
* Log an informational message.
*
- * @param severity a severity of type |log_severity_t|.
+ * @param severity a severity of type `log_severity_t`.
* @param format a format string, as described in print.h. This must be a string
* literal.
* @param ... format parameters matching the format string.
@@ -113,7 +113,7 @@
/**
* Log a warning
*
- * @param severity a severity of type |log_severity_t|.
+ * @param severity a severity of type `log_severity_t`.
* @param format a format string, as described in print.h. This must be a string
* literal.
* @param ... format parameters matching the format string.
@@ -123,7 +123,7 @@
/**
* Log a non-fatal error.
*
- * @param severity a severity of type |log_severity_t|.
+ * @param severity a severity of type `log_severity_t`.
* @param format a format string, as described in print.h. This must be a string
* literal.
* @param ... format parameters matching the format string.
diff --git a/sw/device/lib/base/memory.h b/sw/device/lib/base/memory.h
index f3acd0a..afab02a 100644
--- a/sw/device/lib/base/memory.h
+++ b/sw/device/lib/base/memory.h
@@ -14,10 +14,10 @@
*
* ISO C forbids, in general, casting a pointer to non-character types and
* reading them, though it is frequently necessary to read exactly one word out
- * of a |void *|. This function performs that action in a manner which is
+ * of a `void *`. This function performs that action in a manner which is
* well-defined.
*
- * Of course, |ptr| must point to word-aligned memory that is at least one word
+ * Of course, `ptr` must point to word-aligned memory that is at least one word
* wide. To do otherwise is Undefined Behavior. It goes eithout saying that the
* memory this function intents to read must be initialized.
*
@@ -25,7 +25,7 @@
* non-volatile load.
*
* @param ptr a word-aligned pointer pointed to at least four bytes of memory.
- * @return the word |ptr| points to.
+ * @return the word `ptr` points to.
*/
inline uint32_t read_32(const void *ptr) {
// Both GCC and Clang optimize the code below into a single word-load on most
@@ -34,7 +34,7 @@
//
// Failing to get that particular codegen in either GCC or Clang with -O2 or
// -Os set shall be considred a bug in this function. The same applies to
- // |write32()|.
+ // `write32()`.
ptr = __builtin_assume_aligned(ptr, alignof(uint32_t));
uint32_t val;
__builtin_memcpy(&val, ptr, sizeof(uint32_t));
@@ -46,10 +46,10 @@
*
* ISO C forbids, in general, casting a pointer to non-character types and
* reading them, though it is frequently necessary to write exactly one word to
- * a |void *|. This function performs that action in a manner which is
+ * a `void *`. This function performs that action in a manner which is
* well-defined.
*
- * Of course, |ptr| must point to word-aligned memory that is at least one word
+ * Of course, `ptr` must point to word-aligned memory that is at least one word
* wide. To do otherwise is Undefined Behavior.
*
* This function has reordering properties as weak as a normal, non-atomic,
@@ -60,7 +60,7 @@
*/
inline void write_32(uint32_t value, void *ptr) {
// Both GCC and Clang optimize the code below into a single word-store on most
- // platforms. See the comment in |read_32()| for more implementation-private
+ // platforms. See the comment in `read_32()` for more implementation-private
// information.
ptr = __builtin_assume_aligned(ptr, alignof(uint32_t));
__builtin_memcpy(ptr, &value, sizeof(uint32_t));
@@ -74,7 +74,7 @@
* @param dest the region to copy to.
* @param src the region to copy from.
* @param len the number of bytes to copy.
- * @return the value of |dest|.
+ * @return the value of `dest`.
*/
void *memcpy(void *restrict dest, const void *restrict src, size_t len);
@@ -86,7 +86,7 @@
* @param dest the region to write to.
* @param value the value, converted to a byte, to write to each byte cell.
* @param len the number of bytes to write.
- * @return the value of |dest|.
+ * @return the value of `dest`.
*/
void *memset(void *dest, int value, size_t len);
@@ -100,7 +100,7 @@
* @param rhs the right-hand-side of the comparison.
* @param len the length of both regions, in bytes.
* @return a zero, positive, or negative integer, corresponding to the
- * contingencies of |lhs == rhs|, |lhs > rhs|, and |lhs < rhs| (as buffers, not
+ * contingencies of `lhs == rhs`, `lhs > rhs`, and `lhs < rhs` (as buffers, not
* pointers), respectively.
*/
int memcmp(const void *lhs, const void *rhs, size_t len);
@@ -110,8 +110,8 @@
*
* This function conforms to the semantics defined in ISO C11 S7.24.5.1.
*
- * Since libbase does not provide a |strlen()| function, this function can be
- * used as an approximation: |memchr(my_str, 0, SIZE_MAX) - my_str|.
+ * Since libbase does not provide a `strlen()` function, this function can be
+ * used as an approximation: `memchr(my_str, 0, SIZE_MAX) - my_str`.
*
* @param ptr the region to search.
* @param value the value, converted to a byte, to search for.
diff --git a/sw/device/lib/base/mmio.c b/sw/device/lib/base/mmio.c
index 1a593df..8843f3f 100644
--- a/sw/device/lib/base/mmio.c
+++ b/sw/device/lib/base/mmio.c
@@ -4,7 +4,7 @@
#include "sw/device/lib/base/mmio.h"
-// |extern| declarations to give the inline functions in the
+// `extern` declarations to give the inline functions in the
// corresponding header a link location.
extern uint8_t mmio_region_read8(mmio_region_t base, ptrdiff_t offset);
extern uint16_t mmio_region_read16(mmio_region_t base, ptrdiff_t offset);
diff --git a/sw/device/lib/base/mmio.h b/sw/device/lib/base/mmio.h
index 8369486..79cdf90 100644
--- a/sw/device/lib/base/mmio.h
+++ b/sw/device/lib/base/mmio.h
@@ -19,8 +19,8 @@
* Memory-mapped IO functions, which either map to volatile accesses, or can be
* replaced with instrumentation calls at compile time, for use with tests.
*
- * Compiling translation units that pull in this header with |-DMOCK_MMIO| will
- * disable the definitions of |mmio_region_read| and |mmio_region_write|. These
+ * Compiling translation units that pull in this header with `-DMOCK_MMIO` will
+ * disable the definitions of `mmio_region_read` and `mmio_region_write`. These
* symbols can then be defined by a test harness to allow for instrumentation of
* MMIO accesses.
*/
@@ -33,10 +33,10 @@
typedef struct mmio_region { volatile void *base; } mmio_region_t;
/**
- * Create a new |mmio_region_t| from the given address.
+ * Create a new `mmio_region_t` from the given address.
*
* @param address an address to an MMIO region.
- * @return a |mmio_region_t| value representing that region.
+ * @return a `mmio_region_t` value representing that region.
*/
inline mmio_region_t mmio_region_from_addr(uintptr_t address) {
return (mmio_region_t){
@@ -45,7 +45,7 @@
}
/**
- * Reads an aligned uint8_t from the MMIO region |base| at the given byte
+ * Reads an aligned uint8_t from the MMIO region `base` at the given byte
* offset.
*
* This function is guaranteed to commit a read to memory, and will not be
@@ -60,7 +60,7 @@
}
/**
- * Reads an aligned uint16_t from the MMIO region |base| at the given byte
+ * Reads an aligned uint16_t from the MMIO region `base` at the given byte
* offset.
*
* This function is guaranteed to commit a read to memory, and will not be
@@ -75,7 +75,7 @@
}
/**
- * Reads an aligned uint32_t from the MMIO region |base| at the given byte
+ * Reads an aligned uint32_t from the MMIO region `base` at the given byte
* offset.
*
* This function is guaranteed to commit a read to memory, and will not be
@@ -90,7 +90,7 @@
}
/**
- * Writes an aligned uint8_t to the MMIO region |base| at the given byte
+ * Writes an aligned uint8_t to the MMIO region `base` at the given byte
* offset.
*
* This function is guaranteed to commit a write to memory, and will not be
@@ -106,7 +106,7 @@
}
/**
- * Writes an aligned uint16_t to the MMIO region |base| at the given byte
+ * Writes an aligned uint16_t to the MMIO region `base` at the given byte
* offset.
*
* This function is guaranteed to commit a write to memory, and will not be
@@ -122,7 +122,7 @@
}
/**
- * Writes an aligned uint32_t to the MMIO region |base| at the given byte
+ * Writes an aligned uint32_t to the MMIO region `base` at the given byte
* offset.
*
* This function is guaranteed to commit a write to memory, and will not be
@@ -140,9 +140,9 @@
/**
* "Instrumented" mmio_region_t.
*
- * Instead of containing a volatile pointer, mmio_region_t becomes a |void *|
- * when |-DMOCK_MMIO| is enabled. This makes it incompatible with the non-mock
- * version of |mmio_region_t|, which prevents users from being able to access
+ * Instead of containing a volatile pointer, mmio_region_t becomes a `void *`
+ * when `-DMOCK_MMIO` is enabled. This makes it incompatible with the non-mock
+ * version of `mmio_region_t`, which prevents users from being able to access
* the pointer inside.
*/
typedef struct mmio_region { void *mock; } mmio_region_t;
@@ -160,10 +160,10 @@
#endif // MOCK_MMIO
/**
- * Reads the bits in |mask| from the MMIO region |base| at the given offset.
+ * Reads the bits in `mask` from the MMIO region `base` at the given offset.
*
- * This function has the same guarantees as |mmio_region_read32()| and
- * |mmio_region_write32()|.
+ * This function has the same guarantees as `mmio_region_read32()` and
+ * `mmio_region_write32()`.
*
* @param base the region to mask.
* @param offset the offset to apply the mask at, in bytes.
@@ -179,11 +179,11 @@
}
/**
- * Checks whether the |bit_index|th bit is set in the MMIO region |base| at
+ * Checks whether the `bit_index`th bit is set in the MMIO region `base` at
* the given offset.
*
- * This function has the same guarantees as |mmio_region_read32()| and
- * |mmio_region_write32()|.
+ * This function has the same guarantees as `mmio_region_read32()` and
+ * `mmio_region_write32()`.
*
* @param base the region to mask.
* @param offset the offset to apply the mask at.
@@ -196,7 +196,7 @@
}
/**
- * Clears the bits in |mask| from the MMIO region |base| at the given offset.
+ * Clears the bits in `mask` from the MMIO region `base` at the given offset.
*
* This function performs a non-atomic read-write-modify operation on a
* MMIO region.
@@ -216,7 +216,7 @@
}
/**
- * Sets the bits in |mask| from the MMIO region |base| at the given offset.
+ * Sets the bits in `mask` from the MMIO region `base` at the given offset.
*
* This function performs a non-atomic read-write-modify operation on a
* MMIO region.
@@ -235,10 +235,10 @@
}
/**
- * Clears the |bit_index|th bit in the MMIO region |base| at the given offset.
+ * Clears the `bit_index`th bit in the MMIO region `base` at the given offset.
*
* This function has the same guarantees as
- * |mmio_region_nonatomic_clear_mask()|.
+ * `mmio_region_nonatomic_clear_mask()`.
*
* @param base the region to mask.
* @param offset the offset to apply the mask at.
@@ -251,9 +251,9 @@
}
/**
- * Sets the |bit_index|th bit in the MMIO region |base| at the given offset.
+ * Sets the `bit_index`th bit in the MMIO region `base` at the given offset.
*
- * This function has the same guarantees as |mmio_region_nonatomic_set_mask()|.
+ * This function has the same guarantees as `mmio_region_nonatomic_set_mask()`.
*
* @param base the region to mask.
* @param offset the offset to apply the mask at.
diff --git a/sw/device/lib/base/print.c b/sw/device/lib/base/print.c
index 3e3cc7a..24dcaef 100644
--- a/sw/device/lib/base/print.c
+++ b/sw/device/lib/base/print.c
@@ -35,7 +35,7 @@
};
// NOTE: all of the lengths of the strings below are given so that the NUL
-// terminator is left off; that way, |sizeof(kConst)| does not include it.
+// terminator is left off; that way, `sizeof(kConst)` does not include it.
static const char kDigitsLow[16] = "0123456789abcdef";
static const char kDigitsHigh[16] = "0123456789ABCDEF";
@@ -116,12 +116,12 @@
}
/**
- * Consumes characters from |format| until a '%' or NUL is reached. All
- * characters seen before that are then sinked into |out|.
+ * Consumes characters from `format` until a '%' or NUL is reached. All
+ * characters seen before that are then sinked into `out`.
*
* @param out the sink to write bytes to.
* @param format a pointer to the format string to consume a prefix of.
- * @param bytes_written out param for the number of bytes writen to |out|.
+ * @param bytes_written out param for the number of bytes writen to `out`.
* @return true if an unprocessed '%' was found.
*/
static bool consume_until_percent(buffer_sink_t out, const char **format,
@@ -149,8 +149,8 @@
} format_specifier_t;
/**
- * Consumes characters from |format| until a complete format specifier is
- * parsed. See the documentation in |print.h| for full syntax.
+ * Consumes characters from `format` until a complete format specifier is
+ * parsed. See the documentation in `print.h` for full syntax.
*
* @param out the sink to write bytes to.
* @param format a pointer to the format string to consume a prefix of.
@@ -196,15 +196,15 @@
}
/**
- * Write the digits of |value| onto |out|.
+ * Write the digits of `value` onto `out`.
*
* @param out the sink to write bytes to.
* @param value the value to "stringify".
* @param width the minimum width to print; going below will result in writing
* out zeroes.
- * @param base the base to express |value| in.
+ * @param base the base to express `value` in.
* @param glyphs an array of characters to use as the digits of a number, which
- * should be at least ast long as |base|.
+ * should be at least ast long as `base`.
* @return the number of bytes written.
*/
static size_t write_digits(buffer_sink_t out, uint32_t value, uint32_t width,
@@ -231,14 +231,14 @@
}
/**
- * Prints out the next entry in |args| according to |spec|.
+ * Prints out the next entry in `args` according to `spec`.
*
- * This function assumes that |spec| accurately describes the next entry in
- * |args|.
+ * This function assumes that `spec` accurately describes the next entry in
+ * `args`.
*
* @param out the sink to write bytes to.
* @param spec the specifier to use for stringifying.
- * @param bytes_written out param for the number of bytes writen to |out|.
+ * @param bytes_written out param for the number of bytes writen to `out`.
* @param va_list the list to pull an entry from.
*/
static void process_specifier(buffer_sink_t out, format_specifier_t spec,
@@ -332,8 +332,8 @@
}
// NOTE: This copy is necessary on amd64 and other platforms, where
- // |va_list| is a fixed array type (and, as such, decays to a pointer in
- // an argument list). On PSABI RV32IMC, however, |va_list| is a |void*|, so
+ // `va_list` is a fixed array type (and, as such, decays to a pointer in
+ // an argument list). On PSABI RV32IMC, however, `va_list` is a `void*`, so
// this is a copy of the pointer, not the array.
va_list args_copy;
va_copy(args_copy, args);
diff --git a/sw/device/lib/base/print.h b/sw/device/lib/base/print.h
index 0b15d35..94563b1 100644
--- a/sw/device/lib/base/print.h
+++ b/sw/device/lib/base/print.h
@@ -14,7 +14,7 @@
*
* We avoid using libc names here, since we do not support the full suite of
* format specifier syntax, and use a different character sink type instead of
- * the traditional |FILE *|.
+ * the traditional `FILE *`.
*
* All functions in this file should be machine word size agnostic, that is, the
* same code should work correctly on both 32-bit and 64-bit machines, though
@@ -39,13 +39,13 @@
/**
* Prints out a message to stdout, formatted according to the format string
- * |format|.
+ * `format`.
*
* The definition of "stdout" is not provided by this library; rather, it must
- * be initialized using |base_set_stdout()|.
+ * be initialized using `base_set_stdout()`.
*
* This function supports a subset of the format specifiers provided by standard
- * C |printf|. Those are, namely:
+ * C `printf`. Those are, namely:
* - %%, which prints a percent sign.
* - %c, which prints the lowest byte of a uint32_t as a character.
* - %s, which prints a NUL-terminated string.
@@ -68,7 +68,7 @@
* garbage, and are, as such, unsupported.
*
* This function furthermore supports width modifiers for integer specifiers,
- * such as |%10d|. It does not support dynamic widths like |%*d|, and will also
+ * such as `%10d`. It does not support dynamic widths like `%*d`, and will also
* always pad with zeroes, rather than spaces.
*
* Of course, providing arguments for formatting which are incompatible with a
@@ -81,17 +81,17 @@
/**
* Prints out a message to stdout, formatted according to the format string
- * |format|.
+ * `format`.
*
- * This function is identical to |base_printf|, except in that it takes a
- * |va_list| instead of having a vararg parameter. This function plays a role
- * analogous to |base_vfprintf|, for functions that wish to use the currently
- * set |stdout|.
+ * This function is identical to `base_printf`, except in that it takes a
+ * `va_list` instead of having a vararg parameter. This function plays a role
+ * analogous to `base_vfprintf`, for functions that wish to use the currently
+ * set `stdout`.
*
- * This function *does not* take ownership of |args|; callers are responsible
- * for calling |va_end|.
+ * This function *does not* take ownership of `args`; callers are responsible
+ * for calling `va_end`.
*
- * See |base_printf()| for the semantics of the format specification.
+ * See `base_printf()` for the semantics of the format specification.
*
* @param format the format spec.
* @param args values to interpolate in the format spec.
@@ -99,12 +99,12 @@
size_t base_vprintf(const char *format, va_list args);
/*
- * Prints a message to the buffer |buf|, capped at a given length.
+ * Prints a message to the buffer `buf`, capped at a given length.
*
* It goes without saying that the caller must ensure the given buffer is large
* enough; failure to do so is Undefined Behavior.
*
- * See |base_printf()| for the semantics of the format specification.
+ * See `base_printf()` for the semantics of the format specification.
*
* @param buf a buffer to print to.
* @param format the format spec.
@@ -113,13 +113,13 @@
size_t base_snprintf(char *buf, size_t len, const char *format, ...);
/**
- * Prints a message to the sink |out|.
+ * Prints a message to the sink `out`.
*
- * If |out.sink| is |NULL|, writes are treated as-if they were written to a
+ * If `out.sink` is `NULL`, writes are treated as-if they were written to a
* UNIX-like /dev/null: writes succeed, but the actual bytes are not printed
* anywhere.
*
- * See |base_printf()| for the semantics of the format specification.
+ * See `base_printf()` for the semantics of the format specification.
*
* @param out a sink to print to.
* @param format the format spec.
@@ -128,22 +128,22 @@
size_t base_fprintf(buffer_sink_t out, const char *format, ...);
/**
- * Prints a message to the sink |out|.
+ * Prints a message to the sink `out`.
*
- * This function is identical to |base_fprintf|, except in that it takes a
- * |va_list| instead of having a vararg parameter. This function is provided
+ * This function is identical to `base_fprintf`, except in that it takes a
+ * `va_list` instead of having a vararg parameter. This function is provided
* not for calling directly, but rather for being called by functions that
* already take a variable number of arguments, and wish to make use of
* formatting facilities.
*
- * This function *does not* take ownership of |args|; callers are responsible
- * for calling |va_end|.
+ * This function *does not* take ownership of `args`; callers are responsible
+ * for calling `va_end`.
*
- * If |out.sink| is |NULL|, writes are treated as-if they were written to a
+ * If `out.sink` is `NULL`, writes are treated as-if they were written to a
* UNIX-like /dev/null: writes succeed, but the actual bytes are not printed
* anywhere.
*
- * See |base_printf()| for the semantics of the format specification.
+ * See `base_printf()` for the semantics of the format specification.
*
* @param out a sink to print to.
* @param format the format spec.
@@ -152,7 +152,7 @@
size_t base_vfprintf(buffer_sink_t out, const char *format, va_list args);
/**
- * Sets what the "stdout" sink is, which is used by |base_printf()|.
+ * Sets what the "stdout" sink is, which is used by `base_printf()`.
*
* The default sink behaves like /dev/null on a standard UNIX system: writes
* are treated as successful, but the contents of buffers are ignored.
@@ -160,7 +160,7 @@
* As such, this function must be called for printed messages to wind up
* somewhere.
*
- * Passing in |NULL| instead of a real function pointer will reset stdout to
+ * Passing in `NULL` instead of a real function pointer will reset stdout to
* the default /dev/null behavior.
*
* @param out the sink to use for "default" printing.
diff --git a/sw/device/lib/base/stdasm.h b/sw/device/lib/base/stdasm.h
index 8794d82..9dacb09 100644
--- a/sw/device/lib/base/stdasm.h
+++ b/sw/device/lib/base/stdasm.h
@@ -6,8 +6,8 @@
#define OPENTITAN_SW_DEVICE_LIB_BASE_STDASM_H_
/**
- * This header simply provides the |asm| keyword, in analogy with the ISO C
- * headers |stdbool.h|, |stdnoreturn.h|, and so on.
+ * This header simply provides the `asm` keyword, in analogy with the ISO C
+ * headers `stdbool.h`, `stdnoreturn.h`, and so on.
*/
#define asm __asm__
diff --git a/sw/device/lib/dif/dif_gpio.c b/sw/device/lib/dif/dif_gpio.c
index 6787b65..aaeaf5d 100644
--- a/sw/device/lib/dif/dif_gpio.c
+++ b/sw/device/lib/dif/dif_gpio.c
@@ -20,7 +20,7 @@
* The GPIO device provides masked bit-level atomic writes to its DIRECT_OUT
* and DIRECT_OE registers. This allows software to modify half of the bits
* at a time without requiring a read-modify-write. Note that depending on the
- * value of the |mask|, this function may perform two writes.
+ * value of the `mask`, this function may perform two writes.
*
* For instance, DIRECT_OUT's lower and upper halves can be modified by
* MASKED_OUT_LOWER and MASKED_OUT_UPPER, respectively. Upper half of
@@ -61,7 +61,7 @@
* to perform only one write since it never needs to access both halves of a
* register.
*
- * See also |gpio_masked_write()|.
+ * See also `gpio_masked_write()`.
*
* @param gpio GPIO instance.
* @param reg_lower_offset Offset of the masked access register that corresponds to
@@ -90,9 +90,9 @@
return kDifGpioResultInvalidArgument;
}
- // Save internal state in the given |dif_gpio_t| instance.
+ // Save internal state in the given `dif_gpio_t` instance.
gpio->base_addr = config->base_addr;
- // Reset the GPIO device at the given |base_addr|.
+ // Reset the GPIO device at the given `base_addr`.
dif_gpio_reset(gpio);
return kDifGpioResultOK;
diff --git a/sw/device/lib/dif/dif_gpio.h b/sw/device/lib/dif/dif_gpio.h
index b6b1d92..2e73c7b 100644
--- a/sw/device/lib/dif/dif_gpio.h
+++ b/sw/device/lib/dif/dif_gpio.h
@@ -18,7 +18,7 @@
/**
* Internal state of a GPIO device.
*
- * Instances of this struct must be initialized by |dif_gpio_init()| before
+ * Instances of this struct must be initialized by `dif_gpio_init()` before
* being passed to other functions.
*/
typedef struct dif_gpio { mmio_region_t base_addr; } dif_gpio_t;
@@ -26,9 +26,9 @@
/**
* Generic return codes for the functions in this library.
*
- * |kDifGpioResultInvalidArgument| signals that there is a problem with the
+ * `kDifGpioResultInvalidArgument` signals that there is a problem with the
* argument(s) but the function did not have any side effects.
- * |kDifGpioResultGeneralError| covers other error cases.
+ * `kDifGpioResultGeneralError` covers other error cases.
*/
typedef enum dif_gpio_result {
kDifGpioResultOK,
@@ -50,7 +50,7 @@
} dif_gpio_irq_t;
/**
- * Initialize a GPIO device using |config| and return its internal state.
+ * Initialize a GPIO device using `config` and return its internal state.
*
* A particular GPIO device must first be initialized by this function
* before calling other functions of this library.
@@ -58,8 +58,8 @@
* @param config Configuration for initializing a GPIO device.
* @param gpio GPIO instance that will store the internal state of the
* initialized GPIO device.
- * @return |kDifGpioResultInvalidArgument| if |config| or |gpio| is |NULL|,
- * |kDifGpioResultOK| otherwise.
+ * @return `kDifGpioResultInvalidArgument` if `config` or `gpio` is `NULL`,
+ * `kDifGpioResultOK` otherwise.
*/
dif_gpio_result_t dif_gpio_init(const dif_gpio_config_t *config,
dif_gpio_t *gpio);
@@ -71,8 +71,8 @@
* reset values. Disables interrupts, output, and input filter.
*
* @param gpio GPIO instance
- * @return |kDifGpioResultInvalidArgument| if |gpio| is |NULL|,
- * |kDifGpioResultOK| otherwise.
+ * @return `kDifGpioResultInvalidArgument` if `gpio` is `NULL`,
+ * `kDifGpioResultOK` otherwise.
*/
dif_gpio_result_t dif_gpio_reset(const dif_gpio_t *gpio);
@@ -85,8 +85,8 @@
*
* @param gpio GPIO instance.
* @param pin_values Pin values.
- * @return |kDifGpioResultInvalidArgument| if |gpio| or |pin_values| is |NULL|,
- * |kDifGpioResultOK| otherwise.
+ * @return `kDifGpioResultInvalidArgument` if `gpio` or `pin_values` is `NULL`,
+ * `kDifGpioResultOK` otherwise.
*/
dif_gpio_result_t dif_gpio_all_read(const dif_gpio_t *gpio,
uint32_t *pin_values);
@@ -101,8 +101,8 @@
* @param gpio GPIO instance.
* @param index Zero-based index of the pin to read from.
* @param pin_value Pin value.
- * @return |kDifGpioResultInvalidArgument| if |gpio| or |pin_values| is |NULL|,
- * |kDifGpioResultOK| otherwise.
+ * @return `kDifGpioResultInvalidArgument` if `gpio` or `pin_values` is `NULL`,
+ * `kDifGpioResultOK` otherwise.
*/
dif_gpio_result_t dif_gpio_pin_read(const dif_gpio_t *gpio, uint32_t index,
bool *pin_value);
@@ -114,8 +114,8 @@
*
* @param gpio GPIO instance.
* @param val Value to write.
- * @return |kDifGpioResultInvalidArgument| if |gpio| is |NULL|,
- * |kDifGpioResultOK| otherwise.
+ * @return `kDifGpioResultInvalidArgument` if `gpio` is `NULL`,
+ * `kDifGpioResultOK` otherwise.
*/
dif_gpio_result_t dif_gpio_all_write(const dif_gpio_t *gpio, uint32_t val);
@@ -127,8 +127,8 @@
* @param gpio GPIO instance.
* @param index Zero-based index of the pin to write to.
* @param val Value to write.
- * @return |kDifGpioResultInvalidArgument| if |gpio| is |NULL|,
- * |kDifGpioResultOK| otherwise.
+ * @return `kDifGpioResultInvalidArgument` if `gpio` is `NULL`,
+ * `kDifGpioResultOK` otherwise.
*/
dif_gpio_result_t dif_gpio_pin_write(const dif_gpio_t *gpio, uint32_t index,
bool val);
@@ -141,8 +141,8 @@
* @param gpio GPIO instance
* @param mask Mask that identifies the pins to write to.
* @param val Value to write.
- * @return |kDifGpioResultInvalidArgument| if |gpio| is |NULL|,
- * |kDifGpioResultOK| otherwise.
+ * @return `kDifGpioResultInvalidArgument` if `gpio` is `NULL`,
+ * `kDifGpioResultOK` otherwise.
*/
dif_gpio_result_t dif_gpio_masked_write(const dif_gpio_t *gpio, uint32_t mask,
uint32_t val);
@@ -150,12 +150,12 @@
/**
* Set output modes of all pins.
*
- * Setting |val[i]| to 1 enables output mode for pin |i|.
+ * Setting `val[i]` to 1 enables output mode for pin `i`.
*
* @param gpio GPIO instance.
* @param val Output modes of the pins.
- * @return |kDifGpioResultInvalidArgument| if |gpio| is |NULL|,
- * |kDifGpioResultOK| otherwise.
+ * @return `kDifGpioResultInvalidArgument` if `gpio` is `NULL`,
+ * `kDifGpioResultOK` otherwise.
*/
dif_gpio_result_t dif_gpio_output_mode_all_set(const dif_gpio_t *gpio,
uint32_t val);
@@ -163,13 +163,13 @@
/**
* Set output mode of a pin.
*
- * Setting |val| to |true| enables output mode for the pin.
+ * Setting `val` to `true` enables output mode for the pin.
*
* @param gpio GPIO instance
* @param index Zero-based index of the pin.
* @param val Output mode of the pin.
- * @return |kDifGpioResultInvalidArgument| if |gpio| is |NULL|,
- * |kDifGpioResultOK| otherwise.
+ * @return `kDifGpioResultInvalidArgument` if `gpio` is `NULL`,
+ * `kDifGpioResultOK` otherwise.
*/
dif_gpio_result_t dif_gpio_output_mode_pin_set(const dif_gpio_t *gpio,
uint32_t index, bool val);
@@ -177,13 +177,13 @@
/**
* Set the output modes of the pins identified by a mask.
*
- * Setting |val[i]| to 1 enables output mode for pin |i|.
+ * Setting `val[i]` to 1 enables output mode for pin `i`.
*
* @param gpio GPIO instance
* @param mask Mask that identifies the pins whose output modes will be set.
* @param val Output modes of the pins.
- * @return |kDifGpioResultInvalidArgument| if |gpio| is |NULL|,
- * |kDifGpioResultOK| otherwise.
+ * @return `kDifGpioResultInvalidArgument` if `gpio` is `NULL`,
+ * `kDifGpioResultOK` otherwise.
*/
dif_gpio_result_t dif_gpio_output_mode_masked_set(const dif_gpio_t *gpio,
uint32_t mask, uint32_t val);
@@ -197,8 +197,8 @@
*
* @param gpio GPIO instance.
* @param index Zero-based index of the pin.
- * @return |kDifGpioResultInvalidArgument| if |gpio| is |NULL|,
- * |kDifGpioResultOK| otherwise.
+ * @return `kDifGpioResultInvalidArgument` if `gpio` is `NULL`,
+ * `kDifGpioResultOK` otherwise.
*/
dif_gpio_result_t dif_gpio_irq_pin_test(const dif_gpio_t *gpio, uint32_t index);
@@ -207,8 +207,8 @@
*
* @param gpio GPIO instance.
* @param interrupt_states Interrupt states of all pins.
- * @return |kDifGpioResultInvalidArgument| if |gpio| or |interrupt_states| is
- * |NULL|, |kDifGpioResultOK| otherwise.
+ * @return `kDifGpioResultInvalidArgument` if `gpio` or `interrupt_states` is
+ * `NULL`, `kDifGpioResultOK` otherwise.
*/
dif_gpio_result_t dif_gpio_irq_all_read(const dif_gpio_t *gpio,
uint32_t *interrupt_states);
@@ -220,8 +220,8 @@
* @param index Zero-based index of the pin.
* @param interrupt_state Interrupt state of the pin. True if there is a pending
* interrupt, false otherwise.
- * @return |kDifGpioResultInvalidArgument| if |gpio| or |interrupt_state| is
- * |NULL|, |kDifGpioResultOK| otherwise.
+ * @return `kDifGpioResultInvalidArgument` if `gpio` or `interrupt_state` is
+ * `NULL`, `kDifGpioResultOK` otherwise.
*/
dif_gpio_result_t dif_gpio_irq_pin_read(const dif_gpio_t *gpio, uint32_t index,
bool *interrupt_state);
@@ -231,8 +231,8 @@
*
* @param gpio GPIO instance.
* @param index Zero-based index of the pin.
- * @return |kDifGpioResultInvalidArgument| if |gpio| is |NULL|,
- * |kDifGpioResultOK| otherwise.
+ * @return `kDifGpioResultInvalidArgument` if `gpio` is `NULL`,
+ * `kDifGpioResultOK` otherwise.
*/
dif_gpio_result_t dif_gpio_irq_pin_clear(const dif_gpio_t *gpio,
uint32_t index);
@@ -240,14 +240,14 @@
/**
* Enable noise filter for GPIO inputs.
*
- * Setting |mask[i]| to 1 enables input noise filter for pin |i|. If enabled,
+ * Setting `mask[i]` to 1 enables input noise filter for pin `i`. If enabled,
* changes in the pin value will be ignored unless stable for 16 cycles.
*
* @param gpio GPIO instance.
* @param mask Mask that identifies the pins for which input noise filter will
* be enabled.
- * @return |kDifGpioResultInvalidArgument| if |gpio| is |NULL|,
- * |kDifGpioResultOK| otherwise.
+ * @return `kDifGpioResultInvalidArgument` if `gpio` is `NULL`,
+ * `kDifGpioResultOK` otherwise.
*/
dif_gpio_result_t dif_gpio_input_noise_filter_masked_enable(
const dif_gpio_t *gpio, uint32_t mask);
@@ -255,13 +255,13 @@
/**
* Disable noise filter for GPIO inputs.
*
- * Setting |mask[i]| to 1 disables input noise filter for pin |i|.
+ * Setting `mask[i]` to 1 disables input noise filter for pin `i`.
*
* @param gpio GPIO instance.
* @param mask Mask that identifies the pins for which input noise filter will
* be disabled.
- * @return |kDifGpioResultInvalidArgument| if |gpio| is |NULL|,
- * |kDifGpioResultOK| otherwise.
+ * @return `kDifGpioResultInvalidArgument` if `gpio` is `NULL`,
+ * `kDifGpioResultOK` otherwise.
*/
dif_gpio_result_t dif_gpio_input_noise_filter_masked_disable(
const dif_gpio_t *gpio, uint32_t mask);
@@ -269,7 +269,7 @@
/**
* Enable interrupts for GPIO inputs.
*
- * Setting |mask[i]| to 1 enables detection of interrupt events for pin |i|.
+ * Setting `mask[i]` to 1 enables detection of interrupt events for pin `i`.
* There are four types of interrupts per pin: rising-edge, falling-edge,
* high-level, and low-level. At least one of them must be enabled to generate
* interrupts.
@@ -277,8 +277,8 @@
* @param gpio GPIO instance.
* @param mask Mask that identifies the pins for which interrupts will be
* enabled.
- * @return |kDifGpioResultInvalidArgument| if |gpio| is |NULL|,
- * |kDifGpioResultOK| otherwise.
+ * @return `kDifGpioResultInvalidArgument` if `gpio` is `NULL`,
+ * `kDifGpioResultOK` otherwise.
*/
dif_gpio_result_t dif_gpio_irq_masked_enable(const dif_gpio_t *gpio,
uint32_t mask);
@@ -286,13 +286,13 @@
/**
* Disable interrupts for GPIO inputs.
*
- * Setting |mask[i]| to 1 disables detection of interrupt events for pin |i|.
+ * Setting `mask[i]` to 1 disables detection of interrupt events for pin `i`.
*
* @param gpio GPIO instance.
* @param mask Mask that identifies the pins for which interrupts will be
* disabled.
- * @return |kDifGpioResultInvalidArgument| if |gpio| is |NULL|,
- * |kDifGpioResultOK| otherwise.
+ * @return `kDifGpioResultInvalidArgument` if `gpio` is `NULL`,
+ * `kDifGpioResultOK` otherwise.
*/
dif_gpio_result_t dif_gpio_irq_masked_disable(const dif_gpio_t *gpio,
uint32_t mask);
@@ -306,8 +306,8 @@
* @param gpio GPIO instance.
* @param mask Mask that identifies the pins whose interrupt triggers will be
* disabled.
- * @return |kDifGpioResultInvalidArgument| if |gpio| is |NULL|,
- * |kDifGpioResultOK| otherwise.
+ * @return `kDifGpioResultInvalidArgument` if `gpio` is `NULL`,
+ * `kDifGpioResultOK` otherwise.
*/
dif_gpio_result_t dif_gpio_irq_trigger_masked_disable(const dif_gpio_t *gpio,
uint32_t mask);
@@ -323,8 +323,8 @@
* @param mask Mask that identifies the pins whose interrupt triggers will be
* configured.
* @param config New configuration of interrupt triggers.
- * @return |kDifGpioResultOK| if the function is successful,
- * |kDifGpioResultInvalidArgument| otherwise.
+ * @return `kDifGpioResultOK` if the function is successful,
+ * `kDifGpioResultInvalidArgument` otherwise.
*/
dif_gpio_result_t dif_gpio_irq_trigger_masked_config(
const dif_gpio_t *gpio, uint32_t mask, dif_gpio_irq_t config);
diff --git a/sw/device/lib/dif/dif_uart.c b/sw/device/lib/dif/dif_uart.c
index a555464..63f6aa6 100644
--- a/sw/device/lib/dif/dif_uart.c
+++ b/sw/device/lib/dif/dif_uart.c
@@ -140,7 +140,7 @@
}
/**
- * Write up to |bytes_requested| number of bytes to the TX FIFO.
+ * Write up to `bytes_requested` number of bytes to the TX FIFO.
*/
static size_t uart_bytes_send(const dif_uart_t *uart, const uint8_t *data,
size_t bytes_requested) {
@@ -154,7 +154,7 @@
}
/**
- * Read up to |bytes_requested| number of bytes from the RX FIFO.
+ * Read up to `bytes_requested` number of bytes from the RX FIFO.
*/
static size_t uart_bytes_receive(const dif_uart_t *uart, size_t bytes_requested,
uint8_t *data) {
@@ -263,7 +263,7 @@
return false;
}
- // |bytes_written| is an optional parameter
+ // `bytes_written` is an optional parameter
size_t res = uart_bytes_send(uart, data, bytes_requested);
if (bytes_written != NULL) {
*bytes_written = res;
@@ -278,7 +278,7 @@
return false;
}
- // |bytes_read| is an optional parameter
+ // `bytes_read` is an optional parameter
size_t res = uart_bytes_receive(uart, bytes_requested, data);
if (bytes_read != NULL) {
*bytes_read = res;
diff --git a/sw/device/lib/dif/dif_uart.h b/sw/device/lib/dif/dif_uart.h
index 938488a..c55d1a7 100644
--- a/sw/device/lib/dif/dif_uart.h
+++ b/sw/device/lib/dif/dif_uart.h
@@ -80,7 +80,7 @@
/**
* UART instance state
*
- * UART persistent data that is required by all UART API. |base_address| must
+ * UART persistent data that is required by all UART API. `base_address` must
* be initialised by the caller, before passing into the UART DIF init routine.
*/
typedef struct dif_uart {
diff --git a/sw/device/lib/flash_ctrl.h b/sw/device/lib/flash_ctrl.h
index c7c26dd..f15d197 100644
--- a/sw/device/lib/flash_ctrl.h
+++ b/sw/device/lib/flash_ctrl.h
@@ -50,7 +50,7 @@
int flash_check_empty(void);
/**
- * Erase flash bank |bank_idx|. Blocks until erase is complete.
+ * Erase flash bank `bank_idx`. Blocks until erase is complete.
*
* @param idx Flash bank index.
* @return Non zero on failure.
@@ -59,17 +59,17 @@
int flash_page_erase(uint32_t addr);
/**
- * Write |data| at |addr| offset with |size| in 4B words
+ * Write `data` at `addr` offset with `size` in 4B words
*
* @param addr Flash address 32bit aligned.
* @param data Data to write.
- * @param size Number of 4B words to write from |data| buffer.
+ * @param size Number of 4B words to write from `data` buffer.
* @return Non zero on failure.
*/
int flash_write(uint32_t addr, const uint32_t *data, uint32_t size);
/**
- * Read |size| 4B words and write result to |data|.
+ * Read `size` 4B words and write result to `data`.
*
* @param addr Read start address.
* @param size Number of 4B words to read.
diff --git a/sw/device/lib/hmac.h b/sw/device/lib/hmac.h
index 9c3f22a..d878359 100644
--- a/sw/device/lib/hmac.h
+++ b/sw/device/lib/hmac.h
@@ -35,7 +35,7 @@
void hmac_init(hmac_cfg_t hmac_cfg);
/**
- * Write |size_in_bytes| bytes of |data| to HMAC input buffer
+ * Write `size_in_bytes` bytes of `data` to HMAC input buffer
*
* @param data pointer to input buffer.
* @param size_in_bytes number of bytes to write.
diff --git a/sw/device/lib/hw_sha256.h b/sw/device/lib/hw_sha256.h
index e28f2d5..b60849b 100644
--- a/sw/device/lib/hw_sha256.h
+++ b/sw/device/lib/hw_sha256.h
@@ -14,14 +14,14 @@
#define SHA256_DIGEST_SIZE 32
/**
- * hw_SHA256_init initializes |ctx|.
+ * hw_SHA256_init initializes `ctx`.
*
* @param ctx SHA256 context.
*/
void hw_SHA256_init(HW_SHA256_CTX *ctx);
/**
- * hw_SHA256_update adds |len| bytes from |data| to |ctx|.
+ * hw_SHA256_update adds `len` bytes from `data` to `ctx`.
*
* @param ctx SHA256 context.
* @param data Input buffer.
@@ -30,16 +30,16 @@
void hw_SHA256_update(HW_SHA256_CTX *ctx, const void *data, size_t len);
/**
- * hw_SHA256_final adds the final padding to |ctx| and calculates digest.
+ * hw_SHA256_final adds the final padding to `ctx` and calculates digest.
*
* @param ctx SHA256 context.
*
- * @return pointer to digest buffer held in |ctx|.
+ * @return pointer to digest buffer held in `ctx`.
*/
const uint8_t *hw_SHA256_final(HW_SHA256_CTX *ctx);
/**
- * hw_SHA256_hash writes |digest| from |len| bytes of |data|.
+ * hw_SHA256_hash writes `digest` from `len` bytes of `data`.
*
* @param data Input buffer.
* @param len Number of bytes to add.
diff --git a/sw/device/lib/runtime/ibex.h b/sw/device/lib/runtime/ibex.h
index d6ca643..a6081f5 100644
--- a/sw/device/lib/runtime/ibex.h
+++ b/sw/device/lib/runtime/ibex.h
@@ -17,9 +17,9 @@
/**
* Read the cycle counter.
*
- * The value of the counter is stored across two 32-bit registers: |mcycle| and
- * |mcycleh|. This function is guaranteed to return a valid 64-bit cycle
- * counter value, even if |mcycle| overflows before reading |mcycleh|.
+ * The value of the counter is stored across two 32-bit registers: `mcycle` and
+ * `mcycleh`. This function is guaranteed to return a valid 64-bit cycle
+ * counter value, even if `mcycle` overflows before reading `mcycleh`.
*
* Adapted from: The RISC-V Instruction Set Manual, Volume I: Unprivileged ISA
* V20191213, pp. 61.
@@ -30,11 +30,11 @@
uint32_t cycle_high_2 = 0;
asm volatile(
"read%=:"
- " csrr %0, mcycleh;" // Read |mcycleh|.
- " csrr %1, mcycle;" // Read |mcycle|.
- " csrr %2, mcycleh;" // Read |mcycleh| again.
- " bne %0, %2, read%=;" // Try again if |mcycle| overflowed before
- // reading |mcycleh|.
+ " csrr %0, mcycleh;" // Read `mcycleh`.
+ " csrr %1, mcycle;" // Read `mcycle`.
+ " csrr %2, mcycleh;" // Read `mcycleh` again.
+ " bne %0, %2, read%=;" // Try again if `mcycle` overflowed before
+ // reading `mcycleh`.
: "+r"(cycle_high), "=r"(cycle_low), "+r"(cycle_high_2)
:);
return (uint64_t)cycle_high << 32 | cycle_low;
diff --git a/sw/device/lib/testing/mock_mmio.h b/sw/device/lib/testing/mock_mmio.h
index e1461c3..a3d335a 100644
--- a/sw/device/lib/testing/mock_mmio.h
+++ b/sw/device/lib/testing/mock_mmio.h
@@ -42,7 +42,7 @@
/**
* Represents a single bit field in an integer, similar to BitField. It can be
- * used in most places that need a BitField, as well as in |EXPECT_MASK| macros.
+ * used in most places that need a BitField, as well as in `EXPECT_MASK` macros.
*
* Like with BitFields, we can express the integer 0b0000'0000'1100'0101 as a
* list of BitFieldMasks:
@@ -65,21 +65,21 @@
namespace internal {
/**
- * Implicit conversion guard around |char *|. See |LeInt()|.
+ * Implicit conversion guard around `char *`. See `LeInt()`.
*/
struct LittleEndianBytes {
const char *bytes;
};
/**
- * Converts the argument into an unsigned integer of type |Int|.
+ * Converts the argument into an unsigned integer of type `Int`.
*
* This overload is simply the identity on integers, and allows integers to be
* converted into themselves. This enables the basic EXPECT_* macros:
* EXPECT_READ32(offset, 0xcafecafe);
*
* @param val an integer.
- * @return the value |val|.
+ * @return the value `val`.
*/
template <typename Int>
Int ToInt(Int val) {
@@ -87,16 +87,16 @@
}
/**
- * Converts the argument into an unsinged integer of type |Int|.
+ * Converts the argument into an unsinged integer of type `Int`.
*
- * This overload assumes that |str| is a valid pointer to a buffer of at least
- * |sizeof(Int)| bytes, which are memcpy'd out as an |Int|. This enables
+ * This overload assumes that `str` is a valid pointer to a buffer of at least
+ * `sizeof(Int)` bytes, which are memcpy'd out as an `Int`. This enables
* memcpy-like EXPECT_* macros:
* EXPECT_READ32(offset, LeInt("rv32"));
* EXPECT_READ32(offset, LeInt("imc\0"));
*
- * @param str a pointer to a valid buffer of length at least |sizeof(Int)|.
- * @return a value of type |Int| memcpy'd out of |str|.
+ * @param str a pointer to a valid buffer of length at least `sizeof(Int)`.
+ * @return a value of type `Int` memcpy'd out of `str`.
*/
template <typename Int>
Int ToInt(LittleEndianBytes str) {
@@ -106,15 +106,15 @@
}
/**
- * Converts the argument into an unsigned integer of type |Int|.
+ * Converts the argument into an unsigned integer of type `Int`.
*
- * This overload performs the shifts and ors described by |fields|. See
- * |BitField|'s documentation for details one what this means. This overload
+ * This overload performs the shifts and ors described by `fields`. See
+ * `BitField`'s documentation for details one what this means. This overload
* enables bitfield EXPECT_* macros:
* EXPECT_READ32(offset, {{A_OFFSET, 0x55}, {B_OFFSET, 0xaa}});
*
* @param fields a list of bit field entries.
- * @return a value of type |Int| built out of |fields|.
+ * @return a value of type `Int` built out of `fields`.
*/
template <typename Int>
Int ToInt(std::initializer_list<BitField> fields) {
@@ -131,7 +131,7 @@
} // namespace internal
/**
- * Reads a little-endian integer from |bytes|. This function is lazy, and will
+ * Reads a little-endian integer from `bytes`. This function is lazy, and will
* only perform the converion when used with an EXPECT_* macro. For example:
* EXPECT_READ32(offset, LeInt("abcd"));
*
@@ -146,16 +146,16 @@
*
* MockDevice provides two mockable member functions, representing a read and a
* write at a particular offset from the base address. This class can be
- * converted into a |mmio_region_t| value, which, when used in |mmio.h|
- * functions like |read32()|, will map to the appropriate mock member function
+ * converted into a `mmio_region_t` value, which, when used in `mmio.h`
+ * functions like `read32()`, will map to the appropriate mock member function
* calls.
*
- * To maintain sequencing, |ReadN()| and |WriteN()| should not be
- * |EXPECT_CALL|'ed directly; instead, |EXPECT_READN| and |EXPECT_WRITEN| should
+ * To maintain sequencing, `ReadN()` and `WriteN()` should not be
+ * `EXPECT_CALL`'ed directly; instead, `EXPECT_READN` and `EXPECT_WRITEN` should
* be used, instead.
*
- * To use this class, |-DMOCK_MMIO| must be enabled in all translation units
- * using |mmio.h|.
+ * To use this class, `-DMOCK_MMIO` must be enabled in all translation units
+ * using `mmio.h`.
*/
class MockDevice {
public:
@@ -168,7 +168,7 @@
/**
* Converts this MockDevice into a mmio_region_t opaque object,
- * which is compatible with |mmio.h| functions.
+ * which is compatible with `mmio.h` functions.
*/
mmio_region_t region() { return {this}; }
@@ -197,12 +197,12 @@
/**
* Conveninence fixture for creating device tests.
*
- * This class should be derived by a test fixture (along with |testing::Test|)
- * and used in a |TEST_F| block. Doing so will make the |EXPECT_READN| and
- * |EXPECT_WRITEN| conveinence macros useable.
+ * This class should be derived by a test fixture (along with `testing::Test`)
+ * and used in a `TEST_F` block. Doing so will make the `EXPECT_READN` and
+ * `EXPECT_WRITEN` conveinence macros useable.
*
- * The device being mocked can be accessed in the test body with |this->dev()|.
- * |this->| is required in this case, since the name |dev| is not immediately
+ * The device being mocked can be accessed in the test body with `this->dev()`.
+ * `this->` is required in this case, since the name `dev` is not immediately
* visible.
*/
class MmioTest {
@@ -216,13 +216,13 @@
} // namespace mock_mmio
/**
- * Expect a read to the device |dev| at the given offset, returning the given
+ * Expect a read to the device `dev` at the given offset, returning the given
* 8-bit value.
*
* The value may be given as an integer, a pointer to little-endian data,
- * or a |std::initializer_list<BitField>|.
+ * or a `std::initializer_list<BitField>`.
*
- * This expectation is sequenced with all other |EXPECT_READ| and |EXPECT_WRITE|
+ * This expectation is sequenced with all other `EXPECT_READ` and `EXPECT_WRITE`
* calls.
*/
#define EXPECT_READ8_AT(dev, offset, ...) \
@@ -231,13 +231,13 @@
testing::Return(mock_mmio::internal::ToInt<uint8_t>(__VA_ARGS__)))
/**
- * Expect a read to the device |dev| at the given offset, returning the given
+ * Expect a read to the device `dev` at the given offset, returning the given
* 16-bit value.
*
* The value may be given as an integer, a pointer to little-endian data,
- * or a |std::initializer_list<BitField>|.
+ * or a `std::initializer_list<BitField>`.
*
- * This expectation is sequenced with all other |EXPECT_READ| and |EXPECT_WRITE|
+ * This expectation is sequenced with all other `EXPECT_READ` and `EXPECT_WRITE`
* calls.
*/
#define EXPECT_READ16_AT(dev, offset, ...) \
@@ -246,13 +246,13 @@
testing::Return(mock_mmio::internal::ToInt<uint16_t>(__VA_ARGS__)))
/**
- * Expect a read to the device |dev| at the given offset, returning the given
+ * Expect a read to the device `dev` at the given offset, returning the given
* 32-bit value.
*
* The value may be given as an integer, a pointer to little-endian data,
- * or a |std::initializer_list<BitField>|.
+ * or a `std::initializer_list<BitField>`.
*
- * This expectation is sequenced with all other |EXPECT_READ| and |EXPECT_WRITE|
+ * This expectation is sequenced with all other `EXPECT_READ` and `EXPECT_WRITE`
* calls.
*/
#define EXPECT_READ32_AT(dev, offset, ...) \
@@ -261,13 +261,13 @@
testing::Return(mock_mmio::internal::ToInt<uint32_t>(__VA_ARGS__)))
/**
- * Expect a write to the device |dev| at the given offset with the given 8-bit
+ * Expect a write to the device `dev` at the given offset with the given 8-bit
* value.
*
* The value may be given as an integer, a pointer to little-endian data,
- * or a |std::initializer_list<BitField>|.
+ * or a `std::initializer_list<BitField>`.
*
- * This expectation is sequenced with all other |EXPECT_READ| and |EXPECT_WRITE|
+ * This expectation is sequenced with all other `EXPECT_READ` and `EXPECT_WRITE`
* calls.
*/
#define EXPECT_WRITE8_AT(dev, offset, ...) \
@@ -275,13 +275,13 @@
dev, Write8(offset, mock_mmio::internal::ToInt<uint8_t>(__VA_ARGS__)))
/**
- * Expect a write to the device |dev| at the given offset with the given 16-bit
+ * Expect a write to the device `dev` at the given offset with the given 16-bit
* value.
*
* The value may be given as an integer, a pointer to little-endian data,
- * or a |std::initializer_list<BitField>|.
+ * or a `std::initializer_list<BitField>`.
*
- * This expectation is sequenced with all other |EXPECT_READ| and |EXPECT_WRITE|
+ * This expectation is sequenced with all other `EXPECT_READ` and `EXPECT_WRITE`
* calls.
*/
#define EXPECT_WRITE16_AT(dev, offset, ...) \
@@ -289,13 +289,13 @@
dev, Write16(offset, mock_mmio::internal::ToInt<uint16_t>(__VA_ARGS__)))
/**
- * Expect a write to the device |dev| at the given offset with the given 32-bit
+ * Expect a write to the device `dev` at the given offset with the given 32-bit
* value.
*
* The value may be given as an integer, a pointer to little-endian data,
- * or a |std::initializer_list<BitField>|.
+ * or a `std::initializer_list<BitField>`.
*
- * This expectation is sequenced with all other |EXPECT_READ| and |EXPECT_WRITE|
+ * This expectation is sequenced with all other `EXPECT_READ` and `EXPECT_WRITE`
* calls.
*/
#define EXPECT_WRITE32_AT(dev, offset, ...) \
@@ -306,12 +306,12 @@
* Expect a read at the given offset, returning the given 8-bit value.
*
* The value may be given as an integer, a pointer to little-endian data,
- * or a |std::initializer_list<BitField>|.
+ * or a `std::initializer_list<BitField>`.
*
* This function is only available in tests using a fixture that derives
- * |MmioTest|.
+ * `MmioTest`.
*
- * This expectation is sequenced with all other |EXPECT_READ| and |EXPECT_WRITE|
+ * This expectation is sequenced with all other `EXPECT_READ` and `EXPECT_WRITE`
* calls.
*/
#define EXPECT_READ8(offset, ...) \
@@ -321,12 +321,12 @@
* Expect a read at the given offset, returning the given 16-bit value.
*
* The value may be given as an integer, a pointer to little-endian data,
- * or a |std::initializer_list<BitField>|.
+ * or a `std::initializer_list<BitField>`.
*
* This function is only available in tests using a fixture that derives
- * |MmioTest|.
+ * `MmioTest`.
*
- * This expectation is sequenced with all other |EXPECT_READ| and |EXPECT_WRITE|
+ * This expectation is sequenced with all other `EXPECT_READ` and `EXPECT_WRITE`
* calls.
*/
#define EXPECT_READ16(offset, ...) \
@@ -336,12 +336,12 @@
* Expect a read at the given offset, returning the given 32-bit value.
*
* The value may be given as an integer, a pointer to little-endian data,
- * or a |std::initializer_list<BitField>|.
+ * or a `std::initializer_list<BitField>`.
*
* This function is only available in tests using a fixture that derives
- * |MmioTest|.
+ * `MmioTest`.
*
- * This expectation is sequenced with all other |EXPECT_READ| and |EXPECT_WRITE|
+ * This expectation is sequenced with all other `EXPECT_READ` and `EXPECT_WRITE`
* calls.
*/
#define EXPECT_READ32(offset, ...) \
@@ -351,12 +351,12 @@
* Expect a write to the given offset with the given 8-bit value.
*
* The value may be given as an integer, a pointer to little-endian data,
- * or a |std::initializer_list<BitField>|.
+ * or a `std::initializer_list<BitField>`.
*
* This function is only available in tests using a fixture that derives
- * |MmioTest|.
+ * `MmioTest`.
*
- * This expectation is sequenced with all other |EXPECT_READ| and |EXPECT_WRITE|
+ * This expectation is sequenced with all other `EXPECT_READ` and `EXPECT_WRITE`
* calls.
*/
#define EXPECT_WRITE8(offset, ...) \
@@ -366,12 +366,12 @@
* Expect a write to the given offset with the given 16-bit value.
*
* The value may be given as an integer, a pointer to little-endian data,
- * or a |std::initializer_list<BitField>|.
+ * or a `std::initializer_list<BitField>`.
*
* This function is only available in tests using a fixture that derives
- * |MmioTest|.
+ * `MmioTest`.
*
- * This expectation is sequenced with all other |EXPECT_READ| and |EXPECT_WRITE|
+ * This expectation is sequenced with all other `EXPECT_READ` and `EXPECT_WRITE`
* calls.
*/
#define EXPECT_WRITE16(offset, ...) \
@@ -381,12 +381,12 @@
* Expect a write to the given offset with the given 32-bit value.
*
* The value may be given as an integer, a pointer to little-endian data,
- * or a |std::initializer_list<BitField>|.
+ * or a `std::initializer_list<BitField>`.
*
* This function is only available in tests using a fixture that derives
- * |MmioTest|.
+ * `MmioTest`.
*
- * This expectation is sequenced with all other |EXPECT_READ| and |EXPECT_WRITE|
+ * This expectation is sequenced with all other `EXPECT_READ` and `EXPECT_WRITE`
* calls.
*/
#define EXPECT_WRITE32(offset, ...) \
@@ -413,39 +413,39 @@
} while (false)
/**
- * Expect an unspecified 8-bit read to the device |dev| at the given offset,
+ * Expect an unspecified 8-bit read to the device `dev` at the given offset,
* followed by a write to the same location, with the same value but with some
* bits changed; the remaining bits must be untouched.
*
- * The changed bits are specified by a |std::initializer_list<MaskedBitField>|.
+ * The changed bits are specified by a `std::initializer_list<MaskedBitField>`.
*
- * This expectation is sequenced with all other |EXPECT_READ| and |EXPECT_WRITE|
+ * This expectation is sequenced with all other `EXPECT_READ` and `EXPECT_WRITE`
* calls.
*/
#define EXPECT_MASK8_AT(dev, offset, ...) \
EXPECT_MASK_INTERAL_(8, dev, offset, __VA_ARGS__)
/**
- * Expect an unspecified 16-bit read to the device |dev| at the given offset,
+ * Expect an unspecified 16-bit read to the device `dev` at the given offset,
* followed by a write to the same location, with the same value but with some
* bits changed; the remaining bits must be untouched.
*
- * The changed bits are specified by a |std::initializer_list<MaskedBitField>|.
+ * The changed bits are specified by a `std::initializer_list<MaskedBitField>`.
*
- * This expectation is sequenced with all other |EXPECT_READ| and |EXPECT_WRITE|
+ * This expectation is sequenced with all other `EXPECT_READ` and `EXPECT_WRITE`
* calls.
*/
#define EXPECT_MASK16_AT(dev, offset, ...) \
EXPECT_MASK_INTERAL_(16, dev, offset, __VA_ARGS__)
/**
- * Expect an unspecified 32-bit read to the device |dev| at the given offset,
+ * Expect an unspecified 32-bit read to the device `dev` at the given offset,
* followed by a write to the same location, with the same value but with some
* bits changed; the remaining bits must be untouched.
*
- * The changed bits are specified by a |std::initializer_list<MaskedBitField>|.
+ * The changed bits are specified by a `std::initializer_list<MaskedBitField>`.
*
- * This expectation is sequenced with all other |EXPECT_READ| and |EXPECT_WRITE|
+ * This expectation is sequenced with all other `EXPECT_READ` and `EXPECT_WRITE`
* calls.
*/
#define EXPECT_MASK32_AT(dev, offset, ...) \
@@ -456,12 +456,12 @@
* the same location, with the same value but with some bits changed; the
* remaining bits must be untouched.
*
- * The changed bits are specified by a |std::initializer_list<MaskedBitField>|.
+ * The changed bits are specified by a `std::initializer_list<MaskedBitField>`.
*
* This function is only available in tests using a fixture that derives
- * |MmioTest|.
+ * `MmioTest`.
*
- * This expectation is sequenced with all other |EXPECT_READ| and |EXPECT_WRITE|
+ * This expectation is sequenced with all other `EXPECT_READ` and `EXPECT_WRITE`
* calls.
*/
#define EXPECT_MASK8(offset, ...) \
@@ -472,12 +472,12 @@
* the same location, with the same value but with some bits changed; the
* remaining bits must be untouched.
*
- * The changed bits are specified by a |std::initializer_list<MaskedBitField>|.
+ * The changed bits are specified by a `std::initializer_list<MaskedBitField>`.
*
* This function is only available in tests using a fixture that derives
- * |MmioTest|.
+ * `MmioTest`.
*
- * This expectation is sequenced with all other |EXPECT_READ| and |EXPECT_WRITE|
+ * This expectation is sequenced with all other `EXPECT_READ` and `EXPECT_WRITE`
* calls.
*/
#define EXPECT_MASK16(offset, ...) \
@@ -488,12 +488,12 @@
* the same location, with the same value but with some bits changed; the
* remaining bits must be untouched.
*
- * The changed bits are specified by a |std::initializer_list<MaskedBitField>|.
+ * The changed bits are specified by a `std::initializer_list<MaskedBitField>`.
*
* This function is only available in tests using a fixture that derives
- * |MmioTest|.
+ * `MmioTest`.
*
- * This expectation is sequenced with all other |EXPECT_READ| and |EXPECT_WRITE|
+ * This expectation is sequenced with all other `EXPECT_READ` and `EXPECT_WRITE`
* calls.
*/
#define EXPECT_MASK32(offset, ...) \
