Networking

Module scope

The Networking module is responsible for:

1. TCP/UDP socket based networking for IPv4 and IPv6, including client/server sockets, blocking/nonblocking sockets and asynchronous sockets.
2. Basic DNS functionality (network address lookup).
3. Socket multiplexing (POSIX-select-like functionality).

Note: "asynchronous sockets" in this context means sockets that will call a user-provided callback function when socket events happen.

The pal_plat_network.h header declares the Networking functions.

Prerequisites for this porting stage

For a successful port, a platform needs:

• RTOS module (successfully ported).
• Support for socket configuration parameters:
  • IPv4 or IPv6.
  • TCP (Client)/TCP (Server)/UDP.
  • Asynchronous callback support: sockets that asynchronously receive user defined callbacks when an event happens.
  • Blocking/nonblocking: determined on creation; no need to support switching later.
• Support for DNS lookup of IP addresses.
• Support for some type of socket multiplexing.
• The Networking module has three compile-time flags that you must enable for your port to work with Izuma Device Management services:
  • PAL_NET_TCP_AND_TLS_SUPPORT
  • PAL_NET_ASYNCHRONOUS_SOCKET_API
  • PAL_NET_DNS_SUPPORT

Porting result

After successfully porting the Networking module, all PAL networking tests need to pass. Please see the Tests section for more information.

Porting notes

This section covers implementation information for successfully porting the PAL networking module.

Changes from POSIX

The networking API is similar to the POSIX networking API, but we have made several modifications, including reducing the supported functionality, to make it more portable. For example, the API has fewer supported socket options and socket types.

The main changes are:

• Functions now return a status explicitly as the return value (the networking API does not use errno).
• Output from functions (other than status) is returned through output arguments of functions, instead of being returned by functions as a return value.
• On creation, sockets are bound to a particular interface. This is only enforced where the OS supports it (Mbed OS, for example). Linux doesn't fully allow this without root permissions, so it is not enforced for the Linux reference port.

General notes

• You only need to implement the pal_plat_socketsInit() function if a platform needs special initializations. Otherwise, you can leave the function's implementation empty.
• Do not manually change the values in the palSocketAddress_t structure. Instead, use the functions defined for socket addresses in pal_network.h, such as pal_setSockAddrPort or pal_setSockAddrIPV4Addr.
• Not all of the fields in the palNetInterfaceInfo_t structure (that are used to get information on a registered network interface) are relevant for all interfaces on all platforms. However, the address field is mandatory.
• You have to list the available network interfaces as 0 to N, by allowing the service to register network interfaces using the pal_plat_RegisterNetworkInterface function. The order of registration determines the list order.
• Once you have listed the interfaces you need to support:
  • Returning the number of listed interfaces.
  • Returning information regarding an interface given its index (especially important is retrieving the IP address).
  • When creating a socket, an interface number must be specified. The socket created must be bound to this interface meaning that incoming and outgoing communication performed by this socket needs to use the specified interface (if applicable on the target OS).
• PAL_NET_DEFAULT_INTERFACE defines the default interface for the target port. When porting, set this to the relevant default adapter of the target system.
• By default, PAL supports the registration of up to PAL_MAX_SUPORTED_NET_INTERFACES different interfaces, where the default value is 10. If your port requires support for more than ten interfaces you should change this value in pal_configuration.h.
• Some network stacks limit the number of concurrent sockets. To run the PAL tests, your network must support at least five concurrent sockets.

Porting over the LWIP networking library

• When porting the PAL Networking module using the LWIP library (see the provided port over LWIP 1.4.1) several changes are required to the default LWIP configuration values. The ChangeLog.log file in the lwip_1.4.1 folder provides a comprehensive list of all the changes made to the LWIP files for the LWIP 1.4.1 port of PAL for FreeRTOS. Different versions of the LWIP library may require different changes but the list can serve as a template for the changes that may be required.
• We recommend using the netconn interface for LWIP-based ports, because not all of the required functionality is available through the socket interface.

Reference implementations

PAL provides reference implementations for the following platforms and networking libraries:

Mbed OS

• Netsocket API: pal_plat_network.cpp.

  Located in the folder Source/Port/Reference-Impl/OS_Specific/mbedOS/Networking.

Linux

• Native POSIX networking API: pal_plat_network.c.

  Located in the folder Source/Port/Reference-Impl/OS_Specific/Linux/Networking.