pd: Clarify flag comments

BRANCH=none
BUG=b:141563840
TEST=make -j buildall

Change-Id: Iaff605f5d93ccce26aec4d9e33be78017c7b9231
Signed-off-by: Denis Brockus <dbrockus@chromium.org>
Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/1906194
Reviewed-by: Jett Rink <jettrink@chromium.org>

4 files changed, 142 insertions, 78 deletions

diff --git a/common/usbc/usb_pe_drp_sm.c b/common/usbc/usb_pe_drp_sm.c
index 6bf72d3bff..7390a5e78b 100644
--- a/common/usbc/usb_pe_drp_sm.c
+++ b/common/usbc/usb_pe_drp_sm.c
@@ -55,36 +55,50 @@
 
 /* At least one successful PD communication packet received from port partner */
 #define PE_FLAGS_PD_CONNECTION               BIT(0)
-#define PE_FLAGS_ACCEPT                      BIT(1) /* Got accept message */
-#define PE_FLAGS_PS_READY                    BIT(2) /* Power Supply Ready */
-#define PE_FLAGS_PROTOCOL_ERROR              BIT(3) /* Received Protocol Err */
-#define PE_FLAGS_MODAL_OPERATION             BIT(4) /* Modal operation set */
-#define PE_FLAGS_TX_COMPLETE                 BIT(5) /* Transmit complete */
-#define PE_FLAGS_MSG_RECEIVED                BIT(6) /* Message Received */
-#define PE_FLAGS_HARD_RESET_PENDING          BIT(7) /* Hard reset pending */
-#define PE_FLAGS_WAIT                        BIT(8) /* Wait before msg resend */
-#define PE_FLAGS_EXPLICIT_CONTRACT           BIT(9) /* PD contract in place */
-#define PE_FLAGS_SNK_WAIT_CAP_TIMEOUT        BIT(10)/* Snk caps timeout */
-/* Power Supply transition timeout */
+/* Accept message received from port partner */
+#define PE_FLAGS_ACCEPT                      BIT(1)
+/* Power Supply Ready message received from port partner */
+#define PE_FLAGS_PS_READY                    BIT(2)
+/* Protocol Error was determined based on error recovery current state */
+#define PE_FLAGS_PROTOCOL_ERROR              BIT(3)
+/* Set if we are in Modal Operation */
+#define PE_FLAGS_MODAL_OPERATION             BIT(4)
+/* A message we requested to be sent has been transmitted */
+#define PE_FLAGS_TX_COMPLETE                 BIT(5)
+/* A message sent by a port partner has been received */
+#define PE_FLAGS_MSG_RECEIVED                BIT(6)
+/* A hard reset has been requested but has not been sent, not currently used */
+#define PE_FLAGS_HARD_RESET_PENDING          BIT(7)
+/* Port partner sent a Wait message. Wait before we resend our message */
+#define PE_FLAGS_WAIT                        BIT(8)
+/* An explicit contract is in place with our port partner */
+#define PE_FLAGS_EXPLICIT_CONTRACT           BIT(9)
+/* Waiting for Sink Capabailities timed out.  Used for retry error handling */
+#define PE_FLAGS_SNK_WAIT_CAP_TIMEOUT        BIT(10)
+/* Power Supply voltage/current transition timed out */
 #define PE_FLAGS_PS_TRANSITION_TIMEOUT       BIT(11)
-/* Interruptible Atomic Message Sequence */
+/* Flag to note current Atomic Message Sequence is interruptible */
 #define PE_FLAGS_INTERRUPTIBLE_AMS           BIT(12)
-/* Power Supply reset complete */
+/* Flag to note Power Supply reset has completed */
 #define PE_FLAGS_PS_RESET_COMPLETE           BIT(13)
-/* When set, triggers a Structured Vendor Defined Message transmission */
+/* Flag to note a Structured Vendor Defined Message should be sent */
 #define PE_FLAGS_SEND_SVDM                   BIT(14)
