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
|