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/versal_net/plat_psci_pm.c b/plat/xilinx/versal_net/plat_psci_pm.c
index d39fc2e..87e25bc 100644
--- a/plat/xilinx/versal_net/plat_psci_pm.c
+++ b/plat/xilinx/versal_net/plat_psci_pm.c
@@ -1,6 +1,6 @@
/*
* Copyright (c) 2022, Xilinx, Inc. All rights reserved.
- * Copyright (c) 2022, Advanced Micro Devices, Inc. All rights reserved.
+ * Copyright (c) 2022-2023, Advanced Micro Devices, Inc. All rights reserved.
*
* SPDX-License-Identifier: BSD-3-Clause
*/
@@ -50,9 +50,10 @@
}
/**
- * versal_net_pwr_domain_off() - This function performs actions to turn off core
+ * versal_net_pwr_domain_off() - This function performs actions to turn off
+ * core.
+ * @target_state: Targeted state.
*
- * @param target_state Targeted state
*/
static void versal_net_pwr_domain_off(const psci_power_state_t *target_state)
{
@@ -80,8 +81,10 @@
}
/**
- * versal_net_system_reset() - This function sends the reset request
- * to firmware for the system to reset. This function does not return.
+ * versal_net_system_reset() - This function sends the reset request to firmware
+ * for the system to reset. This function does not
+ * return.
+ *
*/
static void __dead2 versal_net_system_reset(void)
{
@@ -96,9 +99,9 @@
/**
* versal_net_pwr_domain_suspend() - This function sends request to PMC to suspend
- * core.
+ * core.
+ * @target_state: Targeted state.
*
- * @param target_state Targeted state
*/
static void versal_net_pwr_domain_suspend(const psci_power_state_t *target_state)
{
@@ -140,9 +143,9 @@
/**
* versal_net_pwr_domain_suspend_finish() - This function performs actions to finish
- * suspend procedure.
+ * suspend procedure.
+ * @target_state: Targeted state.
*
- * @param target_state Targeted state
*/
static void versal_net_pwr_domain_suspend_finish(const psci_power_state_t *target_state)
{
@@ -168,7 +171,8 @@
/**
* versal_net_system_off() - This function sends the system off request
- * to firmware. This function does not return.
+ * to firmware. This function does not return.
+ *
*/
static void __dead2 versal_net_system_off(void)
{
@@ -183,12 +187,12 @@
/**
* versal_net_validate_power_state() - This function ensures that the power state
- * parameter in request is valid.
+ * parameter in request is valid.
+ * @power_state: Power state of core.
+ * @req_state: Requested state.
*
- * @param power_state Power state of core
- * @param req_state Requested state
+ * Return: Returns status, either PSCI_E_SUCCESS or reason.
*
- * @return Returns status, either PSCI_E_SUCCESS or reason
*/
static int32_t versal_net_validate_power_state(unsigned int power_state,
psci_power_state_t *req_state)
@@ -215,9 +219,10 @@
}
/**
- * versal_net_get_sys_suspend_power_state() - Get power state for system suspend
+ * versal_net_get_sys_suspend_power_state() - Get power state for system
+ * suspend.
+ * @req_state: Requested state.
*
- * @param req_state Requested state
*/
static void versal_net_get_sys_suspend_power_state(psci_power_state_t *req_state)
{
diff --git a/plat/xilinx/versal_net/pm_service/pm_client.c b/plat/xilinx/versal_net/pm_service/pm_client.c
index 3387891..d09c927 100644
--- a/plat/xilinx/versal_net/pm_service/pm_client.c
+++ b/plat/xilinx/versal_net/pm_service/pm_client.c
@@ -152,10 +152,11 @@
const struct pm_proc *primary_proc = &pm_procs_all[0];
/**
- * pm_get_proc() - returns pointer to the proc structure
- * @param cpuid id of the cpu whose proc struct pointer should be returned
+ * pm_get_proc() - returns pointer to the proc structure.
+ * @cpuid: id of the cpu whose proc struct pointer should be returned.
*
- * @return pointer to a proc structure if proc is found, otherwise NULL
+ * Return: Pointer to a proc structure if proc is found, otherwise NULL.
+ *
*/
const struct pm_proc *pm_get_proc(uint32_t cpuid)
{
@@ -168,10 +169,11 @@
}
/**
- * irq_to_pm_node_idx - Get PM node index corresponding to the interrupt number
- * @irq: Interrupt number
+ * irq_to_pm_node_idx - Get PM node index corresponding to the interrupt number.
+ * @irq: Interrupt number.
*
- * Return: PM node index corresponding to the specified interrupt
+ * Return: PM node index corresponding to the specified interrupt.
+ *
*/
enum pm_device_node_idx irq_to_pm_node_idx(uint32_t irq)
{
@@ -295,14 +297,13 @@
}
/**
- * pm_client_suspend() - Client-specific suspend actions
- *
- * This function should contain any PU-specific actions
- * required prior to sending suspend request to PMU
- * Actions taken depend on the state system is suspending to.
+ * pm_client_suspend() - Client-specific suspend actions. This function
+ * should contain any PU-specific actions required
+ * prior to sending suspend request to PMU. Actions
+ * taken depend on the state system is suspending to.
+ * @proc: processor which need to suspend.
+ * @state: desired suspend state.
*
- * @param proc processor which need to suspend
- * @param state desired suspend state
*/
void pm_client_suspend(const struct pm_proc *proc, uint32_t state)
{
@@ -338,10 +339,11 @@
}
/**
- * pm_get_cpuid() - get the local cpu ID for a global node ID
- * @param nid node id of the processor
+ * pm_get_cpuid() - get the local cpu ID for a global node ID.
+ * @nid: node id of the processor.
*
- * @return the cpu ID (starting from 0) for the subsystem
+ * Return: the cpu ID (starting from 0) for the subsystem.
+ *
*/
static uint32_t pm_get_cpuid(uint32_t nid)
{
@@ -354,12 +356,12 @@
}
/**
- * pm_client_wakeup() - Client-specific wakeup actions
+ * pm_client_wakeup() - Client-specific wakeup actions.
+ * @proc: Processor which need to wakeup.
*
* This function should contain any PU-specific actions
- * required for waking up another APU core
+ * required for waking up another APU core.
*
- * @param proc Processor which need to wakeup
*/
void pm_client_wakeup(const struct pm_proc *proc)
{
@@ -393,10 +395,11 @@
}
/**
- * pm_client_abort_suspend() - Client-specific abort-suspend actions
+ * pm_client_abort_suspend() - Client-specific abort-suspend actions.
*
* This function should contain any PU-specific actions
- * required for aborting a prior suspend request
+ * required for aborting a prior suspend request.
+ *
*/
void pm_client_abort_suspend(void)
{
diff --git a/plat/xilinx/versal_net/sip_svc_setup.c b/plat/xilinx/versal_net/sip_svc_setup.c
index f6240f3..0c27dec 100644
--- a/plat/xilinx/versal_net/sip_svc_setup.c
+++ b/plat/xilinx/versal_net/sip_svc_setup.c
@@ -43,6 +43,9 @@
/**
* sip_svc_setup() - Setup SiP Service
+ *
+ * Return: 0 on success, negative error code on failure.
+ *
*/
static int32_t sip_svc_setup(void)
{
diff --git a/plat/xilinx/versal_net/versal_net_ipi.c b/plat/xilinx/versal_net/versal_net_ipi.c
index ed3f2bb..0943c62 100644
--- a/plat/xilinx/versal_net/versal_net_ipi.c
+++ b/plat/xilinx/versal_net/versal_net_ipi.c
@@ -65,10 +65,10 @@
},
};
-/* versal_net_ipi_config_table_init() - Initialize versal_net IPI configuration data
- *
- * @ipi_config_table - IPI configuration table
- * @ipi_total - Total number of IPI available
+/* versal_net_ipi_config_table_init() - Initialize versal_net IPI configuration
+ * data.
+ * @ipi_config_table: IPI configuration table.
+ * @ipi_total: Total number of IPI available.
*
*/
void versal_net_ipi_config_table_init(void)