-#define PE_FLAGS_VCONN_SWAP_COMPLETE         BIT(15)/* VCONN Swap complete */
-/* When set, no more discover identity messages are sent to the port partner */
+/* VCONN swap operation has completed */
+#define PE_FLAGS_VCONN_SWAP_COMPLETE         BIT(15)
+/* Flag to note no more discover identity messages should be sent */
 #define PE_FLAGS_DISCOVER_PORT_IDENTITY_DONE BIT(16)
-/* Starts the Swap Source Start timer when set */
+/* Flag to note Swap Source Start timer should be set at PE_SRC_Startup entry */
 #define PE_FLAGS_RUN_SOURCE_START_TIMER      BIT(17)
-/* Set during the port discovery if the port partner replied with busy */
+/* Flag to note Port Discovery port partner replied with BUSY */
 #define PE_FLAGS_VDM_REQUEST_BUSY            BIT(18)
-/* Set during the port discovery if the port partner replied with nak */
+/* Flag to note Port Discovery port partner replied with NAK */
 #define PE_FLAGS_VDM_REQUEST_NAKED           BIT(19)
-#define PE_FLAGS_FAST_ROLE_SWAP_PATH         BIT(20)/* FRS/PRS Exec Path */
-#define PE_FLAGS_FAST_ROLE_SWAP_ENABLED      BIT(21)/* FRS Listening State */
-#define PE_FLAGS_FAST_ROLE_SWAP_SIGNALED     BIT(22)/* FRS PPC/TCPC Signal */
+/* Flag to note FRS/PRS context in shared state machine path */
+#define PE_FLAGS_FAST_ROLE_SWAP_PATH         BIT(20)
+/* Flag to note if FRS listening is enabled */
+#define PE_FLAGS_FAST_ROLE_SWAP_ENABLED      BIT(21)
+/* Flag to note TCPC passed on FRS signal from port partner */
+#define PE_FLAGS_FAST_ROLE_SWAP_SIGNALED     BIT(22)
 
 /* 6.7.3 Hard Reset Counter */
 #define N_HARD_RESET_COUNT 2
diff --git a/common/usbc/usb_prl_sm.c b/common/usbc/usb_prl_sm.c
index 74f2864533..00460d86cb 100644
--- a/common/usbc/usb_prl_sm.c
+++ b/common/usbc/usb_prl_sm.c
@@ -58,18 +58,28 @@
  *	These flags are used in multiple state machines and could have
  *	different meanings in each state machine.
  */
-#define PRL_FLAGS_TX_COMPLETE             BIT(0) /* Transmit complete */
-#define PRL_FLAGS_START_AMS               BIT(1) /* Start AMS */
-#define PRL_FLAGS_END_AMS                 BIT(2) /* End AMS */
-#define PRL_FLAGS_TX_ERROR                BIT(3) /* TX error occurred */
-#define PRL_FLAGS_PE_HARD_RESET           BIT(4) /* PE triggered Hard Reset */
-#define PRL_FLAGS_HARD_RESET_COMPLETE     BIT(5) /* Hard reset complete */
-#define PRL_FLAGS_PORT_PARTNER_HARD_RESET BIT(6) /* Partner sent hard reset */
-/* Triggers a message transmission */
+/* Flag to note message transmission completed */
+#define PRL_FLAGS_TX_COMPLETE             BIT(0)
+/* Flag to note an AMS is being started by PE */
+#define PRL_FLAGS_START_AMS               BIT(1)
+/* Flag to note an AMS is being stopped by PE */
+#define PRL_FLAGS_END_AMS                 BIT(2)
+/* Flag to note transmission error occurred */
+#define PRL_FLAGS_TX_ERROR                BIT(3)
+/* Flag to note PE triggered a hard reset */
+#define PRL_FLAGS_PE_HARD_RESET           BIT(4)
+/* Flag to note hard reset has completed */
+#define PRL_FLAGS_HARD_RESET_COMPLETE     BIT(5)
+/* Flag to note port partner sent a hard reset */
+#define PRL_FLAGS_PORT_PARTNER_HARD_RESET BIT(6)
+/* Flag to note a message transmission has been requested */
 #define PRL_FLAGS_MSG_XMIT                BIT(7)
