1 /*---------------------------------------------------------------------------* 2 Project: TwlSDK - WM - demos.Twl 3 File: wh.c 4 5 Copyright 2007-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-10-20#$ 14 $Rev: 9005 $ 15 $Author: okubata_ryoma $ 16 *---------------------------------------------------------------------------*/ 17 18 19 #ifndef __WMHIGH_H__ 20 #define __WMHIGH_H__ 21 22 #include "default/wh_config.h" 23 24 /* Added from NITRO-SDK 3.1 RC (before that, is always 1) */ 25 #if !defined(WH_MP_FREQUENCY) 26 #define WH_MP_FREQUENCY 1 27 #endif 28 29 // OFF if initializing by using WM_Initialize 30 // Set to ON if there is a need to individually use and precisely control WM_Init, WM_Enable, and WM_PowerOn. 31 // #define WH_USE_DETAILED_INITIALIZE 32 33 enum 34 { 35 WH_SYSSTATE_STOP, // Initial state 36 WH_SYSSTATE_IDLE, // Waiting 37 WH_SYSSTATE_SCANNING, // Scanning 38 WH_SYSSTATE_BUSY, // Connecting 39 WH_SYSSTATE_CONNECTED, // Completed connection (communications are possible in this state) 40 WH_SYSSTATE_DATASHARING, // Completed connection, with data-sharing enabled 41 WH_SYSSTATE_KEYSHARING, // Completed connection, with key-sharing enabled 42 WH_SYSSTATE_MEASURECHANNEL, // Check the radio wave usage rate of the channel 43 WH_SYSSTATE_CONNECT_FAIL, // Connection to the parent device failed 44 WH_SYSSTATE_ERROR, // Error occurred 45 WH_SYSSTATE_FATAL, // A FATAL error has occurred 46 WH_SYSSTATE_NUM 47 }; 48 49 enum 50 { 51 WH_CONNECTMODE_MP_PARENT, // Parent device MP connection mode 52 WH_CONNECTMODE_MP_CHILD, // Child device MP connection mode 53 WH_CONNECTMODE_KS_PARENT, // Parent device key-sharing connection mode 54 WH_CONNECTMODE_KS_CHILD, // Child device key-sharing connection mode 55 WH_CONNECTMODE_DS_PARENT, // Parent device data-sharing connection mode 56 WH_CONNECTMODE_DS_CHILD, // Child device data-sharing connection mode 57 WH_CONNECTMODE_NUM 58 }; 59 60 enum 61 { 62 // Separate error codes 63 WH_ERRCODE_DISCONNECTED = WM_ERRCODE_MAX, // Disconnected from parent 64 WH_ERRCODE_PARENT_NOT_FOUND, // No parent 65 WH_ERRCODE_NO_RADIO, // Wireless cannot be used 66 WH_ERRCODE_LOST_PARENT, // Parent lost 67 WH_ERRCODE_NOMORE_CHANNEL, // Scan has finished on all channels 68 WH_ERRCODE_MAX 69 }; 70 71 typedef void (*WHStartScanCallbackFunc) (WMBssDesc *bssDesc); 72 73 /* Parent device receive buffer size */ 74 #define WH_PARENT_RECV_BUFFER_SIZE WM_SIZE_MP_PARENT_RECEIVE_BUFFER( WH_CHILD_MAX_SIZE, WH_CHILD_MAX, FALSE ) 75 /* Parent device send buffer size */ 76 #define WH_PARENT_SEND_BUFFER_SIZE WM_SIZE_MP_PARENT_SEND_BUFFER( WH_PARENT_MAX_SIZE, FALSE ) 77 78 /* Child device receive buffer size */ 79 #define WH_CHILD_RECV_BUFFER_SIZE WM_SIZE_MP_CHILD_RECEIVE_BUFFER( WH_PARENT_MAX_SIZE, FALSE ) 80 /* Child device send buffer size */ 81 #define WH_CHILD_SEND_BUFFER_SIZE WM_SIZE_MP_CHILD_SEND_BUFFER( WH_CHILD_MAX_SIZE, FALSE ) 82 83 /* Macro that defines the GGID reserved for the SDK sample demo */ 84 #define SDK_MAKEGGID_SYSTEM(num) (0x003FFF00 | (num)) 85 86 /* Bitmap value that shows a not connected or a parent device only state */ 87 #define WH_BITMAP_EMPTY 1 88 89 // Send callback type (for data-sharing model) 90 typedef void (*WHSendCallbackFunc) (BOOL result); 91 92 // Function type for making connection permission determinations (for multiboot model) 93 typedef BOOL (*WHJudgeAcceptFunc) (WMStartParentCallback *); 94 95 // Receive callback type 96 typedef void (*WHReceiverFunc) (u16 aid, u16 *data, u16 size); 97 98 // Function for generating a WEP key 99 typedef u16 (*WHParentWEPKeyGeneratorFunc) (u16 *wepkey, const WMParentParam *parentParam); 100 typedef u16 (*WHChildWEPKeyGeneratorFunc) (u16 *wepkey, const WMBssDesc *bssDesc); 101 102 103 104 /************************************************************************** 105 * The following functions modify various WH configuration values 106 **************************************************************************/ 107 108 /*---------------------------------------------------------------------------* 109 Name: WH_SetGgid 110 111 Description: Sets the game's group ID. 112 Call before making a connection to the parent device. 113 114 Arguments: ggid Game group ID to configure 115 116 Returns: None. 117 *---------------------------------------------------------------------------*/ 118 extern void WH_SetGgid(u32 ggid); 119 120 /*---------------------------------------------------------------------------* 121 Name: WH_SetSsid 122 123 Description: Sets the SSID specified during child connection. 124 Call before making a connection from the child device. 125 126 Arguments: ssid Buffer in which the SSID to be set has been stored 127 length Data length of the SSID to be set. 128 If less than WM_SIZE_CHILD_SSID (24-byte), fill the subsequent whitespace with 0s. If more than WM_SIZE_CHILD_SSID, truncate. 129 130 131 Returns: None. 132 *---------------------------------------------------------------------------*/ 133 extern void WH_SetSsid(const void *ssid, u32 length); 134 135 /*---------------------------------------------------------------------------* 136 Name: WH_SetUserGameInfo 137 138 Description: Configures user-defined parent device information 139 Call before making a connection to the parent device. 140 141 Arguments: userGameInfo Pointer to user-defined parent device information 142 length Size of the user-defined parent device information 143 144 Returns: None. 145 *---------------------------------------------------------------------------*/ 146 extern void WH_SetUserGameInfo(u16 *userGameInfo, u16 length); 147 148 /*---------------------------------------------------------------------------* 149 Name: WH_SetDebugOutput 150 151 Description: Configures the function for outputting the debug string. 152 153 Arguments: func Function for the set debug string output 154 155 Returns: None. 156 *---------------------------------------------------------------------------*/ 157 void WH_SetDebugOutput(void (*func) (const char *, ...)); 158 159 /*---------------------------------------------------------------------------* 160 Name: WH_SetParentWEPKeyGenerator 161 162 Description: Sets the function that generates WEP Key. 163 If this function is called, WEP will be used for authentication during connection. 164 Using a unique algorithm for each game application, it sets the parent and child to the same value before connection. 165 166 This function is for parents. 167 168 Arguments: func Pointer to the function that generates the WEP Key 169 If NULL is specified, WEP Key is not used 170 171 Returns: None. 172 *---------------------------------------------------------------------------*/ 173 extern void WH_SetParentWEPKeyGenerator(WHParentWEPKeyGeneratorFunc func); 174 175 /*---------------------------------------------------------------------------* 176 Name: WH_SetChildWEPKeyGenerator 177 178 Description: Sets the function that generates WEP Key. 179 If this function is called, WEP will be used for authentication during connection. 180 Using a unique algorithm for each game application, it sets the parent and child to the same value before connection. 181 182 This function is for children. 183 184 Arguments: func Pointer to the function that generates the WEP Key 185 If NULL is specified, WEP Key is not used 186 187 Returns: None. 188 *---------------------------------------------------------------------------*/ 189 extern void WH_SetChildWEPKeyGenerator(WHChildWEPKeyGeneratorFunc func); 190 191 /*---------------------------------------------------------------------------* 192 Name: WH_SetIndCallback 193 194 Description: Sets the callback function specified in the WM_SetIndCallback function called by WH_Initialize. 195 196 This function should be called before WH_Initialize is called. 197 If a callback function is not specified by this function, the default WH_IndicateHandler will be set as the callback. 198 199 200 Arguments: callback Callback for the indication notification specified by WM_SetIndCallback 201 202 Returns: None. 203 *---------------------------------------------------------------------------*/ 204 void WH_SetIndCallback(WMCallbackFunc callback); 205 206 /************************************************************************** 207 * The following wrapper functions get the low-level WM library state 208 **************************************************************************/ 209 210 /* ---------------------------------------------------------------------- 211 Name: WH_GetLinkLevel 212 Description: Gets the radio reception strength. 213 Arguments: None. 214 Returns: Returns the numeric value of WMLinkLevel. 215 ---------------------------------------------------------------------- */ 216 extern int WH_GetLinkLevel(void); 217 218 /* ---------------------------------------------------------------------- 219 Name: WH_GetAllowedChannel 220 Description: Gets the bit pattern of channels that can be used for connection. 221 Arguments: None. 222 Returns: channel pattern 223 ---------------------------------------------------------------------- */ 224 extern u16 WH_GetAllowedChannel(void); 225 226 227 /************************************************************************** 228 * The following functions get the WH state 229 **************************************************************************/ 230 231 /* ---------------------------------------------------------------------- 232 Name: WH_GetBitmap 233 Description: Gets the bit pattern for displaying the connection state. 234 Arguments: None. 235 Returns: bitmap pattern 236 ---------------------------------------------------------------------- */ 237 extern u16 WH_GetBitmap(void); 238 239 /* ---------------------------------------------------------------------- 240 Name: WH_GetSystemState 241 Description: Gets the WH internal state. 242 Arguments: None. 243 Returns: The internal state (WH_SYSSTATE_XXXX). 244 ---------------------------------------------------------------------- */ 245 extern int WH_GetSystemState(void); 246 247 /* ---------------------------------------------------------------------- 248 Name: WH_GetConnectMode 249 Description: Gets the connection information. 250 Arguments: None. 251 Returns: The connection information (WH_CONNECTMODE_XX_XXXX). 252 ---------------------------------------------------------------------- */ 253 extern int WH_GetConnectMode(void); 254 255 /* ---------------------------------------------------------------------- 256 Name: WH_GetLastError 257 Description: Gets the error code that most recently occurred. 258 Arguments: None. 259 Returns: The error code. 260 ---------------------------------------------------------------------- */ 261 extern int WH_GetLastError(void); 262 263 /*---------------------------------------------------------------------------* 264 Name: WH_PrintBssDesc 265 266 Description: Debug outputs the members of the WMBssDesc structure. 267 268 Arguments: info Pointer to the BssDesc to be debug output 269 270 Returns: None. 271 *---------------------------------------------------------------------------*/ 272 extern void WH_PrintBssDesc(WMBssDesc *info); 273 274 275 /************************************************************************** 276 * The following functions perform channel-related processes 277 **************************************************************************/ 278 279 /*---------------------------------------------------------------------------* 280 Name: WH_StartMeasureChannel 281 282 Description: Starts measuring the radio wave usage rate on every usable channel. 283 When measurement is complete, internally calculates the channel with the lowest usage rate, and transitions it to the WH_SYSSTATE_MEASURECHANNEL state. 284 285 286 Arguments: None. 287 288 Returns: None. 289 *---------------------------------------------------------------------------*/ 290 extern BOOL WH_StartMeasureChannel(void); 291 292 /*---------------------------------------------------------------------------* 293 Name: WH_GetMeasureChannel 294 295 Description: Returns the channel with the lowest usage rate from all the usable channels. 296 The WH_MeasureChannel operations must be complete, and it must be in a WH_SYSSTATE_MEASURECHANNEL state. 297 298 When this function is called, the channel with the lowest use rate is returned, and the state transitions to WH_SYSSTATE_IDLE. 299 300 301 Arguments: None. 302 303 Returns: The channel number of the usable channel with the lowest usage rate. 304 *---------------------------------------------------------------------------*/ 305 extern u16 WH_GetMeasureChannel(void); 306 307 308 /************************************************************************** 309 * The following functions initialize wireless communication and move it into an enabled state 310 **************************************************************************/ 311 312 /* ---------------------------------------------------------------------- 313 Name: WH_Initialize 314 Description: Performs initialization operations, and starts the initialization sequence. 315 Arguments: None. 316 Returns: TRUE if the sequence start was a success. 317 ---------------------------------------------------------------------- */ 318 extern BOOL WH_Initialize(void); 319 320 321 /*---------------------------------------------------------------------------* 322 Name: WH_TurnOnPictoCatch 323 324 Description: Enables the Pictochat Search feature. 325 This causes a callback function to be invoked when PictoChat is discovered while scanning with WH_StartScan. 326 327 328 Arguments: None. 329 330 Returns: None. 331 *---------------------------------------------------------------------------*/ 332 extern void WH_TurnOnPictoCatch(void); 333 334 /*---------------------------------------------------------------------------* 335 Name: WH_TurnOffPictoCatch 336 337 Description: Disables the Pictochat Search feature. 338 This makes it to be ignored, even if pictochat was found while scanning with WH_StartScan. 339 340 341 Arguments: None. 342 343 Returns: None. 344 *---------------------------------------------------------------------------*/ 345 extern void WH_TurnOffPictoCatch(void); 346 347 /*---------------------------------------------------------------------------* 348 Name: WH_StartScan 349 350 Description: Fetches the parent beacon. 351 352 Arguments: callback Sets the callback returned when the parent device is found 353 354 macAddr MAC address for the connected parent. 355 If 0xFFFFFF, all parents are searched for. 356 357 channel Channel on which to search for the parent. 358 If 0, all channels are searched. 359 360 Returns: None. 361 *---------------------------------------------------------------------------*/ 362 extern BOOL WH_StartScan(WHStartScanCallbackFunc callback, const u8 *macAddr, u16 channel); 363 364 /*---------------------------------------------------------------------------* 365 Name: WH_EndScan 366 367 Description: Fetches the parent beacon. 368 369 Arguments: None. 370 371 Returns: None. 372 *---------------------------------------------------------------------------*/ 373 extern BOOL WH_EndScan(void); 374 375 /* ---------------------------------------------------------------------- 376 Name: WH_ParentConnect 377 Description: Starts the connection sequence. 378 Arguments: mode If WH_CONNECTMODE_MP_PARENT, MP starts as a parent. 379 If WH_CONNECTMODE_DS_PARENT, DataSharing starts as a parent. 380 If WH_CONNECTMODE_KS_PARENT, KeySharing starts as a parent. 381 tgid Parent device communications tgid 382 channel Parent device communications channel 383 Returns: TRUE if the connection sequence is successful. 384 ---------------------------------------------------------------------- */ 385 extern BOOL WH_ParentConnect(int mode, u16 tgid, u16 channel); 386 387 /* ---------------------------------------------------------------------- 388 Name: WH_ChildConnect 389 Description: Starts the connection sequence. 390 Arguments: mode Start MP as the child if WH_CONNECTMODE_MP_CHILD. 391 Start DataSharing as the child if WH_CONNECTMODE_DS_CHILD. 392 Start KeySharing as the child if WH_CONNECTMODE_KS_CHILD. 393 bssDesc The bssDesc of the parent device to connect to 394 395 Returns: TRUE if the connection sequence is successful. 396 ---------------------------------------------------------------------- */ 397 extern BOOL WH_ChildConnect(int mode, WMBssDesc *bssDesc); 398 399 /* ---------------------------------------------------------------------- 400 Name: WH_ChildConnectAuto 401 Description: Starts the child device connection sequence. 402 However, each type of setting specified with WH_ParentConnect or WH_ChildConnect is left to automatic internal processing. 403 404 Arguments: mode Start MP as the child if WH_CONNECTMODE_MP_CHILD. 405 Start DataSharing as the child if WH_CONNECTMODE_DS_CHILD. 406 Start KeySharing as the child if WH_CONNECTMODE_KS_CHILD. 407 408 macAddr MAC address for the connected parent 409 If 0xFFFFFF, all parents are searched for. 410 411 channel Designate the channels on which to search for the parent. 412 If 0, all channels are searched. 413 414 Returns: TRUE if the connection sequence is successful. 415 ---------------------------------------------------------------------- */ 416 extern BOOL WH_ChildConnectAuto(int mode, const u8 *macAddr, u16 channel); 417 418 /*---------------------------------------------------------------------------* 419 Name: WH_SetJudgeAcceptFunc 420 421 Description: Sets the functions used to determine whether to accept the child device connection. 422 423 Arguments: Set the child device connection determination functions. 424 425 Returns: None. 426 *---------------------------------------------------------------------------*/ 427 extern void WH_SetJudgeAcceptFunc(WHJudgeAcceptFunc func); 428 429 430 /************************************************************************** 431 * The following functions perform direct MP communication using WH_DATA_PORT 432 **************************************************************************/ 433 434 /* ---------------------------------------------------------------------- 435 Name: WH_SetReceiver 436 Description: Configures the data reception callback in the WH_DATA_PORT port. 437 Arguments: proc Data reception callback 438 Returns: None. 439 ---------------------------------------------------------------------- */ 440 extern void WH_SetReceiver(WHReceiverFunc proc); 441 442 /* ---------------------------------------------------------------------- 443 Name: WH_SendData 444 Description: Starts sending data to the WH_DATA_PORT port. 445 (For MP communications. There is no need to call this function while data sharing, etc.) 446 Arguments: size Data size 447 Returns: Returns TRUE if starting the send is successful. 448 ---------------------------------------------------------------------- */ 449 extern BOOL WH_SendData(void *data, u16 datasize, WHSendCallbackFunc callback); 450 451 452 /************************************************************************** 453 * The following functions control data sharing communication 454 **************************************************************************/ 455 456 /* ---------------------------------------------------------------------- 457 Name: WH_GetKeySet 458 Description: Reads the common key data. 459 Arguments: keyset Data storage destination 460 Returns: If it succeeds, returns TRUE. 461 ---------------------------------------------------------------------- */ 462 extern BOOL WH_GetKeySet(WMKeySet *keyset); 463 464 /* ---------------------------------------------------------------------- 465 Name: WH_GetSharedDataAdr 466 Description: Calculates and gets the data address obtained from the machine with the designated AID from the shared data address. 467 468 Arguments: aid The machine designation 469 Returns: NULL on failure. 470 ---------------------------------------------------------------------- */ 471 extern u16 *WH_GetSharedDataAdr(u16 aid); 472 473 /* ---------------------------------------------------------------------- 474 Name: WH_StepDS 475 Description: Proceeds to the next synchronized data sharing process. 476 If communication is performed every frame, this function must also be called every frame. 477 478 Arguments: data Data to send 479 Returns: If it succeeds, returns TRUE. 480 ---------------------------------------------------------------------- */ 481 extern BOOL WH_StepDS(void *data); 482 483 484 /************************************************************************** 485 * The following functions end communication and transition to the initialized state 486 **************************************************************************/ 487 488 /* ---------------------------------------------------------------------- 489 Name: WH_Reset 490 Description: Starts the reset sequence. 491 When this function is called, it resets regardless of the current state. 492 It is used for forced recovery from errors. 493 Arguments: None. 494 Returns: TRUE if the process successfully starts. 495 ---------------------------------------------------------------------- */ 496 extern void WH_Reset(void); 497 498 /* ---------------------------------------------------------------------- 499 Name: WH_Finalize 500 Description: Starts the post-processing / end sequence. 501 When this function is called, the current state is referenced, and an appropriate end sequence is executed. 502 503 This function is used in the normal end process (not WH_Reset). 504 Arguments: None. 505 Returns: None. 506 ---------------------------------------------------------------------- */ 507 extern void WH_Finalize(void); 508 509 /*---------------------------------------------------------------------------* 510 Name: WH_End 511 512 Description: Ends wireless communication. 513 514 Arguments: None. 515 516 Returns: None. 517 *---------------------------------------------------------------------------*/ 518 extern BOOL WH_End(void); 519 520 /*---------------------------------------------------------------------------* 521 Name: WH_GetCurrentAid 522 523 Description: Gets its own current AID. 524 Children may change when they connect or disconnect. 525 526 Arguments: None. 527 528 Returns: AID value. 529 *---------------------------------------------------------------------------*/ 530 extern u16 WH_GetCurrentAid(void); 531 532 #endif 533