chore(xilinx): follow kernel doc format for functional documentation
For TF-A, there is no format specified for functional documentation.
For AMD-Xilinx platforms, following kernel-doc format for the functional
documentation to make sure AMD-xilinx documentation is align with
actual code.
For example use kernel-doc from linux to call:
<linux>/scripts/kernel-doc -man -v 1 >/dev/null file...
Signed-off-by: Prasad Kummari <prasad.kummari@amd.com>
Change-Id: Idcc9def408b6c8da35b36f67ef82fc00890e998c
diff --git a/plat/xilinx/zynqmp/pm_service/pm_api_ioctl.c b/plat/xilinx/zynqmp/pm_service/pm_api_ioctl.c
index afd664e..1880d9b 100644
--- a/plat/xilinx/zynqmp/pm_service/pm_api_ioctl.c
+++ b/plat/xilinx/zynqmp/pm_service/pm_api_ioctl.c
@@ -23,12 +23,13 @@
#include "zynqmp_pm_api_sys.h"
/**
- * pm_ioctl_get_rpu_oper_mode () - Get current RPU operation mode
- * @mode Buffer to store value of oper mode(Split/Lock-step)
+ * pm_ioctl_get_rpu_oper_mode () - Get current RPU operation mode.
+ * @mode: Buffer to store value of oper mode(Split/Lock-step)
*
* This function provides current configured RPU operational mode.
*
- * @return Returns status, either success or error+reason
+ * Return: Returns status, either success or error+reason.
+ *
*/
static enum pm_ret_status pm_ioctl_get_rpu_oper_mode(uint32_t *mode)
{
@@ -46,15 +47,16 @@
}
/**
- * pm_ioctl_set_rpu_oper_mode () - Configure RPU operation mode
- * @mode Value to set for oper mode(Split/Lock-step)
+ * pm_ioctl_set_rpu_oper_mode () - Configure RPU operation mode.
+ * @mode: Value to set for oper mode(Split/Lock-step).
*
* This function configures RPU operational mode(Split/Lock-step).
* It also sets TCM combined mode in RPU lock-step and TCM non-combined
* mode for RPU split mode. In case of Lock step mode, RPU1's output is
* clamped.
*
- * @return Returns status, either success or error+reason
+ * Return: Returns status, either success or error+reason.
+ *
*/
static enum pm_ret_status pm_ioctl_set_rpu_oper_mode(uint32_t mode)
{
@@ -84,13 +86,14 @@
}
/**
- * pm_ioctl_config_boot_addr() - Configure RPU boot address
- * @nid Node ID of RPU
- * @value Value to set for boot address (TCM/OCM)
+ * pm_ioctl_config_boot_addr() - Configure RPU boot address.
+ * @nid: Node ID of RPU.
+ * @value: Value to set for boot address (TCM/OCM).
*
* This function configures RPU boot address(memory).
*
+ * Return: Returns status, either success or error+reason.
+ *
- * @return Returns status, either success or error+reason
*/
static enum pm_ret_status pm_ioctl_config_boot_addr(enum pm_node_id nid,
uint32_t value)
@@ -121,13 +124,14 @@
}
/**
- * pm_ioctl_config_tcm_comb() - Configure TCM combined mode
- * @value Value to set (Split/Combined)
+ * pm_ioctl_config_tcm_comb() - Configure TCM combined mode.
+ * @value: Value to set (Split/Combined).
*
* This function configures TCM to be in split mode or combined
* mode.
*
- * @return Returns status, either success or error+reason
+ * Return: Returns status, either success or error+reason.
+ *
*/
static enum pm_ret_status pm_ioctl_config_tcm_comb(uint32_t value)
{
@@ -149,13 +153,14 @@
}
/**
- * pm_ioctl_set_tapdelay_bypass() - Enable/Disable tap delay bypass
- * @type Type of tap delay to enable/disable (e.g. QSPI)
- * @value Enable/Disable
+ * pm_ioctl_set_tapdelay_bypass() - Enable/Disable tap delay bypass.
+ * @type: Type of tap delay to enable/disable (e.g. QSPI).
+ * @value: Enable/Disable.
*
* This function enable/disable tap delay bypass.
*
- * @return Returns status, either success or error+reason
+ * Return: Returns status, either success or error+reason.
+ *
*/
static enum pm_ret_status pm_ioctl_set_tapdelay_bypass(uint32_t type,
uint32_t value)
@@ -169,15 +174,16 @@
}
/**
- * pm_ioctl_set_sgmii_mode() - Set SGMII mode for the GEM device
- * @nid Node ID of the device
- * @value Enable/Disable
+ * pm_ioctl_set_sgmii_mode() - Set SGMII mode for the GEM device.
+ * @nid: Node ID of the device.
+ * @value: Enable/Disable.
*
* This function enable/disable SGMII mode for the GEM device.
* While enabling SGMII mode, it also ties the GEM PCS Signal
* Detect to 1 and selects EMIO for RX clock generation.
*
+ * Return: Returns status, either success or error+reason.
+ *
- * @return Returns status, either success or error+reason
*/
static enum pm_ret_status pm_ioctl_set_sgmii_mode(enum pm_node_id nid,
uint32_t value)
@@ -229,13 +235,14 @@
}
/**
- * pm_ioctl_sd_dll_reset() - Reset DLL logic
- * @nid Node ID of the device
- * @type Reset type
+ * pm_ioctl_sd_dll_reset() - Reset DLL logic.
+ * @nid: Node ID of the device.
+ * @type: Reset type.
*
* This function resets DLL logic for the SD device.
*
- * @return Returns status, either success or error+reason
+ * Return: Returns status, either success or error+reason.
+ *
*/
static enum pm_ret_status pm_ioctl_sd_dll_reset(enum pm_node_id nid,
uint32_t type)
@@ -278,14 +285,15 @@
}
/**
- * pm_ioctl_sd_set_tapdelay() - Set tap delay for the SD device
- * @nid Node ID of the device
- * @type Type of tap delay to set (input/output)
- * @value Value to set fot the tap delay
+ * pm_ioctl_sd_set_tapdelay() - Set tap delay for the SD device.
+ * @nid: Node ID of the device.
+ * @type: Type of tap delay to set (input/output).
+ * @value: Value to set fot the tap delay.
*
* This function sets input/output tap delay for the SD device.
*
- * @return Returns status, either success or error+reason
+ * Return: Returns status, either success or error+reason.
+ *
*/
static enum pm_ret_status pm_ioctl_sd_set_tapdelay(enum pm_node_id nid,
enum tap_delay_type type,
@@ -375,14 +383,14 @@
}
/**
- * pm_ioctl_set_pll_frac_mode() - Ioctl function for
- * setting pll mode
- * @pll PLL clock id
- * @mode Mode fraction/integar
+ * pm_ioctl_set_pll_frac_mode() - Ioctl function for setting pll mode.
+ * @pll: PLL clock id.
+ * @mode: Mode fraction/integar.
+ *
+ * This function sets PLL mode.
*
- * This function sets PLL mode
+ * Return: Returns status, either success or error+reason.
*
- * @return Returns status, either success or error+reason
*/
static enum pm_ret_status pm_ioctl_set_pll_frac_mode
(uint32_t pll, uint32_t mode)
@@ -391,14 +399,14 @@
}
/**
- * pm_ioctl_get_pll_frac_mode() - Ioctl function for
- * getting pll mode
- * @pll PLL clock id
- * @mode Mode fraction/integar
+ * pm_ioctl_get_pll_frac_mode() - Ioctl function for getting pll mode.
+ * @pll: PLL clock id.
+ * @mode: Mode fraction/integar.
*
- * This function return current PLL mode
+ * This function return current PLL mode.
*
- * @return Returns status, either success or error+reason
+ * Return: Returns status, either success or error+reason.
+ *
*/
static enum pm_ret_status pm_ioctl_get_pll_frac_mode
(uint32_t pll, uint32_t *mode)
@@ -407,15 +415,15 @@
}
/**
- * pm_ioctl_set_pll_frac_data() - Ioctl function for
- * setting pll fraction data
- * @pll PLL clock id
- * @data fraction data
+ * pm_ioctl_set_pll_frac_data() - Ioctl function for setting pll fraction data.
+ * @pll: PLL clock id.
+ * @data: fraction data.
*
* This function sets fraction data.
* It is valid for fraction mode only.
*
- * @return Returns status, either success or error+reason
+ * Return: Returns status, either success or error+reason.
+ *
*/
static enum pm_ret_status pm_ioctl_set_pll_frac_data
(uint32_t pll, uint32_t data)
@@ -433,14 +441,14 @@
}
/**
- * pm_ioctl_get_pll_frac_data() - Ioctl function for
- * getting pll fraction data
- * @pll PLL clock id
- * @data fraction data
+ * pm_ioctl_get_pll_frac_data() - Ioctl function for getting pll fraction data.
+ * @pll: PLL clock id.
+ * @data: fraction data.
*
* This function returns fraction data value.
*
- * @return Returns status, either success or error+reason
+ * Return: Returns status, either success or error+reason.
+ *
*/
static enum pm_ret_status pm_ioctl_get_pll_frac_data
(uint32_t pll, uint32_t *data)
@@ -458,14 +466,15 @@
}
/**
- * pm_ioctl_write_ggs() - Ioctl function for writing
- * global general storage (ggs)
- * @index GGS register index
- * @value Register value to be written
+ * pm_ioctl_write_ggs() - Ioctl function for writing global general storage
+ * (ggs).
+ * @index: GGS register index.
+ * @value: Register value to be written.
*
* This function writes value to GGS register.
*
- * @return Returns status, either success or error+reason
+ * Return: Returns status, either success or error+reason.
+ *
*/
static enum pm_ret_status pm_ioctl_write_ggs(uint32_t index,
uint32_t value)
@@ -479,14 +488,15 @@
}
/**
- * pm_ioctl_read_ggs() - Ioctl function for reading
- * global general storage (ggs)
- * @index GGS register index
- * @value Register value
+ * pm_ioctl_read_ggs() - Ioctl function for reading global general storage
+ * (ggs).
+ * @index: GGS register index.
+ * @value: Register value.
*
* This function returns GGS register value.
*
- * @return Returns status, either success or error+reason
+ * Return: Returns status, either success or error+reason.
+ *
*/
static enum pm_ret_status pm_ioctl_read_ggs(uint32_t index,
uint32_t *value)
@@ -499,14 +509,15 @@
}
/**
- * pm_ioctl_write_pggs() - Ioctl function for writing persistent
- * global general storage (pggs)
- * @index PGGS register index
- * @value Register value to be written
+ * pm_ioctl_write_pggs() - Ioctl function for writing persistent global general
+ * storage (pggs).
+ * @index: PGGS register index.
+ * @value: Register value to be written.
*
* This function writes value to PGGS register.
*
+ * Return: Returns status, either success or error+reason.
+ *
- * @return Returns status, either success or error+reason
*/
static enum pm_ret_status pm_ioctl_write_pggs(uint32_t index,
uint32_t value)
@@ -520,13 +531,12 @@
}
/**
- * pm_ioctl_afi() - Ioctl function for writing afi values
+ * pm_ioctl_afi() - Ioctl function for writing afi values.
+ * @index: AFI register index.
+ * @value: Register value to be written.
*
- * @index AFI register index
- * @value Register value to be written
+ * Return: Returns status, either success or error+reason.
*
- *
- * @return Returns status, either success or error+reason
*/
static enum pm_ret_status pm_ioctl_afi(uint32_t index,
uint32_t value)
@@ -564,14 +574,15 @@
}
/**
- * pm_ioctl_read_pggs() - Ioctl function for reading persistent
- * global general storage (pggs)
- * @index PGGS register index
- * @value Register value
+ * pm_ioctl_read_pggs() - Ioctl function for reading persistent global general
+ * storage (pggs).
+ * @index: PGGS register index.
+ * @value: Register value.
*
* This function returns PGGS register value.
*
- * @return Returns status, either success or error+reason
+ * Return: Returns status, either success or error+reason.
+ *
*/
static enum pm_ret_status pm_ioctl_read_pggs(uint32_t index,
uint32_t *value)
@@ -584,12 +595,12 @@
}
/**
- * pm_ioctl_ulpi_reset() - Ioctl function for performing ULPI reset
+ * pm_ioctl_ulpi_reset() - Ioctl function for performing ULPI reset.
+ *
+ * Return: Returns status, either success or error+reason.
*
* This function peerforms the ULPI reset sequence for resetting
* the ULPI transceiver.
- *
- * @return Returns status, either success or error+reason
*/
static enum pm_ret_status pm_ioctl_ulpi_reset(void)
{
@@ -620,12 +631,14 @@
}
/**
- * pm_ioctl_set_boot_health_status() - Ioctl for setting healthy boot status
+ * pm_ioctl_set_boot_health_status() - Ioctl for setting healthy boot status.
+ * @value: Value to write.
*
* This function sets healthy bit value to indicate boot health status
* to firmware.
*
- * @return Returns status, either success or error+reason
+ * Return: Returns status, either success or error+reason.
+ *
*/
static enum pm_ret_status pm_ioctl_set_boot_health_status(uint32_t value)
{
@@ -634,16 +647,17 @@
}
/**
- * pm_api_ioctl() - PM IOCTL API for device control and configs
- * @node_id Node ID of the device
- * @ioctl_id ID of the requested IOCTL
- * @arg1 Argument 1 to requested IOCTL call
- * @arg2 Argument 2 to requested IOCTL call
- * @value Returned output value
+ * pm_api_ioctl() - PM IOCTL API for device control and configs.
+ * @nid: Node ID of the device.
+ * @ioctl_id: ID of the requested IOCTL.
+ * @arg1: Argument 1 to requested IOCTL call.
+ * @arg2: Argument 2 to requested IOCTL call.
+ * @value: Returned output value.
*
* This function calls IOCTL to firmware for device control and configuration.
*
- * @return Returns status, either success or error+reason
+ * Return: Returns status, either success or error+reason.
+ *
*/
enum pm_ret_status pm_api_ioctl(enum pm_node_id nid,
uint32_t ioctl_id,
@@ -724,8 +738,11 @@
}
/**
- * pm_update_ioctl_bitmask() - API to get supported IOCTL ID mask
- * @bit_mask Returned bit mask of supported IOCTL IDs
+ * tfa_ioctl_bitmask() - API to get supported IOCTL ID mask.
+ * @bit_mask: Returned bit mask of supported IOCTL IDs.
+ *
+ * Return: 0 success, negative value for errors.
+ *
*/
enum pm_ret_status tfa_ioctl_bitmask(uint32_t *bit_mask)
{