From 9659819365bbfb4608348ff064ea658d6bc0471d Mon Sep 17 00:00:00 2001 From: Sam Hurst Date: Tue, 28 Jun 2022 08:51:19 -0700 Subject: [PATCH] usb-c: tcpc: Changes the @return tag to @retval The "@return" command should be used for the arbitrary return description, and "@retval " for the description of named return value Signed-off-by: Sam Hurst --- drivers/usb_c/tcpc/ucpd_stm32.c | 64 +++++----- include/zephyr/drivers/usb_c/usbc_tcpc.h | 150 +++++++++++------------ 2 files changed, 107 insertions(+), 107 deletions(-) diff --git a/drivers/usb_c/tcpc/ucpd_stm32.c b/drivers/usb_c/tcpc/ucpd_stm32.c index 6851c9e7ee2..d4e32febc57 100644 --- a/drivers/usb_c/tcpc/ucpd_stm32.c +++ b/drivers/usb_c/tcpc/ucpd_stm32.c @@ -50,7 +50,7 @@ static int ucpd_txorderset[] = { /** * @brief Test for a goodCRC message * - * @returns true if message is goodCRC, else false + * @retval true if message is goodCRC, else false */ static bool ucpd_msg_is_good_crc(union pd_header header) { @@ -152,8 +152,8 @@ static void stm32_ucpd_state_init(const struct device *dev) /** * @brief Get the state of the CC1 and CC2 lines * - * @return 0 on success - * @return -EIO on failure + * @retval 0 on success + * @retval -EIO on failure */ static int ucpd_get_cc(const struct device *dev, enum tc_cc_voltage_state *cc1, @@ -221,7 +221,7 @@ static int ucpd_get_cc(const struct device *dev, * @brief Get the CC enable mask. The mask indicates which CC line * is enabled. * - * @return CC Enable mask (bit 0: CC1, bit 1: CC2) + * @retval CC Enable mask (bit 0: CC1, bit 1: CC2) */ static uint32_t ucpd_get_cc_enable_mask(const struct device *dev) { @@ -242,9 +242,9 @@ static uint32_t ucpd_get_cc_enable_mask(const struct device *dev) /** * @brief Enable or Disable VCONN * - * @return 0 on success - * @return -EIO on failure - * @return -ENOTSUP if not supported + * @retval 0 on success + * @retval -EIO on failure + * @retval -ENOTSUP if not supported */ static int ucpd_set_vconn(const struct device *dev, bool enable) { @@ -280,7 +280,7 @@ static int ucpd_set_vconn(const struct device *dev, bool enable) /** * @brief Sets the value of the CC pull up resistor used when operating as a Source * - * @return 0 on success + * @retval 0 on success */ static int ucpd_select_rp_value(const struct device *dev, enum tc_rp_value rp) { @@ -294,7 +294,7 @@ static int ucpd_select_rp_value(const struct device *dev, enum tc_rp_value rp) /** * @brief Gets the value of the CC pull up resistor used when operating as a Source * - * @return 0 on success + * @retval 0 on success */ static int ucpd_get_rp_value(const struct device *dev, enum tc_rp_value *rp) { @@ -308,8 +308,8 @@ static int ucpd_get_rp_value(const struct device *dev, enum tc_rp_value *rp) /** * @brief Set the CC pull up or pull down resistors * - * @return 0 on success - * @return -EIO on failure + * @retval 0 on success + * @retval -EIO on failure */ static int ucpd_set_cc(const struct device *dev, enum tc_cc_pull cc_pull) @@ -353,9 +353,9 @@ static int ucpd_set_cc(const struct device *dev, * @brief Set the polarity of the CC line, which is the active CC line * used for power delivery. * - * @return 0 on success - * @return -EIO on failure - * @return -ENOTSUP if polarity is not supported + * @retval 0 on success + * @retval -EIO on failure + * @retval -ENOTSUP if polarity is not supported */ static int ucpd_cc_set_polarity(const struct device *dev, enum tc_cc_polarity polarity) @@ -389,8 +389,8 @@ static int ucpd_cc_set_polarity(const struct device *dev, /** * @brief Enable or Disable Power Delivery * - * @return 0 on success - * @return -EIO on failure + * @retval 0 on success + * @retval -EIO on failure */ static int ucpd_set_rx_enable(const struct device *dev, bool enable) { @@ -425,8 +425,8 @@ static int ucpd_set_rx_enable(const struct device *dev, bool enable) /** * @brief Set the Power and Data role used when sending goodCRC messages * - * @return 0 on success - * @return -EIO on failure + * @retval 0 on success + * @retval -EIO on failure */ static int ucpd_set_roles(const struct device *dev, enum tc_power_role power_role, @@ -443,8 +443,8 @@ static int ucpd_set_roles(const struct device *dev, /** * @brief Enable the reception of SOP Prime messages * - * @return 0 on success - * @return -EIO on failure + * @retval 0 on success + * @retval -EIO on failure */ static int ucpd_sop_prime_enable(const struct device *dev, bool enable) { @@ -888,8 +888,8 @@ static void ucpd_send_good_crc(const struct device *dev, /** * @brief Transmit a power delivery message * - * @return 0 on success - * @return -EFAULT on failure + * @retval 0 on success + * @retval -EFAULT on failure */ static int ucpd_transmit_data(const struct device *dev, struct pd_msg *msg) @@ -932,7 +932,7 @@ static int ucpd_transmit_data(const struct device *dev, /** * @brief Tests if a received Power Delivery message is pending * - * @return true if message is pending, else false + * @retval true if message is pending, else false */ static bool ucpd_is_rx_pending_msg(const struct device *dev, enum pd_packet_type *type) @@ -952,9 +952,9 @@ static bool ucpd_is_rx_pending_msg(const struct device *dev, /** * @brief Retrieves the Power Delivery message from the TCPC * - * @return number of bytes received - * @return -EIO on no message to retrieve - * @return -EFAULT on buf being NULL + * @retval number of bytes received + * @retval -EIO on no message to retrieve + * @retval -EFAULT on buf being NULL */ static int ucpd_receive_data(const struct device *dev, struct pd_msg *msg) { @@ -1175,8 +1175,8 @@ static void ucpd_isr(const struct device *dev_inst[]) /** * @brief Dump a set of TCPC registers * - * @return 0 on success - * @return -EIO on failure + * @retval 0 on success + * @retval -EIO on failure */ static int ucpd_dump_std_reg(const struct device *dev) { @@ -1196,8 +1196,8 @@ static int ucpd_dump_std_reg(const struct device *dev) * @brief Sets the alert function that's called when an interrupt is triggered * due to a TCPC alert * - * @return 0 on success - * @return -EINVAL on failure + * @retval 0 on success + * @retval -EINVAL on failure */ static int ucpd_set_alert_handler_cb(const struct device *dev, tcpc_alert_handler_cb_t handler, void *alert_data) @@ -1373,8 +1373,8 @@ static void ucpd_isr_init(const struct device *dev) /** * @brief Initializes the TCPC * - * @return 0 on success - * @return -EIO on failure + * @retval 0 on success + * @retval -EIO on failure */ static int ucpd_init(const struct device *dev) { diff --git a/include/zephyr/drivers/usb_c/usbc_tcpc.h b/include/zephyr/drivers/usb_c/usbc_tcpc.h index a24c7a884fa..18d91f1a1fd 100644 --- a/include/zephyr/drivers/usb_c/usbc_tcpc.h +++ b/include/zephyr/drivers/usb_c/usbc_tcpc.h @@ -233,8 +233,8 @@ static inline int tcpc_is_cc_only_one_rd(enum tc_cc_voltage_state cc1, * * @param dev Runtime device structure * - * @return 0 on success - * @return -EIO on failure + * @retval 0 on success + * @retval -EIO on failure */ static inline int tcpc_init(const struct device *dev) { @@ -254,9 +254,9 @@ static inline int tcpc_init(const struct device *dev) * @param cc1 A pointer where the CC1 status is written * @param cc2 A pointer where the CC2 status is written * - * @return 0 on success - * @return -EIO on failure - * @return -ENOSYS if not implemented + * @retval 0 on success + * @retval -EIO on failure + * @retval -ENOSYS if not implemented */ static inline int tcpc_get_cc(const struct device *dev, enum tc_cc_voltage_state *cc1, @@ -371,9 +371,9 @@ static inline int tcpc_get_vbus(const struct device *dev, int *vbus_meas) * @param dev Runtime device structure * @param rp Value of the Pull-Up Resistor. * - * @return 0 on success - * @return -ENOSYS - * @return -EIO on failure + * @retval 0 on success + * @retval -ENOSYS + * @retval -EIO on failure */ static inline int tcpc_select_rp_value(const struct device *dev, enum tc_rp_value rp) { @@ -393,9 +393,9 @@ static inline int tcpc_select_rp_value(const struct device *dev, enum tc_rp_valu * @param dev Runtime device structure * @param rp pointer where the value of the Pull-Up Resistor is stored * - * @return 0 on success - * @return -ENOSYS - * @return -EIO on failure + * @retval 0 on success + * @retval -ENOSYS + * @retval -EIO on failure */ static inline int tcpc_get_rp_value(const struct device *dev, enum tc_rp_value *rp) { @@ -415,8 +415,8 @@ static inline int tcpc_get_rp_value(const struct device *dev, enum tc_rp_value * * @param dev Runtime device structure * @param pull The pull resistor to set * - * @return 0 on success - * @return -EIO on failure + * @retval 0 on success + * @retval -EIO on failure */ static inline int tcpc_set_cc(const struct device *dev, enum tc_cc_pull pull) { @@ -460,9 +460,9 @@ static inline void tcpc_set_vconn_cb(const struct device *dev, * @param dev Runtime device structure * @param enable VCONN is enabled when true, it's disabled * - * @return 0 on success - * @return -EIO on failure - * @return -ENOSYS if not implemented + * @retval 0 on success + * @retval -EIO on failure + * @retval -ENOSYS if not implemented */ static inline int tcpc_set_vconn(const struct device *dev, bool enable) { @@ -485,9 +485,9 @@ static inline int tcpc_set_vconn(const struct device *dev, bool enable) * @param power_role current power role * @param data_role current data role * - * @return 0 on success - * @return -EIO on failure - * @return -ENOSYS if not implemented + * @retval 0 on success + * @retval -EIO on failure + * @retval -ENOSYS if not implemented */ static inline int tcpc_set_roles(const struct device *dev, enum tc_power_role power_role, @@ -509,9 +509,9 @@ static inline int tcpc_set_roles(const struct device *dev, * @param dev Runtime device structure * @param type pointer to where message type is written. Can be NULL * - * @return true if message is pending, else false - * @return -EIO on failure - * @return -ENOSYS if not implemented + * @retval true if message is pending, else false + * @retval -EIO on failure + * @retval -ENOSYS if not implemented */ static inline bool tcpc_is_rx_pending_msg(const struct device *dev, enum pd_packet_type *type) @@ -532,10 +532,10 @@ static inline bool tcpc_is_rx_pending_msg(const struct device *dev, * @param dev Runtime device structure * @param buf pointer where the pd_buf pointer is written * - * @return Greater or equal to 0 is the number of bytes received - * @return -EIO on failure - * @return -EFAULT on buf being NULL - * @return -ENOSYS if not implemented + * @retval Greater or equal to 0 is the number of bytes received + * @retval -EIO on failure + * @retval -EFAULT on buf being NULL + * @retval -ENOSYS if not implemented */ static inline int tcpc_receive_data(const struct device *dev, struct pd_msg *buf) @@ -557,9 +557,9 @@ static inline int tcpc_receive_data(const struct device *dev, * @param enable Enable Power Delivery when true, else it's * disabled * - * @return 0 on success - * @return -EIO on failure - * @return -ENOSYS if not implemented + * @retval 0 on success + * @retval -EIO on failure + * @retval -ENOSYS if not implemented */ static inline int tcpc_set_rx_enable(const struct device *dev, bool enable) { @@ -579,8 +579,8 @@ static inline int tcpc_set_rx_enable(const struct device *dev, bool enable) * @param dev Runtime device structure * @param polarity Polarity of the cc line * - * @return 0 on success - * @return -EIO on failure + * @retval 0 on success + * @retval -EIO on failure */ static inline int tcpc_set_cc_polarity(const struct device *dev, enum tc_cc_polarity polarity) @@ -600,9 +600,9 @@ static inline int tcpc_set_cc_polarity(const struct device *dev, * @param dev Runtime device structure * @param msg Power Delivery message to transmit * - * @return 0 on success - * @return -EIO on failure - * @return -ENOSYS if not implemented + * @retval 0 on success + * @retval -EIO on failure + * @retval -ENOSYS if not implemented */ static inline int tcpc_transmit_data(const struct device *dev, struct pd_msg *msg) @@ -622,9 +622,9 @@ static inline int tcpc_transmit_data(const struct device *dev, * * @param dev Runtime device structure * - * @return 0 on success - * @return -EIO on failure - * @return -ENOSYS if not implemented + * @retval 0 on success + * @retval -EIO on failure + * @retval -ENOSYS if not implemented */ static inline int tcpc_dump_std_reg(const struct device *dev) { @@ -648,8 +648,8 @@ static inline int tcpc_dump_std_reg(const struct device *dev) * @param handler The callback function called when the bit is set * @param data user data passed to the callback * - * @return 0 on success - * @return -EINVAL on failure + * @retval 0 on success + * @retval -EINVAL on failure */ static inline int tcpc_set_alert_handler_cb(const struct device *dev, tcpc_alert_handler_cb_t handler, @@ -671,9 +671,9 @@ static inline int tcpc_set_alert_handler_cb(const struct device *dev, * @param reg The status register to read * @param status Pointer where the status is stored * - * @return 0 on success - * @return -EIO on failure - * @return -ENOSYS if not implemented + * @retval 0 on success + * @retval -EIO on failure + * @retval -ENOSYS if not implemented */ static inline int tcpc_get_status_register(const struct device *dev, enum tcpc_status_reg reg, @@ -697,9 +697,9 @@ static inline int tcpc_get_status_register(const struct device *dev, * @param mask A bit mask of the status register to clear. * A status bit is cleared when it's set to 1. * - * @return 0 on success - * @return -EIO on failure - * @return -ENOSYS if not implemented + * @retval 0 on success + * @retval -EIO on failure + * @retval -ENOSYS if not implemented */ static inline int tcpc_clear_status_register(const struct device *dev, enum tcpc_status_reg reg, @@ -723,9 +723,9 @@ static inline int tcpc_clear_status_register(const struct device *dev, * @param mask A bit mask of the status register to mask. * The status bit is masked if it's 0, else it's unmasked. * - * @return 0 on success - * @return -EIO on failure - * @return -ENOSYS if not implemented + * @retval 0 on success + * @retval -EIO on failure + * @retval -ENOSYS if not implemented */ static inline int tcpc_mask_status_register(const struct device *dev, enum tcpc_status_reg reg, @@ -796,9 +796,9 @@ static inline int tcpc_enable_auto_discharge_disconnect( * @param dev Runtime device structure * @param enable Enable Debug Accessory when true, else it's disabled * - * @return 0 on success - * @return -EIO on failure - * @return -ENOSYS if not implemented + * @retval 0 on success + * @retval -EIO on failure + * @retval -ENOSYS if not implemented */ static inline int tcpc_set_debug_accessory(const struct device *dev, bool enable) @@ -818,9 +818,9 @@ static inline int tcpc_set_debug_accessory(const struct device *dev, * * @param dev Runtime device structure * - * @return 0 on success - * @return -EIO on failure - * @return -ENOSYS if not implemented + * @retval 0 on success + * @retval -EIO on failure + * @retval -ENOSYS if not implemented */ static inline int tcpc_set_debug_detach(const struct device *dev) { @@ -840,9 +840,9 @@ static inline int tcpc_set_debug_detach(const struct device *dev) * @param dev Runtime device structure * @param enable Auto dual role toggle is active when true, else it's disabled * - * @return 0 on success - * @return -EIO on failure - * @return -ENOSYS if not implemented + * @retval 0 on success + * @retval -EIO on failure + * @retval -ENOSYS if not implemented */ static inline int tcpc_set_drp_toggle(const struct device *dev, bool enable) { @@ -861,9 +861,9 @@ static inline int tcpc_set_drp_toggle(const struct device *dev, bool enable) * * @param dev Runtime device structure * - * @return true if sinking power - * @return false if not sinking power - * @return -ENOSYS if not implemented + * @retval true if sinking power + * @retval false if not sinking power + * @retval -ENOSYS if not implemented */ static inline bool tcpc_get_snk_ctrl(const struct device *dev) { @@ -882,9 +882,9 @@ static inline bool tcpc_get_snk_ctrl(const struct device *dev) * * @param dev Runtime device structure * - * @return true if sourcing power - * @return false if not sourcing power - * @return -ENOSYS if not implemented + * @retval true if sourcing power + * @retval false if not sourcing power + * @retval -ENOSYS if not implemented */ static inline bool tcpc_get_src_ctrl(const struct device *dev) { @@ -905,9 +905,9 @@ static inline bool tcpc_get_src_ctrl(const struct device *dev) * @param dev Runtime device structure * @param enable The TCPC enters BIST TEST Mode when true * - * @return 0 on success - * @return -EIO on failure - * @return -ENOSYS if not implemented + * @retval 0 on success + * @retval -EIO on failure + * @retval -ENOSYS if not implemented */ static inline int tcpc_set_bist_test_mode(const struct device *dev, bool enable) @@ -928,9 +928,9 @@ static inline int tcpc_set_bist_test_mode(const struct device *dev, * @param dev Runtime device structure * @param chip_info Pointer to TCPC chip info where the version is stored * - * @return 0 on success - * @return -EIO on failure - * @return -ENOSYS if not implemented + * @retval 0 on success + * @retval -EIO on failure + * @retval -ENOSYS if not implemented */ static inline int tcpc_get_chip_info(const struct device *dev, struct tcpc_chip_info *chip_info) @@ -951,9 +951,9 @@ static inline int tcpc_get_chip_info(const struct device *dev, * @param dev Runtime device structure * @param enable The TCPC enters low power mode when true, else it exits it * - * @return 0 on success - * @return -EIO on failure - * @return -ENOSYS if not implemented + * @retval 0 on success + * @retval -EIO on failure + * @retval -ENOSYS if not implemented */ static inline int tcpc_set_low_power_mode(const struct device *dev, bool enable) @@ -974,9 +974,9 @@ static inline int tcpc_set_low_power_mode(const struct device *dev, * @param dev Runtime device structure * @param enable Can receive SOP Prime messages when true, else it can not * - * @return 0 on success - * @return -EIO on failure - * @return -ENOSYS if not implemented + * @retval 0 on success + * @retval -EIO on failure + * @retval -ENOSYS if not implemented */ static inline int tcpc_sop_prime_enable(const struct device *dev, bool enable)