Subversion Repositories or1k

===============================================================================
-- OpenRISC Debug Proxy --
===============================================================================

===============================================================================
-- Description --
===============================================================================
A console application that implements a GDB stub and various ways to
communicate with an OpenRISC processor system. This done by initally making a
connection to a target system before handling a connection from a GDB client
and relaying debug commands. Connections to the target can be made in many
ways, however debugging FPGA or ASIC targets will be through use of the ORSoC
USB debug cable.
===============================================================================
-- Versions --
===============================================================================
0.1.0 090201 jb@orsoc.se 
0.1.1 090304 jb@orsoc.se
0.1.2 090511 jb@orsoc.se

===============================================================================
-- Installation --
===============================================================================

The OR debug proxy application runs on multiple platforms only requiring
slightly different driver configurations on each. Currently, Cygwin Windows,
several Linux distos and Mac OS X (10.4 and above) are supported. All require
installation of some form of the FTDI Chip FTD2XX driver. Instructions for
each platform follow.

-------------------------------------------------------------------------------
-- Installation on Cygwin Windows --
-------------------------------------------------------------------------------

-- ORSoC OpenRISC USB debug cable driver installation --
   
  As per the installation instructions included in FTDI Chip's D2XX Windows
  driver.  http://www.ftdichip.com/Drivers/D2XX.htm

-- Compilation of the OpenRISC Debug Proxy application --

   While in the same directory which this file is located in, run a simple
   "make" command.

       user@cygwin-host ~/or_debug_proxy
       $ make

   Run the resulting executable (or_debug_proxy.exe) for usage details.

-------------------------------------------------------------------------------
-- Installation on Linux
-------------------------------------------------------------------------------

-- ORSoC OpenRISC USB debug cable driver installation --

Before we begin:

It is required that the Linux distribution have a version 2.4 kernel, or
above. This is due to the USB driver libraries by FTDI Chip used to interface
with the USB debug device.

The ORSoC USB debugger cable uses a FTDI dual UART/FIFO chip. 

An aside: These USB to serial devices typically trigger the loading of another
FTDI driver when they're attached to the system. This is the ftdi_sio driver
and now comes standard in newer kernels. This is of use to us, as one of the
two serial devices will remain is a standard uart under /dev/ttyUSBx. However,
to enable a high-speed JTAG interface with our hardware we require newer,
specialised drivers from FTDI called the D2XX drivers.

The Linux driver can be obtained from FTDI Chip's website,
http://www.ftdichip.com, and is found under the links to "Drivers" and then
"D2XX". At the time of writing, the latest version was libftd2xx 0.4.16 and
could be downloaded directly off their site from
http://www.ftdichip.com/Drivers/D2XX/Linux/libftd2xx0.4.16.tar.gz

Statically linked driver:

The simplest way to enable these drivers is to link the application 
statically - that is, have a copy of the driver along with the debugging 
application. This is much simpler than the following driver installation 
instructions. Typically in the FTDI drivers there is also a directory called 
static_lib/ and this contains a driver that can be statically linked against 
when compiling. To compile the OpenRISC debug proxy like this, copy the file in
that static_lib/ path into the lib/ directory under the or_debug_proxy/ 
build directory, and do:

      user@host:~/or_debug_proxy$ make or_debug_proxy_static

This will result in the executable being statically linked to the driver file 
in the the lib/ folder.

Dynamically linked driver install directions:

Uncompress the driver package (tar xzvf libftd2xx0.4.16.tar.gz) and read the
file "readme.dat" located inside, but don't complete their way of installing
yet. Their installation method should be modified slightly to allow easier use
of the USB device by users. Read the following before performing the install
as per the instructions in "readme.dat", and ammend their installation process
as you go.

* In step 4, create an additional symbolic link, however this time with only a
  trailing zero, like so:

  user@host:/usr/local/lib$ ln -s libftd2xx.so.x.x.xx libftd2xx.so.0

* Again, in step 6, create an additional symbolic link with only a trailing
  zero:

  user@host:/usr/lib$ ln -s /usr/local/lib/libftd2xx.so.x.x.xx libftd2xx.so.0

