From 353cc695ad568152c0e95f124d6e5fb9facf81c8 Mon Sep 17 00:00:00 2001 From: Davorin Mista Date: Mon, 8 Jun 2015 11:43:14 -0700 Subject: [PATCH] PMUFW: PM: Update/fix documentation Signed-off-by: Davorin Mista Acked-by: Jyotheeswar Reddy Mutthareddyvari --- lib/sw_apps/zynqmp_pmufw/src/pm_binding.c | 8 ++++++++ lib/sw_apps/zynqmp_pmufw/src/pm_callbacks.c | 2 ++ lib/sw_apps/zynqmp_pmufw/src/pm_core.c | 5 +++++ lib/sw_apps/zynqmp_pmufw/src/pm_master.c | 11 ++++++----- lib/sw_apps/zynqmp_pmufw/src/pm_slave.c | 8 +++++++- lib/sw_apps/zynqmp_pmufw/src/pm_slave.h | 2 ++ lib/sw_apps/zynqmp_pmufw/src/xpfw_version.h | 2 +- 7 files changed, 31 insertions(+), 7 deletions(-) diff --git a/lib/sw_apps/zynqmp_pmufw/src/pm_binding.c b/lib/sw_apps/zynqmp_pmufw/src/pm_binding.c index e92b0dc7..0c3315fb 100644 --- a/lib/sw_apps/zynqmp_pmufw/src/pm_binding.c +++ b/lib/sw_apps/zynqmp_pmufw/src/pm_binding.c @@ -129,6 +129,10 @@ done: * XPfw_PmWfiHandler() - Call from GPI2 interrupt handler to process sleep req * @srcMask Value read from GPI2 register which determines master requestor * + * @return Status of triggering sleep for a processor (XST_INVALID_PARAM if + * processor cannot be determined by srcMask, status of performing + * sleep operation otherwise) + * * @note Call from GPI2 interrupt routine to process sleep request. Must not * clear GPI2 interrupt before this function returns. */ @@ -161,6 +165,10 @@ done: * XPfw_PmWakeHandler() - Call from GPI1 interrupt to process wake request * @srcMask Value read from GPI1 register which determines interrupt source * + * @return Status of performing wake-up (XST_INVALID_PARAM if wake is a + * processor wake event but processor is not found, status of + * performing wake otherwise) + * * @note Call from GPI1 interrupt routine to process wake request. Must not * clear GPI1 interrupt before this function returns. * If the wake source is one of GIC wakes, source of the interrupt diff --git a/lib/sw_apps/zynqmp_pmufw/src/pm_callbacks.c b/lib/sw_apps/zynqmp_pmufw/src/pm_callbacks.c index 5420ba0e..3861117b 100644 --- a/lib/sw_apps/zynqmp_pmufw/src/pm_callbacks.c +++ b/lib/sw_apps/zynqmp_pmufw/src/pm_callbacks.c @@ -64,6 +64,7 @@ void PmAcknowledgeCb(const PmMaster* const master, const PmNodeId nodeId, /** * PmNotifyCb() - notifies a master about an event occurance + * @master Master to be notified about the event * @nodeId Node id regarding which the event is triggered * @event Event to informa master about * @oppoint Optionally event is related to some operating point change @@ -83,6 +84,7 @@ void PmNotifyCb(const PmMaster* const master, const PmNodeId nodeId, /** * PmInitSuspendCb() - request a master to suspend itself + * @master Master to be asked to suspend * @nodeId Node within the master to be suspended * @reason The reason of initiating the suspend * @latency Not supported diff --git a/lib/sw_apps/zynqmp_pmufw/src/pm_core.c b/lib/sw_apps/zynqmp_pmufw/src/pm_core.c index 57dc4979..e66242f0 100644 --- a/lib/sw_apps/zynqmp_pmufw/src/pm_core.c +++ b/lib/sw_apps/zynqmp_pmufw/src/pm_core.c @@ -532,16 +532,19 @@ static void PmSetWakeupSource(const PmMaster *const master, int status = XST_SUCCESS; PmRequirement* req = PmGetRequirementForSlave(master, sourceNode); + /* Is master allowed to use resource (slave)? */ if (NULL == req) { status = XST_PM_NO_ACCESS; goto done; } + /* Does slave have wake-up capability */ if (NULL == req->slave->wake) { status = XST_NO_FEATURE; goto done; } + /* Set/clear request info according to the enable flag */ if (0U == enable) { req->info &= ~PM_MASTER_WAKEUP_REQ_MASK; } else { @@ -765,7 +768,9 @@ void PmProcessRequest(const PmMaster *const master, /* Acknowledge if possible */ if (PM_PAYLOAD_ERR_API_ID != status) { u32 ack = PmRequestAcknowledge(pload); + /* If api does receive acknowledge */ if (REQUEST_ACK_NO != ack) { + /* Acknowledge that parameters are invalid */ PmAcknowledgeCb(master, NODE_UNKNOWN, XST_INVALID_PARAM, 0); } diff --git a/lib/sw_apps/zynqmp_pmufw/src/pm_master.c b/lib/sw_apps/zynqmp_pmufw/src/pm_master.c index ed4aa4eb..c9572a38 100644 --- a/lib/sw_apps/zynqmp_pmufw/src/pm_master.c +++ b/lib/sw_apps/zynqmp_pmufw/src/pm_master.c @@ -420,7 +420,7 @@ done: /** * PmRequirementUpdateScheduled() - Triggers the setting for scheduled - ( requirements + * requirements * @master Master which changed the state and whose scheduled requirements are * triggered * @swap Flag stating should current/default requirements be saved as next @@ -879,7 +879,7 @@ bool PmIsRequestedToSuspend(const PmMaster* const master) * PmRememberSuspendRequest() - Remembers the request suspend to acknowledge * @reqMaster Master which requested suspend * @respMaster Master whose suspend is requested and which should answer - * @ack FIXME: missing coumentation + * @ack Acknowledge flag received with the request suspend call * * @return Status of the operation of remembering the requested acknowledge */ @@ -912,10 +912,11 @@ int PmRememberSuspendRequest(const PmMaster* const reqMaster, } /** - * PmMasterSuspendAck() - Acknowledge to the suspend request of another - * master + * PmMasterSuspendAck() - Acknowledge to the suspend request of another master * @respMaster Master which is responding to the suspend request - * @response FIXME: Missing doc + * @response Status which is acknowledged as a response (whether the suspend + * operation is performed successfully) + * @return Status of the operation of sending acknowledge */ int PmMasterSuspendAck(PmMaster* const respMaster, const int response) { diff --git a/lib/sw_apps/zynqmp_pmufw/src/pm_slave.c b/lib/sw_apps/zynqmp_pmufw/src/pm_slave.c index 41088667..6c129bec 100644 --- a/lib/sw_apps/zynqmp_pmufw/src/pm_slave.c +++ b/lib/sw_apps/zynqmp_pmufw/src/pm_slave.c @@ -95,7 +95,7 @@ static PmSlave* const pmSlaves[] = { * capability * @slave Pointer to a slave whose requests are to be checked * - * @note Check all master requests and return : + * @return Based on checking all masters' requests function returns : * - true if there is at least one master requesting a capability * - false if no master is requesting anything from this slave */ @@ -300,6 +300,10 @@ int PmUpdateSlave(PmSlave* const slave) } if ((XST_SUCCESS == status) && (state != slave->node.currState)) { + /* + * Change state of a slave if state with required capabilities + * exists and slave is not already in that state. + */ status = PmSlaveChangeState(slave, state); } @@ -351,6 +355,8 @@ static int PmSlaveWakeMasters(PmSlave* const slave) * generated interrupt will be determined. Master targets are * determined based on requirements for slave's wake-up capability. * + * @return Status of performing wake-up. + * * @note If multiple slaves has simultaneously generated interrupts (wake * events), they will be all processed in this function). For FPD * GIC Proxy this is a must because reading 32-bit status register diff --git a/lib/sw_apps/zynqmp_pmufw/src/pm_slave.h b/lib/sw_apps/zynqmp_pmufw/src/pm_slave.h index 96f88444..b46fea87 100644 --- a/lib/sw_apps/zynqmp_pmufw/src/pm_slave.h +++ b/lib/sw_apps/zynqmp_pmufw/src/pm_slave.h @@ -120,6 +120,8 @@ typedef struct { /** * PmGicProxyProperties - Information about FPD GIC Proxy groups + * @baseAddr Base address of the group + * @pmuIrqBit Bit (mask) of the interrupt which the group generates to the PMU */ typedef struct { const u32 baseAddr; diff --git a/lib/sw_apps/zynqmp_pmufw/src/xpfw_version.h b/lib/sw_apps/zynqmp_pmufw/src/xpfw_version.h index 7fcf658e..f4f02d54 100644 --- a/lib/sw_apps/zynqmp_pmufw/src/xpfw_version.h +++ b/lib/sw_apps/zynqmp_pmufw/src/xpfw_version.h @@ -1,4 +1,4 @@ #ifndef ZYNQMP_XPFW_VERSION__H_ #define ZYNQMP_XPFW_VERSION__H_ - #define ZYNQMP_XPFW_VERSION "2015.1-swbeta2-42-gfc7dbb7b2e11" + #define ZYNQMP_XPFW_VERSION "2015.1-swbeta2-43-g4d76a0be427c" #endif