usbnotes.html
13.4 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>/tmp/n46software.html</title>
<meta http-equiv="content-type"
content="text/html; charset=ISO-8859-1">
</head>
<body>
<h2>BB Player USB Software Notes</h2>
September 29, 2003<br>
<br>
The changes for USB to be used as the low level transport for the RDB
protocol have been checked in since of June 13, 2003. As of the current
date, the facility works and gives throughput for downloading game rom images
to a flash card of about 400KB/s. This is a little more than twice
the performance of IDE. The RDB protocol is the underlying communication
mechanism between the <b>libultrahost</b> calls on the host (<i>uhReadGame</i>
, <i> uhWriteGame</i>) and the <b>libultra</b> calls <i>osReadHost</i>,
<i> osWriteHost</i> and <i>osRdbSend</i> on the BB.<br>
<br>
This document describes how to use the USB support for debugging and then
describes the changes made to <b>libultra</b> and other tools to implement
RDB over USB.<br>
<h3>Using RDB over USB</h3>
The steps to install and use USB are as follows:<br>
<ul>
<li>Update your tree to at least mid-day on July 3 at the<i> rf/sw</i>
level, since the USB support requires files from both the <i>devroot</i>
subtree and the <i>bbplayer</i> subtree.</li>
<li>Rebuild at least <i>bbplayer/libultra</i>, <i>bbplayer/tools</i>
and <i>bbplayer/bbapps</i>. Safer is just to do the full rebuild:</li>
<ul>
<li>cd bbplayer</li>
<li>make clobber</li>
<li>make headers</li>
<li>make exports</li>
<li>make</li>
</ul>
<li>On the linux system to which the master end of the USB cable will
be connected, install the loadable kernel driver for USB by following these
steps:</li>
<ul>
<li>cd devroot/linux</li>
<li>su</li>
<li>make install_root</li>
</ul>
<li>Note that this driver will only compile on later 2.4.x versions
of linux. It has been tested on RH8.0 (2.4.18-14) and is known to
compile on RH7.2 (2.4.7-10) and RH7.3 (2.4.18-3). Note that compiling
the loadable module for the driver requires that you have the kernel source
option for your distribution installed, since the compile requires the kernel
headers that match your running kernel.<br>
</li>
<li>The build may generate some compile warnings on bbrdb.c, but these
can be ignored. If the build tree is NFS-mounted, you may encounter
permission problems on the "make install_root". The problem is that
this make must be run as <b>root</b> on the NFS client, since it is installing
the driver loadable module under <i>/lib/modules</i>. By default, <b>root</b>
gets translated to <b>nobody</b> across NFS (referred to as "root squashing"),
so <b>root</b> may not be able to write the .o file in <i>devroot/linux/modules</i>
. There are at least two ways to solve the problem:</li>
<ul>
<li>If you are comfortable with allowing <b>root</b> on the client
to become <b>root</b> on your NFS server, you can add the "<i>no_root_squash</i>
" option to the appropriate export specification in the <i>/etc/exports</i>
file on your NFS server.</li>
<li>If you prefer to leave the NFS mount in "<i>root_squash</i>" mode,
you can allow world write on the <i>devroot/linux/modules</i> directory in
your workarea:</li>
<ul>
<li>cd rf/sw/devroot/linux</li>
<li>chmod 777 modules</li>
</ul>
<li>If you don't like either of the above, you can run the make step
as your normal user id (this requires good time synchronization between NFS
client and server):</li>
<ul>
<li>cd rf/sw/devroot/linux/modules</li>
<li>make</li>
<li>su</li>
<li>make install</li>
</ul>
</ul>
<li>If the build of bbrdb.o fails altogether, it probably means that
kernel source is not installed on your development system. You can
find the RPMS under <b>stilton:/big/redhat</b>. Look for "<b>kernel-source*</b>
" under <i>disk2/RedHat/RPMS</i> of the appropriate version of RedHat. Use
"rpm -i" to install the kernel source RPM and then try again.<br>
</li>
<li>Obtain a USB cable with a normal "cat-A" (USB host) connector on
one end and a 5 pin "mini-B" connector on the other. These can be purchased
at Fry's in the normal "Computer Cables" section, although they are sometimes
out of stock. Note that there are 4-pin and 5-pin "mini-B" connectors.
Make sure to get the "5-pin mini-B" variety. Or you can ask Paul
and hope that he has one in stock.</li>
<li>Connect the cable between your linux host and the BB player. The
connector on the BB end can be hot plugged, just like on the host end.</li>
</ul>
<h3>Using shell/mon</h3>
In order to download rom images, tickets or other files to a flash card,
you can use <i>shell</i> and <i>mon</i> over USB as follows:<br>
<ul>
<li>The program <i>bbplayer/bbapps/usbmon/rom</i> needs to be running
on the BB. This can be accomplished in a several ways:</li>
<ul>
<li>Get a flash card with <i>usbmon</i> already installed (talk to
Paul, Tong or Andy to find one of these cards).</li>
<li>Load usbmon yourself using jtag:</li>
<ul>
<li>jboot -v -r bbapps/usbmon/rom</li>
</ul>
</ul>
<li>On the linux host, execute <i>mux</i> and <i>shell</i> (you probably
want these in different windows):</li>
<ul>
<li>cd tools/mux</li>
<li>mux -u</li>
<li>cd ../../bbapps/mon</li>
<li>./shell</li>
</ul>
<li>The "-u" option to mux specifies that it should ignore IDE and use
USB as the low level transport for RDB.</li>
<li>At this point, shell should work the same way it did over IDE.</li>
</ul>
<h3>Using emsh/emsmon</h3>
<i>Emsh</i> and <i>emsmon</i> are more advanced versions of <i>shell</i>
and <i>usbmon</i> that were originally intended for use in manufacturing.
The primary differences are:<br>
<ul>
<li><i>emsh</i> includes the <i>mux</i> logic, so it is no longer necessary
to start a separate <i>mux</i> process</li>
<li><i>emsh</i> includes a new set of commands that use the <i>libbbc</i>
API to perform operations on the BB player or the BB card reader</li>
<li><i>emsh</i> supports the USB BB card reader in addition to a BB Player,
although only the <i>libbbc</i> commands work in this mode</li>
</ul>
To use <i>emsh</i> with a BB Player, build <i>emsmon</i> and <i>emsh</i>
and then use <i>usbmon</i> to load <i>emsmon</i> onto the flash card. Then
do the following:<br>
<ul>
<li>Connect the BB Player to the linux host</li>
<li>Start <i>emsmon.aes</i> on the player</li>
<li>Invoke <i>emsh</i> on the linux host</li>
<li>See the help command ("h") and the include file <i>bbcard.h</i> for
more information on the BBC commands/API</li>
<li>Use the 'B' command to open the BB player in a way that allows full
use of the BBC commands</li>
<li>Use the 'O' command to open the BB player in a way that allows use
of only the <i>usbmon</i> subset (in this case only <i>usbmon</i> is required
on the player side).</li>
</ul>
<h3>Using <i>osSyncPrintf</i> over USB</h3>
In order for an application to print to the <i>mux</i> window using <i>
osSyncPrintf</i> over USB, it necessary to make one change to the application
code:<br>
<br>
After the call to <i>osInitialize()</i> and after the idle thread has
been started and before the first call to <i> osSyncPrintf(),</i> insert
the following call:<br>
<blockquote>(void) osBbUsbInit();<br>
</blockquote>
<i>osBbUsbInit</i> returns the number of USB controllers found (always
2 on BB) or -1 if an error occurs. Note that adding this call drags
in all the USB code from <i>libultra,</i> which will increase the static
size of the executable by about 35K bytes in the current state of the code.
Since <i>osBbUsbInit</i> creates and starts some threads, it will
cause your application to hang if you call it before starting the idle thread.<br>
<h3>Common Problems<br>
</h3>
<b>The compile of the linux <i>bbrdb</i> driver module fails<br>
<br>
</b>This means that either the version of linux on your system is too old
to be compatible with the <i>bbrdb</i> driver code or, more likely, the kernel
source is not loaded on your system. The kernel source RPM needs to
be loaded in order to compile a loadable kernel driver. Check the directory
<i> /lib/modules/<your version>/build/include</i>, where <<i>your
version</i> > is the result of "<b>uname -r</b>". If that directory
is missing or empty, then you need to install the kernel source on the system.
The CD contents for RedHat versions 7.2, 7.3 and 8.0 can be found on
<b>stilton:/big/redhat</b> . In each version, the kernel source RPM
is on disk2.<br>
<b><br>
When <i>usbmon</i> is started, nothing happens</b> <br>
<br>
When <i>usbmon</i> is executed, the linux host hot plug agent should recognize
the new USB device. It has been observed on some systems that this
does not happen automatically. Check <i>/var/log/messages</i> to see
if you got a connect message for the <i>bbrdb</i> driver. If not, you
can manually load the driver using <i>insmod</i>:<br>
<blockquote>su<br>
/sbin/insmod bbrdb.o<br>
</blockquote>
The <i>mux</i> and <i>shell</i> programs should not normally need to be
restarted across a reboot of the BB player, but there are still some cases
in which it will be necessary to restart all three of <i>usbmon,</i> <i>mux</i>
and <i>shell</i> (in that order) to get things back in sync.<br>
<br>
<b>Starting <i>mux</i> fails saying "Bind: address already in use"</b><br>
<br>
This means that some other user has run <i>mux</i> on this linux system
and owns the fifo files in<i> /tmp</i>. The remedy is simple:<br>
<blockquote>su<br>
cd /tmp<br>
rm u64*<br>
</blockquote>
<b>Starting <i>mux</i> fails with the message "Printserver failed: /usr/lib/PR/error.fmt
not found"</b><br>
<br>
This means that you have not run "<b>make install</b>" in the directory
<i> bbplayer/lib/error</i> on this linux system yet.<br>
<br>
<b>Adding the <i>osBbUsbInit</i>() call to the application causes it to
stop working or crash before doing anything interesting</b><br>
<br>
The most likely cause of this is calling <i>osBbUsbInit</i> from the "boot"
routine, before the idle thread is started. <i>osBbUsbInit</i> starts
2 threads, so control will not return to the boot routine after calling <i>osBbUsbInit</i>.
Move the call to <i>osBbUsbInit</i> into the idle thread or one of
the other program threads that runs early on.<br>
<br>
<b>Some of the calls to <i>osSyncPrintf</i> in my program seem to get lost</b><br>
<br>
It turns out that it takes about 800 milliseconds after the call to <i>osBbUsbInit</i>
for the linux USB RDB driver to be ready for input. Any <i>osSyncPrintf</i>
calls that happen sooner than about 800 milliseconds after <i>osBbUsbInit</i>
will be lost. Subsequent <i>osSyncPrintf</i> calls should continue
to work, though.<br>
<h3>Implementation</h3>
<h3>Libultra Files Changed</h3>
The code for <i>osReadHost</i> and fellows lives in <i>libultra/monegi/host</i>
. The only changes here are:<br>
<br>
<b>initrdb.c</b> - clear flag used to indicate that USB is the RDB transport<br>
<b>rdbsend.c</b> - check USB flag to decide whether to send data by USB
or IDE<br>
<br>
The USB driver code lives in <i>libultra/bb/usb</i>. The main routine
to look at there is in:<br>
<br>
<b>rdb_slave.c</b> - the routine<i> rdb_ip6_input</i> contains the code
for USB that is analogous to the interrupt code in <i>nintendo/exception/exceptasm.s</i>
for processing incoming RDB packets. There is a switch statement
that currently only understands HtoG_DATA, HtoG_DATAB and HtoG_DATA_DONE.
Note that the routine<i> rdbs_device_init</i> sets the flag to indicate
that USB is to be used.<br>
<h3>Utilities Changed</h3>
<b>tools/mux/mux.c</b> - added command line flag<b> -u</b> to select
USB as the transport (off by default for now). Modified all the places
that do IO to the lower level stream to choose the appropriate device.<br>
<b><br>
bbapps/mon/mon.c</b> - add initialization for USB, disabled with an ifdef.
To build the USB version of mon, use the following directory;<br>
<br>
<b>bbapps/usbmon</b> - uses vpath to reference <b>mon.c</b> from <b>../mon</b>
, but compiles it with the USB flag turned on.<br>
<h3>Linux RDB driver</h3>
<b>devroot/linux/modules</b> - doing "make install_root" at the <b>devroot/linux</b>
level will build and install the kernel loadable module for the BBRDB
driver. This has currently been tested only on RedHat 8.0, but compiles
and loads on RedHat 7.3.<br>
<br>
<b>bbrdb.c</b> - this is the linux <b>bbrdb</b> driver. It implements
select and non-blocking reads.<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
</body>
</html>