[sw] Update source documentation
Fixes mostly spelling errors and outdated parameters.
Based on the warnings generated by Doxygen.
Signed-off-by: Tobias Wölfel <tobias.woelfel@mailbox.org>
diff --git a/sw/device/lib/base/mmio.h b/sw/device/lib/base/mmio.h
index b349300..cf1aa11 100644
--- a/sw/device/lib/base/mmio.h
+++ b/sw/device/lib/base/mmio.h
@@ -167,7 +167,7 @@
* @param offset the offset to apply the mask at, in bytes.
* @param mask the mask to read from the selected register.
* @param mask_index mask position within the selected register.
- * @retun return the value of the read mask.
+ * @return return the value of the read mask.
*/
MMIO_WARN_UNUSED_RESULT
MMIO_DEPRECATED
diff --git a/sw/device/lib/dif/dif_aes.h b/sw/device/lib/dif/dif_aes.h
index 27516e8..968d3f1 100644
--- a/sw/device/lib/dif/dif_aes.h
+++ b/sw/device/lib/dif/dif_aes.h
@@ -330,7 +330,7 @@
*
* @param aes AES state data.
* @param transaction Configuration data.
- * @param key_share Masked AES key.
+ * @param key Masked AES key.
* @param iv AES Initialisation Vector.
* @return The result of the operation.
*/
@@ -355,7 +355,7 @@
*
* @param aes AES state data.
* @param transaction Configuration data.
- * @paran key Masked AES key.
+ * @param key Masked AES key.
* @param iv AES Initial Counter Value.
* @return The result of the operation.
*/
diff --git a/sw/device/lib/dif/dif_clkmgr.h b/sw/device/lib/dif/dif_clkmgr.h
index 8f51929..bc02b03 100644
--- a/sw/device/lib/dif/dif_clkmgr.h
+++ b/sw/device/lib/dif/dif_clkmgr.h
@@ -198,7 +198,8 @@
*
* @param handle Clock Manager Handle.
* @param clock Hintable Clock ID.
- * @param[out] is_enabled the current software request (hint) for this clock.
+ * @param[out] hinted_is_enabled the current software request (hint) for this
+ * clock.
* @returns The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
diff --git a/sw/device/lib/dif/dif_gpio.h b/sw/device/lib/dif/dif_gpio.h
index 4f8b035..8d10638 100644
--- a/sw/device/lib/dif/dif_gpio.h
+++ b/sw/device/lib/dif/dif_gpio.h
@@ -241,7 +241,8 @@
* Sets whether a particular pin's interrupt is currently enabled or disabled.
*
* @param gpio A GPIO handle.
- * @param pin A GPIO pin.
+ * @param mask Mask that identifies the pins whose interrupt triggers will be
+ * configured.
* @param state The new toggle state for the interrupt.
* @return The result of the operation.
*/
@@ -357,7 +358,7 @@
* The actual values on the pins depend on the output enable setting.
*
* @param gpio A GPIO handle.
- * @param val Value to write.
+ * @param state Value to write.
* @return The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
diff --git a/sw/device/lib/dif/dif_i2c.h b/sw/device/lib/dif/dif_i2c.h
index 1b6f8e6..f85371c 100644
--- a/sw/device/lib/dif/dif_i2c.h
+++ b/sw/device/lib/dif/dif_i2c.h
@@ -356,8 +356,9 @@
* some of the calculations, such as how the allocation of a lengthened SCL
* period.
*
- * @param config Configuration values for producing timing parameters.
- * @param[out] out I2C configuration to which to apply the computed parameters.
+ * @param timing_config Configuration values for producing timing parameters.
+ * @param[out] config I2C configuration to which to apply the computed
+ * parameters.
* @return The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
@@ -616,7 +617,7 @@
* @param i2c An I2C handle.
* @param byte The value to push onto the FIFO.
* @param code The code to use for this write.
- * @param supress_nak_irq Whether to supress the NAK IRQ for this one byte.
+ * @param suppress_nak_irq Whether to supress the NAK IRQ for this one byte.
* May not be used in combination with `Rx` codes.
* @return The result of the operation.
*/
diff --git a/sw/device/lib/dif/dif_keymgr.h b/sw/device/lib/dif/dif_keymgr.h
index 64610ce..75fc1f6 100644
--- a/sw/device/lib/dif/dif_keymgr.h
+++ b/sw/device/lib/dif/dif_keymgr.h
@@ -554,7 +554,7 @@
* Forces a particular alert as if hardware had asserted it.
*
* @param keymgr A key manager handle.
- * @param irq An alert type.
+ * @param alert An alert type.
* @return The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
diff --git a/sw/device/lib/dif/dif_lc_ctrl.h b/sw/device/lib/dif/dif_lc_ctrl.h
index 6d9b89a..9156677 100644
--- a/sw/device/lib/dif/dif_lc_ctrl.h
+++ b/sw/device/lib/dif/dif_lc_ctrl.h
@@ -341,7 +341,7 @@
* up to 16.
*
* @param lc A lifecycle handle.
- * @param[out] state Out-param for the controller's state.
+ * @param[out] count Out-param for the number of attempts.
* @return The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
diff --git a/sw/device/lib/dif/dif_otp_ctrl.h b/sw/device/lib/dif/dif_otp_ctrl.h
index d59d48d..890b5fa 100644
--- a/sw/device/lib/dif/dif_otp_ctrl.h
+++ b/sw/device/lib/dif/dif_otp_ctrl.h
@@ -656,7 +656,7 @@
* Gets the current status of the OTP controller.
*
* @param otp An OTP handle.
- * @param[out] stauts Out-param for the controller's status.
+ * @param[out] status Out-param for the controller's status.
* @return The result of the operation.
*/
DIF_WARN_UNUSED_RESULT
@@ -835,7 +835,7 @@
* addition, `address + len` must also be in-range and must not overflow.
*
* @param otp An OTP handle.
- * @param partition The partition to read from.
+ * @param address The address to read from.
* @param[out] buf A buffer of words to write read values to.
* @param len The number of words to read.
* @return The result of the operation.
diff --git a/sw/device/lib/dif/dif_plic.h b/sw/device/lib/dif/dif_plic.h
index 58dceb3..67b42db 100644
--- a/sw/device/lib/dif/dif_plic.h
+++ b/sw/device/lib/dif/dif_plic.h
@@ -337,7 +337,7 @@
*
* @param plic PLIC state data.
* @param target Target HART.
- * @param is_pending[out] Flag indicating whether the interrupt is pending.
+ * @param[out] is_pending Flag indicating whether the interrupt is pending.
* @return `dif_plic_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 288e9e1..894ed71 100644
--- a/sw/device/lib/dif/dif_usbdev.h
+++ b/sw/device/lib/dif/dif_usbdev.h
@@ -414,7 +414,7 @@
*/
DIF_WARN_UNUSED_RESULT
dif_usbdev_buffer_read_result_t dif_usbdev_buffer_read(
- dif_usbdev_t *usbev, dif_usbdev_buffer_t *buffer, uint8_t *dst,
+ dif_usbdev_t *usbdev, dif_usbdev_buffer_t *buffer, uint8_t *dst,
size_t dst_len, size_t *bytes_written);
/**
diff --git a/sw/device/lib/flash_ctrl.h b/sw/device/lib/flash_ctrl.h
index 0ac86a4..33e3a95 100644
--- a/sw/device/lib/flash_ctrl.h
+++ b/sw/device/lib/flash_ctrl.h
@@ -99,7 +99,7 @@
/**
* Set flash controller default permissions.
*
- * @param rd_end Read enable.
+ * @param rd_en Read enable.
* @param prog_en Write enable.
* @param erase_en Erase enable.
*/
diff --git a/sw/device/lib/handler.c b/sw/device/lib/handler.c
index 4b6a93c..362390d 100644
--- a/sw/device/lib/handler.c
+++ b/sw/device/lib/handler.c
@@ -18,7 +18,7 @@
/**
* Default Error Handling
- * @param error message supplied by caller
+ * @param msg error message supplied by caller
* TODO - this will be soon by a real print formatting
*/
static void print_exc_msg(const char *msg) {
diff --git a/sw/device/lib/runtime/otbn.c b/sw/device/lib/runtime/otbn.c
index fa29823..6a27043 100644
--- a/sw/device/lib/runtime/otbn.c
+++ b/sw/device/lib/runtime/otbn.c
@@ -11,7 +11,7 @@
*
* @param ctx The context object.
* @param ptr The pointer to convert.
- * @param[out] func_addr_otbn The address of the function in OTBN's instruction
+ * @param[out] imem_addr_otbn The address of the function in OTBN's instruction
* memory.
* @return The result of the operation; #kOtbnBadArg if `ptr` is not in the
* instruction memory space of the currently loaded application.
@@ -36,7 +36,7 @@
*
* @param ctx The context object.
* @param ptr The pointer to convert.
- * @param[out] data_addr_otbn The address of the data in OTBN's data memory.
+ * @param[out] dmem_addr_otbn The address of the data in OTBN's data memory.
* @return The result of the operation; #kOtbnBadArg if `ptr` is not in the data
* memory space of the currently loaded application.
*/
diff --git a/sw/device/lib/runtime/pmp.c b/sw/device/lib/runtime/pmp.c
index 8d153b5..c18cd8e 100644
--- a/sw/device/lib/runtime/pmp.c
+++ b/sw/device/lib/runtime/pmp.c
@@ -119,7 +119,6 @@
* Writes the pmpcfg for a given region.
*
* @param region PMP region ID to get/set.
- * @param access CSR access type read/write.
* @param value Value to write into a CSR.
* @return `pmp_region_configure_result_t`.
*/
@@ -320,7 +319,7 @@
*
* @param address Conventional system address.
* @param size The size of a range to protect.
- * @param napot_address Constructed NAPOT address.
+ * @param pmp_address_napot Constructed NAPOT address.
* @return `pmp_region_configure_napot_result_t`.
*/
PMP_WARN_UNUSED_RESULT
diff --git a/sw/device/lib/runtime/print.c b/sw/device/lib/runtime/print.c
index f2f8ae0..beb4f19 100644
--- a/sw/device/lib/runtime/print.c
+++ b/sw/device/lib/runtime/print.c
@@ -253,7 +253,7 @@
* @param out the sink to write bytes to.
* @param spec the specifier to use for stringifying.
* @param[out] bytes_written out param for the number of bytes writen to `out`.
- * @param va_list the list to pull an entry from.
+ * @param args the list to pull an entry from.
*/
static void process_specifier(buffer_sink_t out, format_specifier_t spec,
size_t *bytes_written, va_list *args) {
diff --git a/sw/device/lib/usbdev.h b/sw/device/lib/usbdev.h
index 7c0f5b2..bb9d59d 100644
--- a/sw/device/lib/usbdev.h
+++ b/sw/device/lib/usbdev.h
@@ -128,8 +128,8 @@
* complete, this function should be called to set the new ID. Note
* on a reset the hardware will clear the device ID back to 0.
*
- * @param usbdev context pointer
- * @param new deviceid
+ * @param ctx usbdev context pointer
+ * @param deviceid new deviceid
*/
void usbdev_set_deviceid(usbdev_ctx_t *ctx, int deviceid);
@@ -138,7 +138,7 @@
*
* By default endpoints are enabled, but they can be halted but the host
*
- * @param usbdev context pointer
+ * @param ctx usbdev context pointer
* @param endpoint number
* @param enable set/clear
*/
@@ -147,7 +147,8 @@
/**
* Get halted status for an endpoint
*
- * @param usbdev context pointer
+ * @param ctx usbdev context pointer
+ * @param endpoint number
* @return 1 if endpoint is halted else 0
*/
inline int usbdev_halted(usbdev_ctx_t *ctx, int endpoint) {
@@ -159,7 +160,7 @@
*
* By default endpoints are non-ISO, but they can be set to ISO
*
- * @param usbdev context pointer
+ * @param ctx usbdev context pointer
* @param endpoint number
* @param enable 0: non-ISO, 1: ISO
*/
@@ -167,7 +168,7 @@
/**
* Clear the data toggle bit for an endpoint
- * @param usbdev context pointer
+ * @param ctx usbdev context pointer
* @param endpoint Endpoint number
*/
void usbdev_clear_data_toggle(usbdev_ctx_t *ctx, int endpoint);
@@ -184,7 +185,7 @@
/**
* Enable or disable remote wake
*
- * @param usbdev context pointer
+ * @param ctx usbdev context pointer
* @param enable set/clear
*/
inline void usbdev_rem_wake_en(usbdev_ctx_t *ctx, int enable) {
@@ -194,7 +195,7 @@
/**
* Get ability to wake the host
*
- * @param usbdev context pointer
+ * @param ctx usbdev context pointer
* @return 1 if remote wake is permitted else 0
*/
int usbdev_can_rem_wake(usbdev_ctx_t *ctx);
diff --git a/sw/device/rom_exts/rom_ext_manifest_parser.h b/sw/device/rom_exts/rom_ext_manifest_parser.h
index c0cbf99..1f7305c 100644
--- a/sw/device/rom_exts/rom_ext_manifest_parser.h
+++ b/sw/device/rom_exts/rom_ext_manifest_parser.h
@@ -277,7 +277,7 @@
* interrupts in Ibex - the least significant two bits will have the correct
* value.
*
- * @param param Parameters required for manifest parsing.
+ * @param params Parameters required for manifest parsing.
* @return The value to write to the `mtvec` RISC-V CSR.
*/
uintptr_t rom_ext_get_interrupt_vector(rom_ext_manifest_t params);
diff --git a/sw/device/sca/lib/simple_serial.c b/sw/device/sca/lib/simple_serial.c
index 18a32ce..2c4ebe5 100644
--- a/sw/device/sca/lib/simple_serial.c
+++ b/sw/device/sca/lib/simple_serial.c
@@ -49,7 +49,7 @@
* Converts a hex encoded nibble to binary.
*
* @param hex A hex encoded nibble.
- * @param[out] to Value of the nibble.
+ * @param[out] val Value of the nibble.
*
* @return Result of the operation.
*/
@@ -76,7 +76,7 @@
* - Terminator: '\n'.
*
* @param[out] cmd Simple serial command.
- * @param[out] Buffer for received packet payload.
+ * @param[out] data Buffer for received packet payload.
* @param data_buf_len Length of the packet payload buffer.
* @param[out] data_len Received packet payload length.
*/
