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_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)