The Cafe SDK provides TCP/IP networking via the socket interface, similar to the popular BSD network programming API. The Cafe network stack is organized in two parts:
Before starting on a new CAT-DEV system, network configuration is performed using System Config Tool and saved in NAND memory for the future use. This is equivalent of performing network configuration of Windows, Linux or Mac OS X based systems using their respective UI.
It is mandatory for network programs to first using AC (Auto Connect) library before using ANY other networking library. AC library ensures that network connectivity is up and running so that other networking libraries can send and receive network traffic. Refer to the AC section for descriptions of the AC library APIs.
After this point, programs can use network libraries of their choice including "socket API", "libcURL", "nSSL" or any other networking middleware like NEX etc.
The Cafe network stack offers rich networking features including (but not restricted to):
Refer to the socket demos for examples.
Socket library requires initialization
SOInit call is used to initialize socket API,
SOFinish call is used after an application is finished using socket API).
There calls should be made BEFORE any socket API is used.
It is recommended that these calls be made only once at the beginning of the
program and when the program is being terminated.
Socket API in Wii U stack is designed to match closely with the BSD socket API. Socket API is thread-safe. It provides both blocking and non-blocking IO semantic. "select" call provides UNIX like mechanism to wait on multiple socket descriptors. Refer to individual man-pages for the error codes returned by socket APIs.
Wii U SDK as a whole does not use UNIX style global "
errno" to return system call errors.
However, Socket API errors are returned in a global
errno variable that is thread-safe.
The application can continue to examine this variable after a socket call returns failures.
Application developers should use the error numbers defined in
net_types.h which use
Network stack does not return error numbers found in
It is part of the porting effort, application developers should map the error number macros
used in their code to those found in
net_types.h. While socket APIs will return most
commonly used errors (see man-pages), the list of errors may not be as
exhaustive as other platforms. Other platforms support different OS features
like SIGNAL, PIPEs etc which have error number representation on other system.
These will not apply to Wii U network errors.
There is a significant difference in which how network stack reacts to the loss
of network connectivity. On detecting a network cable being unplugged or on the
loss of link to a wireless access point, network stack will terminate all
sockets belonging to the application. Threads which were blocking in socket API
will be woken up with an error
SO_EABORTED. Subsequent calls on the terminated
sockets will return
SO_ENOTSOCK error. The application is expected to allocate
the socket again and resume operations. It is not required to reinitialize the
socket library using
The Socket API is multithread-safe. In addition to that, multiple threads can operate on the same socket (either in blocking or non-blocking mode) - for example one thread sending on a socket and another thread receiving on the same socket.
If a socket is closed from one thread while there are blocking operations on the same socket from other threads, the blocked operations are aborted.
If multiple threads make a send call on the same socket, the usual send semantics still apply; i.e., the send call may return with fewer bytes sent than the requested amount and send must be called again to send the remaining bytes. This also means that if multiple threads send on the same socket at the same time, the data from these threads may get interleaved as they are sent.
The application can improve performance (by avoiding internal buffer copying) by using buffers
which are aligned with the PPC cache line size (defined by
for data transfer operations
Both buffer address and size must be aligned.
For an implementation example, see the UDP echo demo (
The default TCP and UDP socket buffer sizes are 8 KB for the send buffer and 8 KB for the receive buffer. If the application desires, it can increase
the socket buffer for specific sockets using the
The send and receive buffer for TCP sockets can be increased up to 128 KB if
the socket has
SO_WINSCALE option set, otherwise the maximum limit is 65535 bytes.
For UDP receive buffer the maximum allowed size is 65535 bytes. There is no affect on increasing UDP socket send buffer from the default size because after the UDP packet is transmitted on the link, it is no longer buffered.
For more information on setting socket options, refer to
The network stack buffer pool is mainly consumed by the application's send and receive socket buffers. On the receive path this means when network data is received, the network stack buffer pool memory remains tied up in the socket receive buffer till the application reads the data from the socket receive buffer into its own memory. The application is required to read data actively whenever they expect to receive data otherwise they can negatively affect other network clients and system network performance.
SOSelect function is a good way to optimally receive data from the network.
In general, following behavior of the application is NOT encouraged and should be avoided.
SOSetSockOptfunction. Instead, socket buffer sizes should be configured properly based on the application's real requirements.
The application can obtain socket buffer consumption with
It returns one of the consumption levels (amount of consumed packet buffers by the application) listed below
and the application is required to take an appropriate action depends on the obtained level.
It is not recommended to call
SOGeLibOpt function persistently at short intervals.
It has to be used to check whether the application is unnecessarily consuming/holding socket buffers at some point.
We recommend to put at least 15 seconds interval between each function call.
and Networks Stack Demos overview for further API usage.
The network stack operates with a fixed amount of memory. It initializes a buffer pool from this memory during system initialization and this buffer pool is shared by all network clients including network stack itself for its internal use. The network stack obtains free buffers from this buffer pool when network clients send and receive data, and frees the buffer is not needed anymore.
Here are some examples when memory is consumed from the buffer pool:
Here are some important behaviors related to the buffer pool in the network stack.
We recommend the application which does HTTP data transfer to use Libcurl in Cafe SDK because it handles HTTP packets with stored network setting in the system automatically.
It is allowed to perform HTTP data transfer in the application's own way (e.g. using Libcurl which is not provided by Cafe SDK). But such the application is required to apply proxy setting which is stored in the NAND before starting data transfer. The system stores following proxy information in the NAND.
These information have to be applied before starting HTTP data transfer because Wii U users can configure proxy setting in Wii U menu and expects it gets applied for all the HTTP data transfers.
The application can obtain proxy setting with
nn::Result nn::ac::ReadConfig APIs.
Here are the steps for obtaining proxy setting.
nn::ac::GetStartupIdmust be specified to the argument of this function
nn::ac::GetProxyUsewith obtained network configuration above to see if proxy is enabled
AC_PROXY_STATE_DISABLE, then the application does not have to do anything because proxy is disabled
AC_PROXY_STATE_ENABLE, then the application needs to apply each proxy setting described below
nn::ac::GetProxyHostNamewith obtained network configuration above
nn::ac::GetProxyNoproxyHostswith obtained network configuration above
nn::ac::GetProxyPortwith obtained network configuration above
nn::ac::GetProxyAuthTypewith obtained network configuration above
AC_PROXY_AUTH_TYPE_NONEthen no need to apply user name and password described below
nn::ac::GetProxyUserNamewith obtained network configuration above
nn::ac::GetProxyPasswordwith obtained network configuration above
These functions are allowed to use only for development purpose. But such the application described above is allowed to use it even on the product application. Refer to AC for further information.
2014/02/06 Added "Efficient Memory Utilization" section in Guidelines. "Memory Utilization in the Network Stack" was merged into there.
2013/09/25 Added "Guidelines" section.
2013/08/16 Added "Memory utilization in the network stack" section.
2013/05/16 Added note about Socket Buffer Sizes in Performance Tips section.
2013/05/08 Automated cleanup pass.
2013/03/06 Improved entire description.
2013/01/23 Updates for System Config Tool
2012/07/25 Cleanup pass.
2011/10/14 Fixed for USB-Ethernet wired interface support.
2011/06/07 Modified to use AC library instead of NC library.
2011/02/21 Initial version.