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/common/pm_service/pm_svc_main.c b/plat/xilinx/common/pm_service/pm_svc_main.c
index 1bd2192..bae369e 100644
--- a/plat/xilinx/common/pm_service/pm_svc_main.c
+++ b/plat/xilinx/common/pm_service/pm_svc_main.c
@@ -84,13 +84,13 @@
}
/**
- * pm_register_sgi() - PM register the IPI interrupt
+ * pm_register_sgi() - PM register the IPI interrupt.
+ * @sgi_num: SGI number to be used for communication.
+ * @reset: Reset to invalid SGI when reset=1.
*
- * @sgi - SGI number to be used for communication.
- * @reset - Reset to invalid SGI when reset=1.
- * @return On success, the initialization function must return 0.
- * Any other return value will cause the framework to ignore
- * the service
+ * Return: On success, the initialization function must return 0.
+ * Any other return value will cause the framework to ignore
+ * the service.
*
* Update the SGI number to be used.
*
@@ -115,17 +115,18 @@
}
/**
- * pm_setup() - PM service setup
+ * pm_setup() - PM service setup.
*
- * @return On success, the initialization function must return 0.
- * Any other return value will cause the framework to ignore
- * the service
+ * Return: On success, the initialization function must return 0.
+ * Any other return value will cause the framework to ignore
+ * the service.
*
* Initialization functions for Versal power management for
* communicaton with PMC.
*
* Called from sip_svc_setup initialization function with the
* rt_svc_init signature.
+ *
*/
int32_t pm_setup(void)
{
@@ -152,14 +153,19 @@
}
/**
- * eemi_for_compatibility() - EEMI calls handler for deprecated calls
+ * eemi_for_compatibility() - EEMI calls handler for deprecated calls.
+ * @api_id: identifier for the API being called.
+ * @pm_arg: pointer to the argument data for the API call.
+ * @handle: Pointer to caller's context structure.
+ * @security_flag: SECURE_FLAG or NON_SECURE_FLAG.
*
- * @return - If EEMI API found then, uintptr_t type address, else 0
+ * Return: If EEMI API found then, uintptr_t type address, else 0.
*
* Some EEMI API's use case needs to be changed in Linux driver, so they
* can take advantage of common EEMI handler in TF-A. As of now the old
* implementation of these APIs are required to maintain backward compatibility
* until their use case in linux driver changes.
+ *
*/
static uintptr_t eemi_for_compatibility(uint32_t api_id, uint32_t *pm_arg,
void *handle, uint32_t security_flag)
@@ -214,14 +220,21 @@
}
/**
- * eemi_psci_debugfs_handler() - EEMI API invoked from PSCI
+ * eemi_psci_debugfs_handler() - EEMI API invoked from PSCI.
+ * @api_id: identifier for the API being called.
+ * @pm_arg: pointer to the argument data for the API call.
+ * @handle: Pointer to caller's context structure.
+ * @security_flag: SECURE_FLAG or NON_SECURE_FLAG.
*
* These EEMI APIs performs CPU specific power management tasks.
* These EEMI APIs are invoked either from PSCI or from debugfs in kernel.
* These calls require CPU specific processing before sending IPI request to
* Platform Management Controller. For example enable/disable CPU specific
* interrupts. This requires separate handler for these calls and may not be
- * handled using common eemi handler
+ * handled using common eemi handler.
+ *
+ * Return: If EEMI API found then, uintptr_t type address, else 0.
+ *
*/
static uintptr_t eemi_psci_debugfs_handler(uint32_t api_id, uint32_t *pm_arg,
void *handle, uint32_t security_flag)
@@ -258,11 +271,18 @@
}
/**
- * TF_A_specific_handler() - SMC handler for TF-A specific functionality
+ * TF_A_specific_handler() - SMC handler for TF-A specific functionality.
+ * @api_id: identifier for the API being called.
+ * @pm_arg: pointer to the argument data for the API call.
+ * @handle: Pointer to caller's context structure.
+ * @security_flag: SECURE_FLAG or NON_SECURE_FLAG.
*
* These EEMI calls performs functionality that does not require
* IPI transaction. The handler ends in TF-A and returns requested data to
* kernel from TF-A.
+ *
+ * Return: If TF-A specific API found then, uintptr_t type address, else 0
+ *
*/
static uintptr_t TF_A_specific_handler(uint32_t api_id, uint32_t *pm_arg,
void *handle, uint32_t security_flag)
@@ -306,7 +326,11 @@
}
/**
- * eemi_handler() - Prepare EEMI payload and perform IPI transaction
+ * eemi_handler() - Prepare EEMI payload and perform IPI transaction.
+ * @api_id: identifier for the API being called.
+ * @pm_arg: pointer to the argument data for the API call.
+ * @handle: Pointer to caller's context structure.
+ * @security_flag: SECURE_FLAG or NON_SECURE_FLAG.
*
* EEMI - Embedded Energy Management Interface is Xilinx proprietary protocol
* to allow communication between power management controller and different
@@ -314,6 +338,9 @@
*
* This handler prepares EEMI protocol payload received from kernel and performs
* IPI transaction.
+ *
+ * Return: If EEMI API found then, uintptr_t type address, else 0
+ *
*/
static uintptr_t eemi_handler(uint32_t api_id, uint32_t *pm_arg,
void *handle, uint32_t security_flag)
@@ -345,20 +372,24 @@
/**
* pm_smc_handler() - SMC handler for PM-API calls coming from EL1/EL2.
- * @smc_fid - Function Identifier
- * @x1 - x4 - SMC64 Arguments from kernel
- * x3 (upper 32-bits) and x4 are Unused
- * @cookie - Unused
- * @handler - Pointer to caller's context structure
+ * @smc_fid: Function Identifier.
+ * @x1: SMC64 Arguments from kernel.
+ * @x2: SMC64 Arguments from kernel.
+ * @x3: SMC64 Arguments from kernel (upper 32-bits).
+ * @x4: Unused.
+ * @cookie: Unused.
+ * @handle: Pointer to caller's context structure.
+ * @flags: SECURE_FLAG or NON_SECURE_FLAG.
*
- * @return - Unused
+ * Return: Unused.
*
* Determines that smc_fid is valid and supported PM SMC Function ID from the
* list of pm_api_ids, otherwise completes the request with
- * the unknown SMC Function ID
+ * the unknown SMC Function ID.
*
* The SMC calls for PM service are forwarded from SIP Service SMC handler
- * function with rt_svc_handle signature
+ * function with rt_svc_handle signature.
+ *
*/
uint64_t pm_smc_handler(uint32_t smc_fid, uint64_t x1, uint64_t x2, uint64_t x3,
uint64_t x4, const void *cookie, void *handle, uint64_t flags)