ARM: ADIv5 symbol and comment cleanup

Instead of magic numbers, use their AP_REG_* constants.  Rename
the ROM address symbol as BASE to match ARM's documentation.

Comment various other symbols in the header; add some missing ones.
Remove an unused struct.  Add some doxygen for stuff including the
DAP structure and initialization.

Signed-off-by: David Brownell <dbrownell@users.sourceforge.net>

1 files changed, 37 insertions, 11 deletions

diff --git a/src/target/arm_adi_v5.h b/src/target/arm_adi_v5.h
index a78193c6..2a096844 100644
--- a/src/target/arm_adi_v5.h
+++ b/src/target/arm_adi_v5.h
@@ -23,6 +23,13 @@
 #ifndef ARM_ADI_V5_H
 #define ARM_ADI_V5_H
 
+/**
+ * @file
+ * This defines formats and data structures used to talk to ADIv5 entities.
+ * Those include a DAP, different types of Debug Port (DP), and memory mapped
+ * resources accessed through a MEM-AP.
+ */
+
 #include "arm_jtag.h"
 
 #define DAP_IR_DPACC	0xA
@@ -30,14 +37,22 @@
 
 #define DPAP_WRITE		0
 #define DPAP_READ		1
+
+/* A[3:0] for DP registers (for JTAG, stored in DPACC) */
 #define DP_ZERO			0
 #define DP_CTRL_STAT	0x4
 #define DP_SELECT		0x8
 #define DP_RDBUFF		0xC
 
+/* Fields of the DP's CTRL/STAT register */
 #define CORUNDETECT		(1 << 0)
 #define SSTICKYORUN		(1 << 1)
+/* 3:2 - transaction mode (e.g. pushed compare) */
 #define SSTICKYERR		(1 << 5)
+#define READOK			(1 << 6)
+#define WDATAERR		(1 << 7)
+/* 11:8 - mask lanes for pushed compare or verify ops */
+/* 21:12 - transaction counter */
 #define CDBGRSTREQ		(1 << 26)
 #define CDBGRSTACK		(1 << 27)
 #define CDBGPWRUPREQ	(1 << 28)
@@ -45,26 +60,35 @@
 #define CSYSPWRUPREQ	(1 << 30)
 #define CSYSPWRUPACK	(1 << 31)
 
-#define	AP_REG_CSW		0x00
+/* MEM-AP register addresses */
+/* TODO: rename as MEM_AP_REG_* */
+#define AP_REG_CSW		0x00
 #define AP_REG_TAR		0x04
 #define AP_REG_DRW		0x0C
 #define AP_REG_BD0		0x10
 #define AP_REG_BD1		0x14
 #define AP_REG_BD2		0x18
 #define AP_REG_BD3		0x1C
-#define AP_REG_DBGROMA	0xF8
+#define AP_REG_CFG		0xF4		/* big endian? */
+#define AP_REG_BASE		0xF8
+
+/* Generic AP register address */
 #define AP_REG_IDR		0xFC
 
+/* Fields of the MEM-AP's CSW register */
 #define CSW_8BIT		0
 #define CSW_16BIT		1
 #define CSW_32BIT		2
-
 #define CSW_ADDRINC_MASK	(3 << 4)
 #define CSW_ADDRINC_OFF		0
 #define CSW_ADDRINC_SINGLE	(1 << 4)
 #define CSW_ADDRINC_PACKED	(2 << 4)
-#define CSW_HPROT			(1 << 25)
-#define CSW_MASTER_DEBUG	(1 << 29)
+#define CSW_DEVICE_EN		(1 << 6)
+#define CSW_TRIN_PROG		(1 << 7)
+#define CSW_SPIDEN			(1 << 23)
+/* 30:24 - implementation-defined! */
+#define CSW_HPROT			(1 << 25)		/* ? */
+#define CSW_MASTER_DEBUG	(1 << 29)		/* ? */
 #define CSW_DBGSWENABLE		(1 << 31)
 
 /* transaction mode */
@@ -74,12 +98,14 @@
 /* Freerunning transactions with delays and overrun checking */
 #define TRANS_MODE_COMPOSITE	2
 
-struct swjdp_reg
-{
-	int addr;
-	struct arm_jtag *jtag_info;
-};
-
+/**
+ * This represents an ARM Debug Interface (v5) Debug Access Port (DAP).
+ * A DAP has two types of component:  one Debug Port (DP), which is a
+ * transport agent; and at least one Access Port (AP), controlling
+ * resource access.  Most common is a MEM-AP, for memory access.
+ *
+ * @todo Rename "swjdp_common" as "dap".  Use of SWJ-DP is optional!
+ */
 struct swjdp_common
 {
 	struct arm_jtag *jtag_info;