OpenOCD and the SheevaPlug on Linux x86_64

This is a tutorial for people like me who want to start with JTAG and OpenOCD access on the SheevaPlug. Most of this stuff regarding the installation of OpenOCD on Linux x86_64 is of course generic and can be used for other FTDI based JTAG devices like.

First of all, if you're running a 64 bit OS (Vista, Win7), a word of advice: Don't waste your time trying to get OpenOCD to work on a 64 bit Windows - there's no ready-made package that works (the 32 bit version just don't), so the only way is to recompile the whole shebang yourself, and it's a complete mess, as you will also need a 64 bit gcc-like compiler, and figure out how to get a 64 bit version of a the FTDI GPL library talk to the 64 bit libUSB drivers.
If I ever manage to get a Windows version going, you'll be the first to hear about it, but for the time being, if you value your time, stick with Linux.

Now, the distro I am using is Slackware x86_64. There are of course tutorials on how to compile OpenOCD for Linux here and there, but things are slightly different for 64 bit version, which is why I'm posting my own version.

1. Before anything else, you want to have the serial console to the SheevaPlug through the USB FTDI device. For that you need to compile the kernel driver for the "USB FTDI Single Port Serial Driver" either as a module, or directly in your kernel. You will find that option, in the kernel, under: "Device Drivers ---> USB support ---> USB Serial Converter support ---> USB FTDI Single Port Serial Driver"
   Once you have the driver loaded, with the USB cable connected to the sheevaplug, you should get a /dev/ttyUSB0 device, which you can use as a regular serial port.
   The best way to connect to the SheevaPlug in Linux (or to any serial terminal for that matter) has to be to use screen, with a command like:
   

   screen /dev/ttyUSB0 115200,-crtscts

   Once you have confirmed that you can connect to the plug using the FTDI USB Serial converter driver, you can move to building OpenOCD, as it's a good indication that Linux should have no trouble accessing the rest of the FTDI chip functionalities


2. • OPTION 1: Using the proprietary libftd2xx library from FTDI, provided for completion. Note that using this option will kill any opened serial console whenever you launch openocd, whereas this does not occur with OPTION 2 below, which I strongly advise you to use.
     On an x86_64 MUST pick up the 64 bit version of the Linux drivers from the FTDI website. At the time of this post, that means you must download libftd2xx0.4.16_x86_64.tar.gz, NOT libftd2xx0.4.16.tar.gz. What's more, when you install the library, it has to go into lib64, NOT lib else you will get the ominous
     

     checking whether ftd2xx library works...
     configure: error: Cannot build & run test program using ftd2xx.lib

     Thus:
     

     cd /usr/src
     wget http://www.ftdichip.com/Drivers/D2XX/Linux/libftd2xx0.4.16_x86_64.tar.gz
     tar -xzvf libftd2xx0.4.16_x86_64.tar.gz
     cp libftd2xx0.4.16_x86_64/libftd2xx.so.0.4.16 /usr/local/lib64
     ln -s /usr/local/lib64/libftd2xx.so.0.4.16 /usr/local/lib64/libftd2xx.so
     # even if you specify --libdir=/usr/local/lib64 on openocd compilation
     # it requires libftd2xx.so.0 in /usr/lib64!
     ln -s /usr/local/lib64/libftd2xx.so.0.4.16 /usr/lib64/libftd2xx.so.0

   • OPTION 2 (PREFERRED): Using the GPL/Open source version of the FTDI library

     cd /usr/src
     wget http://www.intra2net.com/en/developer/libftdi/download/libftdi-0.16.tar.gz
     tar -xzvf libftdi-0.16.tar.gz
     cd libftdi-0.16
     # by default, libftdi will go in /usr/local/lib, whereas, on x86_64, it should go to lib64, thus
     ./configure --with--libdir=/usr/local/lib64
     make
     make install
     # openocd looks in /usr/lib64
     ln -s /usr/local/lib64/libftdi.so.1.16.0 /usr/lib64/libftdi.so.1

