1 /*---------------------------------------------------------------------------*
2   Project:  TwlSDK - WXC - include -
3   File:     protocol.h
4 
5   Copyright 2005-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:: 2008-09-18#$
14   $Rev: 8573 $
15   $Author: okubata_ryoma $
16  *---------------------------------------------------------------------------*/
17 
18 #ifndef	NITRO_WXC_PROTOCOL_H_
19 #define	NITRO_WXC_PROTOCOL_H_
20 
21 
22 #include <nitro.h>
23 #include <nitro/wxc/common.h>
24 
25 
26 /*****************************************************************************/
27 /* Constants */
28 
29 /* Command type */
30 #define WXC_BLOCK_COMMAND_IDLE      0  /* State with request or response */
31 #define WXC_BLOCK_COMMAND_INIT      1  /* Send/receive data size and checksum */
32 #define WXC_BLOCK_COMMAND_SEND      2  /* Send/receive data block */
33 #define WXC_BLOCK_COMMAND_STOP      3  /* Send/receive cancel */
34 #define WXC_BLOCK_COMMAND_DONE      4  /* Send/receive completion */
35 #define WXC_BLOCK_COMMAND_QUIT      5  /* Close communication request (disconnect) */
36 
37 /* MP package size for single data exchange */
38 #define WXC_PACKET_BUFFRER_MIN      (int)(WXC_PACKET_SIZE_MIN - sizeof(WXCBlockHeader))
39 /* Maximum data length (32 KB) used for data exchange */
40 #define WXC_MAX_DATA_SIZE           (32 * 1024)
41 #define WXC_RECV_BITSET_SIZE        ((((WXC_MAX_DATA_SIZE + WXC_PACKET_BUFFRER_MIN - 1) / WXC_PACKET_BUFFRER_MIN) + 31) / 32)
42 
43 /* Index history for prevention of duplicate data during block data response */
44 #define WXC_RECENT_SENT_LIST_MAX    2
45 
46 /* Maximum number of data blocks that can be registered */
47 #define WXC_REGISTER_DATA_MAX       16
48 
49 
50 /*****************************************************************************/
51 /* Declaration */
52 
53 /* Block data exchange information */
54 typedef struct WXCBlockInfo
55 {
56     u8      phase;                     /* Block data exchange phase */
57     u8      command;                   /* Command in the current phase */
58     u16     index;                     /* Required sequence number */
59 }
60 WXCBlockInfo;
61 
62 /* Block data exchange packet header */
63 typedef struct WXCBlockHeader
64 {
65     WXCBlockInfo req;                  /* Request from transmission source */
66     WXCBlockInfo ack;                  /* Response to the data destination */
67 }
68 WXCBlockHeader;
69 
70 SDK_STATIC_ASSERT(sizeof(WXCBlockHeader) == 8);
71 
72 
73 /* Block data information structure */
74 typedef struct WXCBlockDataFormat
75 {
76     void   *buffer;                    /* Pointer to a buffer */
77     u32     length;                    /* Data size */
78     u32     buffer_max;                /* Buffer size (match with 'length' for send data) */
79     u16     checksum;                  /* Checksum (use MATH_CalcChecksum8()) */
80     u8      padding[2];
81 }
82 WXCBlockDataFormat;
83 
84 
85 struct WXCProtocolContext;
86 
87 
88 /* Structure regulating the communication protocol interface that can be handled by WXC */
89 typedef struct WXCProtocolImpl
90 {
91     /* String indicating the protocol types */
92     const char *name;
93     /* Beacon send/receive hook function */
94     void    (*BeaconSend) (struct WXCProtocolContext *, WMParentParam *);
95     BOOL    (*BeaconRecv) (struct WXCProtocolContext *, const WMBssDesc *);
96     /* Hook function called prior to connection. */
97     void    (*PreConnectHook) (struct WXCProtocolContext *, const WMBssDesc *, u8 ssid[WM_SIZE_CHILD_SSID]);
98     /* MP packet send/receive hook function */
99     void    (*PacketSend) (struct WXCProtocolContext *, WXCPacketInfo *);
100     BOOL    (*PacketRecv) (struct WXCProtocolContext *, const WXCPacketInfo *);
101     /* Initialization function when connecting */
102     void    (*Init) (struct WXCProtocolContext *, u16, u16);
103     /* Data block registration function */
104     BOOL    (*AddData) (struct WXCProtocolContext *, const void *, u32, void *, u32);
105     /* Function determining whether data is currently being exchanged */
106     BOOL    (*IsExecuting) (struct WXCProtocolContext *);
107     /* Pointer to the work area used by each protocols as needed */
108     void   *impl_work;
109     /* Pointer to manage as a singly linked list */
110     struct WXCProtocolImpl *next;
111 }
112 WXCProtocolImpl;
113 
114 /* Structure regulating the registered protocol operation */
115 typedef struct WXCProtocolRegistry
116 {
117     /* Pointer for managing the singly linked lists in the future */
118     struct WXCProtocolRegistry *next;
119     /* Protocol information */
120     u32     ggid;
121     WXCCallback callback;
122     WXCProtocolImpl *impl;
123     /* Initial automatic send/receive data */
124     WXCBlockDataFormat send;           /* Send buffer */
125     WXCBlockDataFormat recv;           /* Receive buffer */
126 }
127 WXCProtocolRegistry;
128 
129 
130 /* WXC library communication PCI (protocol control information) */
131 typedef struct WXCProtocolContext
132 {
133     WXCBlockDataFormat send;           /* Send buffer */
134     WXCBlockDataFormat recv;           /* Receive buffer */
135     /*
136      * Information on send and receive data to use for exchanges.
137      * This will ultimately be made into a list instead of an array.
138      */
139     WXCProtocolRegistry *current_block;
140     WXCProtocolRegistry data_array[WXC_REGISTER_DATA_MAX];
141     u32     target_ggid;
142 }
143 WXCProtocolContext;
144 
145 
146 /*****************************************************************************/
147 /* Functions */
148 
149 #ifdef  __cplusplus
150 extern "C" {
151 #endif
152 
153 
154 /*---------------------------------------------------------------------------*
155   Name:         WXC_InitProtocol
156 
157   Description:  Initializes the WXC library protocol.
158 
159   Arguments:    protocol: WXCProtocolContext structure
160 
161   Returns:      None.
162  *---------------------------------------------------------------------------*/
163 void    WXC_InitProtocol(WXCProtocolContext * protocol);
164 
165 /*---------------------------------------------------------------------------*
166   Name:         WXC_InstallProtocolImpl
167 
168   Description:  Adds a new selectable protocol.
169 
170   Arguments:    impl: Pointer to the WXCProtocolImpl structure.
171                       This structure is used internally until the library is closed.
172 
173   Returns:      None.
174  *---------------------------------------------------------------------------*/
175 void    WXC_InstallProtocolImpl(WXCProtocolImpl * impl);
176 
177 /*---------------------------------------------------------------------------*
178   Name:         WXC_FindProtocolImpl
179 
180   Description:  Searches for a protocol with the specified name.
181 
182   Arguments:    name: Protocol name
183 
184   Returns:      If a protocol with the specified name is found, its pointer is returned.
185  *---------------------------------------------------------------------------*/
186 WXCProtocolImpl *WXC_FindProtocolImpl(const char *name);
187 
188 /*---------------------------------------------------------------------------*
189   Name:         WXC_ResetSequence
190 
191   Description:  Reinitializes the WXC library protocol.
192 
193   Arguments:    protocol: WXCProtocolContext structure
194                 send_max: Maximum send packet size
195                 recv_max: Maximum receive packet size
196 
197   Returns:      None.
198  *---------------------------------------------------------------------------*/
199 void    WXC_ResetSequence(WXCProtocolContext * protocol, u16 send_max, u16 recv_max);
200 
201 /*---------------------------------------------------------------------------*
202   Name:         WXC_AddBlockSequence
203 
204   Description:  Sets block data exchange.
205 
206   Arguments:    protocol: WXCProtocolContext structure
207                 send_buf: Send buffer
208                 send_size: Send buffer size
209                 recv_buf: Receive buffer
210                 recv_max: Receive buffer size
211 
212   Returns:      None.
213  *---------------------------------------------------------------------------*/
214 void    WXC_AddBlockSequence(WXCProtocolContext * protocol,
215                              const void *send_buf, u32 send_size, void *recv_buf, u32 recv_max);
216 
217 /*---------------------------------------------------------------------------*
218   Name:         WXC_GetCurrentBlock
219 
220   Description:  Gets the currently selected block data.
221 
222   Arguments:    protocol: WXCProtocolContext structure
223 
224   Returns:      Currently selected block data.
225  *---------------------------------------------------------------------------*/
WXC_GetCurrentBlock(WXCProtocolContext * protocol)226 static inline WXCProtocolRegistry *WXC_GetCurrentBlock(WXCProtocolContext * protocol)
227 {
228     return protocol->current_block;
229 }
230 
231 /*---------------------------------------------------------------------------*
232   Name:         WXC_GetCurrentBlockImpl
233 
234   Description:  Gets the currently selected block data's protocol interface.
235 
236   Arguments:    protocol: WXCProtocolContext structure
237 
238   Returns:      Currently selected block data.
239  *---------------------------------------------------------------------------*/
WXC_GetCurrentBlockImpl(WXCProtocolContext * protocol)240 static inline WXCProtocolImpl *WXC_GetCurrentBlockImpl(WXCProtocolContext * protocol)
241 {
242     return protocol->current_block->impl;
243 }
244 
245 /*---------------------------------------------------------------------------*
246   Name:         WXC_SetCurrentBlock
247 
248   Description:  Selects the specified block data.
249 
250   Arguments:    protocol: WXCProtocolContext structure
251                 target: Data block to be selected
252 
253   Returns:      None.
254  *---------------------------------------------------------------------------*/
WXC_SetCurrentBlock(WXCProtocolContext * protocol,WXCProtocolRegistry * target)255 static inline void WXC_SetCurrentBlock(WXCProtocolContext * protocol, WXCProtocolRegistry * target)
256 {
257     protocol->current_block = target;
258 }
259 
260 /*---------------------------------------------------------------------------*
261   Name:         WXC_FindNextBlock
262 
263   Description:  Specifies a GGID and searches for block data.
264 
265   Arguments:    protocol: WXCProtocolContext structure
266                 from: Starting search location.
267                       If NULL, search from the beginning. Otherwise, start searching from the block after the specified one.
268 
269                 ggid: GGID associated with the search block data
270                 match: Search condition.
271                        If TRUE, data with matching GGID will be search target,
272                        If FALSE, those with non-matching GGID will be search target.
273 
274   Returns:      Returns a pointer to the corresponding block data if it exists and NULL otherwise.
275 
276  *---------------------------------------------------------------------------*/
277 WXCProtocolRegistry *WXC_FindNextBlock(WXCProtocolContext * protocol,
278                                        const WXCProtocolRegistry * from, u32 ggid, BOOL match);
279 
280 /*---------------------------------------------------------------------------*
281   Name:         WXC_BeaconSendHook
282 
283   Description:  Hook called at beacon update.
284 
285   Arguments:    protocol: WXCProtocolContext structure
286                 p_param: WMParentParam structure used for next beacon
287                          Change inside the function as necessary.
288 
289   Returns:      None.
290  *---------------------------------------------------------------------------*/
291 void    WXC_BeaconSendHook(WXCProtocolContext * protocol, WMParentParam *p_param);
292 
293 /*---------------------------------------------------------------------------*
294   Name:         WXC_BeaconRecvHook
295 
296   Description:  Hook called for individual scanned beacons.
297 
298   Arguments:    protocol: WXCProtocolContext structure
299                 p_desc: Scanned WMBssDesc structure
300 
301   Returns:      If it is seen as connection target, return TRUE. Otherwise, return FALSE.
302  *---------------------------------------------------------------------------*/
303 BOOL    WXC_BeaconRecvHook(WXCProtocolContext * protocol, const WMBssDesc *p_desc);
304 
305 /*---------------------------------------------------------------------------*
306   Name:         WXC_PacketSendHook
307 
308   Description:  Hook called at MP packet transmission.
309 
310   Arguments:    protocol: WXCProtocolContext structure
311                 packet: WXCPacketInfo pointer configuring transmission packet information
312 
313   Returns:      None.
314  *---------------------------------------------------------------------------*/
315 void    WXC_PacketSendHook(WXCProtocolContext * protocol, WXCPacketInfo * packet);
316 
317 /*---------------------------------------------------------------------------*
318   Name:         WXC_PacketRecvHook
319 
320   Description:  Hook called at MP packet reception.
321 
322   Arguments:    protocol: WXCProtocolContext structure
323                 packet: WXCPacketInfo pointer configuring reception packet information
324 
325   Returns:      TRUE if the other party is disconnected on the protocol side.
326  *---------------------------------------------------------------------------*/
327 BOOL    WXC_PacketRecvHook(WXCProtocolContext * protocol, const WXCPacketInfo * packet);
328 
329 /*---------------------------------------------------------------------------*
330   Name:         WXC_ConnectHook
331 
332   Description:  Hook called at connection detection.
333 
334   Arguments:    protocol: WXCProtocolContext structure
335                 bitmap: AID bitmap of the connected target
336 
337   Returns:      None.
338  *---------------------------------------------------------------------------*/
339 void    WXC_ConnectHook(WXCProtocolContext * protocol, u16 bitmap);
340 
341 /*---------------------------------------------------------------------------*
342   Name:         WXC_DisconnectHook
343 
344   Description:  Hook called at disconnection detection.
345 
346   Arguments:    protocol: WXCProtocolContext structure
347                 bitmap: AID bitmap of the disconnected target
348 
349   Returns:      None.
350  *---------------------------------------------------------------------------*/
351 void    WXC_DisconnectHook(WXCProtocolContext * protocol, u16 bitmap);
352 
353 /*---------------------------------------------------------------------------*
354   Name:         WXC_CallPreConnectHook
355 
356   Description:  Hook called before connecting to the communication target.
357 
358   Arguments:    protocol: WXCProtocolContext structure
359                 p_desc: Connection target WMBssDesc structure
360                 ssid: Buffer that stores the SSID for configuration
361 
362   Returns:      None.
363  *---------------------------------------------------------------------------*/
364 void    WXC_CallPreConnectHook(WXCProtocolContext * protocol, WMBssDesc *p_desc, u8 *ssid);
365 
366 /*---------------------------------------------------------------------------*
367   Name:         WXC_InitProtocolRegistry
368 
369   Description:  Associates GGID and callback to the specified registry structure.
370 
371   Arguments:    p_data: WXCProtocolRegistry structure used for registration
372                 ggid: GGID to be set
373                 callback: Callback function to the user
374                               (Cancel setting if NULL)
375                 impl: Communication protocol to be adopted
376 
377   Returns:      None.
378  *---------------------------------------------------------------------------*/
379 void    WXC_InitProtocolRegistry(WXCProtocolRegistry * p_data, u32 ggid, WXCCallback callback,
380                                  WXCProtocolImpl * impl);
381 
382 /*---------------------------------------------------------------------------*
383   Name:         WXC_SetInitialExchangeBuffers
384 
385   Description:  Sets automatically used data for the initial data exchange.
386 
387   Arguments:    p_data: WXCProtocolRegistry structure used for registration
388                 send_ptr: Pointer to registered data
389                 send_size: Size of registered data
390                 recv_ptr: Pointer to the receive buffer
391                 recv_size: Receive buffer size
392 
393   Returns:      None.
394  *---------------------------------------------------------------------------*/
395 void    WXC_SetInitialExchangeBuffers(WXCProtocolRegistry * p_data, u8 *send_ptr, u32 send_size,
396                                       u8 *recv_ptr, u32 recv_size);
397 
398 WXCProtocolImpl* WXCi_GetProtocolImplCommon(void);
399 WXCProtocolImpl* WXCi_GetProtocolImplWPB(void);
400 WXCProtocolImpl* WXCi_GetProtocolImplWXC(void);
401 
402 
403 #ifdef  __cplusplus
404 }       /* extern "C" */
405 #endif
406 
407 
408 #endif /* NITRO_WXC_PROTOCOL_H_ */
409 
410 /*---------------------------------------------------------------------------*
411   End of file
412  *---------------------------------------------------------------------------*/
413