1 /*---------------------------------------------------------------------------*
2 Project: TwlSDK - WBT - include
3 File: wbt.h
4
5 Copyright 2003-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_WBT_H__
19 #define NITRO_WBT_H__
20
21 #ifdef __cplusplus
22 extern "C" {
23 #endif
24
25 /*===========================================================================*/
26
27 #include <nitro/types.h>
28 #include <nitro/os.h>
29
30 /*---------------------------------------------------------------------------*
31 Type Definitions
32 *---------------------------------------------------------------------------*/
33
34 /* Format for WBT callback functions */
35 typedef void (*WBTCallback) (void *);
36
37
38 /*---------------------------------------------------------------------------*
39 Constant Definitions
40 *---------------------------------------------------------------------------*/
41
42 /* Total number of blocks that can be registered with WBT_RegisterBlock */
43 #define WBT_NUM_MAX_BLOCK_INFO_ID 1000
44
45 /* Minimum value of a block ID that can be registered with WBT_RegisterBlock */
46 #define WBT_BLOCK_ID_MIN WBT_NUM_MAX_BLOCK_INFO_ID
47
48 /*
49 * Minimum packet size that can be set with WBT_InitParent for parent and child devices.
50 * If you set the size to be greater than this value and less than the maximum value specified for MP communications, the WBT protocol creates block transfer packets within that size.
51 *
52 */
53 #define WBT_PACKET_SIZE_MIN 14
54
55 /* Size of the user definition ID area that can be acquired by WBT_GetBlockInfo */
56 #define WBT_USER_ID_LEN 32
57
58 /* Maximum size of the user definition data that can be specified by WBT_PutUserData */
59 #define WBT_SIZE_USER_DATA 9
60
61 /* WBT error codes */
62 typedef s16 WBTResult;
63 #define WBT_RESULT_SUCCESS 0
64 #define WBT_RESULT_ERROR_TIMEOUT 1
65 #define WBT_RESULT_ERROR_UNKNOWN_USER_COMMAND 2
66 #define WBT_RESULT_ERROR_UNKNOWN_PACKET_COMMAND 3
67 #define WBT_RESULT_ERROR_PARSE_INVALID 4
68 #define WBT_RESULT_ERROR_RECV_BUFFER_OVERFLOW 5
69 #define WBT_RESULT_ERROR_SAVE_FAILURE 6
70
71 /* Enum for the callback type */
72 typedef enum
73 {
74 WBT_CMD_REQ_NONE = 0,
75 WBT_CMD_REQ_WAIT,
76 WBT_CMD_REQ_SYNC,
77 WBT_CMD_RES_SYNC,
78 WBT_CMD_REQ_GET_BLOCK,
79 WBT_CMD_RES_GET_BLOCK,
80 WBT_CMD_REQ_GET_BLOCKINFO,
81 WBT_CMD_RES_GET_BLOCKINFO,
82 WBT_CMD_REQ_GET_BLOCK_DONE,
83 WBT_CMD_RES_GET_BLOCK_DONE,
84 WBT_CMD_REQ_USER_DATA,
85 WBT_CMD_RES_USER_DATA,
86 WBT_CMD_SYSTEM_CALLBACK,
87 WBT_CMD_PREPARE_SEND_DATA,
88 WBT_CMD_REQ_ERROR,
89 WBT_CMD_RES_ERROR,
90 WBT_CMD_CANCEL
91 }
92 WBTCommandType;
93
94
95 /* Macro to calculate the received bitmap size from the packet size */
96 #define WBT_PACKET_BITMAP_SIZE(block_size, packet_size) \
97 (((((block_size) + ((packet_size) - WBT_PACKET_SIZE_MIN) - 1)/((packet_size) - WBT_PACKET_SIZE_MIN)) + 31 )/sizeof(u32)) * sizeof(u32)
98
99
100 /* Macros that specify AID */
101 #define WBT_NUM_OF_AID (WBT_AID_CHILD_LAST+1)
102 #define WBT_AID_PARENT 0
103 #define WBT_AID_CHILD_FIRST 1
104 #define WBT_AID_CHILD_LAST (WBT_AID_CHILD_FIRST + 15 - 1)
105 #define WBT_AIDBIT_ALL ((WBTAidBitmap)0xffff)
106 #define WBT_AIDBIT_PARENT ((WBTAidBitmap)1)
107 #define WBT_AIDBIT_CHILD_ALL ((WBTAidBitmap)0xfffe)
108 #define WBT_AIDBIT_CHILD_1 ((WBTAidBitmap)(1<< 1))
109 #define WBT_AIDBIT_CHILD_2 ((WBTAidBitmap)(1<< 2))
110 #define WBT_AIDBIT_CHILD_3 ((WBTAidBitmap)(1<< 3))
111 #define WBT_AIDBIT_CHILD_4 ((WBTAidBitmap)(1<< 4))
112 #define WBT_AIDBIT_CHILD_5 ((WBTAidBitmap)(1<< 5))
113 #define WBT_AIDBIT_CHILD_6 ((WBTAidBitmap)(1<< 6))
114 #define WBT_AIDBIT_CHILD_7 ((WBTAidBitmap)(1<< 7))
115 #define WBT_AIDBIT_CHILD_8 ((WBTAidBitmap)(1<< 8))
116 #define WBT_AIDBIT_CHILD_9 ((WBTAidBitmap)(1<< 9))
117 #define WBT_AIDBIT_CHILD_10 ((WBTAidBitmap)(1<< 10))
118 #define WBT_AIDBIT_CHILD_11 ((WBTAidBitmap)(1<< 11))
119 #define WBT_AIDBIT_CHILD_12 ((WBTAidBitmap)(1<< 12))
120 #define WBT_AIDBIT_CHILD_13 ((WBTAidBitmap)(1<< 13))
121 #define WBT_AIDBIT_CHILD_14 ((WBTAidBitmap)(1<< 14))
122 #define WBT_AIDBIT_CHILD_15 ((WBTAidBitmap)(1<< 15))
123
124
125
126
127 /*
128 * For internal use {
129 */
130 typedef u8 WBTPacketCommand;
131 typedef u8 WBTCommandCounter;
132 typedef u32 WBTBlockId;
133 typedef u16 WBTAidBitmap;
134 typedef s8 WBTPermission;
135 typedef s32 WBTBlockSeqNo;
136 typedef s16 WBTBlockNumEntry;
137 typedef s16 WBTPacketSize;
138 typedef s32 WBTBlockSize;
139 #define WBT_BLOCK_LIST_TYPE_COMMON 0
140 #define WBT_BLOCK_LIST_TYPE_USER 1
141 #define WBT_SIZE_COMMAND sizeof(WBTPacketCommand)
142 #define WBT_SIZE_TARGET_BITMAP sizeof(WBTAidBitmap)
143 #define WBT_SIZE_BLOCK_ID sizeof(WBTBlockId)
144 #define WBT_SIZE_BLOCK_SEQ_NO sizeof(WBTBlockseqNo)
145 #define WBT_SIZE_BLOCK_NUM_ENTRY sizeof(WBTBlockNumEntry)
146 #define WBT_SIZE_PERMISSION sizeof(WBTPermission)
147 /*
148 * } For internal use
149 */
150
151
152 /*---------------------------------------------------------------------------*
153 Structure Definitions
154 *---------------------------------------------------------------------------*/
155
156
157 typedef struct
158 {
159 u32 id;
160 s32 block_size;
161 u8 user_id[WBT_USER_ID_LEN];
162 }
163 WBTBlockInfo;
164
165 typedef struct WBTBlockInfoList
166 {
167 WBTBlockInfo data_info;
168 struct WBTBlockInfoList *next;
169 void *data_ptr;
170 WBTAidBitmap permission_bmp;
171 u16 block_type;
172 }
173 WBTBlockInfoList;
174
175 typedef struct
176 {
177 WBTBlockInfo *block_info[WBT_NUM_OF_AID];
178 }
179 WBTBlockInfoTable;
180
181 typedef struct
182 {
183 u32 *packet_bitmap[WBT_NUM_OF_AID];
184 }
185 WBTPacketBitmapTable;
186
187 typedef struct
188 {
189 u8 *recv_buf[WBT_NUM_OF_AID];
190 }
191 WBTRecvBufTable;
192
193 /* For command callback ******************************************************/
194
195 typedef struct
196 {
197 WBTBlockNumEntry num_of_list;
198 s16 peer_packet_size;
199 s16 my_packet_size;
200 u16 pad1;
201 u32 padd2[2];
202 }
203 WBTRequestSyncCallback;
204
205 typedef struct
206 {
207 u32 block_id;
208 }
209 WBTGetBlockDoneCallback;
210
211 typedef struct
212 {
213 u32 block_id;
214 s32 block_seq_no;
215 void *data_ptr;
216 s16 own_packet_size;
217 u16 padd;
218 }
219 WBTPrepareSendDataCallback;
220
221 typedef struct
222 {
223 u8 data[WBT_SIZE_USER_DATA];
224 u8 size;
225 u8 padd[3];
226 }
227 WBTRecvUserDataCallback;
228
229 typedef struct
230 {
231 u32 block_id;
232 u32 recv_data_size;
233 WBTRecvBufTable recv_buf_table;
234 WBTPacketBitmapTable pkt_bmp_table;
235 }
236 WBTGetBlockCallback;
237
238
239 typedef struct
240 {
241 WBTCommandType command;
242 WBTCommandType event;
243 u16 target_bmp;
244 u16 peer_bmp;
245 WBTCommandCounter my_cmd_counter;
246 WBTCommandCounter peer_cmd_counter; /* For debugging */
247 WBTResult result;
248 WBTCallback callback;
249 union
250 {
251 WBTRequestSyncCallback sync;
252 WBTGetBlockDoneCallback blockdone;
253 WBTPrepareSendDataCallback prepare_send_data;
254 WBTRecvUserDataCallback user_data;
255 WBTGetBlockCallback get;
256 };
257 }
258 WBTCommand;
259
260
261
262 /*---------------------------------------------------------------------------*
263 Function Definitions
264 *---------------------------------------------------------------------------*/
265
266
267 /* Initialization ************************************************************/
268
269
270 /*---------------------------------------------------------------------------*
271 Name: WBT_InitParent
272
273 Description: Initializes WBT-system as MP-parent state in WM.
274 This must be called before any WBT function at least once.
275 When called two or more times, it is only ignored.
276
277 Arguments: send_packet_size: available MP-parent packet size for WBT.
278 This must be below the value specified
279 by WM_SetParentParameter(), and must be
280 WBT_PACKET_SIZE_MIN at least.
281 recv_packet_size: available MP-child packet size for WBT.
282 This must be below the value specified
283 by WM_SetParentParameter(), and must be
284 WBT_PACKET_SIZE_MIN at least.
285 callback: callback function which receives
286 notifications from WBT-system.
287 If NULL is specified, any callback is ignored.
288
289 Returns: None.
290 *---------------------------------------------------------------------------*/
291 void WBT_InitParent(int send_packet_size, int recv_packet_size, WBTCallback callback);
292
293 /*---------------------------------------------------------------------------*
294 Name: WBT_InitChild
295
296 Description: Initializes WBT-system as MP-child state in WM.
297 This must be called before any WBT function at least once.
298 When called two or more times, it is only ignored.
299
300 Arguments: callback: callback function which receives
301 notifications from WBT-system.
302 If NULL is specified, any callback is ignored.
303
304 Returns: None.
305 *---------------------------------------------------------------------------*/
306 void WBT_InitChild(WBTCallback callback);
307
308 /*---------------------------------------------------------------------------*
309 Name: WBT_End
310
311 Description: Makes WBT-system end.
312 This must be called after WBT_InitParent or WBT_InitChild functions once.
313 When called two or more times, it is only ignored.
314
315 Arguments: None.
316
317 Returns: None.
318 *---------------------------------------------------------------------------*/
319 void WBT_End(void);
320
321
322 /* common ********************************************************************/
323
324 /*---------------------------------------------------------------------------*
325 Name: WBT_AidbitmapToAid
326
327 Description: Converts LSB of specified aid-bitmap to aid.
328
329 Arguments: abmp: aid-bitmap to convert
330
331 Returns: converted aid
332 if argument is 0, return -1.
333 *---------------------------------------------------------------------------*/
334 int WBT_AidbitmapToAid(u16 abmp);
335
336 /*---------------------------------------------------------------------------*
337 Name: WBT_AidToAidbitmap
338
339 Description: Converts specified aid to aid-bitmap.
340
341 Arguments: aid: aid to convert
342
343 Returns: Converted aid-bitmap.
344 *---------------------------------------------------------------------------*/
WBT_AidToAidbitmap(int aid)345 static inline u16 WBT_AidToAidbitmap(int aid)
346 {
347 return (u16)(1 << aid);
348 }
349
350 /*---------------------------------------------------------------------------*
351 Name: WBT_GetOwnAid
352
353 Description: Gets own aid.
354
355 Arguments: None.
356
357 Returns: Own aid.
358 If parent, result is always 0.
359 If child, result is equal to recent WBT_SetOwnAid().
360 *---------------------------------------------------------------------------*/
361 int WBT_GetOwnAid(void);
362
363 /*---------------------------------------------------------------------------*
364 Name: WBT_CalcPacketbitmapSize
365
366 Description: Calculates bitmap buffer size which is enough to receive
367 specified block size. (Needed by WBT_GetBlock())
368 If child, this must be called after end of WBT_RequestSync().
369
370 Arguments: block_size: byte size of block to receive.
371
372 Returns: Minimum size of bitmap buffer which can receive
373 specified block data.
374 *---------------------------------------------------------------------------*/
375 int WBT_CalcPacketbitmapSize(int block_size);
376
377 /*---------------------------------------------------------------------------*
378 Name: WBT_GetCurrentDownloadProgress
379
380 Description: Gets the progress of present block reception.
381
382 Arguments: block_id: block id to get progress
383 aid: target aid
384 current_count: destination pointer to store
385 count of received packets.
386 total_count: destination pointer to store
387 count of total packets
388
389 Returns: If receiving now, TRUE, else FALSE.
390 If succeeded, current_count and total_count are set
391 to progress information.
392 *---------------------------------------------------------------------------*/
393 BOOL WBT_GetCurrentDownloadProgress(u32 block_id, int aid, int *current_count, int *total_count);
394
395 /*---------------------------------------------------------------------------*
396 Name: WBT_NumOfRegisteredBlock
397
398 Description: Gets the total of registered blocks.
399
400 Arguments: None.
401
402 Returns: Total of blocks.
403 *---------------------------------------------------------------------------*/
404 int WBT_NumOfRegisteredBlock(void);
405
406 /*---------------------------------------------------------------------------*
407 Name: WBT_RegisterBlock
408
409 Description: Registers data-block to WBT-system so that other peers can
410 enumerate it with WBT_GetBlockInfo() and
411 receive it with WBT_GetBlock().
412
413 Arguments: block_info_list: structure to hold registration information.
414 If succeeded, this is under WBT-system
415 until WBT_UnregisterBlock() is called.
416 block_id: user-defined unique block id which must be
417 more than WBT_NUM_MAX_BLOCK_INFO_ID.
418 user_id: user-defined information
419 (free-data within WBT_USER_ID_LEN byte).
420 data_ptr: pointer to data buffer.
421 If not NULL, this buffer is referred to at
422 WBT-system until WBT_UnregisterBlock() is called.
423 If NULL, WBT_CMD_PREPARE_SEND_DATA callback
424 occurs if needed.
425 data_size: size of data_ptr
426 permission_bmp: must be 0. (reserved)
427
428 Returns: If succeeded, TRUE. else, false.
429 (multiple registration of same block-id will fail)
430 *---------------------------------------------------------------------------*/
431 BOOL WBT_RegisterBlock(WBTBlockInfoList *block_info_list, u32 block_id,
432 const void *user_id, const void *data_ptr, int data_size,
433 u16 permission_bmp);
434
435 /*---------------------------------------------------------------------------*
436 Name: WBT_UnregisterBlock
437
438 Description: Unregisters data-block from WBT-system.
439
440 Arguments: block_id: block-id which is already used
441 for WBT_RegisterBlock().
442
443 Returns: If succeeded, pointer of structure which was registered.
444 *---------------------------------------------------------------------------*/
445 WBTBlockInfoList *WBT_UnregisterBlock(u32 block_id);
446
447 /*---------------------------------------------------------------------------*
448 Name: WBT_PrintBTList
449
450 Description: Debug-prints current internal status of WBT-system.
451
452 Arguments: None.
453
454 Returns: None.
455 *---------------------------------------------------------------------------*/
456 void WBT_PrintBTList(void);
457
458
459 /* parent settings ***********************************************************/
460
461 /*---------------------------------------------------------------------------*
462 Name: WBT_SetPacketSize
463
464 Description: Changes MP-packet size after WBT_InitParent().
465 This function must be called in a situation in which
466 any peer is not using the WBT_GetBlock() command.
467 After this call, any child must call WBT_RequestSync()
468 before calling WBT_GetBlock().
469
470 Arguments: send_packet_size: available MP-parent packet size for WBT.
471 This must be below the value specified
472 by WM_SetParentParameter(), and must be
473 WBT_PACKET_SIZE_MIN at least.
474 recv_packet_size: available MP-child packet size for WBT.
475 This must be below the value specified
476 by WM_SetParentParameter(), and must be
477 WBT_PACKET_SIZE_MIN at least.
478
479 Returns: If succeeded, TRUE.
480 *---------------------------------------------------------------------------*/
481 BOOL WBT_SetPacketSize(int send_packet_size, int recv_packet_size);
482
483 /*---------------------------------------------------------------------------*
484 Name: WBT_MpParentSendHook
485
486 Description: Set WBT protocol data for MP-parent packet.
487
488 Arguments: sendbuf: destination buffer which will be used
489 by WM_SetMPDataToPort() as the parent.
490 send_size: allowed maximum size to send.
491
492 Returns: Size of actual set data.
493 *---------------------------------------------------------------------------*/
494 int WBT_MpParentSendHook(void *sendbuf, int send_size);
495
496 /*---------------------------------------------------------------------------*
497 Name: WBT_MpParentRecvHook
498
499 Description: Notifies received data to WBT-system.
500
501 Arguments: recv_buf: received buffer at WBT protocol port.
502 recv_size: size of received buffer.
503 aid: peer aid.
504
505 Returns: None.
506 *---------------------------------------------------------------------------*/
507 void WBT_MpParentRecvHook(const void *recv_buf, int recv_size, int aid);
508
509
510 /* child settings ************************************************************/
511
512 /*---------------------------------------------------------------------------*
513 Name: WBT_SetOwnAid
514
515 Description: Notifies own aid to WBT-system.
516
517 Arguments: aid: own aid (get with WM_StartConnect(), etc.)
518
519 Returns: None.
520 *---------------------------------------------------------------------------*/
521 void WBT_SetOwnAid(int aid);
522
523 /*---------------------------------------------------------------------------*
524 Name: WBT_MpChildSendHook
525
526 Description: Sets WBT protocol data for MP-child packet.
527
528 Arguments: sendbuf: destination buffer which will be used
529 by WM_SetMPDataToPort() as the parent.
530 send_size: allowed maximum size to send.
531
532 Returns: Size of actual set data.
533 *---------------------------------------------------------------------------*/
534 int WBT_MpChildSendHook(void *sendbuf, int send_size);
535
536 /*---------------------------------------------------------------------------*
537 Name: WBT_MpChildRecvHook
538
539 Description: Notifies received data to WBT-system.
540
541 Arguments: recv_buf: received buffer at WBT protocol port.
542 recv_size: size of received buffer.
543
544 Returns: None.
545 *---------------------------------------------------------------------------*/
546 void WBT_MpChildRecvHook(const void *recv_buf, int recv_size);
547
548
549 /* commands ******************************************************************/
550
551 /*---------------------------------------------------------------------------*
552 Name: WBT_RequestSync
553
554 Description: Synchronizes to target peer.
555 This function must be called before calling WBT_GetBlock().
556
557 Arguments: target: target peers as aid-bitmap.
558 callback: callback on each completion
559
560 Returns: If succeeded, TRUE.
561 When previous command has been operating, it will fail.
562 *---------------------------------------------------------------------------*/
563 BOOL WBT_RequestSync(u16 target, WBTCallback callback);
564
565 /*---------------------------------------------------------------------------*
566 Name: WBT_GetBlockInfo
567
568 Description: Gets block information.
569
570 Arguments: target: target peers as aid-bitmap.
571 index: index in registered block list.
572 block_info_table: pointer of the table which holds pointer of
573 each destination structure.
574 callback: callback on each completion.
575
576 Returns: If succeeded, TRUE.
577 When previous command has been operating, it will fail.
578 *---------------------------------------------------------------------------*/
579 BOOL WBT_GetBlockInfo(u16 target, int index,
580 WBTBlockInfoTable *block_info_table, WBTCallback callback);
581
582 /*---------------------------------------------------------------------------*
583 Name: WBT_GetBlock
584
585 Description: Gets data-block.
586
587 Arguments: target: target peers as aid-bitmap.
588 block_id: block-id to get.
589 recv_buf_table: pointer of the table which holds pointer of
590 each destination structure.
591 recv_size: size of data-block.
592 p_bmp_table: pointer of the table which holds pointer of
593 sequence bitmap buffer for internal tasks.
594 callback: callback on each completion.
595
596 Returns: If succeeded, TRUE.
597 When previous command has been operating, it will fail.
598 *---------------------------------------------------------------------------*/
599 BOOL WBT_GetBlock(u16 target, u32 block_id,
600 WBTRecvBufTable *recv_buf_table, u32 recv_size,
601 WBTPacketBitmapTable *p_bmp_table, WBTCallback callback);
602
603 /*---------------------------------------------------------------------------*
604 Name: WBT_PutUserData
605
606 Description: Sends free-formatted data.
607
608 Arguments: target: target peers as aid-bitmap.
609 user_data: pointer of data buffer to send.
610 size: size of data.
611 This must be WBT_SIZE_USER_DATA at most.
612 callback: callback on each completion.
613
614 Returns: If succeeded, TRUE.
615 When previous command has been operating, it will fail.
616 *---------------------------------------------------------------------------*/
617 BOOL WBT_PutUserData(u16 target, const void *user_data, int size, WBTCallback callback);
618
619
620 /*---------------------------------------------------------------------------*
621 Name: WBT_CancelCurrentCommand
622
623 Description: Cancel current WBT-commands.
624
625 Arguments: target: target peers as aid-bitmap.
626
627 Returns: If no canceled command, FALSE.
628 Else TRUE.
629 *---------------------------------------------------------------------------*/
630 BOOL WBT_CancelCurrentCommand(u16 target);
631
632
633 /*===========================================================================*/
634
635 #ifdef __cplusplus
636 } /* extern "C" */
637 #endif
638
639 #endif /* NITRO_WBT_H__ */
640
641 /*---------------------------------------------------------------------------*
642 End of file
643 *---------------------------------------------------------------------------*/
644