[sw] Document Output-params

This commit updates almost all software doxygen comments to highlight
where a value is an out-param. Out-params are heavily used in e.g. DIF
libraries, so it is useful to explicitly document where they are used.

The criteria I am using for an out-param is a pointer- (or array-) typed
parameter, where the function updates the value stored in that pointer
in order to return data to the caller. This includes both output buffers
(for recieving data into), and output singleton pointers.

Signed-off-by: Sam Elliott <[email protected]>

sw/device/lib/aes.h

@@ -87,14 +87,14 @@ void aes_data_put(const void *data);
  * Wait for AES unit to have valid output data and then
  * get one 16B block of output data from AES unit.
  *
- * @param data pointer to output buffer.
+ * @param[out] data pointer to output buffer.
  */
 void aes_data_get_wait(void *data);
 
 /**
  * Get one 16B block of output data from AES unit.
  *
- * @param data pointer to output buffer.
+ * @param[out] data pointer to output buffer.
  */
 void aes_data_get(void *data);
 

sw/device/lib/base/print.c

@@ -118,7 +118,7 @@ size_t base_fprintf(buffer_sink_t out, const char *format, ...) {
  *
  * @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[out] 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,
@@ -151,7 +151,7 @@ typedef struct format_specifier {
  *
  * @param out the sink to write bytes to.
  * @param format a pointer to the format string to consume a prefix of.
- * @param spec out param for the specifier.
+ * @param[out] spec out param for the specifier.
  * @return whether the parse succeeded.
  */
 static bool consume_format_specifier(buffer_sink_t out, const char **format,
@@ -235,7 +235,7 @@ static size_t write_digits(buffer_sink_t out, uint32_t value, uint32_t width,
  *
  * @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[out] 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,

sw/device/lib/dif/dif_gpio.h

@@ -80,7 +80,7 @@ typedef enum dif_gpio_irq {
  * before calling other functions of this library.
  *
  * @param config Configuration for initializing a GPIO device.
- * @param gpio GPIO instance that will store the internal state of the
+ * @param[out] gpio GPIO instance that will store the internal state of the
  * initialized GPIO device.
  * @return `kDifGpioBadArg` if `config` or `gpio` is `NULL`,
  * `kDifGpioOk` otherwise.
@@ -110,7 +110,7 @@ dif_gpio_result_t dif_gpio_reset(const dif_gpio_t *gpio);
  * the pins.
  *
  * @param gpio GPIO instance.
- * @param pin_values Pin values.
+ * @param[out] pin_values Pin values.
  * @return `kDifGpioBadArg` if `gpio` or `pin_values` is `NULL`,
  * `kDifGpioOk` otherwise.
  */
@@ -127,7 +127,7 @@ dif_gpio_result_t dif_gpio_all_read(const dif_gpio_t *gpio,
  *
  * @param gpio GPIO instance.
  * @param index Zero-based index of the pin to read from.
- * @param pin_value Pin value.
+ * @param[out] pin_value Pin value.
  * @return `kDifGpioBadArg` if `gpio` or `pin_values` is `NULL`,
  * `kDifGpioOk` otherwise.
  */
@@ -241,7 +241,7 @@ dif_gpio_result_t dif_gpio_irq_pin_test(const dif_gpio_t *gpio, uint32_t index);
  * Read the interrupt states of all pins.
  *
  * @param gpio GPIO instance.
- * @param interrupt_states Interrupt states of all pins.
+ * @param[out] interrupt_states Interrupt states of all pins.
  * @return `kDifGpioBadArg` if `gpio` or `interrupt_states` is
  * `NULL`, `kDifGpioOk` otherwise.
  */
@@ -254,8 +254,8 @@ dif_gpio_result_t dif_gpio_irq_all_read(const dif_gpio_t *gpio,
  *
  * @param gpio GPIO instance.
  * @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.
+ * @param[out] interrupt_state Interrupt state of the pin. True if there is a
+ * pending interrupt, false otherwise.
  * @return `kDifGpioBadArg` if `gpio` or `interrupt_state` is
  * `NULL`, `kDifGpioOk` otherwise.
  */

sw/device/lib/dif/dif_hmac.h

@@ -166,7 +166,7 @@ typedef struct dif_hmac { mmio_region_t base_addr; } dif_hmac_t;
  * any other functions in this header with that `mmio_region_t`.
  *
  * @param config Configuration supplied for initializing a particular device.
- * @param hmac_out The location at which to write HMAC state. This location
+ * @param[out] hmac_out The location at which to write HMAC state. This location
  *                 must be valid to write to.
  * @return `kDifHmacBadArg` if `config` is null or contains illegal
  *          arguments or `hmac_out` is null, `kDifHmacOk` otherwise.
@@ -181,7 +181,7 @@ dif_hmac_result_t dif_hmac_init(const dif_hmac_config_t *config,
  *
  * @param hmac HMAC state data.
  * @param irq_type IRQ to get the state of.
- * @param state IRQ state passed back to the caller.
+ * @param[out] state IRQ state passed back to the caller.
  * @return `dif_hmac_result_t`.
  */
 dif_hmac_result_t dif_hmac_irq_state_get(const dif_hmac_t *hmac,
@@ -207,7 +207,7 @@ dif_hmac_result_t dif_hmac_irq_state_clear(const dif_hmac_t *hmac,
  * in `state` back to the caller. Parameter `state` is ignored if NULL.
  *
  * @param hmac HMAC state data.
- * @param state IRQ state passed back to the caller.
+ * @param[out] state IRQ state passed back to the caller.
  * @return 'dif_hmac_result_t'.
  */
 dif_hmac_result_t dif_hmac_irqs_disable(const dif_hmac_t *hmac,
@@ -300,7 +300,7 @@ dif_hmac_result_t dif_hmac_mode_sha256_start(const dif_hmac_t *hmac);
  * @param hmac The HMAC device to send to.
  * @param data A contiguous buffer to copy from.
  * @param len The length of the buffer to copy from.
- * @param bytes_sent The number of bytes sent to the FIFO (optional).
+ * @param[out] bytes_sent The number of bytes sent to the FIFO (optional).
  * @return `kDifHmacFifoFull` if the FIFO fills up, `kDifHmacFifoBadArg` if
  *         `hmac` or `data` is null, and `kDifHmacFifoOk` otherwise.
  */
@@ -314,7 +314,7 @@ dif_hmac_fifo_result_t dif_hmac_fifo_push(const dif_hmac_t *hmac,
  * message length.
  *
  * @param hmac The HMAC device to get the FIFO depth for.
- * @param num_entries The number of entries in the FIFO.
+ * @param[out] num_entries The number of entries in the FIFO.
  * @return `kDifHmacBadArg` if `hmac` or `num_entries` is null, `kDifHmacOk`
  *         otherwise.
  */
@@ -328,7 +328,7 @@ dif_hmac_result_t dif_hmac_fifo_count_entries(const dif_hmac_t *hmac,
  * `msg_len`.
  *
  * @param hmac The HMAC device to get the message length for.
- * @param msg_len The number of bits in the HMAC message.
+ * @param[out] msg_len The number of bits in the HMAC message.
  * @return `kDifHmacBadArg` if `hmac` or `msg_len` is null, `kDifHmacOk`
  *         otherwise.
  */
@@ -358,7 +358,8 @@ dif_hmac_result_t dif_hmac_process(const dif_hmac_t *hmac);
  * requirements for size and alignment requirements of `dif_hmac_digest_t`.
  *
  * @param hmac The HMAC device to read the digest from.
- * @param digest A contiguous 32-byte, 4-byte aligned buffer for the digest.
+ * @param[out] digest A contiguous 32-byte, 4-byte aligned buffer for the
+ * digest.
  * @return `kDifHmacBadArg` if `hmac` or `digest` is null,
  *         `kDifHmacDigestProcessing` if HMAC is still processing, and
  *         `kDifHmacOk` otherwise.

sw/device/lib/dif/dif_i2c.h

@@ -189,7 +189,7 @@ typedef enum dif_i2c_enable {
  * period.
  *
  * @param config Configuration values for producing timing parameters.
- * @param out Out-param for the actual timing parameters.
+ * @param[out] out The computed timing parameters.
  * @return The result of the operation.
  */
 DIF_WARN_UNUSED_RESULT
@@ -204,7 +204,7 @@ dif_i2c_result_t dif_i2c_compute_timing(const dif_i2c_timing_config_t *config,
  *
  * @oaram base_addr The start of the I2C device register.
  * @param timing Timing parameters to initialize with.
- * @param i2c Out param for the initialized device.
+ * @param[out] i2c The initialized I2C device.
  * @return The result of the operation.
  */
 DIF_WARN_UNUSED_RESULT
@@ -253,7 +253,7 @@ dif_i2c_result_t dif_i2c_set_watermarks(const dif_i2c_t *i2c,
  *
  * @param i2c An I2C device.
  * @param type An interrupt type.
- * @param flag_out Out-param for whether the interrupt is pending.
+ * @param[out] flag_out Whether the interrupt is pending.
  * @return The result of the operation.
  */
 DIF_WARN_UNUSED_RESULT
@@ -341,8 +341,8 @@ dif_i2c_result_t dif_i2c_override_drive_pins(const dif_i2c_t *i2c, bool scl,
  * zeroth bit being the most recent.
  *
  * @param i2c An I2C device.
- * @param scl_samples Out-param for SCL sample bits; may be null.
- * @param sda_samples Out-param for SDA sample bits; may be null.
+ * @param[out] scl_samples SCL sample bits; may be null.
+ * @param[out] sda_samples SDA sample bits; may be null.
  * @return The result of the operation.
  */
 DIF_WARN_UNUSED_RESULT
@@ -356,10 +356,8 @@ dif_i2c_result_t dif_i2c_override_sample_pins(const dif_i2c_t *i2c,
  * and entries pending for read by software, respectively.
  *
  * @param i2c An I2C device.
- * @param fmt_fifo_level Out-param for the number of unsent FMT bytes; may be
- *        null.
- * @param rx_fifo_level Out-param for the number of unread RX bytes; may be
- *        null.
+ * @param[out] fmt_fifo_level The number of unsent FMT bytes; may be null.
+ * @param[out] rx_fifo_level The number of unread RX bytes; may be null.
  * @return The result of the operation.
  */
 DIF_WARN_UNUSED_RESULT
@@ -372,7 +370,7 @@ dif_i2c_result_t dif_i2c_get_fifo_levels(const dif_i2c_t *i2c,
  * will still trigger a byte pop.
  *
  * @param i2c An I2C device.
- * @param byte Out-param for the popped byte; may be null.
+ * @param[out] byte The popped byte; may be null.
  * @return The result of the opeartion.
  */
 DIF_WARN_UNUSED_RESULT

sw/device/lib/dif/dif_otbn.h

@@ -125,7 +125,7 @@ typedef enum dif_otbn_enable {
  * before calling other functions of this library.
  *
  * @param config Configuration for initializing an OTBN device.
- * @param otbn OTBN instance that will store the internal state of the
+ * @param[out] otbn OTBN instance that will store the internal state of the
  *             initialized OTBN device.
  * @return `kDifOtbnBadArg` if `otbn` is `NULL`, `kDifOtbnOk` otherwise.
  */
@@ -150,7 +150,7 @@ dif_otbn_result_t dif_otbn_reset(const dif_otbn_t *otbn);
  *
  * @param otbn OTBN state data.
  * @param irq_type IRQ to get the state of.
- * @param state IRQ state passed back to the caller.
+ * @param[out] state IRQ state.
  * @return `kDifOtbnBadArg` if `otbn` is `NULL`, `kDifOtbnOk` otherwise.
  */
 dif_otbn_result_t dif_otbn_irq_state_get(const dif_otbn_t *otbn,
@@ -177,7 +177,7 @@ dif_otbn_result_t dif_otbn_irq_state_clear(const dif_otbn_t *otbn,
  * in `state` back to the caller. Parameter `state` is ignored if NULL.
  *
  * @param otbn OTBN state data.
- * @param state IRQ state passed back to the caller.
+ * @param[out] state IRQ state for use with `dif_otbn_irqs_restore`.
  * @return `kDifOtbnBadArg` if `otbn` is `NULL`, `kDifOtbnOk` otherwise.
  */
 dif_otbn_result_t dif_otbn_irqs_disable(const dif_otbn_t *otbn,
@@ -273,7 +273,7 @@ dif_otbn_result_t dif_otbn_imem_write(const dif_otbn_t *otbn,
  *
  * @param otbn OTBN instance
  * @param offset_bytes the byte offset in IMEM the first word is read from
- * @param dest the main memory location to copy the data to (preallocated)
+ * @param[out] dest the main memory location to copy the data to (preallocated)
  * @param len_bytes number of bytes to copy.
  * @return `kDifOtbnBadArg` if `otbn` is `NULL` or len_bytes or size are
  * invalid, `kDifOtbnOk` otherwise.
@@ -301,7 +301,7 @@ dif_otbn_result_t dif_otbn_dmem_write(const dif_otbn_t *otbn,
  *
  * @param otbn OTBN instance
  * @param offset_bytes the byte offset in DMEM the first word is read from
- * @param dest the main memory location to copy the data to (preallocated)
+ * @param[out] dest the main memory location to copy the data to (preallocated)
  * @param len_bytes number of bytes to copy.
  * @return `kDifOtbnBadArg` if `otbn` is `NULL` or len_bytes or size are
  * invalid, `kDifOtbnOk` otherwise.

sw/device/lib/dif/dif_plic.h

@@ -101,7 +101,7 @@ typedef enum dif_plic_result {
  * be stored in `plic`.
  *
  * @param base_addr Base address of an instance of the PLIC IP block.
- * @param plic PLIC state data.
+ * @param[out] plic PLIC state data.
  * @return `dif_plic_result_t`.
  */
 DIF_WARN_UNUSED_RESULT
@@ -179,7 +179,8 @@ dif_plic_result_t dif_plic_target_threshold_set(const dif_plic_t *plic,
  * source.
  * @param plic PLIC state data.
  * @param irq Interrupt source ID.
- * @param status Flag indicating whether the IRQ pending bit is set in PLIC.
+ * @param[out] status Flag indicating whether the IRQ pending bit is set in
+ * PLIC.
  * @return `dif_plic_result_t`.
  */
 DIF_WARN_UNUSED_RESULT
@@ -196,7 +197,7 @@ dif_plic_result_t dif_plic_irq_pending_status_get(const dif_plic_t *plic,
  *
  * @param plic PLIC state data.
  * @param target Target that claimed the IRQ.
- * @param claim_data Data that describes the origin of the IRQ.
+ * @param[out] claim_data Data that describes the origin of the IRQ.
  * @return `dif_plic_result_t`.
  */
 DIF_WARN_UNUSED_RESULT
@@ -213,8 +214,8 @@ dif_plic_result_t dif_plic_irq_claim(const dif_plic_t *plic,
  *
  * @param plic PLIC state data.
  * @param target Target that claimed the IRQ.
- * @param complete_data Previously claimed IRQ data that is used to signal PLIC
- *                      of the IRQ servicing completion.
+ * @param[out] complete_data Previously claimed IRQ data that is used to signal
+ *                      PLIC of the IRQ servicing completion.
  * @return `dif_plic_result_t`.
  */
 DIF_WARN_UNUSED_RESULT

sw/device/lib/dif/dif_rv_timer.h

@@ -104,7 +104,7 @@ typedef enum dif_rv_timer_approximate_tick_params_result {
  *
  * @param clock_freq The device clock frequency, in Hertz.
  * @param counter_freq The desired counter frequency, in Hertz.
- * @param out Tick parameters that will approximately produce the desired
+ * @param[out] out Tick parameters that will approximately produce the desired
  *         counter frequency.
  * @return The result of the operation.
  */
@@ -151,7 +151,7 @@ typedef struct dif_rv_timer {
  *
  * @param base_addr MMIO region for the device hardware registers.
  * @param config Configuration for initializing a particular timer.
- * @param timer_out Out param for the timer device.
+ * @param[out] timer_out The timer device.
  * @return The result of the operation.
  */
 dif_rv_timer_result_t dif_rv_timer_init(mmio_region_t base_addr,
@@ -204,7 +204,7 @@ dif_rv_timer_result_t dif_rv_timer_counter_set_enabled(
  *
  * @param timer A timer device.
  * @param hart_id The hart counter to read.
- * @param out Out param for the counter value.
+ * @param[out] out The counter value.
  * @return The result of the operation.
  */
 dif_rv_timer_result_t dif_rv_timer_counter_read(const dif_rv_timer_t *timer,
@@ -265,7 +265,7 @@ dif_rv_timer_result_t dif_rv_timer_irq_enable(const dif_rv_timer_t *timer,
  * @param timer A timer device.
  * @param hart_id The hart counter associated with the timer.
  * @param comp_id The comparator associated with the timer.
- * @param flag_out Out-param for the interrupt status.
+ * @param[out] flag_out The interrupt status.
  * @return the result of the operation.
  */
 dif_rv_timer_result_t dif_rv_timer_irq_get(const dif_rv_timer_t *timer,
@@ -303,7 +303,8 @@ dif_rv_timer_result_t dif_rv_timer_irq_force(const dif_rv_timer_t *timer,
  * `state` may be NULL. See `dif_rv_timer_irq_restore()`.
  *
  * @param timer a timer device.
- * @param state out param for IRQ state information.
+ * @param[out] state IRQ state information for use with
+ *                   `dif_rv_timer_irq_restore`.
  * @return the result of the operation.
  */
 dif_rv_timer_result_t dif_rv_timer_irq_disable(const dif_rv_timer_t *timer,