[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 <selliott@lowrisc.org>
diff --git a/sw/device/lib/aes.h b/sw/device/lib/aes.h
index 9486ba1..103ee50 100644
--- a/sw/device/lib/aes.h
+++ b/sw/device/lib/aes.h
@@ -87,14 +87,14 @@
* 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);
diff --git a/sw/device/lib/base/print.c b/sw/device/lib/base/print.c
index 879cac3..50acf33 100644
--- a/sw/device/lib/base/print.c
+++ b/sw/device/lib/base/print.c
@@ -118,7 +118,7 @@
*
* @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 @@
*
* @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 @@
*
* @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,
diff --git a/sw/device/lib/dif/dif_gpio.h b/sw/device/lib/dif/dif_gpio.h
index ae5e15a..6ffca25 100644
--- a/sw/device/lib/dif/dif_gpio.h
+++ b/sw/device/lib/dif/dif_gpio.h
@@ -80,7 +80,7 @@
* 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 @@
* 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 @@
*
* @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 @@
* 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 @@
*
* @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.
*/
diff --git a/sw/device/lib/dif/dif_hmac.h b/sw/device/lib/dif/dif_hmac.h
index 237cf7c..1f2d820 100644
--- a/sw/device/lib/dif/dif_hmac.h
+++ b/sw/device/lib/dif/dif_hmac.h
@@ -166,7 +166,7 @@
* 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 @@
*
* @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 @@
* 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 @@
* @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 @@
* 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 @@
* `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 @@
* 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.
diff --git a/sw/device/lib/dif/dif_i2c.h b/sw/device/lib/dif/dif_i2c.h
index 03f04d8..bad73cd 100644
--- a/sw/device/lib/dif/dif_i2c.h
+++ b/sw/device/lib/dif/dif_i2c.h
@@ -189,7 +189,7 @@
* 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 @@
*
* @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 @@
*
* @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 @@
* 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 @@
* 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 @@
* 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
diff --git a/sw/device/lib/dif/dif_otbn.h b/sw/device/lib/dif/dif_otbn.h
index 76f81a3..6f33909 100644
--- a/sw/device/lib/dif/dif_otbn.h
+++ b/sw/device/lib/dif/dif_otbn.h
@@ -125,7 +125,7 @@
* 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 @@
*
* @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 @@
* 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 @@
*
* @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 @@
*
* @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.
diff --git a/sw/device/lib/dif/dif_plic.h b/sw/device/lib/dif/dif_plic.h
index 0a66b5d..0e6bff7 100644
--- a/sw/device/lib/dif/dif_plic.h
+++ b/sw/device/lib/dif/dif_plic.h
@@ -101,7 +101,7 @@
* 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 @@
* 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 @@
*
* @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 @@
*
* @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
diff --git a/sw/device/lib/dif/dif_rv_timer.h b/sw/device/lib/dif/dif_rv_timer.h
index b494c34..471a2df 100644
--- a/sw/device/lib/dif/dif_rv_timer.h
+++ b/sw/device/lib/dif/dif_rv_timer.h
@@ -104,7 +104,7 @@
*
* @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 @@
*
* @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 @@
*
* @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 @@
* @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 @@
* `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,
diff --git a/sw/device/lib/dif/dif_spi_device.h b/sw/device/lib/dif/dif_spi_device.h
index 8c6af73..8c7b176 100644
--- a/sw/device/lib/dif/dif_spi_device.h
+++ b/sw/device/lib/dif/dif_spi_device.h
@@ -113,7 +113,7 @@
*
* @param base_addr The start of the SPI device register.
* @param config The configuration to initialize with.
- * @param spi Out param for the initialized device.
+ * @param[out] spi The initialized device.
* @return The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
@@ -125,7 +125,7 @@
* Issues an "abort" to the given SPI device, causing all in-progress IO to
* halt.
*
- * @param spi A SPI device.
+ * @param spi An SPI device.
* @return The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
@@ -135,7 +135,7 @@
* Resets all interrupt-related state on the given SPI device, such as enabled
* interrupts and set RX/TX levels.
*
- * @param spi A SPI device.
+ * @param spi An SPI device.
* @return The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
@@ -144,9 +144,9 @@
/**
* Returns whether the given IRQ is currently being serviced.
*
- * @param spi A SPI device.
+ * @param spi An SPI device.
* @param type Which IRQ type to check.
- * @param flag Out param for whether the IRQ is active..
+ * @param[out] flag Whether the IRQ is active.
* @return The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
@@ -157,7 +157,7 @@
/**
* Clears all active interrupt bits.
*
- * @param spi A SPI device.
+ * @param spi An SPI device.
* @return The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
@@ -167,7 +167,7 @@
/**
* Enable or disable a particular interrupt.
*
- * @param spi A SPI device.
+ * @param spi An SPI device.
* @param type Which IRQ type to toggle.
* @param state The state to update the bit to.
* @return The result of the operation.
@@ -180,7 +180,7 @@
/**
* Forces a particular IRQ type to fire.
*
- * @param spi A SPI device.
+ * @param spi An SPI device.
* @param type Which IRQ type to fire.
* @return The result of the operation.
*/
@@ -202,7 +202,7 @@
* to detect that there is free space to write more data to the TX FIFO.
* This is the `Main Memory -> Spi Buffer` case.
*
- * @param spi A SPI device.
+ * @param spi An SPI device.
* @param rx_level The new RX level, as described above.
* @param tx_level The new TX level, as described above.
* @return The result of the operation.
@@ -214,8 +214,8 @@
/**
* Returns the number of bytes still pending receipt by software in the RX FIFO.
*
- * @param spi A SPI device.
- * @param bytes_pending Out param for the number of bytes pending
+ * @param spi An SPI device.
+ * @param[out] bytes_pending The number of bytes pending
* @return The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
@@ -226,8 +226,8 @@
* Returns the number of bytes still pending transmission by hardware in the TX
* FIFO.
*
- * @param spi A SPI device.
- * @param bytes_pending Out param for the number of bytes pending
+ * @param spi An SPI device.
+ * @param[out] bytes_pending The number of bytes pending
* @return The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
@@ -239,10 +239,10 @@
* will be written to `bytes_received`.
*
* @param spi A SPI device.
- * @param buf A pointer to valid memory.
+ * @param[out] buf A pointer to valid memory.
* @param buf_len The length of the buffer `buf` points to.
- * @param bytes_received Out param for the number of bytes successfully read;
- * may be null.
+ * @param[out] bytes_received The number of bytes successfully read; may be
+ * null.
* @return The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
@@ -257,8 +257,7 @@
* @param spi A SPI device.
* @param buf A pointer to bytes to be written.
* @param buf_len The length of the buffer `buf` points to.
- * @param bytes_sent Out param for the number of bytes successfully written;
- * may be null.
+ * @param[out] bytes_sent The number of bytes successfully written; may be null.
* @return The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
diff --git a/sw/device/lib/dif/dif_uart.h b/sw/device/lib/dif/dif_uart.h
index a8d93d6..26f7062 100644
--- a/sw/device/lib/dif/dif_uart.h
+++ b/sw/device/lib/dif/dif_uart.h
@@ -150,7 +150,7 @@
* stored in `uart`.
* @param base_addr Base address of an instance of UART IP block.
* @param config UART configuration data.
- * @param uart UART state data.
+ * @param[out] uart UART state data.
* @return `dif_uart_config_result_t`.
*/
DIF_WARN_UNUSED_RESULT
@@ -214,7 +214,7 @@
* @param uart UART state data.
* @param data Data to be written.
* @param bytes_requested Number of bytes requested to be written by the caller.
- * @param bytes_written Number of bytes written (optional).
+ * @param[out] bytes_written Number of bytes written (optional).
* @return `dif_uart_result_t`.
*/
DIF_WARN_UNUSED_RESULT
@@ -234,8 +234,8 @@
*
* @param uart UART state data.
* @param bytes_requested Number of bytes requested to be read by the caller.
- * @param data Data to be read.
- * @param bytes_read Number of bytes read (optional).
+ * @param[out] data Buffer for up to `bytes_requested` bytes of read data.
+ * @param[out] bytes_read Number of bytes read (optional).
* @return `dif_uart_result_t`
*/
DIF_WARN_UNUSED_RESULT
@@ -265,7 +265,7 @@
* ISR.
*
* @param uart UART state data.
- * @param byte Received byte.
+ * @param[out] byte Received byte.
* @return `dif_uart_result_t`.
*/
DIF_WARN_UNUSED_RESULT
@@ -279,7 +279,7 @@
*
* @param uart UART 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 `dif_uart_result_t`.
*/
DIF_WARN_UNUSED_RESULT
@@ -307,7 +307,7 @@
* in `state` back to the caller. Parameter `state` is ignored if NULL.
*
* @param uart UART state data.
- * @param state IRQ state passed back to the caller.
+ * @param[out] state IRQ state, for use with `dif_uart_irqs_restore`.
* @return 'dif_uart_result_t'.
*/
DIF_WARN_UNUSED_RESULT
@@ -362,7 +362,7 @@
* function can be used to check FIFO full and empty conditions.
*
* @param uart UART state data.
- * @param num_bytes Number of bytes available to be read.
+ * @param[out] num_bytes Number of bytes available to be read.
* @return `dif_uart_result_t`.
*/
DIF_WARN_UNUSED_RESULT
@@ -376,7 +376,7 @@
* function can be used to check FIFO full and empty conditions.
*
* @param uart UART state data.
- * @param num_bytes Number of bytes available to be written.
+ * @param[out] num_bytes Number of bytes available to be written.
* @return `dif_uart_result_t`.
*/
DIF_WARN_UNUSED_RESULT
diff --git a/sw/device/lib/dif/dif_usbdev.h b/sw/device/lib/dif/dif_usbdev.h
index 99d8185..4f1131e 100644
--- a/sw/device/lib/dif/dif_usbdev.h
+++ b/sw/device/lib/dif/dif_usbdev.h
@@ -151,7 +151,7 @@
* functions in this library.
*
* @param config Configuration for initializing a USB device.
- * @param usbdev Internal state of the initialized USB device.
+ * @param[out] usbdev Internal state of the initialized USB device.
* @return The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
@@ -217,7 +217,7 @@
*
* @param usbdev A USB device.
* @param endpoint An endpoint.
- * @param state Current STALL state.
+ * @param[out] state Current STALL state.
* @return The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
@@ -336,6 +336,7 @@
* operation.
*
* @param usbdev A USB device.
+ * @param[out] packet Information for current incoming packet.
* @return The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
@@ -385,6 +386,9 @@
* See also: `dif_usbdev_rx_packet_get_info`.
*
* @param usbdev A USB device.
+ * @param[out] dst Buffer to read bytes into.
+ * @param dst_len Length of `dst`, in bytes.
+ * @param[out] bytes_written Number of bytes written into `dst`.
* @return The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
@@ -506,7 +510,7 @@
* @param endpoint An endpoint.
* @param src Source buffer.
* @param src_len Length of the source buffer.
- * @bytes_written Number of bytes written to the USB device buffer.
+ * @param[out] bytes_written Number of bytes written to the USB device buffer.
* @return The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
@@ -584,7 +588,7 @@
*
* @param usbdev A USB device.
* @param endpoint An endpoint.
- * @param status Status of the packet.
+ * @param[out] status Status of the packet.
* @return The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
@@ -606,7 +610,7 @@
* Get the address of a USB device.
*
* @param usbdev A USB device.
- * @param addr Current address.
+ * @param[out] addr Current address.
* @return The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
@@ -616,7 +620,7 @@
* Get USB frame index.
*
* @param usbdev A USB device.
- * @param frame_index USB frame index.
+ * @param[out] frame_index USB frame index.
* @return The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
@@ -630,7 +634,7 @@
* not been received in the last 4.096ms.
*
* @param usbdev A USB device.
- * @param host_lost Status of the host. `true` if the host is lost, `false`
+ * @param[out] host_lost Status of the host. `true` if the host is lost, `false`
* otherwise.
* @return The result of the operation.
*/
@@ -653,7 +657,7 @@
* Get USB link state.
*
* @param usbdev A USB device.
- * @param link_state USB link state.
+ * @param[out] link_state USB link state.
* @return The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
@@ -664,8 +668,8 @@
* Get the state of the sense pin.
*
* @param usbdev A USB device.
- * @param sense State of the sense pin. `true` if the host is providing VBUS,
- * `false` otherwise.
+ * @param[out] sense State of the sense pin. `true` if the host is providing
+ * VBUS, `false` otherwise.
* @return The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
@@ -678,7 +682,7 @@
* See also: `dif_usbdev_fill_available_fifo`.
*
* @param usbdev A USB device.
- * @param depth Depth of the AV FIFO.
+ * @param[out] depth Depth of the AV FIFO.
* @return The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
@@ -690,7 +694,7 @@
* See also: `dif_usbdev_fill_available_fifo`.
*
* @param usbdev A USB device.
- * @param is_full State of the AV FIFO. `true` if full, false otherwise.
+ * @param[out] is_full State of the AV FIFO. `true` if full, false otherwise.
* @return The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
@@ -702,7 +706,7 @@
* See also: `dif_usbdev_rx_packet_get_info`.
*
* @param usbdev A USB device.
- * @param depth Depth of the RX FIFO.
+ * @param[out] depth Depth of the RX FIFO.
* @return The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
@@ -715,7 +719,8 @@
* See also: `dif_usbdev_rx_packet_get_info`.
*
* @param usbdev A USB device.
- * @param is_empty State of the RX FIFO. `true` if empty, `false` otherwise.
+ * @param[out] is_empty State of the RX FIFO. `true` if empty, `false`
+ * otherwise.
* @return The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
@@ -820,7 +825,7 @@
*
* @param usbdev A USB device.
* @param irq An interrupt.
- * @param state State of the interrupt.
+ * @param[out] state State of the interrupt.
* @return The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
@@ -852,7 +857,7 @@
* configuration.
*
* @param usbdev A USB device.
- * @param cur_config Current interrupt configuration.
+ * @param[out] cur_config Current interrupt configuration.
* @return The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
@@ -863,7 +868,7 @@
* Restore interrupt configuration.
*
* @param usbdev A USB device.
- * @param new_config New interrupt configuration.
+ * @param[out] new_config New interrupt configuration.
* @return The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
diff --git a/sw/device/lib/flash_ctrl.h b/sw/device/lib/flash_ctrl.h
index 00b6640..381d061 100644
--- a/sw/device/lib/flash_ctrl.h
+++ b/sw/device/lib/flash_ctrl.h
@@ -86,7 +86,7 @@
* @param addr Read start address.
* @param part Flash parittion to access.
* @param size Number of 4B words to read.
- * @param data Output buffer.
+ * @param[out] data Output buffer.
* @return Non zero on failure.
*/
int flash_read(uint32_t addr, part_type_t part, uint32_t size, uint32_t *data);
diff --git a/sw/device/lib/hmac.h b/sw/device/lib/hmac.h
index d878359..0cc9c95 100644
--- a/sw/device/lib/hmac.h
+++ b/sw/device/lib/hmac.h
@@ -45,7 +45,7 @@
/**
* Poll for hmac done and read out digest.
*
- * @param digest pointer to output digest buffer.
+ * @param[out] digest pointer to output digest buffer.
*/
void hmac_done(uint32_t *digest);
diff --git a/sw/device/lib/hw_sha256.h b/sw/device/lib/hw_sha256.h
index b60849b..1dfac14 100644
--- a/sw/device/lib/hw_sha256.h
+++ b/sw/device/lib/hw_sha256.h
@@ -43,7 +43,7 @@
*
* @param data Input buffer.
* @param len Number of bytes to add.
- * @param digest Output buffer.
+ * @param[out] digest Output buffer.
*/
const uint8_t *hw_SHA256_hash(const void *data, size_t len, uint8_t *digest);
diff --git a/sw/device/sca/aes_serial/aes_serial.c b/sw/device/sca/aes_serial/aes_serial.c
index d2c237b..348091c 100644
--- a/sw/device/sca/aes_serial/aes_serial.c
+++ b/sw/device/sca/aes_serial/aes_serial.c
@@ -80,7 +80,7 @@
* Convert `from` binary `to` hex.
*
* @param from input value in binary format.
- * @param to output value in hex format.
+ * @param[out] to output value in hex format.
*
* @return kSimpleSerialOk on success, kSimpleSerialError otherwise.
*/
@@ -103,8 +103,8 @@
* `from` size is expected to by twice as big as `to`.
*
* @param from input buffer for hex formatted characters.
- * @param to output binary buffer.
- * @param num number of characters in output buffer.
+ * @param[out] to output buffer for binary.
+ * @param num length of output buffer.
*
* @return kSimpleSerialOk on success, kSimpleSerialError otherwise.
*/
diff --git a/sw/host/spiflash/updater.h b/sw/host/spiflash/updater.h
index 01f9608..92c819c 100644
--- a/sw/host/spiflash/updater.h
+++ b/sw/host/spiflash/updater.h
@@ -83,7 +83,7 @@
* Generates `frames` from `code` image.
*
* @param code software image in binary format.
- * @param frames output SPI frames.
+ * @param[out] frames output SPI frames.
*
* @return true on success, false otherwise.
*/
