pd: Comment all flags

All of the flags in all layer needs comments of what the flags means
and a potential usage. all TC_FLAGS_*, PR_FLAGS_* and PRL_FLAGS_*

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

Signed-off-by: Sam Hurst <shurst@google.com>
Change-Id: I520daa841a61e36a8a6b394e0f96b198b16ad561
Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/1904148
Reviewed-by: Denis Brockus <dbrockus@chromium.org>
Commit-Queue: Denis Brockus <dbrockus@chromium.org>
Tested-by: Denis Brockus <dbrockus@chromium.org>

4 files changed, 104 insertions, 75 deletions

diff --git a/common/usbc/usb_pe_drp_sm.c b/common/usbc/usb_pe_drp_sm.c
index c6d528516f..5bc0bbe077 100644
--- a/common/usbc/usb_pe_drp_sm.c
+++ b/common/usbc/usb_pe_drp_sm.c
@@ -49,31 +49,44 @@
 #define PE_CLR_DPM_REQUEST(port, req) (pe[port].dpm_request &= ~(req))
 #define PE_CHK_DPM_REQUEST(port, req) (pe[port].dpm_request &   (req))
 
-/* Policy Engine Layer Flags */
-#define PE_FLAGS_PD_CONNECTION                  BIT(0)
-#define PE_FLAGS_ACCEPT                         BIT(1)
-#define PE_FLAGS_PS_READY                       BIT(2)
-#define PE_FLAGS_PROTOCOL_ERROR                 BIT(3)
-#define PE_FLAGS_MODAL_OPERATION                BIT(4)
-#define PE_FLAGS_TX_COMPLETE                    BIT(5)
-#define PE_FLAGS_MSG_RECEIVED                   BIT(6)
-#define PE_FLAGS_HARD_RESET_PENDING             BIT(7)
-#define PE_FLAGS_WAIT                           BIT(8)
-#define PE_FLAGS_EXPLICIT_CONTRACT              BIT(9)
-#define PE_FLAGS_SNK_WAIT_CAP_TIMEOUT           BIT(10)
-#define PE_FLAGS_PS_TRANSITION_TIMEOUT          BIT(11)
-#define PE_FLAGS_INTERRUPTIBLE_AMS              BIT(12)
-#define PE_FLAGS_PS_RESET_COMPLETE              BIT(13)
-#define PE_FLAGS_SEND_SVDM                      BIT(14)
-#define PE_FLAGS_VCONN_SWAP_COMPLETE            BIT(15)
-#define PE_FLAGS_DISCOVER_PORT_IDENTITY_DONE    BIT(16)
-#define PE_FLAGS_DISCOVER_VDM_IDENTITY_DONE     BIT(17)
-#define PE_FLAGS_RUN_SOURCE_START_TIMER         BIT(19)
-#define PE_FLAGS_VDM_REQUEST_BUSY               BIT(20)
-#define PE_FLAGS_VDM_REQUEST_NAKED              BIT(21)
-#define PE_FLAGS_FAST_ROLE_SWAP_PATH            BIT(22)/* FRS/PRS Exec Path */
-#define PE_FLAGS_FAST_ROLE_SWAP_ENABLED         BIT(23)/* FRS Listening State */
-#define PE_FLAGS_FAST_ROLE_SWAP_SIGNALED        BIT(24)/* FRS PPC/TCPC Signal */
+/*
+ * 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) /* 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 */
+#define PE_FLAGS_PS_TRANSITION_TIMEOUT       BIT(11)
+/* Interruptible Atomic Message Sequence */
+#define PE_FLAGS_INTERRUPTIBLE_AMS           BIT(12)
+/* Power Supply reset complete */
+#define PE_FLAGS_PS_RESET_COMPLETE           BIT(13)
+/* When set, triggers a Structured Vendor Defined Message transmission */
+#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 */
+#define PE_FLAGS_DISCOVER_PORT_IDENTITY_DONE BIT(16)
+/* Starts the Swap Source Start timer when set */
+#define PE_FLAGS_RUN_SOURCE_START_TIMER      BIT(17)
+/* Set during the port discovery if the 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 */
+#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 */
+/* When set, no more discover identity messages are sent to SOP' */
+#define PE_FLAGS_DISCOVER_VDM_IDENTITY_DONE  BIT(23)
 
 /* 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 a700ee6f2a..74f2864533 100644
--- a/common/usbc/usb_prl_sm.c
+++ b/common/usbc/usb_prl_sm.c
@@ -53,17 +53,23 @@
 #define PDMSG_CHK_FLAG(port, flag) (pdmsg[port].flags & (flag))
 
 /* Protocol Layer Flags */
-#define PRL_FLAGS_TX_COMPLETE             BIT(0)
-#define PRL_FLAGS_START_AMS               BIT(1)
-#define PRL_FLAGS_END_AMS                 BIT(2)
-#define PRL_FLAGS_TX_ERROR                BIT(3)
-#define PRL_FLAGS_PE_HARD_RESET           BIT(4)
-#define PRL_FLAGS_HARD_RESET_COMPLETE     BIT(5)
-#define PRL_FLAGS_PORT_PARTNER_HARD_RESET BIT(6)
+/*
+ * NOTE:
+ *	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 */
 #define PRL_FLAGS_MSG_XMIT                BIT(7)
