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/plat_psci.c b/plat/xilinx/versal/plat_psci.c
index b901e3d..1bc30f1 100644
--- a/plat/xilinx/versal/plat_psci.c
+++ b/plat/xilinx/versal/plat_psci.c
@@ -1,5 +1,6 @@
/*
* Copyright (c) 2018-2021, Arm Limited and Contributors. All rights reserved.
+ * Copyright (c) 2022-2023, Advanced Micro Devices, Inc. All rights reserved.
*
* SPDX-License-Identifier: BSD-3-Clause
*/
@@ -44,9 +45,9 @@
/**
* versal_pwr_domain_suspend() - This function sends request to PMC to suspend
- * core.
+ * core.
+ * @target_state: Targated state.
*
- * @target_state Targated state
*/
static void versal_pwr_domain_suspend(const psci_power_state_t *target_state)
{
@@ -81,9 +82,9 @@
/**
* versal_pwr_domain_suspend_finish() - This function performs actions to finish
- * suspend procedure.
+ * suspend procedure.
+ * @target_state: Targated state.
*
- * @target_state Targated state
*/
static void versal_pwr_domain_suspend_finish(
const psci_power_state_t *target_state)
@@ -120,8 +121,9 @@
}
/**
- * versal_system_off() - This function sends the system off request
- * to firmware. This function does not return.
+ * versal_system_off() - This function sends the system off request to firmware.
+ * This function does not return.
+ *
*/
static void __dead2 versal_system_off(void)
{
@@ -135,8 +137,10 @@
}
/**
- * versal_system_reset() - This function sends the reset request
- * to firmware for the system to reset. This function does not return.
+ * versal_system_reset() - This function sends the reset request to firmware
+ * for the system to reset. This function does not
+ * return.
+ *
*/
static void __dead2 versal_system_reset(void)
{
@@ -150,9 +154,9 @@
}
/**
- * versal_pwr_domain_off() - This function performs actions to turn off core
+ * versal_pwr_domain_off() - This function performs actions to turn off core.
+ * @target_state: Targated state.
*
- * @target_state Targated state
*/
static void versal_pwr_domain_off(const psci_power_state_t *target_state)
{
@@ -181,12 +185,12 @@
/**
* versal_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.
*
- * @power_state Power state of core
- * @req_state Requested state
+ * Return: Returns status, either success or reason.
*
- * @return Returns status, either success or reason
*/
static int32_t versal_validate_power_state(uint32_t power_state,
psci_power_state_t *req_state)
@@ -213,9 +217,9 @@
}
/**
- * versal_get_sys_suspend_power_state() - Get power state for system suspend
+ * versal_get_sys_suspend_power_state() - Get power state for system suspend.
+ * @req_state: Requested state.
*
- * @req_state Requested state
*/
static void versal_get_sys_suspend_power_state(psci_power_state_t *req_state)
{
diff --git a/plat/xilinx/versal/pm_service/pm_client.c b/plat/xilinx/versal/pm_service/pm_client.c
index af5263d..9ad21a1 100644
--- a/plat/xilinx/versal/pm_service/pm_client.c
+++ b/plat/xilinx/versal/pm_service/pm_client.c
@@ -51,10 +51,11 @@
const struct pm_proc *primary_proc = &pm_procs_all[0];
/**
- * 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)
{
@@ -172,11 +173,14 @@
}
/**
- * pm_client_suspend() - Client-specific suspend actions
+ * pm_client_suspend() - Client-specific suspend actions.
+ * @proc: processor which need to suspend.
+ * @state: desired suspend state.
*
* 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.
+ *
*/
void pm_client_suspend(const struct pm_proc *proc, uint32_t state)
{
@@ -194,10 +198,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)
{
@@ -214,10 +219,11 @@
}
/**
- * pm_get_cpuid() - get the local cpu ID for a global node ID
- * @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)
{
@@ -230,10 +236,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.
+ *
*/
void pm_client_wakeup(const struct pm_proc *proc)
{
@@ -254,10 +262,11 @@
}
/**
- * pm_get_proc() - returns pointer to the proc structure
- * @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)
{
diff --git a/plat/xilinx/versal/sip_svc_setup.c b/plat/xilinx/versal/sip_svc_setup.c
index 35118a7..b30254d 100644
--- a/plat/xilinx/versal/sip_svc_setup.c
+++ b/plat/xilinx/versal/sip_svc_setup.c
@@ -1,5 +1,6 @@
/*
* Copyright (c) 2018-2021, Arm Limited and Contributors. All rights reserved.
+ * Copyright (c) 2022-2023, Advanced Micro Devices, Inc. All rights reserved.
*
* SPDX-License-Identifier: BSD-3-Clause
*/
@@ -40,7 +41,9 @@
/**
* sip_svc_setup() - Setup SiP Service
*
- * Invokes PM setup
+ * Return: 0 on success,negative error code on failure.
+ *
+ * Invokes PM setup.
*/
static int32_t sip_svc_setup(void)
{
@@ -51,10 +54,20 @@
}
/**
- * sip_svc_smc_handler() - Top-level SiP Service SMC handler
+ * sip_svc_smc_handler() - Top-level SiP Service SMC handler.
+ * @smc_fid: Function Identifier.
+ * @x1: SMC64 Arguments 1 from kernel.
+ * @x2: SMC64 Arguments 2 from kernel.
+ * @x3: SMC64 Arguments 3 from kernel(upper 32-bits).
+ * @x4: SMC64 Arguments 4 from kernel.
+ * @cookie: Unused
+ * @handle: Pointer to caller's context structure.
+ * @flags: SECURE_FLAG or NON_SECURE_FLAG.
*
* Handler for all SiP SMC calls. Handles standard SIP requests
* and calls PM SMC handler if the call is for a PM-API function.
+ *
+ * Return: Unused.
*/
uintptr_t sip_svc_smc_handler(uint32_t smc_fid,
u_register_t x1,
diff --git a/plat/xilinx/versal/versal_ipi.c b/plat/xilinx/versal/versal_ipi.c
index 51eb759..80a2e83 100644
--- a/plat/xilinx/versal/versal_ipi.c
+++ b/plat/xilinx/versal/versal_ipi.c
@@ -65,10 +65,9 @@
},
};
-/* versal_ipi_config_table_init() - Initialize versal IPI configuration data
- *
- * @ipi_config_table - IPI configuration table
- * @ipi_total - Total number of IPI available
+/* versal_ipi_config_table_init() - Initialize versal IPI configuration data.
+ * @ipi_config_table: IPI configuration table.
+ * @ipi_total: Total number of IPI available.
*
*/
void versal_ipi_config_table_init(void)