PMUFW: PM: Update/fix documentation

Signed-off-by: Davorin Mista <davorin.mista@aggios.com>
Acked-by: Jyotheeswar Reddy Mutthareddyvari <jyothee@xilinx.com>

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

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

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);
 			}

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

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

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;

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