[[PageOutline]]

= Gateworks JTAG support =

'''To use the JTAG software with the Ventana boards, please see the [wiki:jtag_instructions JTAG Software Page]'''

== GW16042 JTAG dongle ==
The GW16042 JTAG dongle uses an FTDI FT2232D which has 2 fairly general purpose 8-bit ports.  The 1st port we use for JTAG utilizing the FTDI MPSSE engine .  The 2nd port we use for Serial Console.

== Gateworks System Controller (GSC) ==

Most of our boards have a 'Gateworks System Controller' implemented with an MSP430 MPU which emulates several I2C devices used for system control and monitoring (see  [wiki:gsc]).  The MSP430 is on our JTAG chain, along with the board specific CPU so that we can access both of these devices via JTAG.  The MSP430 does not use standard JTAG and by default and the part comes up in 'Spy-By-Wire' mode where you must transition TRST and SRST properly to get the part into JTAG mode.  Without doing so, it will 'break the chain'.  Additionally, the MSP430 must be manually clocked when accessing its JTAG interface which the TDI signal is used for.  For these reasons the MSP430 must be the first device on the JTAG chain.  On all Gateworks boards with a GSC a bypass resistor exists across the TDI and TDO pins of the GSC so that it can be optionally loaded with a 0ohm resistor to physically bypass the GSC from the JTAG chain.  When this is done you can still access the rest of the chain, just not the GSC.  The board will function normally you just wont be able to read/write GSC firmware via the GW16042 JTAG dongle and software.  Refer the the individual product user manual for details about the resistor to bypass the GSC from the JTAG chain.

The following state transitions of JTAG TRST# and SRST# will put the MSP430 in JTAG mode:
 1. JTAG TRST# = 0, JTAG SRST# = 1
 2. JTAG TRST# = 1, JTAG SRST# = 1
 3. JTAG TRST# = 1, JTAG SRST# = 0
 4. JTAG TRST# = 0, JTAG SRST# = 0
 5. JTAG TRST# = 1, JTAG SRST# = 0
 6. JTAG TRST# = 1, JTAG SRST# = 1

Once in JTAG mode, it will be in bypass by default with an 8-bit instruction length. Note that the MSP430 does not have a JTAG ID thus it will not show up if you try to auto detect.

References:
 - Gateworks System Controller: [wiki:gsc]
 - FTDI AN_108 MPSSE - http://www.ftdichip.com/Support/Documents/AppNotes/AN_108_Command_Processor_for_MPSSE_and_MCU_Host_Bus_Emulation_Modes.pdf
 - MSP430 Programming Via the JTAG interface - http://www.ti.com/lit/ug/slau320h/slau320h.pdf

== JTAG Chain ==
The Gateworks Ventana family has the following JTAG chain:
 1. GSC (MSP430) (IR length=8bits, defaults to Spy-By-Wire mode on powerup)
 2. IMX6 SoC which internally has the following devices on the JTAG chain:
  a. IMX6 SJC (IR length=5bits)
  b. IMX6 SDMA (IR length=4bits)
  c. ARMV7A DAP (IR length=4bits)

The Gateworks Laguna family has the following JTAG chain:
 1. GSC (MSP430) (IR length=8bits, defaults to Spy-By-Wire mode on powerup)
 2. CNS3xxx CPU (IR length=5 bits)
 3. CNS3xxx CPU (IR length=5 bits) (if dual-core product)

The Gateworks Rincon family has the following JTAG chain:
 1. GSC (MSP430) (IR length=8bits, defaults to Spy-By-Wire mode on powerup)
 2. DM6446 CPU (IR length=6 bits) (in bypass mode at powerup)
 3. ARM9 Core (IR length=4 bits) 

The Gateworks Avila / Cambria family has the following JTAG chain:
 1. GSC (MSP430) (IR length=8bits, defaults to Spy-By-Wire mode on powerup) (only certain avila/cambria products have a GSC)
 2. IXP42x CPU (IR length=7 bits)
 3. PLD (IR length=8 bits) (only certain avila/cambria products have a PLD)

== OpenOCD ==
[http://openocd.sourceforge.net/doc/html/index.html OpenOCD] is an on chip debugger which aims to provide in-system programming and debugging. In order to use OpenOCD on our platform, you must install current version of OpenOCD and apply a patch. Listed below are the steps involved.

Note: These steps were performed on Ubuntu 13.04 32-bit and Ubuntu 14.04 64-bit. The following dependencies were installed prior to installing OpenOCD: libtool, git, curl, texinfo, automake
{{{
$ git clone git://git.code.sf.net/p/openocd/code openocd
$ cd openocd
$ ./bootstrap
$ ./configure --enable-ftdi --enable-maintainer-mode
$ wget http://trac.gateworks.com/raw-attachment/wiki/jtag/gw16042.cfg
$ wget http://trac.gateworks.com/raw-attachment/wiki/jtag/gateworks-openocd.patch
$ git apply gateworks-openocd.patch
$ make
}}}

We currently have a board configuration file for the gw2388 and our Ventana family line. You can grab either one by doing the following:
{{{
wget http://trac.gateworks.com/raw-attachment/wiki/jtag/gw2388.cfg
wget http://trac.gateworks.com/raw-attachment/wiki/jtag/gw5xxx.cfg
}}}

To run OpenOCD on the gw2388, just enter the following:
{{{
./src/openocd -f gw16042.cfg -f gw2388.cfg
}}}

To run OpenOCD on our Ventana family line, do the following (Assuming you are in the build directory for OpenOCD):
{{{
./src/openocd -f gw16042.cfg -f tcl/target/imx6.cfg -f gw5xxx.cfg
}}}

Expect to see retries as the MSP430 takes a few tries to get into 4-wire JTAG mode. After that, just follow the [http://openocd.sourceforge.net/doc/pdf/openocd.pdf openocd user manual].