[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>

doc/rm/c_cpp_coding_style.md

@@ -118,18 +118,20 @@ The above rules also do not apply to system includes, which should be included b
 The first line of the comment is the summary, followed by a new line, and an optional longer description.
 Input arguments and return arguments can be documented with `@param` and `@return` if they are not self-explanatory from the name.
 
-The `@p` modifier can be used to format the following word as monospaced text in the final output.
-The documentation tool will also render markdown within descriptions.
+The documentation tool will also render markdown within descriptions, so backticks should be used to get monospaced text.
+It can also generate references to other named declarations using `#other_function` (for C-style declarations), or `ns::foo` (for C++ declarations).
 
 Example:
 
 ```c
 /**
  * Do something amazing
  *
- * Create a rainbow and place a unicorn at the bottom of it. @p pots_of_gold
+ * Create a rainbow and place a unicorn at the bottom of it. `pots_of_gold`
  * pots of gold will be positioned on the east end of the rainbow.
  *
+ * Can be recycled with #recycle_rainbow.
+ *
  * @param pots_of_gold Number of gold pots to place next to the rainbow
  * @param unicorns Number of unicorns to position on the rainbow
  * @return 0 if the function was successful, -1 otherwise

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.

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

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 @@ _reset_start:
   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 @@ bss_zero_loop:
   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

sw/device/examples/hello_usbdev/hello_usbdev.c

@@ -46,7 +46,7 @@ static usb_ss_ctx_t simple_serial0;
 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 @@ int main(int argc, char **argv) {
 
   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));

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 @@ _start:
   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 @@ bss_zero_loop:
   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:
 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

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 {

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;

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.

sw/device/lib/base/log.c

@@ -24,12 +24,12 @@ static const char *stringify_severity(log_severity_t severity) {
 }
 
 /**
- * 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 @@ void base_log_internal_core(log_severity_t severity, const char *file_name,
 }
 
 /**
- * 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_core(log_severity_t severity, const char *file_name,
  */
 void base_log_internal_dv(log_severity_t severity, const char *format, ...) {
   // Do nothing, for now.
-}
+}

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 @@ void base_log_internal_dv(log_severity_t severity, const char *format, ...);
  *
  * 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 @@ void base_log_internal_dv(log_severity_t severity, const char *format, ...);
 /**
  * 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 @@ void base_log_internal_dv(log_severity_t severity, const char *format, ...);
 /**
  * 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 @@ void base_log_internal_dv(log_severity_t severity, const char *format, ...);
 /**
  * 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.

sw/device/lib/base/memory.h

@@ -14,18 +14,18 @@
  *
  * 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.
  *
  * This function has reordering properties as weak as a normal, non-atomic,
  * 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 @@ inline uint32_t read_32(const void *ptr) {
   //
   // 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 @@ inline uint32_t read_32(const void *ptr) {
  *
  * 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 uint32_t read_32(const void *ptr) {
  */
 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 @@ inline void write_32(uint32_t value, void *ptr) {
  * @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 @@ void *memcpy(void *restrict dest, const void *restrict src, size_t len);
  * @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 @@ void *memset(void *dest, int value, size_t len);
  * @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 @@ int memcmp(const void *lhs, const void *rhs, size_t len);
  *
  * 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.

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);