Changes between Initial Version and Version 1 of jtag_instructions

Timestamp:

10/22/2017 05:28:45 AM (7 years ago)

Author:

trac

Comment:

--

jtag_instructions

@@ +1 @@
+[[PageOutline]]
+
+= JTAG USB User's Guide =
+The [http://shop.gateworks.com/index.php?act=viewProd&productId=56 Gateworks GW16042 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 with support for both [#Linux Linux] and [#Windows Windows] operating systems (Note that for the Ventana product family, you must use the Linux tool). In order to use the windows utility please install the drivers which are also available at the link below (CDM20814_Setup.exe).
+
+[[Image(wiki:jtag_instructions:gw16042.JPG,200px)]]
+
+References:
+ * [http://shop.gateworks.com/index.php?act=viewProd&productId=56 GW16042 on Gateworks on-line store]
+ * [http://svn.gateworks.com/jtag/ Gateworks JTAG Utilities]
+
+
+== JTAG Executables ==
+The latest Gateworks JTAG Utilities are found [http://svn.gateworks.com/jtag/ 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 ===
+[[Image(VentanaJTAG.jpg,400px)]]
+
+
+=== 14 pin: (Typically larger Laguna boards, Avila, Cambria Boards) ===
+[[Image(LagunaJTAG.jpg,400px)]]
+
+
+= Instructions =
+[#Linux Linux Instructions]
+
+[#Windows Windows Instructions]
+
+
+[=#linux-jtag]
+== Linux ==
+The Gateworks '''jtag_usb''' utility supports x86 32bit and 64bit Linux systems. Ubuntu is supported, however most x86 Linux distros should work as well.
+
+ * ''' Note virtual machines are NOT recommended'''
+
+ * If using a 64-bit system and proper operation is not occurring, please try the command:
+{{{
+sudo apt-get install ia32-libs
+}}}
+ * Please contact support@gateworks.com with any other questions
+
+The most recent version '''jtag_usbv4''' supports all Gateworks product families and can be downloaded [http://svn.gateworks.com/jtag/ 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://svn.gateworks.com/jtag/linux/x86/
+
+
+=== 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:
+{{{
+sudo cat <<EOF > /etc/udev/rules.d/51-gateworks-jtag-ftdi.rules 
+# Gateworks USB-JTAG Programmer for normal users (FTDI 2232C Dual USB-ART/FIFO IC)
+SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", SYSFS{idVendor}=="0403", SYSFS{idProduct}=="6010", MODE="0666", NAME="bus/usb/$env{BUSNUM}/$env{DEVNUM}", RUN+="/bin/chmod 0666 %c"
+EOF
+sudo udevadm control --reload-rules # reload udev rules
+}}}
+ * following this unplug the Gateworks JTAG-USB Programmer and re-connect to re-enumerate the bus and invoke this new rule.
+
+The above udev configuration works for Ubuntu, however this configuration may vary on other Linux distro's that use something other than udev.
+
+[=#linux-jtag-flashing]
+=== 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 with the syntax shown below.
+{{{
+./jtag_usbv4 –p <filename> –u <filename> –v <filename>
+}}}
+
+If you encounter any errors see the [#Troubleshooting 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 not supported ||
+||-m        ||Program GSC Firmware using specified filename|| ||
+||-x        ||Verify GSC Firmware using specified filename || ||
+
+
+==== Examples ====
+Example 1: Program the Flash with avila_16.bin image.
+{{{
+./jtag_usbv4 -p avila_16.bin
+}}}
+Example 2: Program and verify Flash with avila_16.bin image.
+{{{
+./jtag_usbv4 -p avila_16.bin -v avila_16.bin
+}}}
+Example 3: Output from programming a binary
+{{{
+./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 ====
+
+ * ''' Note virtual machines are NOT recommended'''
+ * Permission denied: '''libusb couldn't open USB device''' - [#LinuxpermissionsonUSBdevice 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 - [#conflictwithftdi-siodriver 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@gateworks.com.
+ *  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
+
+
+[=#ventana-images]
+=== Creating jtagable images for Ventana ===
+In order to create a jtagable image for our Ventana family line, you can use our [http://svn.gateworks.com/ventana/images/mkimage_jtag mkimage_jtag] script which can be downloaded [http://svn.gateworks.com/ventana/images/mkimage_jtag here]. (You may need to chmod the mkimage_jtag script to make executable. Be sure it does not have any extension such as txt) The usage varies, depending on typical use cases. For example, you can create jtagable images that only update the bootloader without erasing all of NAND. You can also create jtagable images with both the bootloader and a ubi image which will erase all of nand. Below are several examples on how to use this script. Also note that the script outputs to std out, so in the examples below, we redirect it to a file.
+
+To update just the bootloader, create a jtagable image with just the two parts:
+{{{
+$ ./mkimage_jtag SPL u-boot.img > uboot.bin
+}}}
+
+To update both the bootloader and rootfs (ubi)
+{{{
+$ ./mkimage_jtag SPL u-boot.img openwrt-ventana-rootfs.ubi > image.bin
+}}}
+
+To update just the rootfs
+{{{
+$ ./mkimage_jtag openwrt-ventana-rootfs.ubi > 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 mkimage_jtag ====
+ 1. Be sure the mkimage_jtag script does not have any file extensions such as txt. If so, rename it to mkimage_jtag
+ 2. Be sure the mkimage_jtag script has executable permissions. If not, run the command:
+{{{
+chmod 777 mkimage_jtag
+}}}
+
+
+[=#linux-serial]
+=== Serial Console Access on Linux ===
+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
+}}}
+ * 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]
+== Windows ==
+
+=== Installing the Drivers for Windows ===
+
+1. Download and run the file CDM20814_Setup.exe on to your windows machine ([http://svn.gateworks.com/jtag/ Download JTAG Executables]). A window should open and close on its own:
+
+[[Image(wiki:jtag_instructions:winjtag.JPG)]]
+
+2. Once that is finished running, download and install winjtagsetup_0_1_5.msi
+
+[[Image(wiki:jtag_instructions:winjtag2.JPG)]]
+
+3. Choose a location to install the Gateworks Win JTAG.
+
+[[Image(wiki:jtag_instructions:winjtag3.JPG)]]
+
+{{{
+#!html
+<h3 style="color:red">NOTE:  There have been reports of an error regarding a missing DLL file.  If this error is seen, please try to find the DLL on the system, and copy it into the same directory as the executable.</h3>
+}}}
+
+
+[=#windows-jtag]
+=== Operating Instructions For Programming ===
+''' Please note, Windows Programming is not supported for Ventana'''
+
+1. Connect the Gateworks JTAG-USB Programmer to the JTAG header on the board using the attached ribbon cable. 
+
+2. Power on the board and connect the Gateworks JTAG-USB Programmer to a Windows PC using the supplied USB cable.
+
+3. Run the Gateworks !WinJTAG program.
+
+4. Click on Open next to the Program File field and select the file location of a binary image.
+
+5. If desired, select a verify file or click on "Set Verify to Program File."
+
+[[Image(wiki:jtag_instructions:winjtag4.JPG)]]
+
+6. Click on Go and wait for the programming to be complete.
+
+
+[=#windows-terminal]
+=== Operating Instructions For Serial ===
+You can use a terminal program for windows such as [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html Putty] / Hyperterminal to connect to the Gateworks board serially over the JTAG / or serial port.
+
+Connect the the jtag programmer to the computer, or connect a serial cable from the Gateworks board to the computer (if serial is available)
+
+Please reference the device manager area on your windows computer to detect which 'COM' port the JTAG is connected on.
+
+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:
+- [http://kb.cyberoam.com/default.asp?id=2193 Setup Serial Console Connection using PuTTy]
+- [http://www.microsemi.com/document-portal/doc_view/130815-configuring-serial-terminal-emulation-programs 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@gateworks.com.
+ 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
+
+If still have difficulties, please contact Gateworks support at support@gateworks.com
+
+
+= OpenOCD = 
+Please see out JTAG hardware page here: [wiki:jtag#OpenOCD JTAG OCD]
+
+
+= JTAG Programmer Hardware = 
+Please see out JTAG hardware page here: [wiki:jtag JTAG Hardware PAGE]