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/include/pm_api_sys.h b/plat/xilinx/common/include/pm_api_sys.h
index e8a9627..3fcb62f 100644
--- a/plat/xilinx/common/include/pm_api_sys.h
+++ b/plat/xilinx/common/include/pm_api_sys.h
@@ -68,7 +68,7 @@
uint32_t flag);
enum pm_ret_status pm_get_chipid(uint32_t *value);
-/**
+/*
* Assigning of argument values into array elements.
*/
#define PM_PACK_PAYLOAD1(pl, mid, flag, arg0) { \
diff --git a/plat/xilinx/common/include/pm_common.h b/plat/xilinx/common/include/pm_common.h
index af7ca87..c0308ab 100644
--- a/plat/xilinx/common/include/pm_common.h
+++ b/plat/xilinx/common/include/pm_common.h
@@ -1,5 +1,6 @@
/*
* Copyright (c) 2013-2018, Arm Limited and Contributors. All rights reserved.
+ * Copyright (c) 2022-2023, Advanced Micro Devices, Inc. All rights reserved.
*
* SPDX-License-Identifier: BSD-3-Clause
*/
@@ -33,10 +34,11 @@
TZ_VERSION_MINOR)
/**
- * pm_ipi - struct for capturing IPI-channel specific info
- * @local_ipi_id Local IPI agent ID
- * @remote_ipi_id Remote IPI Agent ID
- * @buffer_base base address for payload buffer
+ * struct pm_ipi - struct for capturing IPI-channel specific info.
+ * @local_ipi_id: Local IPI agent ID.
+ * @remote_ipi_id: Remote IPI Agent ID.
+ * @buffer_base: base address for payload buffer.
+ *
*/
struct pm_ipi {
const uint32_t local_ipi_id;
@@ -45,11 +47,12 @@
};
/**
- * pm_proc - struct for capturing processor related info
- * @node_id node-ID of the processor
- * @pwrdn_mask cpu-specific mask to be used for power control register
- * @ipi pointer to IPI channel structure
- * (in APU all processors share one IPI channel)
+ * struct pm_proc - struct for capturing processor related info.
+ * @node_id: node-ID of the processor.
+ * @pwrdn_mask: cpu-specific mask to be used for power control register.
+ * @ipi: pointer to IPI channel structure.
+ * (in APU all processors share one IPI channel)
+ *
*/
struct pm_proc {
const uint32_t node_id;
diff --git a/plat/xilinx/common/include/pm_defs.h b/plat/xilinx/common/include/pm_defs.h
index c5587fd..b80cf45 100644
--- a/plat/xilinx/common/include/pm_defs.h
+++ b/plat/xilinx/common/include/pm_defs.h
@@ -59,7 +59,9 @@
* Enum definitions
********************************************************************/
-//ioctl id
+/*
+ * ioctl id
+ */
enum {
IOCTL_GET_RPU_OPER_MODE = 0,
IOCTL_SET_RPU_OPER_MODE = 1,
@@ -98,16 +100,18 @@
};
/**
- * @PM_PLL_PARAM_DIV2: Enable for divide by 2 function inside the PLL
- * @PM_PLL_PARAM_FBDIV: Feedback divisor integer portion for the PLL
- * @PM_PLL_PARAM_DATA: Feedback divisor fractional portion for the PLL
- * @PM_PLL_PARAM_PRE_SRC: Clock source for PLL input
- * @PM_PLL_PARAM_POST_SRC: Clock source for PLL Bypass mode
- * @PM_PLL_PARAM_LOCK_DLY: Lock circuit config settings for lock windowsize
- * @PM_PLL_PARAM_LOCK_CNT: Lock circuit counter setting
- * @PM_PLL_PARAM_LFHF: PLL loop filter high frequency capacitor control
- * @PM_PLL_PARAM_CP: PLL charge pump control
- * @PM_PLL_PARAM_RES: PLL loop filter resistor control
+ * enum pm_pll_param - enum represents the parameters for a phase-locked loop.
+ * @PM_PLL_PARAM_DIV2: Enable for divide by 2 function inside the PLL.
+ * @PM_PLL_PARAM_FBDIV: Feedback divisor integer portion for the PLL.
+ * @PM_PLL_PARAM_DATA: Feedback divisor fractional portion for the PLL.
+ * @PM_PLL_PARAM_PRE_SRC: Clock source for PLL input.
+ * @PM_PLL_PARAM_POST_SRC: Clock source for PLL Bypass mode.
+ * @PM_PLL_PARAM_LOCK_DLY: Lock circuit config settings for lock windowsize.
+ * @PM_PLL_PARAM_LOCK_CNT: Lock circuit counter setting.
+ * @PM_PLL_PARAM_LFHF: PLL loop filter high frequency capacitor control.
+ * @PM_PLL_PARAM_CP: PLL charge pump control.
+ * @PM_PLL_PARAM_RES: PLL loop filter resistor control.
+ * @PM_PLL_PARAM_MAX: Represents the maximum parameter value for the PLL
*/
enum pm_pll_param {
PM_PLL_PARAM_DIV2,
@@ -205,7 +209,7 @@
PM_OPCHAR_TYPE_LATENCY,
};
-/**
+/*
* Subsystem IDs
*/
typedef enum {
@@ -223,20 +227,24 @@
/* TODO: move pm_ret_status from device specific location to common location */
/**
- * @PM_RET_SUCCESS: success
- * @PM_RET_ERROR_ARGS: illegal arguments provided (deprecated)
- * @PM_RET_ERROR_NOTSUPPORTED: feature not supported (deprecated)
- * @PM_RET_ERROR_NOFEATURE: feature is not available
- * @PM_RET_ERROR_INVALID_CRC: invalid crc in IPI communication
- * @PM_RET_ERROR_NOT_ENABLED: feature is not enabled
- * @PM_RET_ERROR_INTERNAL: internal error
- * @PM_RET_ERROR_CONFLICT: conflict
- * @PM_RET_ERROR_ACCESS: access rights violation
- * @PM_RET_ERROR_INVALID_NODE: invalid node
- * @PM_RET_ERROR_DOUBLE_REQ: duplicate request for same node
- * @PM_RET_ERROR_ABORT_SUSPEND: suspend procedure has been aborted
- * @PM_RET_ERROR_TIMEOUT: timeout in communication with PMU
- * @PM_RET_ERROR_NODE_USED: node is already in use
+ * enum pm_ret_status - enum represents the return status codes for a PM
+ * operation.
+ * @PM_RET_SUCCESS: success.
+ * @PM_RET_ERROR_ARGS: illegal arguments provided (deprecated).
+ * @PM_RET_ERROR_NOTSUPPORTED: feature not supported (deprecated).
+ * @PM_RET_ERROR_NOFEATURE: feature is not available.
+ * @PM_RET_ERROR_INVALID_CRC: invalid crc in IPI communication.
+ * @PM_RET_ERROR_NOT_ENABLED: feature is not enabled.
+ * @PM_RET_ERROR_INTERNAL: internal error.
+ * @PM_RET_ERROR_CONFLICT: conflict.
+ * @PM_RET_ERROR_ACCESS: access rights violation.
+ * @PM_RET_ERROR_INVALID_NODE: invalid node.
+ * @PM_RET_ERROR_DOUBLE_REQ: duplicate request for same node.
+ * @PM_RET_ERROR_ABORT_SUSPEND: suspend procedure has been aborted.
+ * @PM_RET_ERROR_TIMEOUT: timeout in communication with PMU.
+ * @PM_RET_ERROR_NODE_USED: node is already in use.
+ * @PM_RET_ERROR_NO_FEATURE: indicates that the requested feature is not
+ * supported.
*/
enum pm_ret_status {
PM_RET_SUCCESS,
@@ -256,7 +264,7 @@
PM_RET_ERROR_NO_FEATURE = 2008
};
-/**
+/*
* Qids
*/
enum pm_query_id {
diff --git a/plat/xilinx/common/ipi.c b/plat/xilinx/common/ipi.c
index 9c169ab..399d283 100644
--- a/plat/xilinx/common/ipi.c
+++ b/plat/xilinx/common/ipi.c
@@ -1,6 +1,7 @@
/*
* Copyright (c) 2017-2020, Arm Limited and Contributors. All rights reserved.
* Copyright (c) 2020-2022, Xilinx, Inc. All rights reserved.
+ * Copyright (c) 2022-2023, Advanced Micro Devices, Inc. All rights reserved.
*
* SPDX-License-Identifier: BSD-3-Clause
*/
@@ -45,10 +46,9 @@
static uint32_t ipi_total;
/**
- * ipi_config_init() - Initialize IPI configuration data
- *
- * @ipi_config_table - IPI configuration table
- * @ipi_total - Total number of IPI available
+ * ipi_config_table_init() - Initialize IPI configuration data.
+ * @ipi_config_table: IPI configuration table.
+ * @total_ipi: Total number of IPI available.
*
*/
void ipi_config_table_init(const struct ipi_config *ipi_config_table,
@@ -58,12 +58,13 @@
ipi_total = total_ipi;
}
-/* is_ipi_mb_within_range() - verify if IPI mailbox is within range
+/**
+ * is_ipi_mb_within_range() - verify if IPI mailbox is within range.
+ * @local: local IPI ID.
+ * @remote: remote IPI ID.
*
- * @local - local IPI ID
- * @remote - remote IPI ID
+ * Return: - 1 if within range, 0 if not.
*
- * return - 1 if within range, 0 if not
*/
static inline int is_ipi_mb_within_range(uint32_t local, uint32_t remote)
{
@@ -77,13 +78,13 @@
}
/**
- * ipi_mb_validate() - validate IPI mailbox access
+ * ipi_mb_validate() - validate IPI mailbox access.
+ * @local: local IPI ID.
+ * @remote: remote IPI ID.
+ * @is_secure: indicate if the requester is from secure software.
*
- * @local - local IPI ID
- * @remote - remote IPI ID
- * @is_secure - indicate if the requester is from secure software
+ * Return: 0 success, negative value for errors.
*
- * return - 0 success, negative value for errors
*/
int ipi_mb_validate(uint32_t local, uint32_t remote, unsigned int is_secure)
{
@@ -104,9 +105,8 @@
/**
* ipi_mb_open() - Open IPI mailbox.
- *
- * @local - local IPI ID
- * @remote - remote IPI ID
+ * @local: local IPI ID.
+ * @remote: remote IPI ID.
*
*/
void ipi_mb_open(uint32_t local, uint32_t remote)
@@ -119,9 +119,8 @@
/**
* ipi_mb_release() - Open IPI mailbox.
- *
- * @local - local IPI ID
- * @remote - remote IPI ID
+ * @local: local IPI ID.
+ * @remote: remote IPI ID.
*
*/
void ipi_mb_release(uint32_t local, uint32_t remote)
@@ -131,13 +130,13 @@
}
/**
- * ipi_mb_enquire_status() - Enquire IPI mailbox status
+ * ipi_mb_enquire_status() - Enquire IPI mailbox status.
+ * @local: local IPI ID.
+ * @remote: remote IPI ID.
*
- * @local - local IPI ID
- * @remote - remote IPI ID
+ * Return: 0 idle, positive value for pending sending or receiving,
+ * negative value for errors.
*
- * return - 0 idle, positive value for pending sending or receiving,
- * negative value for errors
*/
int ipi_mb_enquire_status(uint32_t local, uint32_t remote)
{
@@ -156,11 +155,11 @@
return ret;
}
-/* ipi_mb_notify() - Trigger IPI mailbox notification
- *
- * @local - local IPI ID
- * @remote - remote IPI ID
- * @is_blocking - if to trigger the notification in blocking mode or not.
+/**
+ * ipi_mb_notify() - Trigger IPI mailbox notification.
+ * @local: local IPI ID.
+ * @remote: remote IPI ID.
+ * @is_blocking: if to trigger the notification in blocking mode or not.
*
* It sets the remote bit in the IPI agent trigger register.
*
@@ -179,10 +178,10 @@
}
}
-/* ipi_mb_ack() - Ack IPI mailbox notification from the other end
- *
- * @local - local IPI ID
- * @remote - remote IPI ID
+/**
+ * ipi_mb_ack() - Ack IPI mailbox notification from the other end.
+ * @local: local IPI ID.
+ * @remote: remote IPI ID.
*
* It will clear the remote bit in the isr register.
*
@@ -193,10 +192,10 @@
IPI_BIT_MASK(remote));
}
-/* ipi_mb_disable_irq() - Disable IPI mailbox notification interrupt
- *
- * @local - local IPI ID
- * @remote - remote IPI ID
+/**
+ * ipi_mb_disable_irq() - Disable IPI mailbox notification interrupt.
+ * @local: local IPI ID.
+ * @remote: remote IPI ID.
*
* It will mask the remote bit in the idr register.
*
@@ -207,10 +206,10 @@
IPI_BIT_MASK(remote));
}
-/* ipi_mb_enable_irq() - Enable IPI mailbox notification interrupt
- *
- * @local - local IPI ID
- * @remote - remote IPI ID
+/**
+ * ipi_mb_enable_irq() - Enable IPI mailbox notification interrupt.
+ * @local: local IPI ID.
+ * @remote: remote IPI ID.
*
* It will mask the remote bit in the idr register.
*
diff --git a/plat/xilinx/common/ipi_mailbox_service/ipi_mailbox_svc.c b/plat/xilinx/common/ipi_mailbox_service/ipi_mailbox_svc.c
index 330288c..6c060d5 100644
--- a/plat/xilinx/common/ipi_mailbox_service/ipi_mailbox_svc.c
+++ b/plat/xilinx/common/ipi_mailbox_service/ipi_mailbox_svc.c
@@ -1,5 +1,6 @@
/*
* Copyright (c) 2017-2019, Arm Limited and Contributors. All rights reserved.
+ * Copyright (c) 2022-2023, Advanced Micro Devices, Inc. All rights reserved.
*
* SPDX-License-Identifier: BSD-3-Clause
*/
@@ -46,21 +47,25 @@
#define UNSIGNED32_MASK 0xFFFFFFFFU /* 32bit mask */
/**
- * ipi_smc_handler() - SMC handler for IPI SMC calls
+ * ipi_smc_handler() - SMC handler for IPI SMC calls.
+ * @smc_fid: Function identifier.
+ * @x1: Arguments.
+ * @x2: Arguments.
+ * @x3: Arguments.
+ * @x4: Arguments.
+ * @cookie: Unused.
+ * @handle: Pointer to caller's context structure.
+ * @flags: SECURE_FLAG or NON_SECURE_FLAG.
*
- * @smc_fid - Function identifier
- * @x1 - x4 - Arguments
- * @cookie - Unused
- * @handler - Pointer to caller's context structure
- *
- * @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 ipi_smc_handler(uint32_t smc_fid, uint64_t x1, uint64_t x2,
uint64_t x3, uint64_t x4, const void *cookie,
diff --git a/plat/xilinx/common/plat_startup.c b/plat/xilinx/common/plat_startup.c
index 007c045..d034e00 100644
--- a/plat/xilinx/common/plat_startup.c
+++ b/plat/xilinx/common/plat_startup.c
@@ -55,11 +55,12 @@
#define FSBL_FLAGS_A53_3 3U
/**
- * @partition: Pointer to partition struct
+ * get_fsbl_cpu() - Get the target CPU for partition.
+ * @partition: Pointer to partition struct.
*
- * Get the target CPU for @partition.
+ * Return: FSBL_FLAGS_A53_0, FSBL_FLAGS_A53_1, FSBL_FLAGS_A53_2 or
+ * FSBL_FLAGS_A53_3.
*
- * Return: FSBL_FLAGS_A53_0, FSBL_FLAGS_A53_1, FSBL_FLAGS_A53_2 or FSBL_FLAGS_A53_3
*/
static int32_t get_fsbl_cpu(const struct xfsbl_partition *partition)
{
@@ -69,11 +70,11 @@
}
/**
- * @partition: Pointer to partition struct
+ * get_fsbl_el() - Get the target exception level for partition.
+ * @partition: Pointer to partition struct.
*
- * Get the target exception level for @partition.
+ * Return: FSBL_FLAGS_EL0, FSBL_FLAGS_EL1, FSBL_FLAGS_EL2 or FSBL_FLAGS_EL3.
*
- * Return: FSBL_FLAGS_EL0, FSBL_FLAGS_EL1, FSBL_FLAGS_EL2 or FSBL_FLAGS_EL3
*/
static int32_t get_fsbl_el(const struct xfsbl_partition *partition)
{
@@ -83,11 +84,11 @@
}
/**
- * @partition: Pointer to partition struct
+ * get_fsbl_ss() - Get the target security state for partition.
+ * @partition: Pointer to partition struct.
*
- * Get the target security state for @partition.
+ * Return: FSBL_FLAGS_NON_SECURE or FSBL_FLAGS_SECURE.
*
- * Return: FSBL_FLAGS_NON_SECURE or FSBL_FLAGS_SECURE
*/
static int32_t get_fsbl_ss(const struct xfsbl_partition *partition)
{
@@ -97,11 +98,11 @@
}
/**
- * @partition: Pointer to partition struct
+ * get_fsbl_endian() - Get the target endianness for partition.
+ * @partition: Pointer to partition struct.
*
- * Get the target endianness for @partition.
+ * Return: SPSR_E_LITTLE or SPSR_E_BIG.
*
- * Return: SPSR_E_LITTLE or SPSR_E_BIG
*/
static int32_t get_fsbl_endian(const struct xfsbl_partition *partition)
{
@@ -117,11 +118,11 @@
}
/**
- * @partition: Pointer to partition struct
+ * get_fsbl_estate() - Get the target execution state for partition.
+ * @partition: Pointer to partition struct.
*
- * Get the target execution state for @partition.
+ * Return: FSBL_FLAGS_ESTATE_A32 or FSBL_FLAGS_ESTATE_A64.
*
- * Return: FSBL_FLAGS_ESTATE_A32 or FSBL_FLAGS_ESTATE_A64
*/
static int32_t get_fsbl_estate(const struct xfsbl_partition *partition)
{
@@ -131,16 +132,17 @@
}
/**
- * Populates the bl32 and bl33 image info structures
- * @bl32: BL32 image info structure
- * @bl33: BL33 image info structure
- * tfa_handoff_addr: TF-A handoff address
+ * fsbl_tfa_handover() - Populates the bl32 and bl33 image info structures.
+ * @bl32: BL32 image info structure.
+ * @bl33: BL33 image info structure.
+ * @tfa_handoff_addr: TF-A handoff address.
*
* Process the handoff parameters from the FSBL and populate the BL32 and BL33
* image info structures accordingly.
*
* Return: Return the status of the handoff. The value will be from the
* fsbl_handoff enum.
+ *
*/
enum fsbl_handoff fsbl_tfa_handover(entry_point_info_t *bl32,
entry_point_info_t *bl33,
diff --git a/plat/xilinx/common/pm_service/pm_api_sys.c b/plat/xilinx/common/pm_service/pm_api_sys.c
index dcdd2dc..ffc39bb 100644
--- a/plat/xilinx/common/pm_service/pm_api_sys.c
+++ b/plat/xilinx/common/pm_service/pm_api_sys.c
@@ -28,9 +28,10 @@
static uint32_t pm_shutdown_scope = XPM_SHUTDOWN_SUBTYPE_RST_SYSTEM;
/**
- * pm_get_shutdown_scope() - Get the currently set shutdown scope
+ * pm_get_shutdown_scope() - Get the currently set shutdown scope.
*
- * @return Shutdown scope value
+ * Return: Shutdown scope value.
+ *
*/
uint32_t pm_get_shutdown_scope(void)
{
@@ -42,7 +43,8 @@
/**
* pm_client_set_wakeup_sources - Set all devices with enabled interrupts as
* wake sources in the XilPM.
- * @node_id: Node id of processor
+ * @node_id: Node id of processor.
+ *
*/
void pm_client_set_wakeup_sources(uint32_t node_id)
{
@@ -91,13 +93,19 @@
}
/**
- * pm_handle_eemi_call() - PM call for processor to send eemi payload
- * @flag 0 - Call from secure source
- * 1 - Call from non-secure source
- * @x0 to x5 Arguments received per SMC64 standard
- * @result Payload received from firmware
+ * pm_handle_eemi_call() - PM call for processor to send eemi payload.
+ * @flag: 0 - Call from secure source.
+ * 1 - Call from non-secure source.
+ * @x0: Arguments received per SMC64 standard.
+ * @x1: Arguments received per SMC64 standard.
+ * @x2: Arguments received per SMC64 standard.
+ * @x3: Arguments received per SMC64 standard.
+ * @x4: Arguments received per SMC64 standard.
+ * @x5: Arguments received per SMC64 standard.
+ * @result: Payload received from firmware.
*
- * @return PM_RET_SUCCESS on success or error code
+ * Return: PM_RET_SUCCESS on success or error code.
+ *
*/
enum pm_ret_status pm_handle_eemi_call(uint32_t flag, uint32_t x0, uint32_t x1,
uint32_t x2, uint32_t x3, uint32_t x4,
@@ -119,17 +127,18 @@
/**
* pm_self_suspend() - PM call for processor to suspend itself
- * @nid Node id of the processor or subsystem
- * @latency Requested maximum wakeup latency (not supported)
- * @state Requested state
- * @address Resume address
- * @flag 0 - Call from secure source
- * 1 - Call from non-secure source
+ * @nid: Node id of the processor or subsystem.
+ * @latency: Requested maximum wakeup latency (not supported).
+ * @state: Requested state.
+ * @address: Resume address.
+ * @flag: 0 - Call from secure source.
+ * 1 - Call from non-secure source.
*
* This is a blocking call, it will return only once PMU has responded.
* On a wakeup, resume address will be automatically set by PMU.
*
- * @return Returns status, either success or error+reason
+ * Return: Returns status, either success or error+reason.
+ *
*/
enum pm_ret_status pm_self_suspend(uint32_t nid,
uint32_t latency,
@@ -160,15 +169,16 @@
/**
* pm_abort_suspend() - PM call to announce that a prior suspend request
- * is to be aborted.
- * @reason Reason for the abort
- * @flag 0 - Call from secure source
- * 1 - Call from non-secure source
+ * is to be aborted.
+ * @reason: Reason for the abort.
+ * @flag: 0 - Call from secure source.
+ * 1 - Call from non-secure source.
*
* Calling PU expects the PMU to abort the initiated suspend procedure.
* This is a non-blocking call without any acknowledge.
*
- * @return Returns status, either success or error+reason
+ * Return: Returns status, either success or error+reason.
+ *
*/
enum pm_ret_status pm_abort_suspend(enum pm_abort_reason reason, uint32_t flag)
{
@@ -188,15 +198,16 @@
/**
* pm_req_suspend() - PM call to request for another PU or subsystem to
- * be suspended gracefully.
- * @target Node id of the targeted PU or subsystem
- * @ack Flag to specify whether acknowledge is requested
- * @latency Requested wakeup latency (not supported)
- * @state Requested state (not supported)
- * @flag 0 - Call from secure source
- * 1 - Call from non-secure source
+ * be suspended gracefully.
+ * @target: Node id of the targeted PU or subsystem.
+ * @ack: Flag to specify whether acknowledge is requested.
+ * @latency: Requested wakeup latency (not supported)
+ * @state: Requested state (not supported).
+ * @flag: 0 - Call from secure source.
+ * 1 - Call from non-secure source.
*
- * @return Returns status, either success or error+reason
+ * Return: Returns status, either success or error+reason.
+ *
*/
enum pm_ret_status pm_req_suspend(uint32_t target, uint8_t ack,
uint32_t latency, uint32_t state,
@@ -216,21 +227,22 @@
/**
* pm_req_wakeup() - PM call for processor to wake up selected processor
- * or subsystem
- * @target Device ID of the processor or subsystem to wake up
- * @set_address Resume address presence indicator
- * 1 - resume address specified, 0 - otherwise
- * @address Resume address
- * @ack Flag to specify whether acknowledge requested
- * @flag 0 - Call from secure source
- * 1 - Call from non-secure source
+ * or subsystem.
+ * @target: Device ID of the processor or subsystem to wake up.
+ * @set_address: Resume address presence indicator.
+ * 1 - resume address specified, 0 - otherwise.
+ * @address: Resume address.
+ * @ack: Flag to specify whether acknowledge requested.
+ * @flag: 0 - Call from secure source.
+ * 1 - Call from non-secure source.
*
* This API function is either used to power up another APU core for SMP
* (by PSCI) or to power up an entirely different PU or subsystem, such
* as RPU0, RPU, or PL_CORE_xx. Resume address for the target PU will be
* automatically set by PMC.
*
- * @return Returns status, either success or error+reason
+ * Return: Returns status, either success or error+reason.
+ *
*/
enum pm_ret_status pm_req_wakeup(uint32_t target, uint32_t set_address,
uintptr_t address, uint8_t ack, uint32_t flag)
@@ -245,15 +257,17 @@
}
/**
- * pm_get_callbackdata() - Read from IPI response buffer
- * @data - array of PAYLOAD_ARG_CNT elements
- * @flag - 0 - Call from secure source
- * 1 - Call from non-secure source
- * @ack - 0 - Do not ack IPI after reading payload
- * 1 - Ack IPI after reading payload
+ * pm_get_callbackdata() - Read from IPI response buffer.
+ * @data: array of PAYLOAD_ARG_CNT elements.
+ * @count: Number of values to return.
+ * @flag: 0 - Call from secure source.
+ * 1 - Call from non-secure source.
+ * @ack: 0 - Do not ack IPI after reading payload.
+ * 1 - Ack IPI after reading payload.
*
* Read value from ipi buffer response buffer.
- * @return Returns status, either success or error
+ * Return: Returns status, either success or error.
+ *
*/
enum pm_ret_status pm_get_callbackdata(uint32_t *data, size_t count, uint32_t flag, uint32_t ack)
{
@@ -273,19 +287,19 @@
}
/**
- * pm_pll_set_param() - Set PLL parameter
+ * pm_pll_set_param() - Set PLL parameter.
+ * @clk_id: PLL clock ID.
+ * @param: PLL parameter ID.
+ * @value: Value to set for PLL parameter.
+ * @flag: 0 - Call from secure source.
+ * 1 - Call from non-secure source.
*
* This API is deprecated and maintained here for backward compatibility.
* New use of this API should be avoided for versal platform.
* This API and its use cases will be removed for versal platform.
*
- * @clk_id PLL clock ID
- * @param PLL parameter ID
- * @value Value to set for PLL parameter
- * @flag 0 - Call from secure source
- * 1 - Call from non-secure source
+ * Return: Returns status, either success or error+reason.
*
- * @return Returns status, either success or error+reason
*/
enum pm_ret_status pm_pll_set_param(uint32_t clk_id, uint32_t param,
uint32_t value, uint32_t flag)
@@ -300,19 +314,19 @@
}
/**
- * pm_pll_get_param() - Get PLL parameter value
+ * pm_pll_get_param() - Get PLL parameter value.
+ * @clk_id: PLL clock ID.
+ * @param: PLL parameter ID.
+ * @value: Buffer to store PLL parameter value.
+ * @flag: 0 - Call from secure source.
+ * 1 - Call from non-secure source.
*
* This API is deprecated and maintained here for backward compatibility.
* New use of this API should be avoided for versal platform.
* This API and its use cases will be removed for versal platform.
*
- * @clk_id PLL clock ID
- * @param PLL parameter ID
- * @value: Buffer to store PLL parameter value
- * @flag 0 - Call from secure source
- * 1 - Call from non-secure source
+ * Return: Returns status, either success or error+reason.
*
- * @return Returns status, either success or error+reason
*/
enum pm_ret_status pm_pll_get_param(uint32_t clk_id, uint32_t param,
uint32_t *value, uint32_t flag)
@@ -327,18 +341,18 @@
}
/**
- * pm_pll_set_mode() - Set PLL mode
+ * pm_pll_set_mode() - Set PLL mode.
+ * @clk_id: PLL clock ID.
+ * @mode: PLL mode.
+ * @flag: 0 - Call from secure source.
+ * 1 - Call from non-secure source.
*
* This API is deprecated and maintained here for backward compatibility.
* New use of this API should be avoided for versal platform.
* This API and its use cases will be removed for versal platform.
*
- * @clk_id PLL clock ID
- * @mode PLL mode
- * @flag 0 - Call from secure source
- * 1 - Call from non-secure source
+ * Return: Returns status, either success or error+reason.
*
- * @return Returns status, either success or error+reason
*/
enum pm_ret_status pm_pll_set_mode(uint32_t clk_id, uint32_t mode,
uint32_t flag)
@@ -353,18 +367,18 @@
}
/**
- * pm_pll_get_mode() - Get PLL mode
+ * pm_pll_get_mode() - Get PLL mode.
+ * @clk_id: PLL clock ID.
+ * @mode: Buffer to store PLL mode.
+ * @flag: 0 - Call from secure source.
+ * 1 - Call from non-secure source.
*
* This API is deprecated and maintained here for backward compatibility.
* New use of this API should be avoided for versal platform.
* This API and its use cases will be removed for versal platform.
*
- * @clk_id PLL clock ID
- * @mode: Buffer to store PLL mode
- * @flag 0 - Call from secure source
- * 1 - Call from non-secure source
+ * Return: Returns status, either success or error+reason.
*
- * @return Returns status, either success or error+reason
*/
enum pm_ret_status pm_pll_get_mode(uint32_t clk_id, uint32_t *mode,
uint32_t flag)
@@ -380,13 +394,14 @@
/**
* pm_force_powerdown() - PM call to request for another PU or subsystem to
- * be powered down forcefully
- * @target Device ID of the PU node to be forced powered down.
- * @ack Flag to specify whether acknowledge is requested
- * @flag 0 - Call from secure source
- * 1 - Call from non-secure source
+ * be powered down forcefully.
+ * @target: Device ID of the PU node to be forced powered down.
+ * @ack: Flag to specify whether acknowledge is requested
+ * @flag: 0 - Call from secure source
+ * 1 - Call from non-secure source
*
- * @return Returns status, either success or error+reason
+ * Return: Returns status, either success or error+reason.
+ *
*/
enum pm_ret_status pm_force_powerdown(uint32_t target, uint8_t ack,
uint32_t flag)
@@ -405,13 +420,14 @@
}
/**
- * pm_system_shutdown() - PM call to request a system shutdown or restart
- * @type Shutdown or restart? 0=shutdown, 1=restart, 2=setscope
- * @subtype Scope: 0=APU-subsystem, 1=PS, 2=system
- * @flag 0 - Call from secure source
- * 1 - Call from non-secure source
+ * pm_system_shutdown() - PM call to request a system shutdown or restart.
+ * @type: Shutdown or restart? 0=shutdown, 1=restart, 2=setscope.
+ * @subtype: Scope: 0=APU-subsystem, 1=PS, 2=system.
+ * @flag: 0 - Call from secure source.
+ * 1 - Call from non-secure source.
*
- * @return Returns status, either success or error+reason
+ * Return: Returns status, either success or error+reason.
+ *
*/
enum pm_ret_status pm_system_shutdown(uint32_t type, uint32_t subtype,
uint32_t flag)
@@ -432,22 +448,22 @@
}
/**
- * pm_query_data() - PM API for querying firmware data
+ * pm_query_data() - PM API for querying firmware data.
+ * @qid: The type of data to query.
+ * @arg1: Argument 1 to requested query data call.
+ * @arg2: Argument 2 to requested query data call.
+ * @arg3: Argument 3 to requested query data call.
+ * @data: Returned output data.
+ * @flag: 0 - Call from secure source.
+ * 1 - Call from non-secure source.
*
* This API is deprecated and maintained here for backward compatibility.
* New use of this API should be avoided for versal platform.
* This API and its use cases will be removed for versal platform.
*
- * @qid The type of data to query
- * @arg1 Argument 1 to requested query data call
- * @arg2 Argument 2 to requested query data call
- * @arg3 Argument 3 to requested query data call
- * @data Returned output data
- * @flag 0 - Call from secure source
- * 1 - Call from non-secure source
+ * Return: 0 if success else non-zero error code of type
+ * enum pm_ret_status.
*
- * @retur - 0 if success else non-zero error code of type
- * enum pm_ret_status
*/
enum pm_ret_status pm_query_data(uint32_t qid, uint32_t arg1, uint32_t arg2,
uint32_t arg3, uint32_t *data, uint32_t flag)
@@ -481,25 +497,25 @@
return ret;
}
/**
- * pm_api_ioctl() - PM IOCTL API for device control and configs
+ * pm_api_ioctl() - PM IOCTL API for device control and configs.
+ * @device_id: Device ID.
+ * @ioctl_id: ID of the requested IOCTL.
+ * @arg1: Argument 1 to requested IOCTL call.
+ * @arg2: Argument 2 to requested IOCTL call.
+ * @arg3: Argument 3 to requested IOCTL call.
+ * @value: Returned output value.
+ * @flag: 0 - Call from secure source.
+ * 1 - Call from non-secure source.
*
* This API is deprecated and maintained here for backward compatibility.
* New use of this API should be avoided for versal platform.
* This API and its use cases will be removed for versal platform.
*
- * @device_id Device ID
- * @ioctl_id ID of the requested IOCTL
- * @arg1 Argument 1 to requested IOCTL call
- * @arg2 Argument 2 to requested IOCTL call
- * @arg3 Argument 3 to requested IOCTL call
- * @value Returned output value
- * @flag 0 - Call from secure source
- * 1 - Call from non-secure source
- *
* This function calls IOCTL to firmware for device control and configuration.
*
- * @return Returns status, either 0 on success or non-zero error code
- * of type enum pm_ret_status
+ * Return: Returns status, either 0 on success or non-zero error code
+ * of type enum pm_ret_status.
+ *
*/
enum pm_ret_status pm_api_ioctl(uint32_t device_id, uint32_t ioctl_id,
uint32_t arg1, uint32_t arg2, uint32_t arg3,
@@ -536,14 +552,16 @@
}
/**
- * pm_set_wakeup_source() - PM call to specify the wakeup source while suspended
- * @target Device id of the targeted PU or subsystem
- * @wkup_node Device id of the wakeup peripheral
- * @enable Enable or disable the specified peripheral as wake source
- * @flag 0 - Call from secure source
- * 1 - Call from non-secure source
+ * pm_set_wakeup_source() - PM call to specify the wakeup source while
+ * suspended.
+ * @target: Device id of the targeted PU or subsystem
+ * @wkup_device: Device id of the wakeup peripheral
+ * @enable: Enable or disable the specified peripheral as wake source
+ * @flag: 0 - Call from secure source
+ * 1 - Call from non-secure source
*
- * @return Returns status, either success or error+reason
+ * Return: Returns status, either success or error+reason.
+ *
*/
enum pm_ret_status pm_set_wakeup_source(uint32_t target, uint32_t wkup_device,
uint8_t enable, uint32_t flag)
@@ -556,15 +574,16 @@
}
/**
- * pm_feature_check() - Returns the supported API version if supported
- * @api_id API ID to check
- * @flag 0 - Call from secure source
- * 1 - Call from non-secure source
- * @ret_payload pointer to array of PAYLOAD_ARG_CNT number of
- * words Returned supported API version and bitmasks
- * for IOCTL and QUERY ID
+ * pm_feature_check() - Returns the supported API version if supported.
+ * @api_id: API ID to check.
+ * @flag: 0 - Call from secure source.
+ * 1 - Call from non-secure source.
+ * @ret_payload: pointer to array of PAYLOAD_ARG_CNT number of
+ * words Returned supported API version and bitmasks
+ * for IOCTL and QUERY ID
*
- * @return Returns status, either success or error+reason
+ * Return: Returns status, either success or error+reason.
+ *
*/
enum pm_ret_status pm_feature_check(uint32_t api_id, uint32_t *ret_payload,
uint32_t flag)
@@ -601,17 +620,17 @@
}
/**
- * pm_load_pdi() - Load the PDI
+ * pm_load_pdi() - Load the PDI. This function provides support to load
+ * PDI from linux.
*
- * This function provides support to load PDI from linux
+ * @src: Source device of pdi(DDR, OCM, SD etc).
+ * @address_low: lower 32-bit Linear memory space address.
+ * @address_high: higher 32-bit Linear memory space address.
+ * @flag: 0 - Call from secure source.
+ * 1 - Call from non-secure source.
*
- * src: Source device of pdi(DDR, OCM, SD etc)
- * address_low: lower 32-bit Linear memory space address
- * address_high: higher 32-bit Linear memory space address
- * @flag 0 - Call from secure source
- * 1 - Call from non-secure source
+ * Return: Returns status, either success or error+reason.
*
- * @return Returns status, either success or error+reason
*/
enum pm_ret_status pm_load_pdi(uint32_t src, uint32_t address_low,
uint32_t address_high, uint32_t flag)
@@ -626,15 +645,16 @@
/**
* pm_register_notifier() - PM call to register a subsystem to be notified
- * about the device event
- * @device_id Device ID for the Node to which the event is related
- * @event Event in question
- * @wake Wake subsystem upon capturing the event if value 1
- * @enable Enable the registration for value 1, disable for value 0
- * @flag 0 - Call from secure source
- * 1 - Call from non-secure source
+ * about the device event.
+ * @device_id: Device ID for the Node to which the event is related.
+ * @event: Event in question.
+ * @wake: Wake subsystem upon capturing the event if value 1.
+ * @enable: Enable the registration for value 1, disable for value 0.
+ * @flag: 0 - Call from secure source.
+ * 1 - Call from non-secure source.
*
- * @return Returns status, either success or error+reason
+ * Return: Returns status, either success or error+reason.
+ *
*/
enum pm_ret_status pm_register_notifier(uint32_t device_id, uint32_t event,
uint32_t wake, uint32_t enable,
@@ -650,11 +670,11 @@
}
/**
- * pm_get_chipid() - Read silicon ID registers
- * @value: Buffer for two 32bit words.
+ * pm_get_chipid() - Read silicon ID registers.
+ * @value: Buffer for two 32bit words.
*
- * @return: Returns status, either success or error+reason and,
- * optionally, @value.
+ * Return: Returns status, either success or error+reason and,
+ * optionally, @value.
*/
enum pm_ret_status pm_get_chipid(uint32_t *value)
{
diff --git a/plat/xilinx/common/pm_service/pm_ipi.c b/plat/xilinx/common/pm_service/pm_ipi.c
index 2c3cb1b..5e59559 100644
--- a/plat/xilinx/common/pm_service/pm_ipi.c
+++ b/plat/xilinx/common/pm_service/pm_ipi.c
@@ -1,7 +1,7 @@
/*
* Copyright (c) 2013-2020, Arm Limited and Contributors. All rights reserved.
* Copyright (c) 2019-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
*/
@@ -52,14 +52,14 @@
/**
* pm_ipi_init() - Initialize IPI peripheral for communication with
- * remote processor
+ * remote processor.
+ * @proc: Pointer to the processor who is initiating request.
*
- * @proc Pointer to the processor who is initiating request
- * @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.
*
- * Called from pm_setup initialization function
+ * Called from pm_setup initialization function.
*/
void pm_ipi_init(const struct pm_proc *proc)
{
@@ -67,14 +67,16 @@
}
/**
- * pm_ipi_send_common() - Sends IPI request to the remote processor
- * @proc Pointer to the processor who is initiating request
- * @payload API id and call arguments to be written in IPI buffer
+ * pm_ipi_send_common() - Sends IPI request to the remote processor.
+ * @proc: Pointer to the processor who is initiating request.
+ * @payload: API id and call arguments to be written in IPI buffer.
+ * @is_blocking: if to trigger the notification in blocking mode or not.
*
* Send an IPI request to the power controller. Caller needs to hold
* the 'pm_secure_lock' lock.
*
- * @return Returns status, either success or error+reason
+ * Return: Returns status, either success or error+reason.
+ *
*/
static enum pm_ret_status pm_ipi_send_common(const struct pm_proc *proc,
uint32_t payload[PAYLOAD_ARG_CNT],
@@ -103,13 +105,14 @@
/**
* pm_ipi_send_non_blocking() - Sends IPI request to the remote processor
- * without blocking notification
- * @proc Pointer to the processor who is initiating request
- * @payload API id and call arguments to be written in IPI buffer
+ * without blocking notification.
+ * @proc: Pointer to the processor who is initiating request.
+ * @payload: API id and call arguments to be written in IPI buffer.
*
* Send an IPI request to the power controller.
*
- * @return Returns status, either success or error+reason
+ * Return: Returns status, either success or error+reason.
+ *
*/
enum pm_ret_status pm_ipi_send_non_blocking(const struct pm_proc *proc,
uint32_t payload[PAYLOAD_ARG_CNT])
@@ -126,13 +129,14 @@
}
/**
- * pm_ipi_send() - Sends IPI request to the remote processor
- * @proc Pointer to the processor who is initiating request
- * @payload API id and call arguments to be written in IPI buffer
+ * pm_ipi_send() - Sends IPI request to the remote processor.
+ * @proc: Pointer to the processor who is initiating request.
+ * @payload: API id and call arguments to be written in IPI buffer.
*
* Send an IPI request to the power controller.
*
- * @return Returns status, either success or error+reason
+ * Return: Returns status, either success or error+reason.
+ *
*/
enum pm_ret_status pm_ipi_send(const struct pm_proc *proc,
uint32_t payload[PAYLOAD_ARG_CNT])
@@ -151,12 +155,13 @@
/**
* pm_ipi_buff_read() - Reads IPI response after remote processor has handled
- * interrupt
- * @proc Pointer to the processor who is waiting and reading response
- * @value Used to return value from IPI buffer element (optional)
- * @count Number of values to return in @value
+ * interrupt.
+ * @proc: Pointer to the processor who is waiting and reading response.
+ * @value: Used to return value from IPI buffer element (optional).
+ * @count: Number of values to return in @value.
*
- * @return Returns status, either success or error+reason
+ * Return: Returns status, either success or error+reason.
+ *
*/
static enum pm_ret_status pm_ipi_buff_read(const struct pm_proc *proc,
uint32_t *value, size_t count)
@@ -208,13 +213,15 @@
/**
* pm_ipi_buff_read_callb() - Callback function that reads value from
- * ipi response buffer
- * @value Used to return value from IPI buffer element
- * @count Number of values to return in @value
+ * ipi response buffer.
+ * @value: Used to return value from IPI buffer element.
+ * @count: Number of values to return in @value.
*
* This callback function fills requested data in @value from ipi response
* buffer.
- * @return Returns status, either success or error
+ *
+ * Return: Returns status, either success or error.
+ *
*/
enum pm_ret_status pm_ipi_buff_read_callb(uint32_t *value, size_t count)
{
@@ -258,16 +265,17 @@
}
/**
- * pm_ipi_send_sync() - Sends IPI request to the remote processor
- * @proc Pointer to the processor who is initiating request
- * @payload API id and call arguments to be written in IPI buffer
- * @value Used to return value from IPI buffer element (optional)
- * @count Number of values to return in @value
+ * pm_ipi_send_sync() - Sends IPI request to the remote processor.
+ * @proc: Pointer to the processor who is initiating request.
+ * @payload: API id and call arguments to be written in IPI buffer.
+ * @value: Used to return value from IPI buffer element (optional).
+ * @count: Number of values to return in @value.
*
* Send an IPI request to the power controller and wait for it to be handled.
*
- * @return Returns status, either success or error+reason and, optionally,
- * @value
+ * Return: Returns status, either success or error+reason and, optionally,
+ * @value.
+ *
*/
enum pm_ret_status pm_ipi_send_sync(const struct pm_proc *proc,
uint32_t payload[PAYLOAD_ARG_CNT],
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)
diff --git a/plat/xilinx/common/versal.c b/plat/xilinx/common/versal.c
index 019c862..3ea022c 100644
--- a/plat/xilinx/common/versal.c
+++ b/plat/xilinx/common/versal.c
@@ -15,12 +15,12 @@
/**
* plat_is_smccc_feature_available() - This function checks whether SMCCC
- * feature is availabile for platform.
- * @fid: SMCCC function id
+ * feature is availabile for platform.
+ * @fid: SMCCC function id.
*
- * Return:
- * * SMC_ARCH_CALL_SUCCESS - if SMCCC feature is available
- * * SMC_ARCH_CALL_NOT_SUPPORTED - Otherwise
+ * Return: SMC_ARCH_CALL_SUCCESS - if SMCCC feature is available.
+ * SMC_ARCH_CALL_NOT_SUPPORTED - Otherwise.
+ *
*/
int32_t plat_is_smccc_feature_available(u_register_t fid)
{
@@ -33,12 +33,12 @@
}
/**
- * plat_get_soc_version() - Get the SOC version of the platform
+ * plat_get_soc_version() - Get the SOC version of the platform.
+ *
+ * Return: SiP defined SoC version in JEP-106.
*
* This function is called when the SoC_ID_type == 0.
- * For further details please refer to section 7.4 of SMC Calling Convention
- *
- * Return: SiP defined SoC version in JEP-106
+ * For further details please refer to section 7.4 of SMC Calling Convention.
*/
int32_t plat_get_soc_version(void)
{
@@ -50,12 +50,12 @@
}
/**
- * plat_get_soc_revision() - Get the SOC revision for the platform
+ * plat_get_soc_revision() - Get the SOC revision for the platform.
+ *
+ * Return: SiP defined SoC revision.
*
* This function is called when the SoC_ID_type == 1
* For further details please refer to section 7.4 of SMC Calling Convention
- *
- * Return: SiP defined SoC revision
*/
int32_t plat_get_soc_revision(void)
{