1 /*---------------------------------------------------------------------------* 2 Project: Horizon 3 File: uds_Type.h 4 5 Copyright (C) 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 $Rev: 57824 $ 14 *---------------------------------------------------------------------------*/ 15 16 /*! @file 17 @brief UDS type definitions. 18 */ 19 20 #ifndef NN_UDS_CAFE_UDS_TYPE_H_ 21 #define NN_UDS_CAFE_UDS_TYPE_H_ 22 23 #include <nn/types.h> 24 #include <nn/config.h> 25 #include <nn/cfg/CTR/cfg_UserInfo.h> 26 27 namespace nn { 28 namespace uds { 29 30 namespace Cafe { 31 32 namespace 33 { 34 const char PORT_NAME_UDS[] = "nwm::UDS"; 35 } 36 37 #define UDS_ROUNDUP( _x_, _n_) ( ( (_x_) + (_n_ - 1) ) & ~(_n_ - 1)) 38 #define UDS_ROUNDUP_2( _x_ ) UDS_ROUNDUP( _x_, 2) 39 #define UDS_ROUNDUP_4( _x_ ) UDS_ROUNDUP( _x_, 4) 40 #define UDS_ROUNDUP_8( _x_ ) UDS_ROUNDUP( _x_, 8) 41 #define UDS_ROUNDUP_64( _x_ ) UDS_ROUNDUP( _x_, 64) 42 #define UDS_ROUNDDOWN( _x_, _n_ ) ( (_x_) & ~(_n_ - 1) ) 43 #define UDS_ROUNDDOWN_2( _x_ ) UDS_ROUNDDOWN( _x_, 2) 44 #define UDS_ROUNDDOWN_4( _x_ ) UDS_ROUNDDOWN( _x_, 4) 45 #define UDS_ROUNDDOWN_8( _x_ ) UDS_ROUNDDOWN( _x_, 8) 46 47 /*! 48 @addtogroup nn_uds_api 49 @{ 50 */ 51 52 53 const u8 SYSTEM_RESERVED_PORT = 0x00; // UDS port reserved by the system. 54 const u16 BROADCAST_NODE_ID = 0xffff; //!< Node ID representing all node addresses of the network. Data sent to <tt>BROADCAST_NODE_ID</tt> can be retrieved by <tt>Spectator</tt>s. 55 56 const u8 NODE_MAX = 9; //!< Maximum value for the maximum number of network connections. 57 const u8 ENDPOINT_MAX = 16; //!< The maximum number of endpoints that can be created. This value is subject to change in the future. 58 59 const u8 PROTOCOL_NODE_MAX = 16; //!< A definition for compatibility with CTR. The maximum value for the number of nodes in the CTR network. (Actually, the number of nodes guaranteed to operate with CTR is up to 12.) 60 61 /*! 62 @name Transmission Data Sizes 63 @{ 64 */ 65 66 const u8 NET_DESC_APPDATA_SIZE_MAX = 200; //!< Maximum size of the application data that can be set for the beacon. 67 const u16 UDS_PACKET_PAYLOAD_MAX_SIZE = 1478; //!< Maximum size of the data that can be sent in a single call to <tt>@ref nn::uds::Cafe::SendTo</tt>. 68 const size_t ATTACH_BUFFER_SIZE_MIN = UDS_ROUNDUP_64(UDS_PACKET_PAYLOAD_MAX_SIZE); //!< Minimum size of the receive buffer specified in a call to the <tt>@ref Attach</tt> function. 69 const size_t ATTACH_BUFFER_SIZE_DEFAULT = UDS_ROUNDUP_64(UDS_PACKET_PAYLOAD_MAX_SIZE * 8); //!< Default size of the receive buffer specified in a call to the <tt>@ref Attach</tt> function. 70 /*! 71 @} 72 */ 73 /*! 74 @name String Length of the Passphrase 75 @{ 76 */ 77 const size_t UDS_PASSPHRASE_LENGTH_MIN = 8; //!< Minimum size of the passphrase for generating the encrypted key used in communication. 78 const size_t UDS_PASSPHRASE_LENGTH_MAX = 255; //!< Maximum size of the passphrase for generating the encryption key used in communication. 79 /*! 80 @} 81 */ 82 83 /*! 84 @name Send/Receive Options 85 @{ 86 */ 87 const bit8 NO_WAIT = 0x01; //!< If this constant is specified as an argument to the <tt>@ref SendTo</tt> function, wireless transmission occurs immediately without buffering within the UDS library. If this constant is specified as an argument to either the <tt>@ref Receive</tt> or <tt>@ref ReceiveFrom</tt> functions, the wireless transmission ends immediately, even if no data has been received. 88 const bit8 FORCE_DIRECT_BC = 0x02; //!< When <tt>@ref SendTo</tt> has been specified, sends using direct broadcast without asking for a recipient. Unicast communication occurs between clients without the intervention of a host. This reduces communication latency, but results in the problem of hidden nodes. 89 /*! 90 @} 91 */ 92 93 const u8 MAC_ADDRESS_SIZE = 6; 94 const u8 OUI_SIZE = 3; 95 96 /*! 97 @brief Enumerates UDS states. 98 */ 99 enum State 100 { 101 STATE_NONE = 0,//!< Not initialized. 102 STATE_PROCESSING_INITIALIZE = 1,//!< Internal state indicating that initialization is underway. Applications never see this value. 103 #if 0 104 STATE_PROCESSING_FINALIZE = 2,//!< Internal state indicating finalization is currently underway. Applications never see this value. 105 #endif 106 STATE_DISCONNECTED = 3,//!< Not communicating (not connected). 107 STATE_CREATING_NETWORK = 4,//!< Intermediate state between not connected, and building a new network and running as the host. Automatically transitions to <tt>STATE_MASTER</tt>. 108 STATE_DESTROYING_NETWORK = 5,//!< Intermediate state between no longer running as the host and not connected. Automatically transition to <tt>STATE_DISCONNECTED</tt>. 109 STATE_MASTER = 6,//!< Running as host. 110 #ifdef NN_UDS_SUPPORT_CLIENT 111 STATE_CONNECTING_NETWORK = 7,//!< Intermediate state between not connected, and building a new network and running as a client or spectator. Transitions to <tt>STATE_DISCONNECTED</tt> if the connection fails or <tt>STATE_CLIENT</tt>/<tt>STATE_SPECTATOR</tt> if the connection succeeds 112 STATE_DISCONNECTING_NETWORK = 8,//!< Intermediate state between disconnecting from the network and not connected. Automatically transitions to <tt>STATE_DISCONNECTED</tt>. 113 STATE_CLIENT = 9,//!< Running as a client. If the connection degrades to the point where the network connection can no longer be maintained, automatically transitions to <tt>STATE_DISCONNECTING_NETWORK</tt>. 114 STATE_SPECTATOR =10,//!< Running as a spectator. If the connection degrades to the point where the network connection can no longer be maintained, automatically transitions to <tt>STATE_DISCONNECTING_NETWORK</tt>. 115 STATE_AUDIENCE = STATE_SPECTATOR, 116 #endif 117 STATE_ERROR =11,//!< Specifies that the UDS library needs to be initialized. The library transitions to this state if wireless communications are turned off or the system enters sleep mode while using UDS. 118 STATE_MAX, 119 STATE_MAX_BIT = (1u << 31) 120 }; 121 122 123 /*! 124 @brief Enumerates the reasons for disconnection. 125 */ 126 enum DisconnectReason 127 { 128 BEFORE_COMMUNICATION = 0, //!< Not yet communicating. 129 NETWORK_IS_AVAILABLE = 1, //!< Connection being maintained. 130 REQUEST_FROM_MYSELF = 2, //!< Disconnected from the network due to local action. 131 REQUEST_FROM_SYSTEM = 3, //!< Disconnected from the network due to a system request (transition to wireless off mode or sleep mode). 132 #ifdef NN_UDS_SUPPORT_CLIENT 133 DISCARDED_FROM_NETWORK = 4, //!< Kicked off the network due to an instruction from the host. 134 CONNECTION_LOST = 5, //!< Connectivity has degraded and the connection cannot be maintained. 135 UNKNOWN_DISCONNECT_REASON = 6, //!< Disconnected due to an unknown reason. 136 #endif 137 DISCONNECT_REASON_MAX = 7, 138 DISCONNECT_REASON_MAX_BIT = (1u << 31) 139 }; 140 141 #ifdef NN_UDS_SUPPORT_CLIENT 142 /*! 143 @brief Enumerated type that represents modes used during connection to the network. 144 */ 145 enum ConnectType 146 { 147 CONNECT_AS_CLIENT = 1, //!< Connect to the network as a client (a node that can both send and receive data and is given an ID when it connects). 148 CONNECT_AS_SPECTATOR, //!< Connect to the network as a spectator (a node that can only receive data and is not given an ID when it connects). 149 CONNECT_AS_MASTER //!< Connect to the network as a host (only used internally by the library). 150 }; 151 152 const ConnectType CONNECT_AS_AUDIENCE = CONNECT_AS_SPECTATOR ; 153 #endif 154 155 #ifdef NN_UDS_SUPPORT_POWER_SAVE 156 /*! 157 @brief Enumerates the network's power-saving modes. 158 */ 159 enum PowerSaveMode 160 { 161 ALWAYS_ACTIVE, //!< Mode that emphasizes low latency and high traffic, and that does not use any power-saving features. 162 POWERSAVE_NORMAL, //!< Normal mode. This mode has higher latency, but uses almost 20% less power for communication than when in <tt>ALWAYS_ACTIVE</tt> mode. 163 POWERSAVE_HIGH, //!< Mode that emphasizes power conservation. This mode has higher latency, but uses almost 50% less power for communication than when in <tt>ALWAYS_ACTIVE</tt> mode. 164 POWERSAVE_MODE_MAX 165 }; 166 #endif 167 /* 168 Enumerated type indicating the communication quality (link level). 169 */ 170 enum LinkLevel 171 { 172 LINK_LEVEL_0 = 0, // The communication quality is very bad or communication could not be established. 173 LINK_LEVEL_1, // Communication quality is bad. 174 LINK_LEVEL_2, // Communication quality is not good. 175 LINK_LEVEL_3 // Communication quality is good. 176 }; 177 178 179 180 /*! 181 @brief Stores the UDS connection status. 182 */ 183 struct ConnectionStatus 184 { 185 State nowState; //!< Current state. 186 DisconnectReason disconnectReason; //!< Reason for disconnection. A value of <tt>NETWORK_IS_AVAILABLE</tt> is always returned while there is an active network connection. 187 u16 myNodeId; //!< The node ID of the local system. This value is undefined in the absence of a network connection. 188 bit16 updateNodeBitmap; //!< Bitmap representing a list of IDs for nodes that have changed since the last time <tt>GetConnectionStatus</tt> was run. 189 u16 nodeIdList[PROTOCOL_NODE_MAX ]; //!< List of the nodes currently connected to the network. 190 u8 nowEntry; //!< The number of nodes connected to the network. 191 u8 maxEntry; //!< The maximum number of nodes that can connect to the network at the same time. (This number does not change during communication.) 192 bit16 slotBitmap; //!< Bitmap indicating which slots store node information. Unlike <var>updateNodeBitmap</var>, this attribute does not indicate changes from the previous values. 193 }; 194 195 /* 196 Data frame buffer index. 197 */ 198 enum DataFrameIndex 199 { 200 UNICAST_DATAFRAME = 0, // Unicast data frame. 201 BROADCAST_DATAFRAME, // Broadcast data frame. 202 NUM_OF_DATAFRAME 203 }; 204 205 static const size_t SCRAMBLED_LOCAL_FRIEND_CODE_SIZE = 12; //!< The byte length of <tt>@ref ScrambledLocalFriendCode</tt>. 206 207 /*! 208 @brief This structure stores information that can be converted to a local friend code using the friends library (CTR). 209 210 <b>Because friend codes work differently on Cafe and CTR, this information cannot be directly used on Cafe. See below for more information. </b> 211 212 To protect the privacy of users and prevent tracking of specific individuals, you can query the friends library and get the local friend code as represented by a data array of <tt>@ref nn::uds::Cafe::SCRAMBLED_LOCAL_FRIEND_CODE_SIZE</tt> bytes. The friend code makes it easy to use friend features in local communications without getting the local friend code from the UDS library. 213 214 Even on the same device, this data has a different value every time the application starts. It cannot be used to identify devices after the application has started. 215 If the application is not restarted between UDS and DLP, the device can be identified by matching the first eight bytes. 216 217 218 */ 219 struct ScrambledLocalFriendCode 220 { 221 bit16 value[SCRAMBLED_LOCAL_FRIEND_CODE_SIZE/sizeof(bit16)]; //!< Data array that can be converted into the local friend code. 222 }; 223 224 /*! 225 @brief Stores user information about nodes connected to the network. 226 */ 227 struct NodeInformation 228 { 229 ScrambledLocalFriendCode scrambledLocalFriendCode; //!< Data that can be converted to a local friend code by using the friends library. This type of data helps protect privacy of users. 230 nn::cfg::CTR::UserName userName; //!< User name data. For more information, see <tt>nn::cfg::CTR::UserName</tt> in the CTR-SDK. 231 u16 nodeId; //!< Node ID. 232 NN_PADDING2; 233 }; 234 235 /*! 236 @brief An <tt>endpoint</tt> descriptor. Corresponds to a socket descriptor. 237 238 Currently this descriptor contains only an ID, but other fields might be added in the future. 239 */ 240 struct EndpointDescriptor 241 { 242 u32 id; //!< ID assigned each time <tt>@ref CreateEndpoint</tt> is called. 243 }; 244 245 /* 246 @} 247 */ 248 249 250 //The following code is for internal use. 251 namespace detail{ 252 253 /* 254 Structure for use in the <tt>RadioStrengthInfo</tt> class. 255 */ 256 struct RadioStrength 257 { 258 s8 rssi; 259 bool isValid; 260 }; 261 262 /* 263 Gets the strength of the received signal that is more detailed than <tt>GetLinkLevel</tt>. Get with <tt>GetRadioStrangthInfo</tt>. 264 Use the acquired value to determine the strength of the relative signal. 265 */ 266 class RadioStrengthInfo 267 { 268 public: RadioStrengthInfo()269 RadioStrengthInfo(){m_IsInitialized = false;} 270 void Initialize( const RadioStrength& masterLink, const RadioStrength directLink[PROTOCOL_NODE_MAX ] ); ~RadioStrengthInfo()271 ~RadioStrengthInfo(){m_IsInitialized = false;} 272 273 s8 GetAverage(); // Mean value of the signal intensity received by the local unit. 274 s8 GetMinimum(); // Minimum value of the signal intensity received by the local unit. 275 s8 GetMaximum(); // Maximum value of the signal intensity received by the local unit. 276 s8 GetMasterLink(); // The strength of the signal received from the master is 0 when the local unit is the master. 277 278 private: 279 bool m_IsInitialized; 280 void GetRawData(s8 rawLink[PROTOCOL_NODE_MAX ] ); // Gets the raw data for signal intensity received by the local unit (0 = invalid data). 281 282 RadioStrength m_MasterLink; 283 RadioStrength m_DirectLink[PROTOCOL_NODE_MAX ]; 284 }; 285 286 /*! 287 @brief Stores the received result for each <tt>Endpoint</tt> that could be obtained by calling <tt>DestroyEndpoint</tt>. 288 */ 289 struct ReceiveReport 290 { 291 u32 id; //!< Endpoint ID (<tt>EndpointDescriptor.id</tt>). 292 u16 targetNodeId; //!< The target node ID. 293 u16 port; //!< Port number. 294 u32 receiveCount; //!< The total number of packets received by the attached <tt>Endpoint</tt>. 295 u32 lostCount; //!< The number of packets lost because of the overflow of the receive buffer. 296 }; 297 Swap16(u16 value)298 inline u16 Swap16( u16 value ) 299 { 300 return static_cast<u16>( (((value) & 0xFF00UL) >> 8UL) | (((value) & 0x00FFUL) << 8UL)); 301 } 302 Swap32(u32 value)303 inline u32 Swap32( u32 value ) 304 { 305 return static_cast<u32>( (((value) & 0xFF000000UL) >> 24UL) | (((value) & 0x00FF0000UL) >> 8UL) | (((value) & 0x0000FF00UL) << 8UL) | (((value) & 0x000000FFUL) << 24UL)); 306 } 307 Swap64(u64 value)308 inline u64 Swap64( u64 value ) 309 { 310 return static_cast<u64> 311 ( ((value & 0xff00000000000000ull) >> 56) 312 | ((value & 0x00ff000000000000ull) >> 40) 313 | ((value & 0x0000ff0000000000ull) >> 24) 314 | ((value & 0x000000ff00000000ull) >> 8) 315 | ((value & 0x00000000ff000000ull) << 8) 316 | ((value & 0x0000000000ff0000ull) << 24) 317 | ((value & 0x000000000000ff00ull) << 40) 318 | ((value & 0x00000000000000ffull) << 56) ); 319 } 320 321 // UDS versions. 322 // 1.0: Initial version 323 // 2.0: Revised the return values of <tt>ConnectNetwork</tt> in CTR-SDK 2.X series (ctr-support:1415). Now sends <tt>Deauth</tt> at <tt>Eject</tt>. 324 // 3.0: Resolved the latency issue in <tt>Finalize</tt> in CTR-SDK 3.<i>X</i> series (+100 milliseconds prior to version 3.0) (ctr-net:1631). 325 // 4.0: <tt>ResultInvalidState</tt>(ctr-net:1667) for <tt>Initialize</tt> during sleep in CTR-SDK 4.X series. 326 #define NN_UDS_DEFINE_UDS_VERSION(major, minor) ((bit16)major<<8 | (bit16)minor&0x00FF) 327 const bit16 UDS_SDK_VERSION = NN_UDS_DEFINE_UDS_VERSION(4, 0); 328 329 /* 330 inline u32 UDS_LE2BE32( u32 value) 331 { 332 NN_ASM("rev value, value"); 333 return value; 334 } 335 */ 336 337 } //end of namespace detail 338 339 340 #if NN_ENDIAN == NN_ENDIAN_VALUE_LITTLE NE2HE16(u16 value)341 inline u16 NE2HE16( u16 value ) 342 { 343 return detail::Swap16(value); 344 } 345 NE2HE32(u32 value)346 inline u32 NE2HE32( u32 value ) 347 { 348 return detail::Swap32(value); 349 } 350 NE2HE64(u64 value)351 inline u64 NE2HE64( u64 value ) 352 { 353 return detail::Swap64(value); 354 } 355 HE2NE16(u16 value)356 inline u16 HE2NE16( u16 value ) 357 { 358 return detail::Swap16(value); 359 } 360 HE2NE32(u32 value)361 inline u32 HE2NE32( u32 value) 362 { 363 return detail::Swap32(value); 364 } 365 HE2NE64(u64 value)366 inline u64 HE2NE64( u64 value ) 367 { 368 return detail::Swap64(value); 369 } 370 #else NE2HE16(u16 value)371 inline u16 NE2HE16( u16 value ) 372 { 373 return value; 374 } 375 NE2HE32(u32 value)376 inline u32 NE2HE32( u32 value ) 377 { 378 return value; 379 } 380 NE2HE64(u64 value)381 inline u64 NE2HE64( u64 value ) 382 { 383 return value; 384 } 385 HE2NE16(u16 value)386 inline u16 HE2NE16( u16 value ) 387 { 388 return value; 389 } 390 HE2NE32(u32 value)391 inline u32 HE2NE32( u32 value) 392 { 393 return value; 394 } 395 HE2NE64(u64 value)396 inline u64 HE2NE64( u64 value ) 397 { 398 return value; 399 } 400 HE2LE16(u16 value)401 inline u16 HE2LE16( u16 value ) 402 { 403 return detail::Swap16(value); 404 } 405 HE2LE32(u32 value)406 inline u32 HE2LE32( u32 value ) 407 { 408 return detail::Swap32(value); 409 } 410 #endif 411 412 } // end of namespace Cafe 413 } // end of namespace uds 414 } // end of namespace nn 415 416 #endif /* NN_UDS_CAFE_UDS_TYPE_H_ */ 417