-#define PRL_FLAGS_MSG_RECEIVED            BIT(8) /* Message was received */
-#define PRL_FLAGS_ABORT                   BIT(9) /* Abort sending message */
-#define PRL_FLAGS_CHUNKING                BIT(10)/* Use message chunking */
+/* Flag to note a message was received */
+#define PRL_FLAGS_MSG_RECEIVED            BIT(8)
+/* Flag to note aborting current TX message, not currently set */
+#define PRL_FLAGS_ABORT                   BIT(9)
+/* Flag to note current TX message uses chunking */
+#define PRL_FLAGS_CHUNKING                BIT(10)
 
 /* PD counter definitions */
 #define PD_MESSAGE_ID_COUNT 7
diff --git a/common/usbc/usb_tc_drp_acc_trysrc_sm.c b/common/usbc/usb_tc_drp_acc_trysrc_sm.c
index 1e393fe4bf..61208f0edb 100644
--- a/common/usbc/usb_tc_drp_acc_trysrc_sm.c
+++ b/common/usbc/usb_tc_drp_acc_trysrc_sm.c
@@ -34,28 +34,51 @@
 #endif
 
 /* Type-C Layer Flags */
-#define TC_FLAGS_VCONN_ON               BIT(0) /* VCONN is being sourced */
-#define TC_FLAGS_TS_DTS_PARTNER         BIT(1) /* Partner has rp/rp or rd/rd */
-#define TC_FLAGS_VBUS_NEVER_LOW         BIT(2) /* VBUS input never been low */
-#define TC_FLAGS_LPM_TRANSITION         BIT(3) /* Tracks HW LPM transition */
-#define TC_FLAGS_LPM_ENGAGED            BIT(4) /* Tracks HW LPM state */
-#define TC_FLAGS_LPM_REQUESTED          BIT(5) /* Tracks SW LPM state */
-#define TC_FLAGS_CTVPD_DETECTED         BIT(6) /* CTVPD has been detected */
-#define TC_FLAGS_REQUEST_VC_SWAP_ON     BIT(7) /* Requests swap to VCONN on */
-#define TC_FLAGS_REQUEST_VC_SWAP_OFF    BIT(8) /* Requests swap to VCONN off */
-#define TC_FLAGS_REJECT_VCONN_SWAP      BIT(9) /* Rejects VCONN swap */
-#define TC_FLAGS_REQUEST_PR_SWAP        BIT(10)/* Requests a power role swap */
-#define TC_FLAGS_REQUEST_DR_SWAP        BIT(11)/* Requests a data role swap */
-#define TC_FLAGS_POWER_OFF_SNK          BIT(12)/* Powers off the sink */
-#define TC_FLAGS_PARTNER_EXTPOWER       BIT(13)/* Port partner has ext. PWR */
-#define TC_FLAGS_PARTNER_DR_DATA        BIT(14)/* Port partner is DR data */
-#define TC_FLAGS_PARTNER_DR_POWER       BIT(15)/* Port partner is DR power */
-#define TC_FLAGS_PARTNER_PD_CAPABLE     BIT(16)/* Port partner is PD capable */
-#define TC_FLAGS_HARD_RESET             BIT(17)/* Triggers a hard reset */
-#define TC_FLAGS_PARTNER_USB_COMM       BIT(18)/* port partner is USB comms */
-#define TC_FLAGS_PR_SWAP_IN_PROGRESS    BIT(19)/* PR swap in progress */
-#define TC_FLAGS_DO_PR_SWAP             BIT(20)/* Triggers a PR swap */
-#define TC_FLAGS_DISC_IDENT_IN_PROGRESS BIT(21)/* Discover Ident. in progress */
+
+/* Flag to note we are sourcing VCONN */
+#define TC_FLAGS_VCONN_ON               BIT(0)
+/* Flag to note port partner has Rp/Rp or Rd/Rd */
+#define TC_FLAGS_TS_DTS_PARTNER         BIT(1)
+/* Flag to note VBus input has never been low */
+#define TC_FLAGS_VBUS_NEVER_LOW         BIT(2)
+/* Flag to note Low Power Mode transition is currently happening */
+#define TC_FLAGS_LPM_TRANSITION         BIT(3)
+/* Flag to note Low Power Mode is currently on */
+#define TC_FLAGS_LPM_ENGAGED            BIT(4)
+/* Flag to note Low Power Mode is requested. Not currently used */
+#define TC_FLAGS_LPM_REQUESTED          BIT(5)
+/* Flag to note CVTPD has been detected */
+#define TC_FLAGS_CTVPD_DETECTED         BIT(6)
+/* Flag to note request to swap to VCONN on */
+#define TC_FLAGS_REQUEST_VC_SWAP_ON     BIT(7)
+/* Flag to note request to swap to VCONN off */
+#define TC_FLAGS_REQUEST_VC_SWAP_OFF    BIT(8)
+/* Flag to note request to swap VCONN is being rejected */
+#define TC_FLAGS_REJECT_VCONN_SWAP      BIT(9)
+/* Flag to note request to power role swap */
+#define TC_FLAGS_REQUEST_PR_SWAP        BIT(10)
+/* Flag to note request to data role swap */
+#define TC_FLAGS_REQUEST_DR_SWAP        BIT(11)
+/* Flag to note request to power off sink */
+#define TC_FLAGS_POWER_OFF_SNK          BIT(12)
+/* Flag to note port partner has external power */
+#define TC_FLAGS_PARTNER_EXTPOWER       BIT(13)
+/* Flag to note port partner is Dual Role Data */
+#define TC_FLAGS_PARTNER_DR_DATA        BIT(14)
+/* Flag to note port partner is Dual Role Power */
+#define TC_FLAGS_PARTNER_DR_POWER       BIT(15)
+/* Flag to note port partner is Power Delivery capable */
+#define TC_FLAGS_PARTNER_PD_CAPABLE     BIT(16)
+/* Flag to note hard reset has been triggered */
+#define TC_FLAGS_HARD_RESET             BIT(17)
+/* Flag to note port partner is USB comms capable */
+#define TC_FLAGS_PARTNER_USB_COMM       BIT(18)
+/* Flag to note we are currently performing PR Swap */
+#define TC_FLAGS_PR_SWAP_IN_PROGRESS    BIT(19)
+/* Flag to note we need to perform PR Swap */
+#define TC_FLAGS_DO_PR_SWAP             BIT(20)
+/* Flag to note we are performing Discover Identity */
+#define TC_FLAGS_DISC_IDENT_IN_PROGRESS BIT(21)
 
 enum ps_reset_sequence {
 	PS_STATE0,
diff --git a/test/usb_pe.h b/test/usb_pe.h
index d384ae2e47..e9dc58925c 100644
--- a/test/usb_pe.h
+++ b/test/usb_pe.h
@@ -31,39 +31,56 @@
  * be changed here as well.
  */
 
-/* Policy Engine Layer Flags */
+/*
+ * Policy Engine Layer Flags
+ */
+
 /* At least one successful PD communication packet received from port partner */
 #define PE_FLAGS_PD_CONNECTION               BIT(0)
-#define PE_FLAGS_ACCEPT                      BIT(1) /* Got accept message */
-#define PE_FLAGS_PS_READY                    BIT(2) /* Power Supply Ready */
-#define PE_FLAGS_PROTOCOL_ERROR              BIT(3) /* Received Protocol Err */
-#define PE_FLAGS_MODAL_OPERATION             BIT(4) /* Modal operation set */
-#define PE_FLAGS_TX_COMPLETE                 BIT(5) /* Transmit complete */
-#define PE_FLAGS_MSG_RECEIVED                BIT(6) /* Messaged Received */
-#define PE_FLAGS_HARD_RESET_PENDING          BIT(7) /* Hard reset pending */
-#define PE_FLAGS_WAIT                        BIT(8) /* Wait before msg resend */
-#define PE_FLAGS_EXPLICIT_CONTRACT           BIT(9) /* PD contract in place */
-#define PE_FLAGS_SNK_WAIT_CAP_TIMEOUT        BIT(10)/* Snk caps timeout */
-/* Power Supply transition timeout */
+/* Accept message received from port partner */
+#define PE_FLAGS_ACCEPT                      BIT(1)
+/* Power Supply Ready message received from port partner */
+#define PE_FLAGS_PS_READY                    BIT(2)
+/* Protocol Error was determined based on error recovery current state */
+#define PE_FLAGS_PROTOCOL_ERROR              BIT(3)
+/* Set if we are in Modal Operation */
+#define PE_FLAGS_MODAL_OPERATION             BIT(4)
+/* A message we requested to be sent has been transmitted */
+#define PE_FLAGS_TX_COMPLETE                 BIT(5)
+/* A message sent by a port partner has been received */
+#define PE_FLAGS_MSG_RECEIVED                BIT(6)
+/* A hard reset has been requested but has not been sent, not currently used */
+#define PE_FLAGS_HARD_RESET_PENDING          BIT(7)
+/* Port partner sent a Wait message. Wait before we resend our message */
+#define PE_FLAGS_WAIT                        BIT(8)
+/* An explicit contract is in place with our port partner */
+#define PE_FLAGS_EXPLICIT_CONTRACT           BIT(9)
+/* Waiting for Sink Capabailities timed out.  Used for retry error handling */
+#define PE_FLAGS_SNK_WAIT_CAP_TIMEOUT        BIT(10)
+/* Power Supply voltage/current transition timed out */
 #define PE_FLAGS_PS_TRANSITION_TIMEOUT       BIT(11)
-/* Interruptible Atomic Message Sequence */
+/* Flag to note current Atomic Message Sequence is interruptible */
 #define PE_FLAGS_INTERRUPTIBLE_AMS           BIT(12)
-/* Power Supply reset complete */
+/* Flag to note Power Supply reset has completed */
 #define PE_FLAGS_PS_RESET_COMPLETE           BIT(13)
-/* When set, triggers a Structured Vendor Defined Message transmission */
+/* Flag to note a Structured Vendor Defined Message should be sent */
 #define PE_FLAGS_SEND_SVDM                   BIT(14)
-#define PE_FLAGS_VCONN_SWAP_COMPLETE         BIT(15)/* VCONN Swap complete */
-/* When set, no more discover identity messages are sent to the port partner */
+/* VCONN swap operation has completed */
+#define PE_FLAGS_VCONN_SWAP_COMPLETE         BIT(15)
+/* Flag to note no more discover identity messages are sent to port partner */
 #define PE_FLAGS_DISCOVER_PORT_IDENTITY_DONE BIT(16)
-/* Starts the Swap Source Start timer when set */
+/* Flag to note Swap Source Start timer should be set at PE_SRC_Startup entry */
 #define PE_FLAGS_RUN_SOURCE_START_TIMER      BIT(17)
-/* Set during the port discovery if the port partner replied with busy */
+/* Flag to note Port Discovery port partner replied with BUSY */
 #define PE_FLAGS_VDM_REQUEST_BUSY            BIT(18)
-/* Set during the port discovery if the port partner replied with nak */
+/* Flag to note Port Discovery port partner replied with NAK */
 #define PE_FLAGS_VDM_REQUEST_NAKED           BIT(19)
-#define PE_FLAGS_FAST_ROLE_SWAP_PATH         BIT(20)/* FRS/PRS Exec Path */
-#define PE_FLAGS_FAST_ROLE_SWAP_ENABLED      BIT(21)/* FRS Listening State */
-#define PE_FLAGS_FAST_ROLE_SWAP_SIGNALED     BIT(22)/* FRS PPC/TCPC Signal */
+/* Flag to note FRS/PRS context in shared state machine path */
+#define PE_FLAGS_FAST_ROLE_SWAP_PATH         BIT(20)
+/* Flag to note if FRS listening is enabled */
+#define PE_FLAGS_FAST_ROLE_SWAP_ENABLED      BIT(21)
+/* Flag to note TCPC passed on FRS signal from port partner */
+#define PE_FLAGS_FAST_ROLE_SWAP_SIGNALED     BIT(22)
 
 /* List of all Policy Engine level states */
 enum usb_pe_state {