Subversion Repositories openrisc_2011-10-31

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

===============================================================================
-- Description --
===============================================================================
A console application implementing a GDB stub and and communication with an 
OpenRISC processor system via a 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
0.1.3 090604 jb@orsoc.se
0.1.4 090828 jb@orsoc.se
0.1.5 090903 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 distros and Mac OS X (10.4 and above) are supported. 
Use with the ORSoC debug cable requires installation of some form of the FTDI 
Chip FTD2XX driver. Instructions for each platform follow.

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

-- 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.


-- 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

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

-- Compilation of the OpenRISC Debug Proxy application --

   There are two options for compilation. One results in a dynamically linked
   executable, the other links against a static library. See details on
   installing the desired library in the following section.

   -- Dynamically linked executable --

   This is the default build method. In the same directory this README is
   located, run a simple "make" command:

       user@host:~/or_debug_proxy$ make

   Ensure the driver library is installed before attempting to build, else it 
   will fail.

   -- Static linked executable --

   To be able to use the proxy with the ORSoC USB debug cable without requiring
   installation of the driver libraries into system directories, a method of
   building and linking the proxy app to static libraries is provided. Ensure
   the static library for your platform is located in the lib/ directory
   underneath the path this README is located.

   To build, run:

      user@host:~/or_debug_proxy$ make static


-- 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 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 amend 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.

-- Usage OpenRISC Debug Proxy application --

   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 processors
  stall indicator. If it detects the processor is stalled it will check against
  a list of software breakpoints to determine if this was the reason for the 
  halt, otherwise it returns a signal depending on what it thinks the problem
  is.

* The there is alo polling for "interrupt" (^C signals) sent 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: 
     * 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 determined 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.
       SOLVED: It appears increasing the packet size of the GDB transfers can
       achieve a significant increase in speed. GDB queries the proxy at when
       it connects about its maximum packet size. It was previously 255 bytes
       and this meant larger downloads were "slow". Raising this transfer size
       to around 4kB (4096 bytes) resulted in a throughput increase of almost
       10-times. This is due to the fact that most of the transfer time is
       spent on waiting for the driver - the overhead per call is significant
       if only transferring 255 bytes, so increasing the amount per transfer
       reduces the amount of time waiting for the driver to perform the trans-
       action. Sizes greater than 4kB, for some reason, cause the driver to
       have issues - resulting in incorrect CRC reading and bad Status returns
       from the driver functions. Why this is so should be investigated.
     * 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