-#define PRL_FLAGS_MSG_RECEIVED            BIT(8)
-#define PRL_FLAGS_ABORT                   BIT(9)
-#define PRL_FLAGS_CHUNKING                BIT(10)
+#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 */
 
 /* 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 a6c58ce843..1e393fe4bf 100644
--- a/common/usbc/usb_tc_drp_acc_trysrc_sm.c
+++ b/common/usbc/usb_tc_drp_acc_trysrc_sm.c
@@ -34,28 +34,28 @@
 #endif
 
 /* Type-C Layer Flags */
-#define TC_FLAGS_VCONN_ON                 BIT(0)
-#define TC_FLAGS_TS_DTS_PARTNER           BIT(1)
-#define TC_FLAGS_VBUS_NEVER_LOW           BIT(2)
-#define TC_FLAGS_LPM_TRANSITION           BIT(3)
-#define TC_FLAGS_LPM_ENGAGED              BIT(4)
-#define TC_FLAGS_LPM_REQUESTED            BIT(5)
-#define TC_FLAGS_CTVPD_DETECTED           BIT(6)
-#define TC_FLAGS_REQUEST_VC_SWAP_ON       BIT(7)
-#define TC_FLAGS_REQUEST_VC_SWAP_OFF      BIT(8)
-#define TC_FLAGS_REJECT_VCONN_SWAP        BIT(9)
-#define TC_FLAGS_REQUEST_PR_SWAP          BIT(10)
-#define TC_FLAGS_REQUEST_DR_SWAP          BIT(11)
-#define TC_FLAGS_POWER_OFF_SNK            BIT(12)
-#define TC_FLAGS_PARTNER_EXTPOWER         BIT(13)
-#define TC_FLAGS_PARTNER_DR_DATA          BIT(14)
-#define TC_FLAGS_PARTNER_DR_POWER         BIT(15)
-#define TC_FLAGS_PARTNER_PD_CAPABLE         BIT(16)
-#define TC_FLAGS_HARD_RESET               BIT(17)
-#define TC_FLAGS_PARTNER_USB_COMM         BIT(18)
-#define TC_FLAGS_PR_SWAP_IN_PROGRESS      BIT(19)
-#define TC_FLAGS_DO_PR_SWAP               BIT(20)
-#define TC_FLAGS_DISC_IDENT_IN_PROGRESS   BIT(21)
+#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 */
 
 enum ps_reset_sequence {
 	PS_STATE0,
diff --git a/test/usb_pe.h b/test/usb_pe.h
index f54040e6a6..71eb16ca1b 100644
--- a/test/usb_pe.h
+++ b/test/usb_pe.h
@@ -32,30 +32,40 @@
  */
 
 /* 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)
-#define PE_FLAGS_PS_READY                    BIT(2)
-#define PE_FLAGS_PROTOCOL_ERROR              BIT(3)
-#define PE_FLAGS_MODAL_OPERATION             BIT(4)
-#define PE_FLAGS_TX_COMPLETE                 BIT(5)
-#define PE_FLAGS_MSG_RECEIVED                BIT(6)
-#define PE_FLAGS_HARD_RESET_PENDING          BIT(7)
-#define PE_FLAGS_WAIT                        BIT(8)
-#define PE_FLAGS_EXPLICIT_CONTRACT           BIT(9)
-#define PE_FLAGS_SNK_WAIT_CAP_TIMEOUT        BIT(10)
+#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 */
 #define PE_FLAGS_PS_TRANSITION_TIMEOUT       BIT(11)
+/* Interruptible Atomic Message Sequence */
 #define PE_FLAGS_INTERRUPTIBLE_AMS           BIT(12)
+/* Power Supply reset complete */
 #define PE_FLAGS_PS_RESET_COMPLETE           BIT(13)
+/* When set, triggers a Structured Vendor Defined Message transmission */
 #define PE_FLAGS_SEND_SVDM                   BIT(14)
-#define PE_FLAGS_VCONN_SWAP_COMPLETE         BIT(15)
+#define PE_FLAGS_VCONN_SWAP_COMPLETE         BIT(15)/* VCONN Swap complete */
+/* When set, no more discover identity messages are sent to the port partner */
 #define PE_FLAGS_DISCOVER_PORT_IDENTITY_DONE BIT(16)
-#define PE_FLAGS_DISCOVER_VDM_IDENTITY_DONE  BIT(17)
-#define PE_FLAGS_RUN_SOURCE_START_TIMER      BIT(19)
-#define PE_FLAGS_VDM_REQUEST_BUSY            BIT(20)
-#define PE_FLAGS_VDM_REQUEST_NAKED           BIT(21)
-#define PE_FLAGS_FAST_ROLE_SWAP_PATH         BIT(22)/* FRS/PRS Exec Path */
-#define PE_FLAGS_FAST_ROLE_SWAP_ENABLED      BIT(23)/* FRS Listening State */
-#define PE_FLAGS_FAST_ROLE_SWAP_SIGNALED     BIT(24)/* FRS PPC/TCPC Signal */
+/* Starts the Swap Source Start timer when set */
+#define PE_FLAGS_RUN_SOURCE_START_TIMER      BIT(17)
+/* Set during the port discovery if the 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 */
+#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 */
+/* When set, no more discover identity messages are sent to SOP' */
+#define PE_FLAGS_DISCOVER_VDM_IDENTITY_DONE  BIT(23)
 
 /* List of all Policy Engine level states */
 enum usb_pe_state {