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>

1 files changed, 28 insertions, 18 deletions

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 {