1 /*---------------------------------------------------------------------------*
2 Project: TwlSDK - WBT - include
3 File: wbt.h
4
5 Copyright 2003-2009 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:: 2009-06-04#$
14 $Rev: 10698 $
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 optional user-defined information within WBT_USER_ID_LEN bytes.
419 data_ptr: pointer to data buffer.
420 If not NULL, this buffer is referred to at
421 WBT-system until WBT_UnregisterBlock() is called.
422 If NULL, WBT_CMD_PREPARE_SEND_DATA callback
423 occurs if needed.
424 data_size: size of data_ptr
425 permission_bmp: must be 0. (reserved)
426
427 Returns: If succeeded, TRUE. else, false.
428 (multiple registration of same block-id will fail)
429 *---------------------------------------------------------------------------*/
430 BOOL WBT_RegisterBlock(WBTBlockInfoList *block_info_list, u32 block_id,
431 const void *user_id, const void *data_ptr, int data_size,
432 u16 permission_bmp);
433
434 /*---------------------------------------------------------------------------*
435 Name: WBT_UnregisterBlock
436
437 Description: Unregisters data-block from WBT-system.
438
439 Arguments: block_id: block-id which is already used
440 for WBT_RegisterBlock().
441
442 Returns: If succeeded, pointer of structure which was registered.
443 *---------------------------------------------------------------------------*/
444 WBTBlockInfoList *WBT_UnregisterBlock(u32 block_id);
445
446 /*---------------------------------------------------------------------------*
447 Name: WBT_PrintBTList
448
449 Description: Debug-prints current internal status of WBT-system.
450
451 Arguments: None.
452
453 Returns: None.
454 *---------------------------------------------------------------------------*/
455 void WBT_PrintBTList(void);
456
457
458 /* parent settings ***********************************************************/
459
460 /*---------------------------------------------------------------------------*
461 Name: WBT_SetPacketSize
462
463 Description: Changes MP-packet size after WBT_InitParent().
464 This function must be called in a situation in which
465 any peer is not using the WBT_GetBlock() command.
466 After this call, any child must call WBT_RequestSync()
467 before calling WBT_GetBlock().
468
469 Arguments: send_packet_size: available MP-parent packet size for WBT.
470 This must be below the value specified
471 by WM_SetParentParameter(), and must be
472 WBT_PACKET_SIZE_MIN at least.
473 recv_packet_size: available MP-child packet size for WBT.
474 This must be below the value specified
475 by WM_SetParentParameter(), and must be
476 WBT_PACKET_SIZE_MIN at least.
477
478 Returns: If succeeded, TRUE.
479 *---------------------------------------------------------------------------*/
480 BOOL WBT_SetPacketSize(int send_packet_size, int recv_packet_size);
481
482 /*---------------------------------------------------------------------------*
483 Name: WBT_MpParentSendHook
484
485 Description: Set WBT protocol data for MP-parent packet.
486
487 Arguments: sendbuf: destination buffer which will be used
488 by WM_SetMPDataToPort() as the parent.
489 send_size: allowed maximum size to send.
490
491 Returns: Size of actual set data.
492 *---------------------------------------------------------------------------*/
493 int WBT_MpParentSendHook(void *sendbuf, int send_size);
494
495 /*---------------------------------------------------------------------------*
496 Name: WBT_MpParentRecvHook
497
498 Description: Notifies received data to WBT-system.
499
500 Arguments: recv_buf: received buffer at WBT protocol port.
501 recv_size: size of received buffer.
502 aid: peer aid.
503
504 Returns: None.
505 *---------------------------------------------------------------------------*/
506 void WBT_MpParentRecvHook(const void *recv_buf, int recv_size, int aid);
507
508
509 /* child settings ************************************************************/
510
511 /*---------------------------------------------------------------------------*
512 Name: WBT_SetOwnAid
513
514 Description: Notifies own aid to WBT-system.
515
516 Arguments: aid: own aid (get with WM_StartConnect(), etc.)
517
518 Returns: None.
519 *---------------------------------------------------------------------------*/
520 void WBT_SetOwnAid(int aid);
521
522 /*---------------------------------------------------------------------------*
523 Name: WBT_MpChildSendHook
524
525 Description: Sets WBT protocol data for MP-child packet.
526
527 Arguments: sendbuf: destination buffer which will be used
528 by WM_SetMPDataToPort() as the parent.
529 send_size: allowed maximum size to send.
530
531 Returns: Size of actual set data.
532 *---------------------------------------------------------------------------*/
533 int WBT_MpChildSendHook(void *sendbuf, int send_size);
534
535 /*---------------------------------------------------------------------------*
536 Name: WBT_MpChildRecvHook
537
538 Description: Notifies received data to WBT-system.
539
540 Arguments: recv_buf: received buffer at WBT protocol port.
541 recv_size: size of received buffer.
542
543 Returns: None.
544 *---------------------------------------------------------------------------*/
545 void WBT_MpChildRecvHook(const void *recv_buf, int recv_size);
546
547
548 /* commands ******************************************************************/
549
550 /*---------------------------------------------------------------------------*
551 Name: WBT_RequestSync
552
553 Description: Synchronizes to target peer.
554 This function must be called before calling WBT_GetBlock().
555
556 Arguments: target: target peers as aid-bitmap.
557 callback: callback on each completion
558
559 Returns: If succeeded, TRUE.
560 When previous command has been operating, it will fail.
561 *---------------------------------------------------------------------------*/
562 BOOL WBT_RequestSync(u16 target, WBTCallback callback);
563
564 /*---------------------------------------------------------------------------*
565 Name: WBT_GetBlockInfo
566
567 Description: Gets block information.
568
569 Arguments: target: target peers as aid-bitmap.
570 index: index in registered block list.
571 block_info_table: pointer of the table which holds pointer of
572 each destination structure.
573 callback: callback on each completion.
574
575 Returns: If succeeded, TRUE.
576 When previous command has been operating, it will fail.
577 *---------------------------------------------------------------------------*/
578 BOOL WBT_GetBlockInfo(u16 target, int index,
579 WBTBlockInfoTable *block_info_table, WBTCallback callback);
580
581 /*---------------------------------------------------------------------------*
582 Name: WBT_GetBlock
583
584 Description: Gets data-block.
585
586 Arguments: target: target peers as aid-bitmap.
587 block_id: block-id to get.
588 recv_buf_table: pointer of the table which holds pointer of
589 each destination structure.
590 recv_size: size of data-block.
591 p_bmp_table: pointer of the table which holds pointer of
592 sequence bitmap buffer for internal tasks.
593 callback: callback on each completion.
594
595 Returns: If succeeded, TRUE.
596 When previous command has been operating, it will fail.
597 *---------------------------------------------------------------------------*/
598 BOOL WBT_GetBlock(u16 target, u32 block_id,
599 WBTRecvBufTable *recv_buf_table, u32 recv_size,
600 WBTPacketBitmapTable *p_bmp_table, WBTCallback callback);
601
602 /*---------------------------------------------------------------------------*
603 Name: WBT_PutUserData
604
605 Description: Sends free-formatted data.
606
607 Arguments: target: target peers as aid-bitmap.
608 user_data: pointer of data buffer to send.
609 size: size of data.
610 This must be WBT_SIZE_USER_DATA at most.
611 callback: callback on each completion.
612
613 Returns: If succeeded, TRUE.
614 When previous command has been operating, it will fail.
615 *---------------------------------------------------------------------------*/
616 BOOL WBT_PutUserData(u16 target, const void *user_data, int size, WBTCallback callback);
617
618
619 /*---------------------------------------------------------------------------*
620 Name: WBT_CancelCurrentCommand
621
622 Description: Cancel current WBT-commands.
623
624 Arguments: target: target peers as aid-bitmap.
625
626 Returns: If no canceled command, FALSE.
627 Else TRUE.
628 *---------------------------------------------------------------------------*/
629 BOOL WBT_CancelCurrentCommand(u16 target);
630
631
632 /*===========================================================================*/
633
634 #ifdef __cplusplus
635 } /* extern "C" */
636 #endif
637
638 #endif /* NITRO_WBT_H__ */
639
640 /*---------------------------------------------------------------------------*
641 End of file
642 *---------------------------------------------------------------------------*/
643