From e60c164cdb50a0aa268165e57de0a4cd0d58fcdf Mon Sep 17 00:00:00 2001 From: David Brownell Date: Sat, 2 Jan 2010 15:53:03 -0800 Subject: [PATCH] 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 --- src/target/arm_adi_v5.c | 75 +++++++++++++++++++++++++++++++---------- src/target/arm_adi_v5.h | 48 ++++++++++++++++++++------ 2 files changed, 94 insertions(+), 29 deletions(-) diff --git a/src/target/arm_adi_v5.c b/src/target/arm_adi_v5.c index 6ca50ab7c..59f5638ec 100644 --- a/src/target/arm_adi_v5.c +++ b/src/target/arm_adi_v5.c @@ -7,7 +7,7 @@ * * * Copyright (C) 2009 by Oyvind Harboe * * oyvind.harboe@zylin.com * - * * + * * * This program is free software; you can redistribute it and/or modify * * it under the terms of the GNU General Public License as published by * * the Free Software Foundation; either version 2 of the License, or * @@ -23,16 +23,34 @@ * Free Software Foundation, Inc., * * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * ***************************************************************************/ -/*************************************************************************** - * * - * This file implements support for the ARM Debug Interface v5 (ADI_V5) * - * * - * ARM(tm) Debug Interface v5 Architecture Specification ARM IHI 0031A * - * * - * CoreSight(tm) DAP-Lite TRM, ARM DDI 0316D * - * Cortex-M3(tm) TRM, ARM DDI 0337G * - * * -***************************************************************************/ + +/** + * @file + * This file implements support for the ARM Debug Interface version 5 (ADIv5) + * debugging architecture. Compared with previous versions, this includes + * a low pin-count Serial Wire Debug (SWD) alternative to JTAG for message + * transport, and focusses on memory mapped resources as defined by the + * CoreSight architecture. + * + * A key concept in ADIv5 is the Debug Access Port, or DAP. A DAP has two + * basic components: a Debug Port (DP) transporting messages to and from a + * debugger, and an Access Port (AP) accessing resources. Three types of DP + * are defined. One uses only JTAG for communication, and is called JTAG-DP. + * One uses only SWD for communication, and is called SW-DP. The third can + * use either SWD or JTAG, and is called SWJ-DP. The most common type of AP + * is used to access memory mapped resources and is called a MEM-AP. Also a + * JTAG-AP is also defined, bridging to JTAG resources; those are uncommon. + */ + +/* + * Relevant specifications from ARM include: + * + * ARM(tm) Debug Interface v5 Architecture Specification ARM IHI 0031A + * CoreSight(tm) v1.0 Architecture Specification ARM IHI 0029B + * + * CoreSight(tm) DAP-Lite TRM, ARM DDI 0316D + * Cortex-M3(tm) TRM, ARM DDI 0337G + */ #ifdef HAVE_CONFIG_H #include "config.h" @@ -950,6 +968,13 @@ int mem_ap_read_buf_u8(struct swjdp_common *swjdp, uint8_t *buffer, int count, u return retval; } +/** + * Initialize a DAP. + * + * @todo Rename this. We also need an initialization scheme which account + * for SWD transports not just JTAG; that will need to address differences + * in layering. (JTAG is useful without any debug target; but not SWD.) + */ int ahbap_debugport_init(struct swjdp_common *swjdp) { uint32_t idreg, romaddr, dummy; @@ -959,9 +984,17 @@ int ahbap_debugport_init(struct swjdp_common *swjdp) LOG_DEBUG(" "); + /* Default MEM-AP setup. + * + * REVISIT AP #0 may be an inappropriate default for this. + * Should we probe, or receve a hint from the caller? + * Presumably we can ignore the possibility of multiple APs. + */ swjdp->apsel = 0; swjdp->ap_csw_value = -1; swjdp->ap_tar_value = -1; + + /* DP initialization */ swjdp->trans_mode = TRANS_MODE_ATOMIC; dap_dp_read_reg(swjdp, &dummy, DP_CTRL_STAT); dap_dp_write_reg(swjdp, SSTICKYERR, DP_CTRL_STAT); @@ -999,8 +1032,14 @@ int ahbap_debugport_init(struct swjdp_common *swjdp) dap_dp_write_reg(swjdp, swjdp->dp_ctrl_stat, DP_CTRL_STAT); dap_dp_read_reg(swjdp, &dummy, DP_CTRL_STAT); - dap_ap_read_reg_u32(swjdp, 0xFC, &idreg); - dap_ap_read_reg_u32(swjdp, 0xF8, &romaddr); + /* + * REVISIT this isn't actually *initializing* anything in an AP, + * and doesn't care if it's a MEM-AP at all (much less AHB-AP). + * Should it? If the ROM address is valid, is this the right + * place to scan the table and do any topology detection? + */ + dap_ap_read_reg_u32(swjdp, AP_REG_IDR, &idreg); + dap_ap_read_reg_u32(swjdp, AP_REG_BASE, &romaddr); LOG_DEBUG("AHB-AP ID Register 0x%" PRIx32 ", Debug ROM Address 0x%" PRIx32 "", idreg, romaddr); @@ -1035,8 +1074,8 @@ int dap_info_command(struct command_context *cmd_ctx, struct swjdp_common *swjdp apselold = swjdp->apsel; dap_ap_select(swjdp, apsel); - dap_ap_read_reg_u32(swjdp, 0xF8, &dbgbase); - dap_ap_read_reg_u32(swjdp, 0xFC, &apid); + dap_ap_read_reg_u32(swjdp, AP_REG_BASE, &dbgbase); + dap_ap_read_reg_u32(swjdp, AP_REG_IDR, &apid); swjdp_transaction_endcheck(swjdp); /* Now we read ROM table ID registers, ref. ARM IHI 0029B sec */ mem_ap = ((apid&0x10000) && ((apid&0x0F) != 0)); @@ -1387,7 +1426,7 @@ DAP_COMMAND_HANDLER(dap_baseaddr_command) if (apselsave != apsel) dap_ap_select(swjdp, apsel); - dap_ap_read_reg_u32(swjdp, 0xF8, &baseaddr); + dap_ap_read_reg_u32(swjdp, AP_REG_BASE, &baseaddr); retval = swjdp_transaction_endcheck(swjdp); command_print(CMD_CTX, "0x%8.8" PRIx32, baseaddr); @@ -1436,7 +1475,7 @@ DAP_COMMAND_HANDLER(dap_apsel_command) } dap_ap_select(swjdp, apsel); - dap_ap_read_reg_u32(swjdp, 0xFC, &apid); + dap_ap_read_reg_u32(swjdp, AP_REG_IDR, &apid); retval = swjdp_transaction_endcheck(swjdp); command_print(CMD_CTX, "ap %" PRIi32 " selected, identification register 0x%8.8" PRIx32, apsel, apid); @@ -1464,7 +1503,7 @@ DAP_COMMAND_HANDLER(dap_apid_command) if (apselsave != apsel) dap_ap_select(swjdp, apsel); - dap_ap_read_reg_u32(swjdp, 0xFC, &apid); + dap_ap_read_reg_u32(swjdp, AP_REG_IDR, &apid); retval = swjdp_transaction_endcheck(swjdp); command_print(CMD_CTX, "0x%8.8" PRIx32, apid); if (apselsave != apsel) diff --git a/src/target/arm_adi_v5.h b/src/target/arm_adi_v5.h index a78193c6d..2a0968440 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;