3. Now it's time to get OpenOCD compiled. For that:
   

   svn checkout svn://svn.berlios.de/openocd/trunk openocd
   cd openocd
   ./bootstrap
   # OPTION 1 - PROPRIETARY LIB FROM FTDI
   ./configure --libdir=/usr/local/lib64 --enable-maintainer-mode --enable-ft2232_ftd2xx
   # OPTION 2 - GPL FTDI LIBRARY
   ./configure --libdir=/usr/local/lib64 --enable-maintainer-mode --enable-ft2232_libftdi
   make
   make install

   Note that if you don't use the "--enable-maintainer-mode" option, you will get an error when make reaches the creation of the documentation, which is not a problem per se, but will prevent the openocd configuration scripts to be copied over on make install
   
   
4. If the above completed successfully, then you have openOCD ready to run. To connect to the SheevPlug then, issue a:
   

   openocd -f /usr/local/share/openocd/scripts/board/sheevaplug.cfg

   At this stage, if you are getting the following, then you need to reboot the plug and launch openOCD in the early stages of reboot:
   

   Error: JTAG scan chain interrogation failed: all zeroes
   Error: Check JTAG interface, timings, target power, etc.
   Error: Trying to use configured scan chain anyway...
   Error: feroceon.cpu: IR capture error; saw 0x00 not 0x..1
   Warn : Errors during IR capture, continuing anyway...
   Error: unexpected Feroceon EICE version signature

   What you really want to see when launching openOCD is:
   

   root@stella:/usr/src/openocd# openocd -f /usr/local/share/openocd/scripts/board/sheevaplug.cfg
   Open On-Chip Debugger 0.3.0-in-development (2009-10-07-01:35) svn:2808
   $URL: svn://svn.berlios.de/openocd/trunk/src/openocd.c $
   For bug reports, read http://svn.berlios.de/svnroot/repos/openocd/trunk/BUGS
   2000 kHz
   jtag_nsrst_delay: 200
   jtag_ntrst_delay: 200
   dcc downloads are enabled
   Warn : use 'feroceon.cpu' as target identifier, not '0'
   Info : clock speed 2000 kHz
   Info : JTAG tap: feroceon.cpu tap/device found: 0x20a023d3 (mfg: 0x1e9, part: 0x0a02, ver: 0x2)

5. OpenOCD is a client server software, so when you launch openOCD, you are really only launching the server part. To actually send JTAG commands and all that Jazz, you need to open a client session with:
   

   telnet localhost 4444

   This should then provide you with the On-Chip Debugger prompt.
   
   
6. Now, JTAG operations are a bit tricky (there are various JTAG states involved) so you can't really send any JTAG command you want (eg. NAND ID) any time you like and expect a meaningful reply. If you looked in the cfg file for the SheevaPlug, you'll see that before any NAND access operation is performed, a "sheevaplug_init" command is being called, so this is what we'll do. Once it's run, you will get a whole lot of interesting commands working, as illustrated with the session below:
   

   > sheevaplug_init
   target state: halted
   target halted in ARM state due to debug-request, current mode: Supervisor
   cpsr: 0x000000d3 pc: 0xffff0000
   MMU: disabled, D-Cache: disabled, I-Cache: disabled
   0 0 1 0: 00052078
   > scan_chain
        TapName            | Enabled |   IdCode      Expected    IrLen IrCap  IrMask Instr
   ---|--------------------|---------|------------|------------|------|------|------|---------
    0 | feroceon.cpu       |    Y    | 0x20a023d3 | 0x20a023d3 | 0x04 | 0x01 | 0x0f | 0x0c
   > nand probe 0
   NAND flash device 'NAND 512MiB 3,3V 8-bit' found
   > nand list
   #0: NAND 512MiB 3,3V 8-bit (Hynix) pagesize: 2048, buswidth: 8,
       blocksize: 131072, blocks: 4096
   > nand info 0
   #0: NAND 512MiB 3,3V 8-bit (Hynix) pagesize: 2048, buswidth: 8, erasesize: 131072
   #0: 0x00000000 (128kB) erase state unknown (block condition unknown)
   #1: 0x00020000 (128kB) erase state unknown (block condition unknown)
   (...)
   #4094: 0x1ffc0000 (128kB) erase state unknown (block condition unknown)
   #4095: 0x1ffe0000 (128kB) erase state unknown (block condition unknown)