Porting the Networking module
The Networking module is responsible for:
- TCP/UDP socket based networking for IPv4 and IPv6, including client/server sockets, blocking/nonblocking sockets and asynchronous sockets.
- Basic DNS functionality (network address lookup).
- 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.
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 Pelion Device Management services:
After successfully porting the Networking module, all PAL networking tests need to pass. Please see the Tests section for more information.
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
- 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.
- 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_tstructure. Instead, use the functions defined for socket addresses in
pal_network.h, such as
- Not all of the fields in the
palNetInterfaceInfo_tstructure (that are used to get information on a registered network interface) are relevant for all interfaces on all platforms. However, the
addressfield 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_RegisterNetworkInterfacefunction. 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_INTERFACEdefines 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_INTERFACESdifferent interfaces, where the default value is
10. If your port requires support for more than ten interfaces you should change this value in
- 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.logfile in the
lwip_1.4.1folder 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
netconninterface for LWIP-based ports, because not all of the required functionality is available through the socket interface.
PAL provides reference implementations for the following platforms and networking libraries:
Located in the folder
Native POSIX networking API:
Located in the folder