diff options
author | Chris Kay <chris.kay@arm.com> | 2020-09-28 11:12:52 +0100 |
---|---|---|
committer | jimqui01 <54316584+jimqui01@users.noreply.github.com> | 2020-10-02 14:19:09 +0100 |
commit | 8d2dafa877386947f8ffadff97767114a55efe62 (patch) | |
tree | af17d79d1d068e0eb0e6e88923a7665113997c0c /module | |
parent | 51d7ddacf6ade12fe86af0cec5096691059c5e2a (diff) |
docs: Ensure Doxygen return values use references
At present a lot of the code-base uses `\retval` commands to framework
status codes but does not explicitly link to them. In some cases it's
necessary to explicitly link to these status codes to have Doxygen
generate a link to the relevant enumeration, and we can do this by
prefixing the name with `::`.
This style is already used in much of the code-base, so should not
conflict with any existing styles.
Change-Id: Ifc78eb425981bee3a01c791757a41a61c20e636c
Signed-off-by: Chris Kay <chris.kay@arm.com>
Diffstat (limited to 'module')
21 files changed, 361 insertions, 359 deletions
diff --git a/module/bootloader/include/mod_bootloader.h b/module/bootloader/include/mod_bootloader.h index e673a3e6..b7b56228 100644 --- a/module/bootloader/include/mod_bootloader.h +++ b/module/bootloader/include/mod_bootloader.h @@ -78,20 +78,21 @@ struct mod_bootloader_api { * \param config Pointer to an scp_bootloader_config structure containing * settings that control where the image is copied from and to. * - * \retval FWK_SUCCESS The RAM Firmware image was copied successfully. - * \retval FWK_E_ALIGN The given image offset is not properly aligned. - * \retval FWK_E_DATA The image did not pass checksum validation. - * \retval FWK_E_PARAM The config structure pointer is invalid. - * \retval FWK_E_PARAM One or more config structure fields are invalid. - * \retval FWK_E_SIZE The given image size is below the minimum possible + * \retval ::FWK_SUCCESS The RAM Firmware image was copied successfully. + * \retval ::FWK_E_ALIGN The given image offset is not properly aligned. + * \retval ::FWK_E_DATA The image did not pass checksum validation. + * \retval ::FWK_E_PARAM The config structure pointer is invalid. + * \retval ::FWK_E_PARAM One or more config structure fields are invalid. + * \retval ::FWK_E_SIZE The given image size is below the minimum possible * size. - * \retval FWK_E_SIZE The image is too large for the destination memory + * \retval ::FWK_E_SIZE The image is too large for the destination memory * area. - * \retval FWK_E_SIZE The given image offset is beyond the source memory - * area. - * \retval FWK_E_SIZE The header's size field does not match the given size. - * \retval FWK_E_SIZE Part of the image lies outside of the source memory + * \retval ::FWK_E_SIZE The given image offset is beyond the source memory * area. + * \retval ::FWK_E_SIZE The header's size field does not match the given + * size. + * \retval ::FWK_E_SIZE Part of the image lies outside of the source + * memory area. */ int (*load_image)(void); }; diff --git a/module/clock/include/mod_clock.h b/module/clock/include/mod_clock.h index d1e23a9f..4dbd52d1 100644 --- a/module/clock/include/mod_clock.h +++ b/module/clock/include/mod_clock.h @@ -255,9 +255,9 @@ struct mod_clock_drv_api { * \param round_mode The type of rounding to perform, if required, to * achieve the given rate. * - * \retval FWK_PENDING The request is pending. The driver will provide the + * \retval ::FWK_PENDING The request is pending. The driver will provide the * requested value later through the driver response API. - * \retval FWK_SUCCESS The operation succeeded. + * \retval ::FWK_SUCCESS The operation succeeded. * \return One of the standard framework error codes. */ int (*set_rate)(fwk_id_t clock_id, uint64_t rate, @@ -270,9 +270,9 @@ struct mod_clock_drv_api { * * \param[out] rate The current clock rate in Hertz. * - * \retval FWK_PENDING The request is pending. The driver will provide the + * \retval ::FWK_PENDING The request is pending. The driver will provide the * requested value later through the driver response API. - * \retval FWK_SUCCESS The operation succeeded. + * \retval ::FWK_SUCCESS The operation succeeded. * \return One of the standard framework error codes. */ int (*get_rate)(fwk_id_t clock_id, uint64_t *rate); @@ -286,7 +286,7 @@ struct mod_clock_drv_api { * * \param[out] rate The rate, in Hertz, corresponding to the index. * - * \retval FWK_SUCCESS The operation succeeded. + * \retval ::FWK_SUCCESS The operation succeeded. * \return One of the standard framework error codes. */ int (*get_rate_from_index)(fwk_id_t clock_id, unsigned int rate_index, @@ -299,9 +299,9 @@ struct mod_clock_drv_api { * * \param state One of the valid clock states. * - * \retval FWK_PENDING The request is pending. The driver will provide the + * \retval ::FWK_PENDING The request is pending. The driver will provide the * requested value later through the driver response API. - * \retval FWK_SUCCESS The operation succeeded. + * \retval ::FWK_SUCCESS The operation succeeded. * \return One of the standard framework error codes. */ int (*set_state)(fwk_id_t clock_id, enum mod_clock_state state); @@ -313,9 +313,9 @@ struct mod_clock_drv_api { * * \param[out] state The current clock state. * - * \retval FWK_PENDING The request is pending. The driver will provide the + * \retval ::FWK_PENDING The request is pending. The driver will provide the * requested value later through the driver response API. - * \retval FWK_SUCCESS The operation succeeded. + * \retval ::FWK_SUCCESS The operation succeeded. * \return One of the standard framework error codes. */ int (*get_state)(fwk_id_t clock_id, enum mod_clock_state *state); @@ -327,7 +327,7 @@ struct mod_clock_drv_api { * * \param[out] range The clock range structure. * - * \retval FWK_SUCCESS The operation succeeded. + * \retval ::FWK_SUCCESS The operation succeeded. * \return One of the standard framework error codes. */ int (*get_range)(fwk_id_t clock_id, struct mod_clock_range *range); @@ -352,7 +352,7 @@ struct mod_clock_drv_api { * \param new_state The power state that the clock's power domain will * transition to. * - * \retval FWK_SUCCESS The operation succeeded. + * \retval ::FWK_SUCCESS The operation succeeded. * \return One of the standard framework error codes. */ int (*process_pending_power_transition)( @@ -379,7 +379,7 @@ struct mod_clock_drv_api { * \param state The power state that the clock's power domain transitioned * to. * - * \retval FWK_SUCCESS The operation succeeded. + * \retval ::FWK_SUCCESS The operation succeeded. * \return One of the standard framework error codes. */ int (*process_power_transition)(fwk_id_t clock_id, unsigned int state); @@ -399,11 +399,11 @@ struct mod_clock_api { * \param round_mode The type of rounding to perform, if required, to * achieve the given rate. * - * \retval FWK_SUCCESS The operation succeeded. - * \retval FWK_PENDING The request is pending. The result for this operation - * will be provided via a response event. - * \retval FWK_E_PARAM The clock identifier was invalid. - * \retval FWK_E_SUPPORT Deferred handling of asynchronous drivers is not + * \retval ::FWK_SUCCESS The operation succeeded. + * \retval ::FWK_PENDING The request is pending. The result for this + * operation will be provided via a response event. + * \retval ::FWK_E_PARAM The clock identifier was invalid. + * \retval ::FWK_E_SUPPORT Deferred handling of asynchronous drivers is not * supported. * \return One of the standard framework error codes. */ @@ -417,12 +417,12 @@ struct mod_clock_api { * * \param[out] rate The current clock rate in Hertz. * - * \retval FWK_SUCCESS The operation succeeded. - * \retval FWK_PENDING The request is pending. The requested rate will be + * \retval ::FWK_SUCCESS The operation succeeded. + * \retval ::FWK_PENDING The request is pending. The requested rate will be * provided via a response event. - * \retval FWK_E_PARAM The clock identifier was invalid. - * \retval FWK_E_PARAM The rate pointer was NULL. - * \retval FWK_E_SUPPORT Deferred handling of asynchronous drivers is not + * \retval ::FWK_E_PARAM The clock identifier was invalid. + * \retval ::FWK_E_PARAM The rate pointer was NULL. + * \retval ::FWK_E_SUPPORT Deferred handling of asynchronous drivers is not * supported. * \return One of the standard framework error codes. */ @@ -437,9 +437,9 @@ struct mod_clock_api { * * \param[out] rate The rate, in Hertz, corresponding to the index. * - * \retval FWK_SUCCESS The operation succeeded. - * \retval FWK_E_PARAM The clock identifier was invalid. - * \retval FWK_E_PARAM The rate pointer was NULL. + * \retval ::FWK_SUCCESS The operation succeeded. + * \retval ::FWK_E_PARAM The clock identifier was invalid. + * \retval ::FWK_E_PARAM The rate pointer was NULL. * \return One of the standard framework error codes. */ int (*get_rate_from_index)(fwk_id_t clock_id, unsigned int rate_index, @@ -452,11 +452,11 @@ struct mod_clock_api { * * \param state One of the valid clock states. * - * \retval FWK_SUCCESS The operation succeeded. - * \retval FWK_PENDING The request is pending. The result for this operation - * will be provided via a response event. - * \retval FWK_E_PARAM The clock identifier was invalid. - * \retval FWK_E_SUPPORT Deferred handling of asynchronous drivers is not + * \retval ::FWK_SUCCESS The operation succeeded. + * \retval ::FWK_PENDING The request is pending. The result for this + * operation will be provided via a response event. + * \retval ::FWK_E_PARAM The clock identifier was invalid. + * \retval ::FWK_E_SUPPORT Deferred handling of asynchronous drivers is not * supported. * \return One of the standard framework error codes. */ @@ -469,12 +469,12 @@ struct mod_clock_api { * * \param[out] state The current clock state. * - * \retval FWK_SUCCESS The operation succeeded. - * \retval FWK_PENDING The request is pending. The requested state will be + * \retval ::FWK_SUCCESS The operation succeeded. + * \retval ::FWK_PENDING The request is pending. The requested state will be * provided via a response event. - * \retval FWK_E_PARAM The clock identifier was invalid. - * \retval FWK_E_PARAM The state pointer was NULL. - * \retval FWK_E_SUPPORT Deferred handling of asynchronous drivers is not + * \retval ::FWK_E_PARAM The clock identifier was invalid. + * \retval ::FWK_E_PARAM The state pointer was NULL. + * \retval ::FWK_E_SUPPORT Deferred handling of asynchronous drivers is not * supported. * \return One of the standard framework error codes. */ @@ -487,9 +487,9 @@ struct mod_clock_api { * * \param[out] info The clock device properties. * - * \retval FWK_SUCCESS The operation succeeded. - * \retval FWK_E_PARAM The clock identifier was invalid. - * \retval FWK_E_PARAM The info pointer was NULL. + * \retval ::FWK_SUCCESS The operation succeeded. + * \retval ::FWK_E_PARAM The clock identifier was invalid. + * \retval ::FWK_E_PARAM The info pointer was NULL. * \return One of the standard framework error codes. */ int (*get_info)(fwk_id_t clock_id, struct mod_clock_info *info); diff --git a/module/cmn600/include/mod_cmn600.h b/module/cmn600/include/mod_cmn600.h index bf04bfa3..a2016a4e 100644 --- a/module/cmn600/include/mod_cmn600.h +++ b/module/cmn600/include/mod_cmn600.h @@ -255,53 +255,53 @@ struct mod_cmn600_ccix_host_node_config { * \brief CMN600 CCIX configuration interface */ struct mod_cmn600_ccix_config_api { - /*! - * \brief Get the CCIX host configuration - * - * \param[out] config CCIX host configuration - * - * \retval FWK_SUCCESS if the operation succeed. - * \return one of the error code otherwise. - */ - int (*get_config)(struct mod_cmn600_ccix_host_node_config *config); - /*! - * \brief set the CCIX endpoint configuration - * - * \param[in] config CCIX endpoint configuration - * - * \retval FWK_SUCCESS if the operation succeed. - * \return one of the error code otherwise. - */ - int (*set_config)(struct mod_cmn600_ccix_remote_node_config *config); - /*! - * \brief Interface to trigger the protocol credit exchange - * - * \param link_id Link on which the protocol credit exchange - * would initiate. - * - * \retval FWK_SUCCESS if the operation succeed. - * \return one of the error code otherwise. - */ - int (*exchange_protocol_credit)(uint8_t link_id); - /*! - * \brief Interface to configure for system coherency - * - * \param link_id Link on which the coherency has to - * be enabled. - * - * \retval FWK_SUCCESS if the operation succeed. - * \return one of the error code otherwise. - */ - int (*enter_system_coherency)(uint8_t link_id); - /*! - * \brief Interface to enter DVM domain - * - * \param link_id Link on which DVM domain has to be enabled - * - * \retval FWK_SUCCESS if the operation succeed. - * \return one of the error code otherwise. - */ - int (*enter_dvm_domain)(uint8_t link_id); + /*! + * \brief Get the CCIX host configuration + * + * \param[out] config CCIX host configuration + * + * \retval ::FWK_SUCCESS if the operation succeed. + * \return one of the error code otherwise. + */ + int (*get_config)(struct mod_cmn600_ccix_host_node_config *config); + /*! + * \brief set the CCIX endpoint configuration + * + * \param[in] config CCIX endpoint configuration + * + * \retval ::FWK_SUCCESS if the operation succeed. + * \return one of the error code otherwise. + */ + int (*set_config)(struct mod_cmn600_ccix_remote_node_config *config); + /*! + * \brief Interface to trigger the protocol credit exchange + * + * \param link_id Link on which the protocol credit exchange + * would initiate. + * + * \retval ::FWK_SUCCESS if the operation succeed. + * \return one of the error code otherwise. + */ + int (*exchange_protocol_credit)(uint8_t link_id); + /*! + * \brief Interface to configure for system coherency + * + * \param link_id Link on which the coherency has to + * be enabled. + * + * \retval ::FWK_SUCCESS if the operation succeed. + * \return one of the error code otherwise. + */ + int (*enter_system_coherency)(uint8_t link_id); + /*! + * \brief Interface to enter DVM domain + * + * \param link_id Link on which DVM domain has to be enabled + * + * \retval ::FWK_SUCCESS if the operation succeed. + * \return one of the error code otherwise. + */ + int (*enter_dvm_domain)(uint8_t link_id); }; /*! diff --git a/module/css_clock/include/mod_css_clock.h b/module/css_clock/include/mod_css_clock.h index b260324d..3dbce6ac 100644 --- a/module/css_clock/include/mod_css_clock.h +++ b/module/css_clock/include/mod_css_clock.h @@ -150,7 +150,7 @@ struct mod_css_clock_direct_api { * \param new_state The power state that the clock's power domain will * transition to. * - * \retval FWK_SUCCESS The operation succeeded. + * \retval ::FWK_SUCCESS The operation succeeded. * \return One of the standard framework error codes. */ int (*process_pending_power_transition)( @@ -177,7 +177,7 @@ struct mod_css_clock_direct_api { * \param state The power state that the clock's power domain transitioned * to. * - * \retval FWK_SUCCESS The operation succeeded. + * \retval ::FWK_SUCCESS The operation succeeded. * \return One of the standard framework error codes. */ int (*process_power_transition)(fwk_id_t clock_id, unsigned int state); diff --git a/module/debug/include/mod_debug.h b/module/debug/include/mod_debug.h index 2aeec8f4..46482b4f 100644 --- a/module/debug/include/mod_debug.h +++ b/module/debug/include/mod_debug.h @@ -85,11 +85,11 @@ struct mod_debug_api { * * \param user_id The user requesting the Debug functionality. * - * \retval FWK_SUCCESS The operation succeeded. - * \retval FWK_PENDING The operation has been acknowledged. - * \retval FWK_E_PARAM One or more parameters were incorrect. - * \retval FWK_E_BUSY Another request is already being processed. - * \retval FWK_E_ACCESS The specified user doesn't have the permission to + * \retval ::FWK_SUCCESS The operation succeeded. + * \retval ::FWK_PENDING The operation has been acknowledged. + * \retval ::FWK_E_PARAM One or more parameters were incorrect. + * \retval ::FWK_E_BUSY Another request is already being processed. + * \retval ::FWK_E_ACCESS The specified user doesn't have the permission to * perform the requested action. * \return One of the standard framework error codes. */ @@ -105,11 +105,11 @@ struct mod_debug_api { * * \param user_id The user requesting the Debug enabled status. * - * \retval FWK_SUCCESS The operation succeeded. - * \retval FWK_PENDING The operation has been acknowledged. - * \retval FWK_E_PARAM One or more parameters were incorrect. - * \retval FWK_E_BUSY Another request is already being processed. - * \retval FWK_E_ACCESS The specified user doesn't have the permission to + * \retval ::FWK_SUCCESS The operation succeeded. + * \retval ::FWK_PENDING The operation has been acknowledged. + * \retval ::FWK_E_PARAM One or more parameters were incorrect. + * \retval ::FWK_E_BUSY Another request is already being processed. + * \retval ::FWK_E_ACCESS The specified user doesn't have the permission to * perform the requested action. * \return One of the standard framework error codes. */ @@ -120,7 +120,7 @@ struct mod_debug_api { * * \param id Debug device identifier. * - * \retval FWK_E_SUPPORT The operation is not supported. + * \retval ::FWK_E_SUPPORT The operation is not supported. * \return One of the standard framework error codes. */ int (*reset)(fwk_id_t id); @@ -130,7 +130,7 @@ struct mod_debug_api { * * \param id Debug device identifier. * - * \retval FWK_E_SUPPORT The operation is not supported. + * \retval ::FWK_E_SUPPORT The operation is not supported. * \return One of the standard framework error codes. */ int (*end)(fwk_id_t id); @@ -150,9 +150,9 @@ struct mod_debug_driver_api { * * \param user_id The user requesting the Debug driver functionality. * - * \retval FWK_SUCCESS The operation succeeded. - * \retval FWK_PENDING The operation has been acknowledged. - * \retval FWK_E_BUSY Another request is already being processed. + * \retval ::FWK_SUCCESS The operation succeeded. + * \retval ::FWK_PENDING The operation has been acknowledged. + * \retval ::FWK_E_BUSY Another request is already being processed. * \return One of the standard framework error codes. */ int (*set_enabled)(fwk_id_t id, bool enable, enum scp_debug_user user_id); @@ -167,9 +167,9 @@ struct mod_debug_driver_api { * * \param user_id The user requesting the Debug driver enabled status. * - * \retval FWK_SUCCESS The operation succeeded. - * \retval FWK_PENDING The operation has been acknowledged. - * \retval FWK_E_BUSY Another request is already being processed. + * \retval ::FWK_SUCCESS The operation succeeded. + * \retval ::FWK_PENDING The operation has been acknowledged. + * \retval ::FWK_E_BUSY Another request is already being processed. * \return One of the standard framework error codes. */ int (*get_enabled)(fwk_id_t id, bool *enabled, enum scp_debug_user user_id); @@ -204,7 +204,7 @@ struct mod_debug_driver_input_api { * * \param user_id The requesting user. * - * \retval FWK_SUCCESS The operation succeeded. + * \retval ::FWK_SUCCESS The operation succeeded. * \return One of the standard framework error codes. */ int (*enable)(fwk_id_t id, bool enable, enum scp_debug_user user_id); diff --git a/module/dmc500/include/mod_dmc500.h b/module/dmc500/include/mod_dmc500.h index 7e19a01f..8c73b548 100644 --- a/module/dmc500/include/mod_dmc500.h +++ b/module/dmc500/include/mod_dmc500.h @@ -529,7 +529,7 @@ struct mod_dmc_ddr_phy_api { * \param element_id Element identifier corresponding to the device to * configure. * - * \retval FWK_SUCCESS if the operation succeed. + * \retval ::FWK_SUCCESS if the operation succeed. * \return one of the error code otherwise. */ int (*configure)(fwk_id_t element_id); diff --git a/module/dmc620/include/mod_dmc620.h b/module/dmc620/include/mod_dmc620.h index 27a5e109..255e42cd 100644 --- a/module/dmc620/include/mod_dmc620.h +++ b/module/dmc620/include/mod_dmc620.h @@ -636,7 +636,7 @@ struct mod_dmc_ddr_phy_api { * \param element_id Element identifier corresponding to the device to * configure. * - * \retval FWK_SUCCESS if the operation succeed. + * \retval ::FWK_SUCCESS if the operation succeed. * \return one of the error code otherwise. */ int (*configure)(fwk_id_t element_id); diff --git a/module/fip/include/mod_fip.h b/module/fip/include/mod_fip.h index b54a6663..de6d8341 100644 --- a/module/fip/include/mod_fip.h +++ b/module/fip/include/mod_fip.h @@ -86,10 +86,11 @@ struct mod_fip_api { * \param type FIP ToC entry type. * \param[out] entry Updated if the type of entry requested is found. - * \retval FWK_SUCCESS Entry found and \p entry updated. - * \retval FWK_E_INIT Underlying storage could not be parsed (during init). - * \retval FWK_E_RANGE No entry of type \p type could be located. - * \retval FWK_E_DATA FIP ToC corrupted or otherwise not usable on this + * \retval ::FWK_SUCCESS Entry found and \p entry updated. + * \retval ::FWK_E_INIT Underlying storage could not be parsed (during + * init). + * \retval ::FWK_E_RANGE No entry of type \p type could be located. + * \retval ::FWK_E_DATA FIP ToC corrupted or otherwise not usable on this * platform. */ int (*get_entry)( diff --git a/module/i2c/include/mod_i2c.h b/module/i2c/include/mod_i2c.h index 273c456f..cd381c19 100644 --- a/module/i2c/include/mod_i2c.h +++ b/module/i2c/include/mod_i2c.h @@ -107,9 +107,9 @@ struct mod_i2c_driver_api { * \param dev_id Identifier of the I2C device * \param transmit_request Request information for the I2C transmission * - * \retval FWK_PENDING The request was submitted. - * \retval FWK_SUCCESS The request was successfully completed. - * \retval FWK_E_PARAM One or more parameters were invalid. + * \retval ::FWK_PENDING The request was submitted. + * \retval ::FWK_SUCCESS The request was successfully completed. + * \retval ::FWK_E_PARAM One or more parameters were invalid. * \return One of the standard framework status codes. */ int (*transmit_as_master)( @@ -126,9 +126,9 @@ struct mod_i2c_driver_api { * \param dev_id Identifier of the I2C device * \param receive_request Request information for the I2C reception * - * \retval FWK_PENDING The request was submitted. - * \retval FWK_SUCCESS The request was successfully completed. - * \retval FWK_E_PARAM One or more parameters were invalid. + * \retval ::FWK_PENDING The request was submitted. + * \retval ::FWK_SUCCESS The request was successfully completed. + * \retval ::FWK_E_PARAM One or more parameters were invalid. * \return One of the standard framework status codes. */ int (*receive_as_master)( @@ -153,10 +153,10 @@ struct mod_i2c_api { * \param data Pointer to the data bytes to transmit to the slave * \param byte_count Number of data bytes to transmit * - * \retval FWK_PENDING The request was submitted. - * \retval FWK_E_PARAM One or more parameters were invalid. - * \retval FWK_E_BUSY An I2C transaction is already on-going. - * \retval FWK_E_DEVICE The transmission is aborted due to a device error. + * \retval ::FWK_PENDING The request was submitted. + * \retval ::FWK_E_PARAM One or more parameters were invalid. + * \retval ::FWK_E_BUSY An I2C transaction is already on-going. + * \retval ::FWK_E_DEVICE The transmission is aborted due to a device error. * \return One of the standard framework status codes. */ int (*transmit_as_master)(fwk_id_t dev_id, uint8_t slave_address, @@ -176,10 +176,10 @@ struct mod_i2c_api { * \param data Pointer to the buffer to receive data from the slave * \param byte_count Number of data bytes to receive * - * \retval FWK_PENDING The request was submitted. - * \retval FWK_E_PARAM One or more parameters were invalid. - * \retval FWK_E_BUSY An I2C transaction is already on-going. - * \retval FWK_E_DEVICE The reception is aborted due to a device error. + * \retval ::FWK_PENDING The request was submitted. + * \retval ::FWK_E_PARAM One or more parameters were invalid. + * \retval ::FWK_E_BUSY An I2C transaction is already on-going. + * \retval ::FWK_E_DEVICE The reception is aborted due to a device error. * \return One of the standard framework status codes. */ int (*receive_as_master)(fwk_id_t dev_id, uint8_t slave_address, @@ -206,10 +206,10 @@ struct mod_i2c_api { * \param receive_byte_count Number of data bytes to receive in the second * phase. * - * \retval FWK_PENDING The request was submitted. - * \retval FWK_E_PARAM One or more parameters were invalid. - * \retval FWK_E_BUSY An I2C transaction is already on-going. - * \retval FWK_E_DEVICE The reception is aborted due to a device error. + * \retval ::FWK_PENDING The request was submitted. + * \retval ::FWK_E_PARAM One or more parameters were invalid. + * \retval ::FWK_E_BUSY An I2C transaction is already on-going. + * \retval ::FWK_E_DEVICE The reception is aborted due to a device error. * \return One of the standard framework status codes. */ int (*transmit_then_receive_as_master)(fwk_id_t dev_id, diff --git a/module/power_domain/include/mod_power_domain.h b/module/power_domain/include/mod_power_domain.h index 1dada0a6..b725aa37 100644 --- a/module/power_domain/include/mod_power_domain.h +++ b/module/power_domain/include/mod_power_domain.h @@ -294,8 +294,8 @@ struct mod_pd_driver_api { * \param dev_id Driver identifier of the power domain. * \param state Power state the power domain has to be put into. * - * \retval FWK_SUCCESS The power state has been successfully set. - * \retval FWK_E_ACCESS Invalid access, the framework has rejected the + * \retval ::FWK_SUCCESS The power state has been successfully set. + * \retval ::FWK_E_ACCESS Invalid access, the framework has rejected the * call to the API. * \return One of the other specific error codes described by the driver * module. @@ -312,8 +312,8 @@ struct mod_pd_driver_api { * \param dev_id Driver identifier of the power domain. * \param[out] state Power state of the power domain. * - * \retval FWK_SUCCESS The power state was successfully returned. - * \retval FWK_E_ACCESS Invalid access, the framework has rejected the + * \retval ::FWK_SUCCESS The power state was successfully returned. + * \retval ::FWK_E_ACCESS Invalid access, the framework has rejected the * call to the API. */ int (*get_state)(fwk_id_t dev_id, unsigned int *state); @@ -327,8 +327,8 @@ struct mod_pd_driver_api { * * \param dev_id Driver identifier of the power domain. * - * \retval FWK_SUCCESS The power domain was successfully reset. - * \retval FWK_E_ACCESS Invalid access, the framework has rejected the + * \retval ::FWK_SUCCESS The power domain was successfully reset. + * \retval ::FWK_E_ACCESS Invalid access, the framework has rejected the * call to the API. * \return One of the other specific error codes described by the module. */ @@ -370,8 +370,8 @@ struct mod_pd_driver_api { * * \param dev_id Driver identifier of the power domain. * - * \retval FWK_SUCCESS The core has been successfully prepared. - * \retval FWK_E_ACCESS Invalid access, the framework has rejected the + * \retval ::FWK_SUCCESS The core has been successfully prepared. + * \retval ::FWK_E_ACCESS Invalid access, the framework has rejected the * call to the API. */ int (*prepare_core_for_system_suspend)(fwk_id_t dev_id); @@ -387,10 +387,10 @@ struct mod_pd_driver_api { * \param dev_id Driver identifier of the power domain. * \param system_shutdown Type of system shutdown. * - * \retval FWK_SUCCESS The operation succeeded. - * \retval FWK_PENDING The operation was acknowledged. Please note that at + * \retval ::FWK_SUCCESS The operation succeeded. + * \retval ::FWK_PENDING The operation was acknowledged. Please note that at * present there is no dedicated driver input api for this case. - * \retval FWK_E_ACCESS Invalid access, the framework has rejected the + * \retval ::FWK_E_ACCESS Invalid access, the framework has rejected the * call to the API. */ int (*shutdown)(fwk_id_t dev_id, @@ -412,11 +412,11 @@ struct mod_pd_public_api { * queried for. * \param[out] type Type of the power domain. * - * \retval FWK_SUCCESS The type of the power domain was returned. - * \retval FWK_E_INIT The module has not been initialized. - * \retval FWK_E_STATE The power domain module is in an invalid state. - * \retval FWK_E_PARAM The power domain identifier is unknown. - * \retval FWK_E_PARAM The pointer 'type' is equal to NULL. + * \retval ::FWK_SUCCESS The type of the power domain was returned. + * \retval ::FWK_E_INIT The module has not been initialized. + * \retval ::FWK_E_STATE The power domain module is in an invalid state. + * \retval ::FWK_E_PARAM The power domain identifier is unknown. + * \retval ::FWK_E_PARAM The pointer 'type' is equal to NULL. */ int (*get_domain_type)(fwk_id_t pd_id, enum mod_pd_type *type); @@ -429,12 +429,12 @@ struct mod_pd_public_api { * \param pd_id Identifier of the power domain. * \param[out] parent_pd_id Identifier of the parent power domain. * - * \retval FWK_SUCCESS The identifier of the parent power domain was + * \retval ::FWK_SUCCESS The identifier of the parent power domain was * returned. - * \retval FWK_E_INIT The module has not been initialized. - * \retval FWK_E_STATE The power domain module is in an invalid state. - * \retval FWK_E_PARAM The power domain identifier is unknown. - * \retval FWK_E_PARAM The pointer 'parent_pd_id' is equal to NULL. + * \retval ::FWK_E_INIT The module has not been initialized. + * \retval ::FWK_E_STATE The power domain module is in an invalid state. + * \retval ::FWK_E_PARAM The power domain identifier is unknown. + * \retval ::FWK_E_PARAM The pointer 'parent_pd_id' is equal to NULL. */ int (*get_domain_parent_id)(fwk_id_t pd_id, fwk_id_t *parent_pd_id); }; @@ -455,11 +455,11 @@ struct mod_pd_restricted_api { * queried for. * \param[out] type Type of the power domain. * - * \retval FWK_SUCCESS The type of the power domain was returned. - * \retval FWK_E_INIT The module has not been initialized. - * \retval FWK_E_STATE The power domain module is in an invalid state. - * \retval FWK_E_PARAM The power domain identifier is unknown. - * \retval FWK_E_PARAM The pointer 'type' is equal to NULL. + * \retval ::FWK_SUCCESS The type of the power domain was returned. + * \retval ::FWK_E_INIT The module has not been initialized. + * \retval ::FWK_E_STATE The power domain module is in an invalid state. + * \retval ::FWK_E_PARAM The power domain identifier is unknown. + * \retval ::FWK_E_PARAM The pointer 'type' is equal to NULL. */ int (*get_domain_type)(fwk_id_t pd_id, enum mod_pd_type *type); @@ -472,12 +472,12 @@ struct mod_pd_restricted_api { * \param pd_id Identifier of the power domain. * \param[out] parent_pd_id The identifier of the parent power domain. * - * \retval FWK_SUCCESS The identifier of the parent power domain was + * \retval ::FWK_SUCCESS The identifier of the parent power domain was * returned. - * \retval FWK_E_INIT The module has not been initialized. - * \retval FWK_E_STATE The power domain module is in an invalid state. - * \retval FWK_E_PARAM The power domain identifier is unknown. - * \retval FWK_E_PARAM The pointer 'parent_pd_id' is equal to NULL. + * \retval ::FWK_E_INIT The module has not been initialized. + * \retval ::FWK_E_STATE The power domain module is in an invalid state. + * \retval ::FWK_E_PARAM The power domain identifier is unknown. + * \retval ::FWK_E_PARAM The pointer 'parent_pd_id' is equal to NULL. */ int (*get_domain_parent_id)(fwk_id_t pd_id, fwk_id_t *parent_pd_id); @@ -497,11 +497,11 @@ struct mod_pd_restricted_api { * and the children of the power domain involved are in a state where * the transition can be completed. * - * \retval FWK_SUCCESS The power state transition was completed. - * \retval FWK_E_ACCESS Invalid access, the framework has rejected the + * \retval ::FWK_SUCCESS The power state transition was completed. + * \retval ::FWK_E_ACCESS Invalid access, the framework has rejected the * call to the API. - * \retval FWK_E_HANDLER The function is not called from a thread. - * \retval FWK_E_PARAM One or more parameters were invalid. + * \retval ::FWK_E_HANDLER The function is not called from a thread. + * \retval ::FWK_E_PARAM One or more parameters were invalid. */ int (*set_state)(fwk_id_t pd_id, uint32_t state); @@ -523,10 +523,10 @@ struct mod_pd_restricted_api { * and the children of the power domain involved are in a state where * the transition can be completed. * - * \retval FWK_SUCCESS The power state transition was submitted. - * \retval FWK_E_ACCESS Invalid access, the framework has rejected the + * \retval ::FWK_SUCCESS The power state transition was submitted. + * \retval ::FWK_E_ACCESS Invalid access, the framework has rejected the * call to the API. - * \retval FWK_E_PARAM One or more parameters were invalid. + * \retval ::FWK_E_PARAM One or more parameters were invalid. */ int (*set_state_async)(fwk_id_t pd_id, bool resp_requested, uint32_t state); @@ -537,12 +537,12 @@ struct mod_pd_restricted_api { * retrieved. * \param[out] state The power domain state. * - * \retval FWK_SUCCESS The power state was returned. - * \retval FWK_E_ACCESS Invalid access, the framework has rejected the + * \retval ::FWK_SUCCESS The power state was returned. + * \retval ::FWK_E_ACCESS Invalid access, the framework has rejected the * call to the API. - * \retval FWK_E_HANDLER The function is not called from a thread. - * \retval FWK_E_PARAM The power domain identifier is unknown. - * \retval FWK_E_PARAM The pointer 'state' is equal to NULL. + * \retval ::FWK_E_HANDLER The function is not called from a thread. + * \retval ::FWK_E_PARAM The power domain identifier is unknown. + * \retval ::FWK_E_PARAM The pointer 'state' is equal to NULL. */ int (*get_state)(fwk_id_t pd_id, unsigned int *state); @@ -554,12 +554,12 @@ struct mod_pd_restricted_api { * * \param pd_id Identifier of the power domain to reset. * - * \retval FWK_SUCCESS Power state retrieving request transmitted. - * \retval FWK_E_ACCESS Invalid access, the framework has rejected the + * \retval ::FWK_SUCCESS Power state retrieving request transmitted. + * \retval ::FWK_E_ACCESS Invalid access, the framework has rejected the * call to the API. - * \retval FWK_E_HANDLER The function is not called from a thread. - * \retval FWK_E_NOMEM Failed to allocate a request descriptor. - * \retval FWK_E_PARAM The power domain identifier is unknown. + * \retval ::FWK_E_HANDLER The function is not called from a thread. + * \retval ::FWK_E_NOMEM Failed to allocate a request descriptor. + * \retval ::FWK_E_PARAM The power domain identifier is unknown. */ int (*reset)(fwk_id_t pd_id); @@ -574,14 +574,14 @@ struct mod_pd_restricted_api { * \param state State the system has to be suspended to. The definition * of those states is platform specific. * - * \retval FWK_SUCCESS The system suspension has been initiated + * \retval ::FWK_SUCCESS The system suspension has been initiated * successfully. - * \retval FWK_E_ACCESS Invalid access, the framework has rejected the + * \retval ::FWK_E_ACCESS Invalid access, the framework has rejected the * call to the API. - * \retval FWK_E_HANDLER The function is not called from a thread. - * \retval FWK_E_NOMEM Failed to allocate a request descriptor. - * \retval FWK_E_PARAM Invalid state. - * \retval FWK_E_STATE The system is not in the proper state to be + * \retval ::FWK_E_HANDLER The function is not called from a thread. + * \retval ::FWK_E_NOMEM Failed to allocate a request descriptor. + * \retval ::FWK_E_PARAM Invalid state. + * \retval ::FWK_E_STATE The system is not in the proper state to be * suspended. */ int (*system_suspend)(unsigned int state); @@ -592,12 +592,12 @@ struct mod_pd_restricted_api { * \note The function shutdowns the system whatever its current state. If * the shutdown is successful, the function does not return. * - * \retval FWK_E_ACCESS Invalid access, the framework has rejected the + * \retval ::FWK_E_ACCESS Invalid access, the framework has rejected the * call to the API. - * \retval FWK_PENDING Request aknowledged. A response event will not be + * \retval ::FWK_PENDING Request aknowledged. A response event will not be * sent to the caller. - * \retval FWK_E_HANDLER The function is not called from a thread. - * \retval FWK_E_NOMEM Failed to allocate a request descriptor. + * \retval ::FWK_E_HANDLER The function is not called from a thread. + * \retval ::FWK_E_NOMEM Failed to allocate a request descriptor. */ int (*system_shutdown)(enum mod_pd_system_shutdown system_shutdown); }; @@ -628,10 +628,10 @@ struct mod_pd_driver_input_api { * and the children of the power domain involved are in a state where * the transition can be completed. * - * \retval FWK_SUCCESS The composite power state transition was submitted. - * \retval FWK_E_ACCESS Invalid access, the framework has rejected the + * \retval ::FWK_SUCCESS The composite power state transition was submitted. + * \retval ::FWK_E_ACCESS Invalid access, the framework has rejected the * call to the API. - * \retval FWK_E_PARAM One or more parameters were invalid. + * \retval ::FWK_E_PARAM One or more parameters were invalid. */ int (*set_state_async)( fwk_id_t pd_id, @@ -650,12 +650,12 @@ struct mod_pd_driver_input_api { * \param resp_requested True if the caller wants to be notified with an * event response at the end of the request processing. * - * \retval FWK_SUCCESS Reset request transmitted. - * \retval FWK_E_ACCESS Invalid access, the framework has rejected the + * \retval ::FWK_SUCCESS Reset request transmitted. + * \retval ::FWK_E_ACCESS Invalid access, the framework has rejected the * call to the API. - * \retval FWK_E_HANDLER The function is not called from a thread. - * \retval FWK_E_NOMEM Failed to allocate a request descriptor. - * \retval FWK_E_PARAM The power domain identifier is unknown. + * \retval ::FWK_E_HANDLER The function is not called from a thread. + * \retval ::FWK_E_NOMEM Failed to allocate a request descriptor. + * \retval ::FWK_E_PARAM The power domain identifier is unknown. */ int (*reset_async)(fwk_id_t pd_id, bool resp_requested); @@ -669,11 +669,11 @@ struct mod_pd_driver_input_api { * \param pd_id Identifier of the power domain, a power state transition * report is is sent to. * - * \retval FWK_SUCCESS Report transmitted. - * \retval FWK_E_ACCESS Invalid access, the framework has rejected the call - * to the API. - * \retval FWK_E_NOMEM Failed to allocate a report event. - * \retval FWK_E_PARAM The power domain identifier is unknown. + * \retval ::FWK_SUCCESS Report transmitted. + * \retval ::FWK_E_ACCESS Invalid access, the framework has rejected the + * call to the API. + * \retval ::FWK_E_NOMEM Failed to allocate a report event. + * \retval ::FWK_E_PARAM The power domain identifier is unknown. */ int (*report_power_state_transition)(fwk_id_t pd_id, unsigned int state); @@ -693,8 +693,8 @@ struct mod_pd_driver_input_api { * * \param[out] last_core_pd_id Identifier of the last core. * - * \retval FWK_E_PARAM The pointer to the identifier is not valid. - * \retval FWK_SUCCESS The request was successful. + * \retval ::FWK_E_PARAM The pointer to the identifier is not valid. + * \retval ::FWK_SUCCESS The request was successful. * \return One of the standard framework error codes. */ int (*get_last_core_pd_id)(fwk_id_t *last_core_pd_id); diff --git a/module/power_domain/src/mod_power_domain.c b/module/power_domain/src/mod_power_domain.c index b8cd704a..9415f9a3 100644 --- a/module/power_domain/src/mod_power_domain.c +++ b/module/power_domain/src/mod_power_domain.c @@ -661,8 +661,8 @@ static bool initiate_power_state_pre_transition_notification(struct pd_ctx *pd) * \param pd Description of the power domain to initiate the state transition * for. * - * \retval FWK_SUCCESS The power state transition was initiated. - * \retval FWK_E_DEVICE The power state transition was denied by the driver. + * \retval ::FWK_SUCCESS The power state transition was initiated. + * \retval ::FWK_E_DEVICE The power state transition was denied by the driver. * \return One of the other driver-defined error codes. */ static int initiate_power_state_transition(struct pd_ctx *pd) diff --git a/module/ppu_v1/include/mod_ppu_v1.h b/module/ppu_v1/include/mod_ppu_v1.h index e67a21f8..f968a602 100644 --- a/module/ppu_v1/include/mod_ppu_v1.h +++ b/module/ppu_v1/include/mod_ppu_v1.h @@ -174,7 +174,7 @@ struct ppu_v1_boot_api { * * \param pd_id Identifier of the power domain * - * \retval FWK_SUCCESS Operation successful. + * \retval ::FWK_SUCCESS Operation successful. * \return One of the standard framework error codes. */ int (*power_mode_on)(fwk_id_t pd_id); diff --git a/module/reset_domain/include/mod_reset_domain.h b/module/reset_domain/include/mod_reset_domain.h index 48cfcf99..775fe9a2 100644 --- a/module/reset_domain/include/mod_reset_domain.h +++ b/module/reset_domain/include/mod_reset_domain.h @@ -139,7 +139,7 @@ struct mod_reset_domain_api { * \param mode Reset domain mode. * \param reset_state Reset domain state as defined in SCMIv2 specification. * \param cookie Context-specific value. - * \retval FWK_SUCCESS or one of FWK_E_* error codes. + * \retval ::FWK_SUCCESS or one of FWK_E_* error codes. */ int (*set_reset_state)(fwk_id_t element_id, enum mod_reset_domain_mode mode, @@ -162,7 +162,7 @@ struct mod_reset_domain_drv_api { * \param reset_state Reset domain state as defined in SCMIv2 specification. * * \param cookie Context-specific value. - * \retval FWK_SUCCESS or one of FWK_E_* error codes. + * \retval ::FWK_SUCCESS or one of FWK_E_* error codes. */ int (*set_reset_state)(fwk_id_t dev_id, enum mod_reset_domain_mode mode, diff --git a/module/resource_perms/include/mod_resource_perms.h b/module/resource_perms/include/mod_resource_perms.h index 8a3bd64a..ac2fefd4 100644 --- a/module/resource_perms/include/mod_resource_perms.h +++ b/module/resource_perms/include/mod_resource_perms.h @@ -408,9 +408,9 @@ struct mod_res_permissions_api { * \param device_id identifier of the device. * \param flags permissions to set. * - * \retval FWK_SUCCESS The operation has completed successfully. - * \retval FWK_E_ACCESS Unknown agent_id or device_id. - * \retval FWK_E_PARAM Invalid flags or protocol_ID. + * \retval ::FWK_SUCCESS The operation has completed successfully. + * \retval ::FWK_E_ACCESS Unknown agent_id or device_id. + * \retval ::FWK_E_PARAM Invalid flags or protocol_ID. */ int (*agent_set_device_permission)( uint32_t agent_id, @@ -425,9 +425,9 @@ struct mod_res_permissions_api { * \param device_id identifier of the protocol. * \param flags permissions to set. * - * \retval FWK_SUCCESS The operation has completed successfully. - * \retval FWK_E_ACCESS Unknown agent_id or device_id. - * \retval FWK_E_PARAM Invalid flags or protocol_ID. + * \retval ::FWK_SUCCESS The operation has completed successfully. + * \retval ::FWK_E_ACCESS Unknown agent_id or device_id. + * \retval ::FWK_E_PARAM Invalid flags or protocol_ID. */ int (*agent_set_device_protocol_permission)( uint32_t agent_id, @@ -441,9 +441,9 @@ struct mod_res_permissions_api { * \param agent_id identifier of the agent. * \param flags permissions to set. * - * \retval FWK_SUCCESS The operation has completed successfully. - * \retval FWK_E_ACCESS Unknown agent_id. - * \retval FWK_E_PARAM Invalid flags. + * \retval ::FWK_SUCCESS The operation has completed successfully. + * \retval ::FWK_E_ACCESS Unknown agent_id. + * \retval ::FWK_E_PARAM Invalid flags. */ int (*agent_reset_config)(uint32_t agent_id, uint32_t flags); }; diff --git a/module/scmi/include/mod_scmi.h b/module/scmi/include/mod_scmi.h index 21d9c019..39153824 100644 --- a/module/scmi/include/mod_scmi.h +++ b/module/scmi/include/mod_scmi.h @@ -165,9 +165,9 @@ struct mod_scmi_to_transport_api { * \param[out] secure Channel security state. True if the channel * is secure, or false if it is non-secure. * - * \retval FWK_SUCCESS The operation succeeded. - * \retval FWK_E_PARAM The channel_id parameter is invalid. - * \retval FWK_E_PARAM The secure parameter is NULL. + * \retval ::FWK_SUCCESS The operation succeeded. + * \retval ::FWK_E_PARAM The channel_id parameter is invalid. + * \retval ::FWK_E_PARAM The secure parameter is NULL. * \return One of the standard error codes for implementation-defined * errors. */ @@ -179,9 +179,9 @@ struct mod_scmi_to_transport_api { * \param channel_id Channel identifier. * \param[out] size Maximum payload size in bytes. * - * \retval FWK_SUCCESS The operation succeeded. - * \retval FWK_E_PARAM The channel_id parameter is invalid. - * \retval FWK_E_PARAM The size parameter is NULL. + * \retval ::FWK_SUCCESS The operation succeeded. + * \retval ::FWK_E_PARAM The channel_id parameter is invalid. + * \retval ::FWK_E_PARAM The size parameter is NULL. * \return One of the standard error codes for implementation-defined * errors. */ @@ -193,10 +193,10 @@ struct mod_scmi_to_transport_api { * \param channel_id Channel identifier. * \param[out] message_header SCMI message header. * - * \retval FWK_SUCCESS The operation succeeded. - * \retval FWK_E_PARAM The channel_id parameter is invalid. - * \retval FWK_E_PARAM The message_header parameter is NULL. - * \retval FWK_E_ACCESS No message is available to read. + * \retval ::FWK_SUCCESS The operation succeeded. + * \retval ::FWK_E_PARAM The channel_id parameter is invalid. + * \retval ::FWK_E_PARAM The message_header parameter is NULL. + * \retval ::FWK_E_ACCESS No message is available to read. * \return One of the standard error codes for implementation-defined * errors. */ @@ -210,10 +210,10 @@ struct mod_scmi_to_transport_api { * \param[out] size Payload size. May be NULL, in which case the * parameter should be ignored. * - * \retval FWK_SUCCESS The operation succeeded. - * \retval FWK_E_PARAM The channel_id parameter is invalid. - * \retval FWK_E_PARAM The payload parameter is NULL. - * \retval FWK_E_ACCESS No message is available to read. + * \retval ::FWK_SUCCESS The operation succeeded. + * \retval ::FWK_E_PARAM The channel_id parameter is invalid. + * \retval ::FWK_E_PARAM The payload parameter is NULL. + * \retval ::FWK_E_ACCESS No message is available to read. * \return One of the standard error codes for implementation-defined * errors. */ @@ -228,9 +228,9 @@ struct mod_scmi_to_transport_api { * \param payload Payload data to write. * \param size Size of the payload data. * - * \retval FWK_SUCCESS The operation succeeded. - * \retval FWK_E_PARAM The payload parameter is NULL. - * \retval FWK_E_PARAM The offset and size provided are not within the + * \retval ::FWK_SUCCESS The operation succeeded. + * \retval ::FWK_E_PARAM The payload parameter is NULL. + * \retval ::FWK_E_PARAM The offset and size provided are not within the * bounds of the payload area. * \return One of the standard error codes for implementation-defined * errors. @@ -246,11 +246,11 @@ struct mod_scmi_to_transport_api { * been written. * \param size Size of the payload source. * - * \retval FWK_SUCCESS The operation succeeded. - * \retval FWK_E_PARAM The channel_id parameter is invalid. - * \retval FWK_E_PARAM The size parameter is less than the size of one + * \retval ::FWK_SUCCESS The operation succeeded. + * \retval ::FWK_E_PARAM The channel_id parameter is invalid. + * \retval ::FWK_E_PARAM The size parameter is less than the size of one * payload entry. - * \retval FWK_E_ACCESS No message is available to respond to. + * \retval ::FWK_E_ACCESS No message is available to respond to. * \return One of the standard error codes for implementation-defined * errors. */ @@ -264,9 +264,9 @@ struct mod_scmi_to_transport_api { * \param payload Payload data to write. * \param size Size of the payload source. * - * \retval FWK_SUCCESS The operation succeeded. - * \retval FWK_E_PARAM The channel_id parameter is invalid. - * \retval FWK_E_PARAM The size parameter is less than the size of one + * \retval ::FWK_SUCCESS The operation succeeded. + * \retval ::FWK_E_PARAM The channel_id parameter is invalid. + * \retval ::FWK_E_PARAM The size parameter is less than the size of one * payload entry. * \return One of the standard error codes for implementation-defined * errors. @@ -289,8 +289,8 @@ struct mod_scmi_from_transport_api { * * \param service_id service identifier. * - * \retval FWK_SUCCESS The operation succeeded. - * \retval FWK_E_PARAM The service_id parameter is invalid. + * \retval ::FWK_SUCCESS The operation succeeded. + * \retval ::FWK_E_PARAM The service_id parameter is invalid. * \return One of the standard error codes for implementation-defined * errors. */ @@ -301,9 +301,9 @@ struct mod_scmi_from_transport_api { * * \param service_id SCMI service identifier. * - * \retval FWK_SUCCESS The operation succeeded. - * \retval FWK_E_PARAM The channel_id parameter is invalid. - * \retval FWK_E_PARAM The secure parameter is NULL. + * \retval ::FWK_SUCCESS The operation succeeded. + * \retval ::FWK_E_PARAM The channel_id parameter is invalid. + * \retval ::FWK_E_PARAM The secure parameter is NULL. * \return One of the standard error codes for implementation-defined * errors. */ @@ -329,7 +329,7 @@ struct mod_scmi_from_transport_api { * \param message_id Identifier of the message to be handled by the protocol * handler. * - * \retval FWK_SUCCESS The operation succeeded. + * \retval ::FWK_SUCCESS The operation succeeded. * \return One of the standard error codes for implementation-defined errors. * */ @@ -348,7 +348,7 @@ struct mod_scmi_to_protocol_api { * \param protocol_id Identifier of the protocol module. * \param scmi_protocol_id SCMI protocol identifier. * - * \retval FWK_SUCCESS The operation succeeded. + * \retval ::FWK_SUCCESS The operation succeeded. * \return One of the standard error codes for implementation-defined * errors. * @@ -373,7 +373,7 @@ struct mod_scmi_notification_api { * \param element_count Number of elements that support notification. * \param operation_count Number of notification SCMI messages supported. * - * \retval FWK_SUCCESS Initialization successful. + * \retval ::FWK_SUCCESS Initialization successful. * \retval One of the standard error codes for implementation-defined * errors. */ @@ -392,9 +392,10 @@ struct mod_scmi_notification_api { * \param operation_id Identifier of the operation. * \param service_id Identifier of the agent's SCMI service context. * - * \retval FWK_SUCCESS Adding of subscriber agent to the list is successful. + * \retval ::FWK_SUCCESS Adding of subscriber agent to the list is + * successful. * \retval One of the standard error codes for implementation-defined - * errors. + * errors. */ int (*scmi_notification_add_subscriber)( unsigned int protocol_id, @@ -411,7 +412,7 @@ struct mod_scmi_notification_api { * context. * \param operation_id Identifier of the operation. * - * \retval FWK_SUCCESS Removing of subscriber agent from the list is + * \retval ::FWK_SUCCESS Removing of subscriber agent from the list is * successful. * \retval One of the standard error codes for implementation-defined * errors. @@ -433,7 +434,7 @@ struct mod_scmi_notification_api { * agent. * \param payload_size Size of the message. * - * \retval FWK_SUCCESS Notification to agents is successful. + * \retval ::FWK_SUCCESS Notification to agents is successful. * \retval One of the standard error codes for implementation-defined * errors. */ @@ -455,10 +456,10 @@ struct mod_scmi_from_protocol_api { * * \param[out] agent_count Number of active agents. * - * \retval FWK_SUCCESS The agent count was returned. - * \retval FWK_E_PARAM The parameter `agent_count` is equal to `NULL`. + * \retval ::FWK_SUCCESS The agent count was returned. + * \retval ::FWK_E_PARAM The parameter `agent_count` is equal to `NULL`. */ - int (*get_agent_count)(int *agent_count); + int (*get_agent_count)(int *agent_count); /*! * \brief Get the identifier of the agent associated with a service @@ -466,13 +467,13 @@ struct mod_scmi_from_protocol_api { * \param service_id Identifier of the service. * \param[out] agent_id Agent identifier. * - * \retval FWK_SUCCESS The agent identifier was returned. - * \retval FWK_E_PARAM The service identifier is not valid. - * \retval FWK_E_PARAM The parameter 'agent_id' is equal to NULL. - * \retval FWK_E_INIT The service is not initialized. - * \retval FWK_E_STATE The service is in an invalid state. + * \retval ::FWK_SUCCESS The agent identifier was returned. + * \retval ::FWK_E_PARAM The service identifier is not valid. + * \retval ::FWK_E_PARAM The parameter 'agent_id' is equal to NULL. + * \retval ::FWK_E_INIT The service is not initialized. + * \retval ::FWK_E_STATE The service is in an invalid state. */ - int (*get_agent_id)(fwk_id_t service_id, unsigned int *agent_id); + int (*get_agent_id)(fwk_id_t service_id, unsigned int *agent_id); /*! * \brief Get the type of the agent given its identifier. @@ -483,12 +484,11 @@ struct mod_scmi_from_protocol_api { * \param agent_id Identifier of the agent. * \param[out] agent_type Agent type. * - * \retval FWK_SUCCESS The agent identifier was returned. - * \retval FWK_E_PARAM The agent identifier is not valid. - * \retval FWK_E_PARAM The parameter 'agent_type' is equal to NULL. + * \retval ::FWK_SUCCESS The agent identifier was returned. + * \retval ::FWK_E_PARAM The agent identifier is not valid. + * \retval ::FWK_E_PARAM The parameter 'agent_type' is equal to NULL. */ - int (*get_agent_type)(uint32_t agent_id, - enum scmi_agent_type *agent_type); + int (*get_agent_type)(uint32_t agent_id, enum scmi_agent_type *agent_type); /*! * \brief Get the maximum permitted payload size of a channel associated @@ -497,11 +497,11 @@ struct mod_scmi_from_protocol_api { * \param service_id Service identifier. * \param[out] size Maximum payload size in bytes. * - * \retval FWK_SUCCESS The operation succeeded. - * \retval FWK_E_PARAM The service_id parameter is invalid. - * \retval FWK_E_PARAM The size parameter is NULL. - * \retval FWK_E_INIT The service is not initialized. - * \retval FWK_E_STATE The service is in an invalid sate. + * \retval ::FWK_SUCCESS The operation succeeded. + * \retval ::FWK_E_PARAM The service_id parameter is invalid. + * \retval ::FWK_E_PARAM The size parameter is NULL. + * \retval ::FWK_E_INIT The service is not initialized. + * \retval ::FWK_E_STATE The service is in an invalid sate. * \return One of the standard error codes for implementation-defined * errors. */ @@ -515,9 +515,9 @@ struct mod_scmi_from_protocol_api { * \param payload Payload data to write. * \param size Size of the payload data. * - * \retval FWK_SUCCESS The operation succeeded. - * \retval FWK_E_PARAM The payload parameter is NULL. - * \retval FWK_E_PARAM The offset and size provided are not within the + * \retval ::FWK_SUCCESS The operation succeeded. + * \retval ::FWK_E_PARAM The payload parameter is NULL. + * \retval ::FWK_E_PARAM The offset and size provided are not within the * bounds of the payload area. * \return One of the standard error codes for implementation-defined * errors. diff --git a/module/sds/include/mod_sds.h b/module/sds/include/mod_sds.h index 6005b203..84aa30f5 100644 --- a/module/sds/include/mod_sds.h +++ b/module/sds/include/mod_sds.h @@ -170,10 +170,10 @@ struct mod_sds_api { * * \param size Size, in bytes, of the data to be written. * - * \retval FWK_SUCCESS Data was successfully written to the structure. - * \retval FWK_E_PARAM The data pointer parameter was NULL. - * \retval FWK_E_PARAM An invalid structure identifier was provided. - * \retval FWK_E_RANGE The field extends outside of the structure bounds. + * \retval ::FWK_SUCCESS Data was successfully written to the structure. + * \retval ::FWK_E_PARAM The data pointer parameter was NULL. + * \retval ::FWK_E_PARAM An invalid structure identifier was provided. + * \retval ::FWK_E_RANGE The field extends outside of the structure bounds. */ int (*struct_write)(uint32_t structure_id, unsigned int offset, const void *data, size_t size); @@ -204,10 +204,10 @@ struct mod_sds_api { * \param size Size, in bytes, of the storage pointed to by the data * parameter. * - * \retval FWK_SUCCESS Data was successfully read from the structure. - * \retval FWK_E_PARAM The data pointer parameter was NULL. - * \retval FWK_E_PARAM An invalid structure identifier was provided. - * \retval FWK_E_RANGE The field extends outside of the structure bounds. + * \retval ::FWK_SUCCESS Data was successfully read from the structure. + * \retval ::FWK_E_PARAM The data pointer parameter was NULL. + * \retval ::FWK_E_PARAM An invalid structure identifier was provided. + * \retval ::FWK_E_RANGE The field extends outside of the structure bounds. */ int (*struct_read)(uint32_t structure_id, unsigned int offset, void *data, size_t size); @@ -219,9 +219,9 @@ struct mod_sds_api { * \param structure_id The identifier of the Shared Data Structure to * finalize. * - * \retval FWK_SUCCESS The structure was successfully finalized. - * \retval FWK_E_PARAM An invalid structure identifier was provided. - * \retval FWK_E_STATE The structure has already been finalized. + * \retval ::FWK_SUCCESS The structure was successfully finalized. + * \retval ::FWK_E_PARAM An invalid structure identifier was provided. + * \retval ::FWK_E_STATE The structure has already been finalized. */ int (*struct_finalize)(uint32_t structure_id); }; diff --git a/module/sensor/include/mod_sensor.h b/module/sensor/include/mod_sensor.h index 5e39d7c9..94ec3d70 100644 --- a/module/sensor/include/mod_sensor.h +++ b/module/sensor/include/mod_sensor.h @@ -180,9 +180,9 @@ struct mod_sensor_driver_api { * \param id Specific sensor device id. * \param[out] value Sensor value. * - * \retval FWK_PENDING The request is pending. The driver will provide the + * \retval ::FWK_PENDING The request is pending. The driver will provide the * requested value later through the driver response API. - * \retval FWK_SUCCESS Value was read successfully. + * \retval ::FWK_SUCCESS Value was read successfully. * \return One of the standard framework error codes. */ int (*get_value)(fwk_id_t id, uint64_t *value); @@ -193,7 +193,7 @@ struct mod_sensor_driver_api { * \param id Specific sensor device id. * \param[out] info The sensor information. * - * \retval FWK_SUCCESS The information was read successfully. + * \retval ::FWK_SUCCESS The information was read successfully. * \return One of the standard framework error codes. */ int (*get_info)(fwk_id_t id, struct mod_sensor_info *info); @@ -211,11 +211,11 @@ struct mod_sensor_api { * \param id Specific sensor device id. * \param[out] value The sensor value. * - * \retval FWK_SUCCESS Operation succeeded. - * \retval FWK_E_DEVICE Driver error. - * \retval FWK_E_BUSY At least one reading of the sensor value is already + * \retval ::FWK_SUCCESS Operation succeeded. + * \retval ::FWK_E_DEVICE Driver error. + * \retval ::FWK_E_BUSY At least one reading of the sensor value is already * on-going. - * \retval FWK_PENDING The request is pending. The requested value will be + * \retval ::FWK_PENDING The request is pending. The requested value will be * provided via a response event. * \return One of the standard framework error codes. */ @@ -229,8 +229,8 @@ struct mod_sensor_api { * \param id Specific sensor device id. * \param[out] info The information structure. * - * \retval FWK_SUCCESS Operation succeeded. - * \retval FWK_E_DEVICE Driver error. + * \retval ::FWK_SUCCESS Operation succeeded. + * \retval ::FWK_E_DEVICE Driver error. * \return One of the standard framework error codes. */ int (*get_info)(fwk_id_t id, struct mod_sensor_info *info); diff --git a/module/sid/include/mod_sid.h b/module/sid/include/mod_sid.h index f17824a1..cfa2779a 100644 --- a/module/sid/include/mod_sid.h +++ b/module/sid/include/mod_sid.h @@ -101,8 +101,8 @@ struct mod_sid_subsystem_config { * * \param[out] system_info Pointer to the system information data. * - * \retval FWK_SUCCESS The pointer was returned successfully. - * \retval FWK_E_INIT The system information is not initialized. + * \retval ::FWK_SUCCESS The pointer was returned successfully. + * \retval ::FWK_E_INIT The system information is not initialized. */ int mod_sid_get_system_info(const struct mod_sid_info **system_info); diff --git a/module/smt/include/mod_smt.h b/module/smt/include/mod_smt.h index 893f96e1..9850a4fd 100644 --- a/module/smt/include/mod_smt.h +++ b/module/smt/include/mod_smt.h @@ -93,8 +93,8 @@ struct mod_smt_driver_api { * * \param device_id Device identifier * - * \retval FWK_SUCCESS The operation succeeded - * \retval FWK_E_PARAM The device_id parameter is invalid + * \retval ::FWK_SUCCESS The operation succeeded + * \retval ::FWK_E_PARAM The device_id parameter is invalid * \return One of the standard error codes for implementation-defined * errors */ @@ -112,7 +112,7 @@ struct mod_smt_driver_input_api { * * \param device_id Channel identifier * - * \retval FWK_SUCCESS The operation succeeded. + * \retval ::FWK_SUCCESS The operation succeeded. * \return One of the standard error codes for implementation-defined * errors. */ @@ -131,9 +131,9 @@ struct mod_smt_to_transport_api { * \param[out] secure Channel security state. True if the channel * is secure, or false if it is non-secure. * - * \retval FWK_SUCCESS The operation succeeded. - * \retval FWK_E_PARAM The channel_id parameter is invalid. - * \retval FWK_E_PARAM The secure parameter is NULL. + * \retval ::FWK_SUCCESS The operation succeeded. + * \retval ::FWK_E_PARAM The channel_id parameter is invalid. + * \retval ::FWK_E_PARAM The secure parameter is NULL. * \return One of the standard error codes for implementation-defined * errors. */ @@ -145,9 +145,9 @@ struct mod_smt_to_transport_api { * \param channel_id Channel identifier. * \param[out] size Maximum payload size in bytes. * - * \retval FWK_SUCCESS The operation succeeded. - * \retval FWK_E_PARAM The channel_id parameter is invalid. - * \retval FWK_E_PARAM The size parameter is NULL. + * \retval ::FWK_SUCCESS The operation succeeded. + * \retval ::FWK_E_PARAM The channel_id parameter is invalid. + * \retval ::FWK_E_PARAM The size parameter is NULL. * \return One of the standard error codes for implementation-defined * errors. */ @@ -159,10 +159,10 @@ struct mod_smt_to_transport_api { * \param channel_id Channel identifier. * \param[out] message_header Pointer to the message header. * - * \retval FWK_SUCCESS The operation succeeded. - * \retval FWK_E_PARAM The channel_id parameter is invalid. - * \retval FWK_E_PARAM The message_header parameter is NULL. - * \retval FWK_E_ACCESS No message is available to read. + * \retval ::FWK_SUCCESS The operation succeeded. + * \retval ::FWK_E_PARAM The channel_id parameter is invalid. + * \retval ::FWK_E_PARAM The message_header parameter is NULL. + * \retval ::FWK_E_ACCESS No message is available to read. * \return One of the standard error codes for implementation-defined * errors. */ @@ -176,10 +176,10 @@ struct mod_smt_to_transport_api { * \param[out] size Payload size. May be NULL, in which case the * parameter should be ignored. * - * \retval FWK_SUCCESS The operation succeeded. - * \retval FWK_E_PARAM The channel_id parameter is invalid. - * \retval FWK_E_PARAM The payload parameter is NULL. - * \retval FWK_E_ACCESS No message is available to read. + * \retval ::FWK_SUCCESS The operation succeeded. + * \retval ::FWK_E_PARAM The channel_id parameter is invalid. + * \retval ::FWK_E_PARAM The payload parameter is NULL. + * \retval ::FWK_E_ACCESS No message is available to read. * \return One of the standard error codes for implementation-defined * errors. */ @@ -194,9 +194,9 @@ struct mod_smt_to_transport_api { * \param payload Payload data to write. * \param size Size of the payload data. * - * \retval FWK_SUCCESS The operation succeeded. - * \retval FWK_E_PARAM The payload parameter is NULL. - * \retval FWK_E_PARAM The offset and size provided are not within the + * \retval ::FWK_SUCCESS The operation succeeded. + * \retval ::FWK_E_PARAM The payload parameter is NULL. + * \retval ::FWK_E_PARAM The offset and size provided are not within the * bounds of the payload area. * \return One of the standard error codes for implementation-defined * errors. @@ -212,11 +212,11 @@ struct mod_smt_to_transport_api { * been written. * \param size Size of the payload source. * - * \retval FWK_SUCCESS The operation succeeded. - * \retval FWK_E_PARAM The channel_id parameter is invalid. - * \retval FWK_E_PARAM The size parameter is less than the size of one + * \retval ::FWK_SUCCESS The operation succeeded. + * \retval ::FWK_E_PARAM The channel_id parameter is invalid. + * \retval ::FWK_E_PARAM The size parameter is less than the size of one * payload entry. - * \retval FWK_E_ACCESS No message is available to respond to. + * \retval ::FWK_E_ACCESS No message is available to respond to. * \return One of the standard error codes for implementation-defined * errors. */ @@ -234,8 +234,8 @@ struct mod_smt_from_transport_api { * * \param service_id service identifier. * - * \retval FWK_SUCCESS The operation succeeded. - * \retval FWK_E_PARAM The service_id parameter is invalid. + * \retval ::FWK_SUCCESS The operation succeeded. + * \retval ::FWK_E_PARAM The service_id parameter is invalid. * \return One of the standard error codes for implementation-defined * errors. */ @@ -246,9 +246,9 @@ struct mod_smt_from_transport_api { * * \param service_id Service identifier. * - * \retval FWK_SUCCESS The operation succeeded. - * \retval FWK_E_PARAM The channel_id parameter is invalid. - * \retval FWK_E_PARAM The secure parameter is NULL. + * \retval ::FWK_SUCCESS The operation succeeded. + * \retval ::FWK_E_PARAM The channel_id parameter is invalid. + * \retval ::FWK_E_PARAM The secure parameter is NULL. * \return One of the standard error codes for implementation-defined * errors. */ diff --git a/module/system_info/include/mod_system_info.h b/module/system_info/include/mod_system_info.h index ef5870e5..02889e78 100644 --- a/module/system_info/include/mod_system_info.h +++ b/module/system_info/include/mod_system_info.h @@ -101,8 +101,8 @@ struct mod_system_info_get_info_api { * * \param[out] sys_info Pointer to the system information data. * - * \retval FWK_SUCCESS if the sys_info pointer has been successfully set. - * \retval FWK_E_SUPPORT if the system information is not supported by the + * \retval ::FWK_SUCCESS if the sys_info pointer has been successfully set. + * \retval ::FWK_E_SUPPORT if the system information is not supported by the * product. */ int (*get_system_info)(const struct mod_system_info **sys_info); diff --git a/module/timer/include/mod_timer.h b/module/timer/include/mod_timer.h index 45e0a522..daa1282b 100644 --- a/module/timer/include/mod_timer.h +++ b/module/timer/include/mod_timer.h @@ -122,8 +122,8 @@ struct mod_timer_api { * \param dev_id Element identifier that identifies the timer device. * \param[out] frequency The timer frequency. * - * \retval FWK_SUCCESS Operation succeeded. - * \retval FWK_E_PARAM The frequency pointer was invalid. + * \retval ::FWK_SUCCESS Operation succeeded. + * \retval ::FWK_E_PARAM The frequency pointer was invalid. * \retval One of the other specific error codes described by the framework. */ int (*get_frequency)(fwk_id_t dev_id, uint32_t *frequency); @@ -139,8 +139,8 @@ struct mod_timer_api { * \param microseconds Period, in microseconds. * \param[out] timestamp The resulting counter timestamp. * - * \retval FWK_SUCCESS Operation succeeded. - * \retval FWK_E_PARAM The timestamp pointer was invalid. + * \retval ::FWK_SUCCESS Operation succeeded. + * \retval ::FWK_E_PARAM The timestamp pointer was invalid. * \retval One of the other specific error codes described by the framework. */ int (*time_to_timestamp)(fwk_id_t dev_id, @@ -156,8 +156,8 @@ struct mod_timer_api { * \param dev_id Element identifier that identifies the timer device. * \param[out] counter The counter value. * - * \retval FWK_SUCCESS Operation succeeded. - * \retval FWK_E_PARAM The counter pointer was invalid. + * \retval ::FWK_SUCCESS Operation succeeded. + * \retval ::FWK_E_PARAM The counter pointer was invalid. * \retval One of the other specific error codes described by the framework. */ int (*get_counter)(fwk_id_t dev_id, uint64_t *counter); @@ -171,7 +171,7 @@ struct mod_timer_api { * \param dev_id Element identifier that identifies the timer device. * \param microseconds The amount of time, given in microseconds, to delay. * - * \retval FWK_SUCCESS Operation succeeded. + * \retval ::FWK_SUCCESS Operation succeeded. * \retval One of the other specific error codes described by the framework. */ int (*delay)(fwk_id_t dev_id, uint32_t microseconds); @@ -191,10 +191,10 @@ struct mod_timer_api { * or until the timeout period has elapsed. * \param data Pointer passed to the condition function when it is called. * - * \retval FWK_SUCCESS The condition was met before the timeout period + * \retval ::FWK_SUCCESS The condition was met before the timeout period * elapsed. - * \retval FWK_E_TIMEOUT The timeout period elapsed before the condition was - * met. + * \retval ::FWK_E_TIMEOUT The timeout period elapsed before the condition + * was met. * \retval One of the other specific error codes described by the framework. */ int (*wait)(fwk_id_t dev_id, @@ -215,8 +215,8 @@ struct mod_timer_api { * \param[out] remaining_ticks The remaining number of ticks before * the timer value reaches the given timestamp. * - * \retval FWK_SUCCESS Operation succeeded. - * \retval FWK_E_PARAM The remaining_ticks pointer was invalid. + * \retval ::FWK_SUCCESS Operation succeeded. + * \retval ::FWK_E_PARAM The remaining_ticks pointer was invalid. * \retval One of the other specific error codes described by the framework. * * \note remaining_ticks is also a timestamp. @@ -238,8 +238,8 @@ struct mod_timer_api { * \param [out] remaining_ticks Number of ticks between now and the next * alarm trigger of the timer identified by \p dev_id. * - * \retval FWK_SUCCESS Operation succeeded. - * \retval FWK_E_PARAM One of the parameters is invalid. + * \retval ::FWK_SUCCESS Operation succeeded. + * \retval ::FWK_E_PARAM One of the parameters is invalid. * \return One of the other specific error codes described by the framework. */ int (*get_next_alarm_remaining)(fwk_id_t dev_id, @@ -277,9 +277,9 @@ struct mod_timer_alarm_api { * \pre \p alarm_id must be a valid sub-element alarm identifier that has * previously been bound to. * - * \retval FWK_E_ACCESS The function was called from an interrupt handler + * \retval ::FWK_E_ACCESS The function was called from an interrupt handler * OR could not attain call context. - * \retval FWK_SUCCESS The alarm was started. + * \retval ::FWK_SUCCESS The alarm was started. */ int (*start)(fwk_id_t alarm_id, unsigned int milliseconds, @@ -299,12 +299,12 @@ struct mod_timer_alarm_api { * \pre \p alarm_id must be a valid sub-element alarm identifier that has * previously been bound to. * - * \retval FWK_SUCCESS The alarm was stopped. - * \retval FWK_E_STATE The alarm was already stopped. - * \retval FWK_E_ACCESS The function was called from an interrupt handler + * \retval ::FWK_SUCCESS The alarm was stopped. + * \retval ::FWK_E_STATE The alarm was already stopped. + * \retval ::FWK_E_ACCESS The function was called from an interrupt handler * different from the interrupt handler of the timer the alarm is * associated to OR could not attain call context. - * \retval FWK_E_INIT The component has not been initialized. + * \retval ::FWK_E_INIT The component has not been initialized. */ int (*stop)(fwk_id_t alarm_id); }; |