JTAG USB User's Guide

The ​Gateworks GW16099 JTAG Adapter is used for flashing firmware to Gateworks Boards as well as serial console access.

The device is primarily used used to access Gateworks devices for debugging and developing purposes.

Gateworks provides a software utility application supporting x86 Linux. While JTAG programming is not supported for Windows operating systems you can use the JTAG dongle as a serial console.

References:

• ​GW16099 on Gateworks on-line store
• ​Gateworks JTAG Utilities

JTAG Executables

The latest Gateworks JTAG Utilities are found ​here

Physical Connections

Depending on the board model, the Gateworks SBC may have a larger 14pin JTAG header or a smaller 10pin JTAG header on it.

The header can be identified by looking at the connectors and identifying which one has the word JTAG by it silkscreened onto the board.

Below are images showing the connections depending on a 14pin or 10pin board.

10 pin: (Typically smaller Laguna boards, Ventana Boards) - Adapter May/May Not be Needed

14 pin: (Typically larger Laguna boards)

Instructions

Linux

​Click here for instructional video based on this section, mkimage and jtag_usbv4 are demonstrated

The Gateworks jtag_usb utility supports x86 32bit and 64bit Linux systems. Ubuntu is supported, however most x86 Linux distros should work as well.

• Virtual Machines should work fine as long as they allow access to USB devices (ie Virtualbox has been known to work well)
• If using a 64-bit system, the following is recommended to support the 32-bit binary:

  sudo dpkg --add-architecture i386
  apt-get update
  sudo apt-get install lib32ncurses5 lib32z1
  sudo apt-get install libc6:i386 libstdc++6:i386 libudev1:i386
  

• Please email support @ gateworks.com with any other questions

The most recent version jtag_usbv4 supports all Gateworks product families and can be downloaded ​here

The GW16042 JTAG dongle uses a FTDI FT2232C Dual USB-UART/FIFO chip and when enumerated on the USB bus will show as:

lsusb | grep 0403:6010
Bus 001 Device 007: ID 0403:6010 Future Technology Devices International, Ltd FT2232C Dual USB-UART/FIFO IC

With the Linux kernel ftdi-sio driver installed this will expose two USB serial devices:

ls -l /dev/ttyUSB*
crw-rw---- 1 root dialout 188, 0 Apr  2 07:04 /dev/ttyUSB0
crw-rw---- 1 root dialout 188, 1 Apr  2 07:04 /dev/ttyUSB1

The first serial device (/dev/ttyUSB0) is used for JTAG and the second device (/dev/ttyUSB1) is connected to the target board's serial console UART. Note that you must remove the Linux ftdi_sio driver (which will remove both of the above serial devices) in order to use the jtag_usb application (see below).

Note that because the jtag_usb works by loading a small application onto the target processor over JTAG which runs out of SDRAM. Therefore the jtag_usb application will configure SDRAM and occasionally you may need to update to the latest version in order to have support for new boards or memory configurations.

References:

• Latest Linux x86 jtag_usb download: ​http://dev.gateworks.com/jtag/

Conflict with ftdi-sio driver

The jtag_usb application requires that the Linux ftdi_sio kernel module not be loaded to run. You can temporarily unload it, then reload it (ie by hotplugging the jtag dongle) when done if you require it:

sudo rmmod ftdi_sio

You can determine if the ftdi_sio module is loaded with lsmod:

lsmod | grep ftdi
ftdi_sio               39858  1 
usbserial              42355  3 ftdi_sio

• Here the ftdi_sio IS loaded, and we must remove it to use jtag_usb

If you want to re-load the ftdi_sio module you can either unplug and reconnect the Gateworks JTAG-USB Programmer on the USB bus (which triggers a hotplug event and loads the appropriate driver for the device) or manually load it with a 'sudo modprobe ftdi_sio'.

Linux permissions on USB device

If you encounter permission errors when running jtag_usb it is likely that you require root privileges to access the USB device via libusb:

$ jtag_usbv4
libusb couldn't open USB device /dev/bus/usb/001/005: Permission denied.
libusb requires write access to USB device nodes.
libusb couldn't open USB device /dev/bus/usb/001/005: Permission denied.
libusb requires write access to USB device nodes.
$ ls -l /dev/bus/usb/001/005
crw-rw-r-- 1 root root 189, 4 Apr  2 06:54 /dev/bus/usb/001/005

• the above shows that you must be root to read/write to /dev/bus/usb/0

You can either use 'sudo jtag_usbv4' or 'sudo chmod 666' on the particular directory for the device however its likely that you want to install a udev rule to change the device permissions of this particular device every time its enumerated on the bus. You can do this by adding a udev rule that identifies the VendorID and ProductID of the Gateworks JTAG-USB Programmer and executes a chmod on it:

