auxdata.html
15.3 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
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Auxiliary Data State Saving</title>
</head>
<body>
<h2 align="center">Auxiliary Game State Saving API</h2>
<br>
<div align="center">$Revision: 1.7 $<br>
$Date: 2004/12/01 23:07:59 $<br>
</div>
<br>
The following API is provided to support traveling data for Animal
Forest. Games using these state saving functions must first call <span
style="font-weight: bold; font-family: monospace;">osBbAuxDataInit()</span>.
Here is sample code that should be executed in a real thread (not
the
boot thread) after the PI manager thread has been started:<br>
<blockquote><b style="font-family: monospace;">#include
<ultra64.h><br>
#include <os_bb.h><br>
#include <os_bbfs.h><br>
#include <os_bbexec.h></b><br>
<b style="font-family: monospace;"> <br>
char auxbuf[32768] __attribute__((aligned(16)));<br>
osBbAuxDataInit(auxbuf, sizeof(auxbuf));<br>
</b></blockquote>
The buffer passed to <small><span style="font-weight: bold;">osBbAuxDataInit</span></small>
must be a least 32K bytes in size and must be aligned on a cache-line
boundary (16 bytes). Once the call has been made, the buffer
should not be used by the application for any other purpose. If
the cartridge is removed and any cartridge (even the same one) is
reinserted after <small><span style="font-weight: bold;">osBbAuxDataInit</span></small>
has been called, subsequent calls to any of the functions in the
Auxiliary Game State Saving API will fail until <small><span
style="font-weight: bold;">osBbAuxDataInit</span></small> has been
called again. This is necessary to initialize the file system
data structures associated with the cartridge. Note that the same
buffer should be used on all calls to <small><span
style="font-weight: bold;">osBbAuxDataInit.</span></small><br>
<h3>Game State API Changes </h3>
A function is provided for a game to commit the game state in memory to
the BBCard. For a game to use this function, the game must be published
with access to the BBCard and the ability to sign a file (the game also
must be linked with <i>libcrypto.a</i>). Even though this
function
is not part of the Auxiliary Data set of functions, <span
style="font-family: monospace; font-weight: bold;">osBbAuxDataInit</span>
has to be called before this function can be used.<br>
<br>
<span style="font-family: monospace;"> /* </span><br
style="font-family: monospace;">
<span style="font-family: monospace;"> * Commits the state to the
BBCard
from within a Game.<br>
* NOTE: osBbAuxDataInit must be called before this function can
be
used. </span><br style="font-family: monospace;">
<span style="font-family: monospace;"> * Returns 0 if successful,
<0
if unsuccessful. </span><br style="font-family: monospace;">
<span style="font-family: monospace;"> */ </span><br
style="font-family: monospace;">
<b style="font-family: monospace;">s32 osBbGameCommitState()</b><span
style="font-family: monospace;">;</span><br>
<br>
After this call returns, any game state saved using the iQue Player's
emulation
of N64 Game Paks (Flash, EEPROM or SRAM) or Controller Paks will be
written
to a file on the iQue cartridge.
<h3>Auxiliary Game Data API</h3>
The traveling data will be saved as unsigned auxiliary data that is
separate from the main game data. Each game can theoretically have up
to 16 32K auxiliary
data, although the actual number of auxiliary data files that can be
created
by any one game is limited by the metadata<span
style="font-style: italic;"></span> to four. The auxiliary data for
each
game will be identified by the content ID of that game, and the
traveling
data can be shared only between players for a game of the same content
ID.
So if 2 iQue Players and cards have different versions of the same
game,
the cids will be different and they will not be able to share the
traveling
data. The auxiliary data will be stored in the file cid.u0x where x is
the
state ID (0 to f). All game state files will be renamed with the new
cid
when the game version is updated. The API functions are described
below.
Note that they will use the same error return codes as the
cartridge
file system API (see<i> os_bbfs.h</i>). Each function will access the
BBCard
directly. In order to use them, the game must be published with
rights
to access the card. <br>
<br>
NOTE: To determine the cid of the game, these functions uses
information
set up by the viewer. If the information is not found (perhaps due
to an older version of the viewer), these functions will return <span
style="font-family: monospace; font-weight: bold;">BBFS_ERR_STATE</span>.<br>
<br>
<pre>/*<br> * Initializes the card for auxiliary game data. Must be called each<br> * time a new card is inserted, before any other auxiliary game data <br> * functions or osBbGameCommitState can be used.<br> * Parameters:<br> * buf - Buffer for internal state. Must be 16 byte aligned.<br> * NOTE: buf should not be reused by the calling application<br> * for any other purpose<br> * len - Length of the buffer, must be at least 32KB.<br> * Returns: 0 if successful, <0 if unsuccessful<br> */<span
style="font-weight: bold; font-family: monospace;"><br>s32 osBbAuxDataInit(void* buf, u32 len);</span><br
style="font-weight: bold; font-family: monospace;"></pre>
<span style="font-family: monospace;"> /* </span><br
style="font-family: monospace;">
<span style="font-family: monospace;"> * Saves the auxiliary data
to
the card. If a file with the </span><br style="font-family: monospace;">
<span style="font-family: monospace;"> * specifed id already
exists,
that file will be overwritten. </span><br
style="font-family: monospace;">
<span style="font-family: monospace;"> * NOTE: skExit() should be
called after all auxiliary data </span><br
style="font-family: monospace;">
<span style="font-family: monospace;"> * has been saved to force
a
save to card of the main game state. </span><br
style="font-family: monospace;">
<span style="font-family: monospace;"> * Parameters: </span><br
style="font-family: monospace;">
<span style="font-family: monospace;"> * buf - Data to write
(must
be 16 byte aligned)</span><br style="font-family: monospace;">
<span style="font-family: monospace;"> * len - Length of the
buffer,
must be a multiple of 16K and <= 32K </span><br
style="font-family: monospace;">
<span style="font-family: monospace;"> * id - Aux Data ID (0-15)</span><br
style="font-family: monospace;">
<span style="font-family: monospace;"> * Returns: number of bytes
saved
if successful, </span><br style="font-family: monospace;">
<span style="font-family: monospace;"> <span
style="font-family: monospace;">* < 0 (see error codes
below) if unsuccessfu</span><br style="font-family: monospace;">
<span style="font-family: monospace;"> </span></span><span
style="font-family: monospace;">* <span
style="font-weight: bold;">BBFS_ERR_STATE_LIMIT</span> is returned if
id
is valid but <br>
* is >= number of auxiliary data files
specified
in the metadata</span><br style="font-family: monospace;">
<span style="font-family: monospace;"><span
style="font-family: monospace;"> </span>*/ </span><br
style="font-family: monospace;">
<b style="font-family: monospace;">s32 osBbAuxDataSave(u8 id, void*
buf,
u32 len)</b><span style="font-family: monospace;">;</span><br
style="font-family: monospace;">
<br style="font-family: monospace;">
<span style="font-family: monospace;"> /* </span><br
style="font-family: monospace;">
<span style="font-family: monospace;"> * Loads the auxiliary data
from
the card </span><br style="font-family: monospace;">
<span style="font-family: monospace;"> * Parameters: </span><br
style="font-family: monospace;">
<span style="font-family: monospace;"> * buf - Buffer to receive
the
data (must be 16 byte aligned)</span><br style="font-family: monospace;">
<span style="font-family: monospace;"> * len - Length of the
buffer,
must be a multiple of 16K</span><br style="font-family: monospace;">
<span style="font-family: monospace;"> * id - Aux Data ID (0-15)</span><br
style="font-family: monospace;">
<span style="font-family: monospace;"> * Returns: number of bytes
read
if successful, <0 if unsuccessful </span><br
style="font-family: monospace;">
<span style="font-family: monospace;"> */ </span><br
style="font-family: monospace;">
<b style="font-family: monospace;">s32 osBbAuxDataLoad(u8 id, void*
buf,
u32 len)</b><span style="font-family: monospace;">;</span><br
style="font-family: monospace;">
<br style="font-family: monospace;">
<span style="font-family: monospace;"> /* </span><br
style="font-family: monospace;">
<span style="font-family: monospace;"> * Remove the auxiliary
data from the card </span><br style="font-family: monospace;">
<span style="font-family: monospace;"> * Parameters: </span><br
style="font-family: monospace;">
<span style="font-family: monospace;"> * id - Aux Data ID (0-15)</span><br
style="font-family: monospace;">
<span style="font-family: monospace;"> * Returns: 0 if
successful, <0 if unsuccessful</span><br
style="font-family: monospace;">
<span style="font-family: monospace;"> */ </span><br
style="font-family: monospace;">
<b style="font-family: monospace;">s32 osBbAuxDataDelete(u8 id)</b><span
style="font-family: monospace;">; </span><br
style="font-family: monospace;">
<br style="font-family: monospace;">
<span style="font-family: monospace;"> /*</span><br
style="font-family: monospace;">
<span style="font-family: monospace;"> * Provides the size of the
auxiliary
data</span><br style="font-family: monospace;">
<span style="font-family: monospace;"> * Parameters:</span><br
style="font-family: monospace;">
<span style="font-family: monospace;"> * id - Aux Data ID (0-15)</span><br
style="font-family: monospace;">
<span style="font-family: monospace;"> * Returns: size of user
data
if successful, <0 if unsuccessful</span><br
style="font-family: monospace;">
<span style="font-family: monospace;"> */ </span><br
style="font-family: monospace;">
<b style="font-family: monospace;">s32 osBbAuxDataSize(u8 id)</b><span
style="font-family: monospace;">;</span><br
style="font-family: monospace;">
<br style="font-family: monospace;">
<span style="font-family: monospace;"> /* </span><br
style="font-family: monospace;">
<span style="font-family: monospace;"> * Provides a list of
auxiliary
data ids on the card for the game </span><br
style="font-family: monospace;">
<span style="font-family: monospace;"> * Parameters:</span><br
style="font-family: monospace;">
<span style="font-family: monospace;"> * ids - Buffer to receive
the
ids</span><br style="font-family: monospace;">
<span style="font-family: monospace;"> * Returns: # of ids if
successful,
<0 if unsuccessful</span><br style="font-family: monospace;">
<span style="font-family: monospace;"> */</span><br
style="font-family: monospace;">
<b style="font-family: monospace;">s32 osBbAuxDataIds(u8 ids[16])</b><span
style="font-family: monospace;">; </span><br>
<br>
<i><b>Error codes</b></i><br>
<br>
These functions will return the following error codes to indicate
failures:
<br>
<br>
<span style="font-family: monospace; font-weight: bold;"> #define
BBFS_ERR_NO_CARD
(-1) /* card not present */ </span><br
style="font-family: monospace; font-weight: bold;">
<span style="font-family: monospace; font-weight: bold;"> #define
BBFS_ERR_FAIL
(-2) /*
operation
failed */ </span><br style="font-family: monospace; font-weight: bold;">
<span style="font-family: monospace; font-weight: bold;"> #define
BBFS_ERR_INVALID
(-3) /* invalid parameters */</span><br
style="font-family: monospace; font-weight: bold;">
<span style="font-family: monospace; font-weight: bold;"> #define
BBFS_ERR_CHANGED
(-4) /* card changed
*/ </span><br style="font-family: monospace; font-weight: bold;">
<span style="font-family: monospace; font-weight: bold;"> #define
BBFS_ERR_UNINIT
(-5) /* fs
uninitialized
*/ </span><br style="font-family: monospace; font-weight: bold;">
<span style="font-family: monospace; font-weight: bold;"> #define
BBFS_ERR_EXISTS
(-6) /* file exists */ </span><br
style="font-family: monospace; font-weight: bold;">
<span style="font-family: monospace; font-weight: bold;"> #define
BBFS_ERR_SPACE
(-7) /* no space */ </span><br
style="font-family: monospace; font-weight: bold;">
<span style="font-family: monospace; font-weight: bold;"> #define
BBFS_ERR_ENTRY
(-8) /* no
entry
*/ </span><br style="font-family: monospace; font-weight: bold;">
<span style="font-family: monospace; font-weight: bold;"> #define
BBFS_ERR_STATE (-9)
/* invalid
state */</span><br style="font-family: monospace; font-weight: bold;">
<span style="font-family: monospace; font-weight: bold;">#define
BBFS_ERR_STATE_LIMIT
(-10) /* id over state limit */ </span><br
style="font-weight: bold;">
<h3>Usage Notes</h3>
<ul>
<li>If a game uses any of the Auxiliary Data APIs, then the ROM file
must
be processed with the <i>rommd</i> command to add metadata about how
many
Auxiliary Data files (from 0 to 4) it can create. For instance,
to
allow a game to create 4 auxiliary data files, use "<span
style="font-style: italic;">r</span><span style="font-style: italic;">ommd
-u4 <romfile></span>". The game can then save 4 auxiliary
data
files with ids from 0 to 3. If the game attempts to save an
auxiliary
data file with an id that is larger than 3, <b
style="font-family: monospace;">osBbAuxDataSave </b>will return <span
style="font-family: monospace; font-weight: bold;">BBFS_ERR_STATE_LIMIT</span>.</li>
<li>Games that use <b style="font-family: monospace;">osBbGameCommitState</b>
must be linked with <i>libcrypto.a</i>.</li>
<li>The buffers used to save and load auxiliary data must be
cache-line
aligned (16 byte boundary). In C this can be done by attaching "<span
style="font-family: monospace;">__attribute__ ((aligned (16)))</span>"
to
the data declaration.</li>
<li>The Game State and Auxiliary Data functions cannot be used
concurrently
with cartridge (PI) DMA. For instance, background audio loops
that
make accesses to the cartridge (i.e. the audio not preloaded into
memory)
need to be quiesced before the Game State or Auxiliary Data functions
can
be used. <br>
</li>
<li><span style="font-weight: bold; font-family: monospace;">osBbAuxDataInit</span>
must be called again if the card is changed. All Auxiliary Data
API functions will return the error code <small><span
style="font-weight: bold;">BBFS_ERR_CHANGED</span></small> in this
case. This will happen even if the same card is reinserted.
The same buffer should be used for all calls to <small><span
style="font-weight: bold;">osBbAuxDataInit.</span></small><br>
</li>
</ul>
<br>
<br>
<br>
</body>
</html>