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

Subversion Repositories openrisc

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

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

powered by: WebSVN 2.1.0

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