cat << EOF > 51-gateworks-jtag-ftdi.rules 
# GW16060 Dongle 
SUBSYSTEM=="usb",ATTR{idVendor}=="0403",ATTR{idProduct}=="6010",MODE="0666",GROUP="users" 
# GW16061 Gang adapter
SUBSYSTEM=="usb",ATTR{idVendor}=="0403",ATTR{idProduct}=="6011",MODE="0666",GROUP="users"
EOF
sudo mv 51-gateworks-jtag-ftdi.rules /etc/udev/rules.d
sudo chmod 655 /etc/udev/rules.d/51-gateworks-jtag-ftdi.rules
# cause rules to be re-read and processed (or reboot)
sudo udevadm control --reload-rules
sudo service udev restart
sudo udevadm trigger

The above udev configuration works for Ubuntu, however this configuration may vary on other Linux distro's that use something other than udev.

Using jtag_usb to read/write Firmware, Programming Software

Please see above for the download link to the latest jtag_usb executable. Note that an update may be required for new board models or memory configurations.

1. Connect the GW11008 JTAG-USB Programmer to the JTAG header on a Gateworks Single Board Computer using the attached ribbon cable.

2. Power on the Gateworks Single Board Computer.

3. Connect the JTAG-USB Programmer to a PC USB port using the supplied USB cable.

4. If trying to use the JTAG programmer to flash a new .bin binary image to the board, make sure the FTDI module is not loaded:

   sudo rmmod ftdi_sio ; # remove module from running kernel
   

5. Run the JTAG program (jtag_usbv4) with the syntax shown below to program a .bin file to the board:

   ./jtag_usbv4 –p <filename> # optionally you can append 2>/dev/null to redirect error
   

The switches –u <filename> –v <filename> are also available but are unnecessary to use when programming flash.

• Note - For Laguna boards, please do not flash a squashfs file to the board. A proper JTAG binary must be created with instructions here

If you encounter any errors see the Troubleshooting section below

jtag_usb options:

Option	Operation	Notes
-p	Program Flash device using specified filename
-v	Verify Flash device using specified filename
-u	Upload Flash device using specified filename	Ventana & Newport not supported
-m	Program GSC Firmware using specified filename
-x	Verify GSC Firmware using specified filename

Examples

programming a firmware image:

./jtag_usbv4 -p laguna_nor_1408.bin


Gateworks JTAG Programmer v4.0 r327
Copyright (C) 2004-2014, Gateworks Corporation, All Rights Reserved
Built 08:28:20, Oct 29 2014
Using USB Port

Channel #      S01                                                             
--------------------------------------------------------------------------------
USB Open Rev    r0                                                             
JTAG_ID #00    CNS                                                             
JTAG_ID #01    CNS                                                             
JTAG_ID #02    MSP                                                             
Core 0 DRAM     OK                                                             
Load Debugger   OK                                                             
Flash Size      16                                                             
Flash Erase     OK                                                             
Flash Prog      OK     

Troubleshooting

• Permission denied: libusb couldn't open USB device - see above regarding Linux permissions
• fOP: USB Open Rev fOP - failure to open the USB device via libusb - you likely have the ftdi_sio serial driver loaded - see above
• FAL: JTAG_ID_#00 FAL - failure to identify a supported JTAG TAP on the target device - likely you have not powered the target board
• If while programming a board it gets stuck an invalid image may have locked up the board or the board is not powered on. Please try powering on the board.
• JTAG utility stuck at Core 0 DRAM 00% while programming a Laguna family board - A lockup may have occurred in which a detailed fix may be available. Please contact Gateworks support at support@….
• Flashing a invalid image. There are times when downloading files that the html version was downloaded rather than the file itself. Check the file extension and file size to be sure you have the correct file.
• While programming, if it gets stuck at "Load Debugger: fS3' or fS2, this may mean there are issues with the GSC. Please re-flash the GSC firmware as demonstrated here: http://trac.gateworks.com/wiki/gsc#GSCUpdates
• Error message: "libgcc_s.so.1 must be installed for pthread_cancel to work”. Try to install gcc-multilib.

Creating jtagable binary images with mkimage_jtag

​Click here for instructional video based on this section, mkimage and jtag_usbv4 are demonstrated

In order to create a jtagable image for Newport and Ventana products, you need to use the mkimage_jtag script to create a binary file containing flash instructions and content used by the jtag_usbv4 application. You can download the latest version of the script ​here:

wget http://dev.gateworks.com/ventana/images/mkimage_jtag
chmod +x mkimage_jtag

The usage varies, depending on what you want to program, how, and where. For example, you can create images that only update the boot firmware without touching the rest of flash. In general you provide binary files and details on where to place them and what to erase.

Notes:

• for eMMC you can specify the '--partconf <boot0|boot1|user>' option to instruct jtag_usbv4 to set the eMMC register that specifies the hardware to boot from
• the -s option invokes the 'scripted' mode which allows you to specify multiple objects
• the -e option invokes the 'scripted' mode but also instructs jtag_usbv4 to erase the entire part
• Because JTAG is extremely slow for large flash parts such as eMMC it is advised that you use JTAG just to flash the boot firmware then use the boot firmware to flash the remainder of the device

