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

Subversion Repositories openrisc

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

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

powered by: WebSVN 2.1.0

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