OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [or_debug_proxy/] [README] - Blame information for rev 46

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 39 julius
===============================================================================
2
-- OpenRISC Debug Proxy --
3
===============================================================================
4
 
5
===============================================================================
6
-- Description --
7
===============================================================================
8
A console application implementing a GDB stub and and communication with an
9
OpenRISC processor system via a USB debug cable.
10
===============================================================================
11
-- Versions --
12
===============================================================================
13
0.1.0 090201 jb@orsoc.se
14
0.1.1 090304 jb@orsoc.se
15
0.1.2 090511 jb@orsoc.se
16
0.1.3 090604 jb@orsoc.se
17 46 julius
0.1.4 090828 jb@orsoc.se
18 39 julius
===============================================================================
19
-- Installation --
20
===============================================================================
21
 
22
The OR debug proxy application runs on multiple platforms only requiring
23
slightly different driver configurations on each. Currently, Cygwin Windows,
24
several Linux distros and Mac OS X (10.4 and above) are supported.
25
Use with the ORSoC debug cable requires installation of some form of the FTDI
26
Chip FTD2XX driver. Instructions for each platform follow.
27
 
28
-------------------------------------------------------------------------------
29
-- Installation on Cygwin Windows --
30
-------------------------------------------------------------------------------
31
 
32
-- Compilation of the OpenRISC Debug Proxy application --
33
 
34
   While in the same directory which this file is located in, run a simple
35
   "make" command.
36
 
37
       user@cygwin-host ~/or_debug_proxy
38
       $ make
39
 
40
   Run the resulting executable (or_debug_proxy.exe) for usage details.
41
 
42
 
43
-- ORSoC OpenRISC USB debug cable driver installation --
44
 
45
  As per the installation instructions included in FTDI Chip's D2XX Windows
46
  driver.  http://www.ftdichip.com/Drivers/D2XX.htm
47
 
48
-------------------------------------------------------------------------------
49
-- Installation on Linux
50
-------------------------------------------------------------------------------
51
 
52
-- Compilation of the OpenRISC Debug Proxy application --
53
 
54
   There are two options for compilation. One results in a dynamically linked
55
   executable, the other links against a static library. See details on
56
   installing the desired library in the following section.
57
 
58
   -- Dynamically linked executable --
59
 
60
   This is the default build method. In the same directory this README is
61
   located, run a simple "make" command:
62
 
63
       user@host:~/or_debug_proxy$ make
64
 
65
   Ensure the driver library is installed before attempting to build, else it
66
   will fail.
67
 
68
   -- Static linked executable --
69
 
70
   To be able to use the proxy with the ORSoC USB debug cable without requiring
71
   installation of the driver libraries into system directories, a method of
72
   building and linking the proxy app to static libraries is provided. Ensure
73
   the static library for your platform is located in the lib/ directory
74
   underneath the path this README is located.
75
 
76
   To build, run:
77
 
78
      user@host:~/or_debug_proxy$ make static
79
 
80
 
81
-- ORSoC OpenRISC USB debug cable driver installation --
82
 
83
Before we begin:
84
 
85
It is required that the Linux distribution have a version 2.4 kernel, or
86
above. This is due to the USB driver libraries by FTDI Chip used to interface
87
with the USB debug device.
88
 
89
The ORSoC USB debugger cable uses a FTDI dual UART/FIFO chip.
90
 
91
An aside: These USB to serial devices typically trigger the loading of another
92
FTDI driver when they're attached to the system. This is the ftdi_sio driver
93
and now comes standard in newer kernels. This is of use to us, as one of the
94
two serial devices will remain is a standard UART under /dev/ttyUSBx. However,
95
to enable a high-speed JTAG interface with our hardware we require newer,
96
specialised drivers from FTDI called the D2XX drivers.
97
 
98
The Linux driver can be obtained from FTDI Chip's website,
99
http://www.ftdichip.com, and is found under the links to "Drivers" and then
100
"D2XX". At the time of writing, the latest version was libftd2xx 0.4.16 and
101
could be downloaded directly off their site from
102
http://www.ftdichip.com/Drivers/D2XX/Linux/libftd2xx0.4.16.tar.gz
103
 
104
Statically linked driver:
105
 
106
The simplest way to enable these drivers is to link the application
107
statically - that is, have a copy of the driver along with the debugging
108
application. This is much simpler than the following driver installation
109
instructions. Typically in the FTDI drivers there is also a directory called
110
static_lib/ and this contains a driver that can be statically linked against
111
when compiling. To compile the OpenRISC debug proxy like this, copy the file in
112
that static_lib/ path into the lib/ directory under the or_debug_proxy/
113
build directory, and do:
114
 
115
      user@host:~/or_debug_proxy$ make static
116
 
117
This will result in the executable being statically linked to the driver file
118
in the the lib/ folder.
119
 