Examples:

• Newport eMMC:
  • update the boot firmware and set the hardware partition and erase the entire part:

    ./mkimage_jtag --emmc -e --partconf=user firmware-newport.img@user:erase_all:0-16M > firmware-newport.bin
    

• Ventana NAND: (see wiki:ventana/bootloader#nand here for NAND flash map)
  • update just the boot firmware (SPL and u-boot) - Does not erase anything else:

    ./mkimage_jtag SPL u-boot.img > uboot.bin
    

  • update just the rootfs (does not touch boot firmware):

    ./mkimage_jtag openwrt-ventana-rootfs.ubi > image.bin
    

  • update the boot firmware and the root filesystem (erases entire flash):

    ./mkimage_jtag SPL u-boot.img openwrt-ventana-rootfs.ubi > image.bin
    

• Program U-boot SPL, env, and erase entire part

  mkimage_jtag -e SPL@0 u-boot.img@14M env@16M > image.bin
  

• Program U-boot SPL and erase entire part

  mkimage_jtag -e SPL@0 u-boot.img@14M > image.bin
  

Once these steps are complete and the bin file has been generated, follow the other instructions on this page to flash this .bin file to the board. Linux instructions for programming are here #linux-jtag-flashing

Troubleshooting:

• If downloaded from a browser, make sure the mkimage_jtag script does not have any file extensions such as txt and be sure is has executable permissions.

Serial Console Access on Linux

​Establishing a serial console in Linux instructional video

The JTAG connector on all Gateworks Families includes a serial port.

You may use the device with your favorite linux terminal program (Screen, etc...) at 115,200 baud, 8 data bits, 1 stop bit, no parity and no flow control

Gateworks suggests using the program screen to access the serial console.

Example: open /dev/ttyUSB1 (Note that the device may vary on your system if you had /dev/ttyUSB devices prior to plugging the JTAG adapter into your USB bus)

screen /dev/ttyUSB1 115200,cs8

• You may need to use the sudo command in front of the screen command
• Typically /dev/tty* nodes are owned by root.dialout which means you need to be root or a member of the dialout group. If this is the case you will get a permissions error and you can either run the command with a 'sudo' in front of it, or add your user to the dialout group

Troubleshooting:

• you will likely need to add your user to the dialog group by editing the /etc/group file:

  ls -l /dev/ttyUSB*
  

• make sure modem-manager is not installed as this will perform serial operations on new tty devices when they appear on the system and likely cause issues with using screen on the same port:

  sudo apt-get remove --purge modem-manager
  

Windows

Gateworks no longer maintains the Windows JTAG software and thus it is not recommended.

Gateworks recommends using the provided Linux JTAG software as found above.

Windows Operating Instructions For Serial

You can use a terminal program for windows such as ​Putty / Hyperterminal to connect to the Gateworks board serially over the JTAG / or serial port as long as the FTDI Virtual COM port drivers are installed on your system:

• ​https://www.ftdichip.com/Drivers/VCP.htm - Downloads for x86 (32bit) and x64 (64bit) Windows drivers

To see if you have the proper drivers installed simply connect the Gateworks JTAG dongle to your Windows PC and look in the 'Device Manager' application under 'COM Ports' to see if a new serial device was added.

Then, start a standard serial connection on that port. Configure the terminal program for 115,200 baud, 8 data bits, 1 stop bit, no parity and no flow control.

Power the board, and wait for text to output. Hitting the 'Enter' key may also bring up a prompt.

Please see these excellent howto's for various terminal program on Windows:

• ​Setup Serial Console Connection using PuTTy
• ​Configuring Serial Terminal Emulation Programs (Hyperterm, PuTTy, and Terra Term Pro)

General Troubleshooting

1. If while programming a board it gets stuck an invalid image may have locked up the board or the board is not powered on. Please try powering on the board.
2. JTAG utility stuck at Core 0 DRAM 00% while programming a Laguna family board - A lockup may have occurred in which a detailed fix may be available. Please contact Gateworks support at support@….
3. Flashing a invalid image. There are times when downloading files that the html version was downloaded rather than the file itself. Check the file extension and file size to be sure you have the correct file.
4. While programming, if it gets stuck at "Load Debugger: fS3' or fS2, this may mean there are issues with the GSC. Please re-flash the GSC firmware as demonstrated here: http://trac.gateworks.com/wiki/gsc#GSCUpdates
5. Ground loops can occur between the board power supply and the JTAG cable. Be aware of this and isolate properly.
6. GW16042 with 10 > 14 pin adapter board will flail to flash Newport boards. Serial console is verified to work.

If still have difficulties, please contact Gateworks support at support@gateworks.com

OpenOCD

Please see out JTAG hardware page here: JTAG OCD

JTAG Programmer Hardware

Please see out JTAG hardware page here: JTAG Hardware PAGE