1 /*---------------------------------------------------------------------------*
2 Project: TwlSDK - wireless_shared - demos - wfs
3 File: wfs.h
4
5 Copyright 2006-2008 Nintendo. All rights reserved.
6
7 These coded instructions, statements, and computer programs contain
8 proprietary information of Nintendo of America Inc. and/or Nintendo
9 Company Ltd., and are protected by Federal copyright law. They may
10 not be disclosed to third parties or copied or duplicated in any form,
11 in whole or in part, without the prior written consent of Nintendo.
12
13 $Date:: 2008-09-18#$
14 $Rev: 8573 $
15 $Author: okubata_ryoma $
16 *---------------------------------------------------------------------------*/
17
18 #ifndef NITRO_BUILD_DEMOS_WIRELESSSHARED_WFS_INCLUDE_WFS_H_
19 #define NITRO_BUILD_DEMOS_WIRELESSSHARED_WFS_INCLUDE_WFS_H_
20
21
22 #include <nitro.h>
23
24 #ifdef __cplusplus
25 extern "C" {
26 #endif
27
28
29 /*****************************************************************************/
30 /* Constants */
31
32
33 /*
34 * This enumerated type indicates the internal WFS state.
35 */
36 typedef enum
37 {
38 WFS_STATE_STOP,
39 WFS_STATE_IDLE,
40 WFS_STATE_READY,
41 WFS_STATE_ERROR
42 }
43 WFSState;
44
45
46 /*****************************************************************************/
47 /* Prototypes */
48
49 /*
50 * This callback is invoked whenever the internal WFS state changes.
51 * The FS will become usable automatically when WFS_STATE_READY is returned.
52 */
53 typedef void (*WFSStateCallback) (void *);
54
55
56 /*
57 * This is a dynamic memory allocation callback internal to WFS.
58 * arg is a user-defined argument.
59 * If ptr is NULL, return size bytes of memory.
60 * If ptr is not NULL, deallocate ptr.
61 */
62 typedef void *(*WFSAllocator) (void *arg, u32 size, void *ptr);
63
64
65 /*****************************************************************************/
66 /* Functions */
67
68 /*---------------------------------------------------------------------------*
69 Name: WFS_InitParent
70
71 Description: Initializes wireless file system (WFS) as parent.
72 Because this function configures and automatically activates the port callback to the WM library, this must be called when WM is in a READY state or later.
73
74
75 Arguments: port Port number used for internal MP communications.
76 callback Callback that receives various state notifications.
77 allocator Callback used for internal memory allocation.
78 The amount of memory the WFS uses is decided each time application runs.
79
80 allocator_arg User-defined argument given to allocator.
81 parent_packet Default parent send size.
82 This value must be WBT_PACKET_SIZE_MIN or greater, and equal to or smaller than parent maximum send size.
83
84 A child device will be simply ignored.
85 p_rom The file pointer indicating the program that includes the FAT/FNT/OVT provided to the child device.
86
87 Normally, this designates the child device program sent via wireless download.
88
89 Seek position maintains the position before the call.
90 When this argument is NULL, provides parent's own file system.
91
92 use_parent_fs When TRUE, provides parent's own FAT/FNT, not program specified with p-rom.
93
94 With these configurations, an independent parent/child program can share a single file system.
95
96 If p_rom is NULL, this setting is ignored, and always handled as shared.
97
98
99 Returns: None.
100 *---------------------------------------------------------------------------*/
101 void WFS_InitParent(int port, WFSStateCallback callback,
102 WFSAllocator allocator, void *allocator_arg, int parent_packet,
103 FSFile *p_rom, BOOL use_parent_fs);
104
105 /*---------------------------------------------------------------------------*
106 Name: WFS_InitChild
107
108 Description: Initializes wireless file system (WFS) as child.
109 Because this function configures and automatically activates the port callback to the WM library, this must be called when WM is in a READY state or later.
110
111
112 Arguments: port Port number used for internal MP communications.
113 callback Callback that receives various state notifications.
114 allocator Callback used for internal memory allocation.
115 The amount of memory the WFS uses is decided each time application runs.
116
117 allocator_arg User-defined argument given to allocator.
118
119 Returns: None.
120 *---------------------------------------------------------------------------*/
121 void WFS_InitChild(int port, WFSStateCallback callback,
122 WFSAllocator allocator, void *allocator_arg);
123
124 /*---------------------------------------------------------------------------*
125 Name: WFS_Init
126
127 Description: Initializes wireless file system (WFS).
128 After initializing internal state as parent or child, this function configures and automatically activates the port callback to the WM library. This function must be called when WM is in a READY state or later.
129
130
131
132 Arguments: is_parent If wireless parent, TRUE. If child, FALSE.
133 For actual multiboot, this argument is given !MB_IsMultiBootChild().
134
135 port Port number used for internal MP communications.
136 parent_packet Default parent send size.
137 This value must be WBT_PACKET_SIZE_MIN or greater, and equal to or smaller than parent maximum send size.
138
139 A child device will be simply ignored.
140 callback Callback that receives various state notifications.
141 allocator Callback used for internal memory allocation.
142 The amount of memory the WFS uses is decided each time application runs.
143
144 allocator_arg User-defined argument given to allocator.
145
146 Returns: None.
147 *---------------------------------------------------------------------------*/
WFS_Init(BOOL is_parent,int port,int parent_packet,WFSStateCallback callback,WFSAllocator allocator,void * allocator_arg)148 SDK_INLINE void WFS_Init(BOOL is_parent, int port, int parent_packet,
149 WFSStateCallback callback, WFSAllocator allocator, void *allocator_arg)
150 {
151 if (is_parent)
152 WFS_InitParent(port, callback, allocator, allocator_arg, parent_packet, NULL, TRUE);
153 else
154 WFS_InitChild(port, callback, allocator, allocator_arg);
155 }
156
157 /*---------------------------------------------------------------------------*
158 Name: WFS_Start
159
160 Description: For WFS, sends notification that wireless has entered MP state.
161 After this notification, WFS uses WM_SetMPDataToPort() and runs automatically with "Priority: low (WM_PRIORITY_LOW)".
162
163 For this reason, it must be called in MP_PARENT or MP_CHILD state.
164
165 Normally, this function is called in the WM_StartMP() callback after WM_STATECODE_MP_START is passed to the parameter state.
166
167
168 Arguments: None.
169
170 Returns: None.
171 *---------------------------------------------------------------------------*/
172 void WFS_Start(void);
173
174 /*---------------------------------------------------------------------------*
175 Name: WFS_End
176
177 Description: Called when WFS is not needed.
178 Deallocates all internally allocated memory and returns to state before initialization.
179 Normally, this is called when all wireless communications have been disconnected.
180 This function cannot be called from the interrupt handler.
181
182 Arguments: None.
183
184 Returns: None.
185 *---------------------------------------------------------------------------*/
186 void WFS_End(void);
187
188 /*---------------------------------------------------------------------------*
189 Name: WFS_GetStatus
190
191 Description: Gets current internal state of WFS in WFSState type.
192
193 Arguments: None.
194
195 Returns: One of WFSState-type enumerated values.
196 *---------------------------------------------------------------------------*/
197 WFSState WFS_GetStatus(void);
198
199 /*---------------------------------------------------------------------------*
200 Name: WFS_GetCurrentBitmap
201
202 Description: Gets the current child device group bitmap that WBT is aware of.
203 This function can only be called by the parent.
204
205 Arguments: None.
206
207 Returns: Currently recognized child devices.
208 *---------------------------------------------------------------------------*/
209 int WFS_GetCurrentBitmap(void);
210
211 /*---------------------------------------------------------------------------*
212 Name: WFS_GetSyncBitmap
213
214 Description: Gets bitmap of child group with access sync specified.
215 This function can only be called by the parent.
216
217 Arguments: None.
218
219 Returns: Child devices that are specified to synchronize access
220 *---------------------------------------------------------------------------*/
221 int WFS_GetSyncBitmap(void);
222
223 /*---------------------------------------------------------------------------*
224 Name: WFS_GetBusyBitmap
225
226 Description: Gets bitmap of child devices that are currently accessing parent.
227 This function can only be called by the parent.
228
229 Arguments: None.
230
231 Returns: Child devices that are currently accessing parent.
232 *---------------------------------------------------------------------------*/
233 int WFS_GetBusyBitmap(void);
234
235 /*---------------------------------------------------------------------------*
236 Name: WFS_IsBusy
237
238 Description: Determines whether the child device of a designated AID is being accessed.
239 This function can only be called by the parent.
240
241 Arguments: aid AID of child to check.
242
243 Returns: If the designated child device is being accessed, TRUE. Otherwise, FALSE.
244 *---------------------------------------------------------------------------*/
245 BOOL WFS_IsBusy(int aid);
246
247 /*---------------------------------------------------------------------------*
248 Name: WFS_GetCurrentDownloadProgress
249
250 Description: Gets the progress status of the file that child is currently performing ReadFile with.
251 The unit will be the WBT internal sequence number.
252 This function can only be called by children.
253
254 Arguments: current_count Address to the variable storing the number of currently received sequences.
255
256 total_count Address to the variable storing the total number of sequences that should be received.
257
258
259 Returns: If this is the current ReadFile state and the correct progress can be obtained, TRUE.
260 Otherwise, returns FALSE.
261 *---------------------------------------------------------------------------*/
262 BOOL WFS_GetCurrentDownloadProgress(int *current_count, int *total_count);
263
264 /*---------------------------------------------------------------------------*
265 Name: WFS_GetPacketSize
266
267 Description: Gets MP communication packet size of parent set in WFS.
268
269 Arguments: None.
270
271 Returns: MP communication packet size of parent set in WFS.
272 *---------------------------------------------------------------------------*/
273 int WFS_GetPacketSize(void);
274
275 /*---------------------------------------------------------------------------*
276 Name: WFS_SetPacketSize
277
278 Description: Sets parent MP communication packet size.
279 If this value is increased, it will improve transmission efficiency. If it is decreased, the single MP communication transmission will be bundled with separate port communications such as data sharing, and unilateral slowdowns due to the port priority can be avoided.
280
281
282 This function can only be called by the parent.
283
284 Arguments: size Parent send size to set.
285 This value must be WBT_PACKET_SIZE_MIN or greater, and equal to or smaller than parent maximum send size.
286
287
288 Returns: None.
289 *---------------------------------------------------------------------------*/
290 void WFS_SetPacketSize(int size);
291
292 /*---------------------------------------------------------------------------*
293 Name: WFS_EnableSync
294
295 Description: Configures the settings of the child device group that takes access synchronization on the parent device side.
296 This function achieves efficient transmission rates that utilities unique characteristics of the WBT library; this is done by synchronizing responses to child devices that are all guaranteed to access the same files in precisely the same order.
297
298
299 However, be cautious of the fact that if the synchronization start timing is not logically safe, responses to child devices will become out-of-sync, causing deadlocks to occur.
300
301 This function can only be called by the parent.
302
303 Arguments: sync_bitmap The AID bitmap of the child device group that takes the access synchronization.
304 The lowest bit 1 indicating the parent device itself is ignored.
305 By assigning 0 for this value, synchronicity does not occur.
306 This is the default state.
307
308 Returns: None.
309 *---------------------------------------------------------------------------*/
310 void WFS_EnableSync(int sync_bitmap);
311
312 /*---------------------------------------------------------------------------*
313 Name: WFS_DisableSync
314
315 Description: The parent device releases access synchronization among child devices.
316 This function is equivalent to specifying WFS_EnableSync() 0.
317
318 Arguments: None.
319
320 Returns: None.
321 *---------------------------------------------------------------------------*/
WFS_DisableSync(void)322 SDK_INLINE void WFS_DisableSync(void)
323 {
324 WFS_EnableSync(0);
325 }
326
327 /*---------------------------------------------------------------------------*
328 Name: WFS_SetDebugMode
329
330 Description: Enables/disables WFS internal debug output.
331 The default setting is FALSE.
332
333 Arguments: enable_debug TRUE if debug output is enabled. FALSE if disabled.
334
335 Returns: None.
336 *---------------------------------------------------------------------------*/
337 void WFS_SetDebugMode(BOOL enable_debug);
338
339
340 /*****************************************************************************/
341
342
343 #ifdef __cplusplus
344 } /* extern "C" */
345 #endif
346
347
348 #endif /* NITRO_BUILD_DEMOS_WIRELESSSHARED_WFS_INCLUDE_WFS_H_ */
349