120
Dynamically linked driver install directions:
121
 
122
Uncompress the driver package (tar xzvf libftd2xx0.4.16.tar.gz) and read the
123
file "readme.dat" located inside, but don't complete their way of installing
124
yet. Their installation method should be modified slightly to allow easier use
125
of the USB device by users. Read the following before performing the install
126
as per the instructions in "readme.dat", and amend their installation process
127
as you go.
128
 
129
* In step 4, create an additional symbolic link, however this time with only a
130
  trailing zero, like so:
131
 
132
  user@host:/usr/local/lib$ ln -s libftd2xx.so.x.x.xx libftd2xx.so.0
133
 
134
* Again, in step 6, create an additional symbolic link with only a trailing
135
  zero:
136
 
137
  user@host:/usr/lib$ ln -s /usr/local/lib/libftd2xx.so.x.x.xx libftd2xx.so.0
138
 
139
* In step 7 (the following may vary depending on your distribution, however in
140
  the most recent Ubuntu our suggested modification was required) instead of
141
  the line provided in "readme.dat", use the following in your /etc/fstab file
142
  (note the difference is a change from "usbdevfs" to "usbfs")
143
 
144
     none /proc/bus/usb usbfs defaults,devmode=0666 0 0
145
 
146
* The last step (mount -a) outlined in "readme.dat" can then be performed.
147
 
148
-- Setting USB device permissions --
149
 
150
Depending on the Linux distribution and how recent it is, the method for
151
defining the permissions of the USB device when it's loaded by the kernel can
152
vary.
153
 
154
* Recent udev systems (most 2.6 kernel systems)
155
 
156
There can be variations in the way udev organises its files for setting up
157
rules and permissions of devices attached to the system, but the following
158
should cover most systems.
159
 
160
Do a listing of the udev rules directory
161
 
162
        user@host:~$ ls /etc/udev/rules.d/
163
 
164
There should be a file somewhere, with the word "permissions" in the name. On
165
some systems it could be called "40-permissions.rules", on others possibly
166
"020_permissions.rules". Locate the permissions file in /etc/udev/rules.d/
167
and, as the super user (root), open the file to edit. The author prefers nano.
168
 
169
      user@host:/etc/udev/rules.d$ sudo nano 40-permissions.rules
170
      [sudo] password for user:
171
 