* In step 7 (the following may vary depending on your distribution, however in
  the most recent Ubuntu our suggested modification was required) instead of
  the line provided in "readme.dat", use the following in your /etc/fstab file
  (note the difference is a change from "usbdevfs" to "usbfs")
  
     none /proc/bus/usb usbfs defaults,devmode=0666 0 0

* The last step (mount -a) outlined in "readme.dat" can then be performed.

-- Setting USB device permissions --

Depending on the Linux distribution and how recent it is, the method for
defining the permissions of the USB device when it's loaded by the kernel can
vary.

* Recent udev systems (most 2.6 kernel systems)

There can be variations in the way udev organises its files for setting up
rules and permissions of devices attached to the system, but the following
should cover most systems.

Do a listing of the udev rules directory

        user@host:~$ ls /etc/udev/rules.d/

There should be a file somewhere, with the word "permissions" in the name. On
some systems it could be called "40-permissions.rules", on others possibly
"020_permissions.rules". Locate the permissions file in /etc/udev/rules.d/
and, as the super user (root), open the file to edit. The author prefers nano.

      user@host:/etc/udev/rules.d$ sudo nano 40-permissions.rules
      [sudo] password for user:

Of course, editing as super user (sudo'ing) will require the ability to sudo.

The following can differ from system to system. In this case, a recent version
of Ubuntu, the file "40-permissions.rules" was present and will be edited.

In this particular permissions file there are different sections, some with
labels.

Search for the lines with LABEL="usb_serial_start" and
LABEL="usb_serial_end". In BETWEEN these two LABEL lines, insert two new lines
containing the following:

  # Permissions for ORSoC USB debugger FT2232 device
  ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6010", MODE="0666", GROUP="tty"

If these LABEL="" lines cannot be found (for instance, different distros have
their udev setup differently) insert the above line anywhere in the file. This
is not a definite way of enabling these permissions, and udev exists in many
forms and configurations, so if this does not work, please contact the author
regarding the issue.

* Fedora 9

As an example of a slightly different system, Fedora 9 does not have a
xx-permissions.rules file. The solution is to create a new file, but in this
case choose the name "51-permissions.rules". It can have just the rule listed
above:

  # Permissions for ORSoC USB debugger FT2232 device
  ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6010", MODE="0666", GROUP="tty"

The reason for the filename change is that the udev rules files are read in
lexical order (i.e. the order they would appear in a dictionary). With Fedora
9 the old FTDI driver is included as standard, and there is default rule in
50-udev-default.rules, which would override anything in 40-permissions.rules
(since it would be read first). By using the name 51-permissions.rules, our
rule will override anything set in 50-udev-default.rules.

If you find problems with permissions, then check that no later rules files
are overriding settings.

The devices whose permissions are set are /dev/ttyUSB0 /dev/ttyUSB1, the
/dev/usbdevnnn for the USB slot (nnn) being used, and the files in
/dev/bus/usb/nnn/xxx. They should all be in group tty and have permission
rw-rw-rw.

* Older systems, (early udev, devfs)
  
None of these systems were tested, however it should be easy enough to locate
the device by the vendor ID and product ID on the USB bus. See the Udev
instructions above for these values.

* Reloading the ftdi_sio driver

If it is desired that the D2XX drivers be unloaded and the original ftdi_sio one
reactivated (recreating the two /dev/ttyUSB devices), it is as simple as
removing and replacing the USB dongle from the system. However, it can also be
done at the prompt by first running as root "modprobe -r ftdi_sio", and then
"modprobe ftdi_sio vendor=0x0403 product=0x6010", which totally removes and
then reloads the device.

-- Compilation of the OpenRISC Debug Proxy application --

   While in the same directory which this file is located in, run a simple
   "make" command.

       user@host:~/or_debug_proxy$ make

   The proxy application can then be run with the desired options, or for
   usage details, run the program with no options specified.

       user@host:~/or_debug_proxy$ ./or_debug_proxy

       Invalid or insufficient arguments

       OpenRISC GDB proxy server usage: or_debug_proxy -server_type port

       server_type:
            -r Start a server using RSP, connection to hadware target via
               USB
            -j Start a server using legacy OR remote JTAG protocol, to
               hardware target via USB
            -v Start a server using RSP, connection to RTL sim. VPI server
               target via sockets

        port_number:
            Any free port within the usable range of 0 - 65535

        Example:
            Start a GDB server on port 5555, using RSP, connecting to
            hardware target via USB
            or_debug_proxy -r 5555


* Platforms tested, and known to be working, on:
  Ubuntu 8.04
  Debian 

-------------------------------------------------------------------------------
-- Installation on Mac OS X --
-------------------------------------------------------------------------------

-- ORSoC OpenRISC USB debug cable driver installation --

  As per the installation instructions included in FTDI Chip's D2XX Mac OS X
  driver.  http://www.ftdichip.com/Drivers/D2XX.htm

-- Compilation of the OpenRISC Debug Proxy application --

   As per the Linux instructions.


* Note: Tested on an Intel Mac, running OS X version 10.4



===============================================================================
-- Usage notes --
===============================================================================

When the program initialises it sets up some form of communication with an
OpenRISC processor (developed and tested with a OR1k design similar to the
ORPSoC design found in the OR1k project archive on OpenCores), either via a
USB debug cable or via sockets interface to an RTL simulation. After this, it
waits for a connection from GDB, and then the debugging session can begin.

The proxy has been written to be robust, for example it will hopefully handle
disruptions like processor crashes, hardware resets, and connection dropouts
gracefully enough to not require a complete restart of the proxy and GDB.

Some basic mechanics of the proxy are as follows:

* When the program is "continued" from GDB, the proxy will poll the previous
  program counter (PPC), checking it against the internal list of software
  breakpoints, at second intervals to see if a software breakpoint has been
  reached.

* The one second polling also applies to "interrupt" (^C signals) from GDB,
  which will cause the processor to be stalled, wherever it is, and control
  returned to GDB (the proxy will await further commands from GDB.) It is
  optional to implement this awareness of the interrupt signal from GDB, but
  the developers have found this functionality extremely useful and thought
  others might too.

* Troubleshooting tip: If the proxy prints out the following line(s):
                  RSP step with signal 'S04' received 
  when attempting to continue, or single step, a program from GDB, it is 
  necessary to restart both the proxy and GDB before being continuing.
  This bug is perhaps caused by changing the file GDB is debugging during the 
  same session.

TODO List: 
     * Explicit char and short reading and writing ability:
       Currently only full word writing and reading is supported by the proxy. 
       It would be great if individual words and chars could be read also. It 
       is possible to receive such requests from GDB, so there's no reason why 
       they shouldn't be supported. It should be simple enough to implement.
     * Correct organisation of non-word aligned reading
       There's some problems when reading a word from a non-word aligned 
       boundary. This should be possible, for instance in GDB, doing something 
       like "x/4 0x101" should read the four bytes starting at address 0x101 
       and should display them LSB first. However this doesn't appear to 
       function as intended.
     * USB<->JTAG Driver TODO: Increase speed of the proxy
       It appears that the current transfer rate of around 20k/s is due to 
       pauses in the driver. This was deteremined by profiling the proxy and 
       noticing that, over a 4-odd megabyte transfer from GDB, taking about 4 
       minutes, the proxy only executed for 2.5 seconds, and the three most 
       used functions, accounting for 50% of execution were functions in the 
       driver. This indicates that either better use of, or better 
       implementation of, the driver could dramatically increase speed.
     * USB<->JTAG Driver TODO:
       Get the latest version of the MPSSE function code (from 
       http://ftdichip.com/Projects/MPSSE/FTCJTAG/FTCJTAG_Source.zip at last 
       check) and update our Linux compatible version with the ones here. This 
       might provide improved stability or performance, but from the list of 
       improvements made to the files from our version it doesn't appear like 
       it would result in significant improvement in the proxy app.
     * Better README
       It would be nice to provide more important documentation of nuances of 
       the proxy operation