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