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 the OpenCores 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
0.1.6 110307 jb@orsoc.se
0.1.7 110308 jb@orsoc.se
0.1.8 110422 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".

WARNING: Later versions of the ftd2xx library appear not to work in the same way
as the earlier versions. Version 1.0.4 does not open the USB device unless the
kernel module ftdi_sio is unloaded (sudo rmmod ftdi_sio), however unloading this
module removes device nodes /dev/ttyUSB0 and /dev/ttyUSB1. These later 
libraries can be used with or_debug_proxy but the because the ftdi_sio kernel 
module must be unloaded first the serial consoles disappear. With this in mind
it is probably better to use the older driver that does not require this kernel
module be unloaded.

FTDI Chip do not make older versions of their drivers available on their website
but there are locations where version the static 0.4.16 library can be obtained.

See the discussion at the following URL for a link to the older static library
- http://opencores.org/forum,OpenRISC,0,4170 - which must be downloaded and
placed in the or_debug_proxy/lib path and a static compile performed, as 
outline below.

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 libftd2xxX.Y.Z.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
       Usage: or_debug_proxy <SERVERTYPE> <PORT> <OPTIONS>
       OpenRISC GDB Proxy Server

        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 (DEPRECATED)

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

        Options:
        -k      Accesses to 0xC0000000 map to 0x0. Useful for kernel debugging.

        Example:
                Start a GDB server on port 50001, using RSP, connecting to
                hardware target via USB:

                ./or_debug_proxy -r 50001

* Platforms tested, and known to be working, on:
  Ubuntu 8.04, 9.10, 10.10
  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:
       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