172
Of course, editing as super user (sudo'ing) will require the ability to sudo.
173
 
174
The following can differ from system to system. In this case, a recent version
175
of Ubuntu, the file "40-permissions.rules" was present and will be edited.
176
 
177
In this particular permissions file there are different sections, some with
178
labels.
179
 
180
Search for the lines with LABEL="usb_serial_start" and
181
LABEL="usb_serial_end". In BETWEEN these two LABEL lines, insert two new lines
182
containing the following:
183
 
184
  # Permissions for ORSoC USB debugger FT2232 device
185
  ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6010", MODE="0666", GROUP="tty"
186
 
187
If these LABEL="" lines cannot be found (for instance, different distros have
188
their udev setup differently) insert the above line anywhere in the file. This
189
is not a definite way of enabling these permissions, and udev exists in many
190
forms and configurations, so if this does not work, please contact the author
191
regarding the issue.
192
 
193
* Fedora 9
194
 
195
As an example of a slightly different system, Fedora 9 does not have a
196
xx-permissions.rules file. The solution is to create a new file, but in this
197
case choose the name "51-permissions.rules". It can have just the rule listed
198
above:
199
 
200
  # Permissions for ORSoC USB debugger FT2232 device
201
  ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6010", MODE="0666", GROUP="tty"
202
 
203
The reason for the filename change is that the udev rules files are read in
204
lexical order (i.e. the order they would appear in a dictionary). With Fedora
205
9 the old FTDI driver is included as standard, and there is default rule in
206
50-udev-default.rules, which would override anything in 40-permissions.rules
207
(since it would be read first). By using the name 51-permissions.rules, our
208
rule will override anything set in 50-udev-default.rules.
209
 
210
If you find problems with permissions, then check that no later rules files
211
are overriding settings.
212
 
213
The devices whose permissions are set are /dev/ttyUSB0 /dev/ttyUSB1, the
214
/dev/usbdevnnn for the USB slot (nnn) being used, and the files in
215
/dev/bus/usb/nnn/xxx. They should all be in group tty and have permission
216
rw-rw-rw.
217
 
218
* Older systems, (early udev, devfs)
219
 
220
None of these systems were tested, however it should be easy enough to locate
221
the device by the vendor ID and product ID on the USB bus. See the Udev
222
instructions above for these values.
223
 
224
* Reloading the ftdi_sio driver
225
 
226
If it is desired that the D2XX drivers be unloaded and the original ftdi_sio one
227
reactivated (recreating the two /dev/ttyUSB devices), it is as simple as
228
removing and replacing the USB dongle from the system. However, it can also be
229
done at the prompt by first running as root "modprobe -r ftdi_sio", and then
230
"modprobe ftdi_sio vendor=0x0403 product=0x6010", which totally removes and
231
then reloads the device.
232
 
233
-- Usage OpenRISC Debug Proxy application --
234
 
235
   The proxy application can then be run with the desired options, or for
236
   usage details, run the program with no options specified.
237
 
238
       user@host:~/or_debug_proxy$ ./or_debug_proxy
239
 
240
       Invalid or insufficient arguments
241
 
242
       OpenRISC GDB proxy server usage: or_debug_proxy -server_type port
243
 
244
       server_type:
245
            -r Start a server using RSP, connection to hadware target via
246
               USB
247
            -j Start a server using legacy OR remote JTAG protocol, to
248
               hardware target via USB
249
            -v Start a server using RSP, connection to RTL sim. VPI server
250
               target via sockets
251
 
252
        port_number:
253
            Any free port within the usable range of 0 - 65535
254
 
255
        Example:
256
            Start a GDB server on port 5555, using RSP, connecting to
257
            hardware target via USB
258
            or_debug_proxy -r 5555
259
 
260
 
261
* Platforms tested, and known to be working, on:
262
  Ubuntu 8.04
263
  Debian
264
 
265
-------------------------------------------------------------------------------
266
-- Installation on Mac OS X --
267
-------------------------------------------------------------------------------
268
 
269
-- ORSoC OpenRISC USB debug cable driver installation --
270
 
271
  As per the installation instructions included in FTDI Chip's D2XX Mac OS X
272
  driver.  http://www.ftdichip.com/Drivers/D2XX.htm
273
 
274
-- Compilation of the OpenRISC Debug Proxy application --
275
 
276
   As per the Linux instructions.
277
 
278
 
279
* Note: Tested on an Intel Mac, running OS X version 10.4
280
 
281
 
282
 
283
===============================================================================
284
-- Usage notes --
285
===============================================================================
286
 
287
When the program initialises it sets up some form of communication with an
288
OpenRISC processor (developed and tested with a OR1k design similar to the
289
ORPSoC design found in the OR1k project archive on OpenCores), either via a
290
USB debug cable or via sockets interface to an RTL simulation. After this, it
291
waits for a connection from GDB, and then the debugging session can begin.
292
 
293
The proxy has been written to be robust, for example it will hopefully handle
294
disruptions like processor crashes, hardware resets, and connection dropouts
295
gracefully enough to not require a complete restart of the proxy and GDB.
296
 
297
Some basic mechanics of the proxy are as follows:
298
 
299
* When the program is "continued" from GDB, the proxy will poll the processors
300
  stall indicator. If it detects the processor is stalled it will check against
301
  a list of software breakpoints to determine if this was the reason for the
302
  halt, otherwise it returns a signal depending on what it thinks the problem
303
  is.
304
 
305
* The there is alo polling for "interrupt" (^C signals) sent from GDB,
306
  which will cause the processor to be stalled, wherever it is, and control
307
  returned to GDB (the proxy will await further commands from GDB.) It is
308
  optional to implement this awareness of the interrupt signal from GDB, but
309
  the developers have found this functionality extremely useful and thought
310
  others might too.
311
 
312
* Troubleshooting tip: If the proxy prints out the following line(s):
313
                  RSP step with signal 'S04' received
314
  when attempting to continue, or single step, a program from GDB, it is
315
  necessary to restart both the proxy and GDB before being continuing.
316
  This bug is perhaps caused by changing the file GDB is debugging during the
317
  same session.
318
 
319
TODO List:
320
     * USB<->JTAG Driver TODO: Increase speed of the proxy
321
       It appears that the current transfer rate of around 20k/s is due to
322
       pauses in the driver. This was determined by profiling the proxy and
323
       noticing that, over a 4-odd megabyte transfer from GDB, taking about 4
324
       minutes, the proxy only executed for 2.5 seconds, and the three most
325
       used functions, accounting for 50% of execution were functions in the
326
       driver. This indicates that either better use of, or better
327
       implementation of, the driver could dramatically increase speed.
328
     * USB<->JTAG Driver TODO:
329
       Get the latest version of the MPSSE function code (from
330
       http://ftdichip.com/Projects/MPSSE/FTCJTAG/FTCJTAG_Source.zip at last
331
       check) and update our Linux compatible version with the ones here. This
332
       might provide improved stability or performance, but from the list of
333
       improvements made to the files from our version it doesn't appear like
334
       it would result in significant improvement in the proxy app.
335
     * Better README
336
       It would be nice to provide more important documentation of nuances of
337
       the proxy operation

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.