mbed OS Ethernet MAC (EMAC) drivers

This document describes how to port and test an Ethernet MAC (EMAC) driver to mbed OS. It is based on work on the feature-emac branch as of mbed OS 5.8, which is intended to be merged into mbed OS 5.9

The scope of this document is limited to Ethernet (IEEE 802.3) or Ethernet-like devices such as Wi-Fi (IEEE 802.11), where the device presents a MAC interface to send and receive frames, and this will be used by one of the onboard network stacks that runs on mbed OS on the host processor.

(If the device has an off-board network stack, a driver would need to implement NetworkStack directly instead to pass network calls to that offboard stack).

Abstractions

The EMAC interface is designed to abstract network stacks and drivers, and to easily permit multiple instances. The key API classes are:

• NetworkInterface - an mbed OS network interface of any type
• NetworkStack - an mbed OS network stack of any type (may be off-board)
• OnboardNetworkStack - an on-board network stack
• EMAC - an Ethernet MAC device driver
• EMACMemoryManager - a memory manager used to pass data between driver and stack
• EMACInterface- a NetworkInterface that uses an EMAC driver and an OnboardNetworkStack

The EMAC driver core

The first step in the port is to create a driver class that can be instantiated to control your device. This must be derived from class EMAC. This API is used by a network stack (or test framework) to control your driver.

The EMAC-derived driver would normally be installed in connectivity/drivers/emac, often in a TARGET_XXX directory.

Class EMAC is entirely abstract - you need to implement about a dozen calls to activate the driver, send and receive packets, and perform other control and information functions.

There are also callback registration functions for upcalls from the driver - the stack can register callback functions for packet reception and link status changes.

The EMAC memory manager

For the send and receive paths, data is transferred in memory buffers controlled via an EMACMemoryManager object. The network stack using an EMAC driver provides it with a reference to the memory manager in use before powering up - this will be constant as long as the EMAC is powered up.

On the output call, the EMAC driver is given ownership of a buffer chain - it must free the chain when it has finished with the data. The data may or may not be contiguous. A driver can express alignment preferences for outgoing data, but the network stack is not required to meet these prefernces, so a driver relying on alignment may need a slow path that copies data into an aligned (or contiguous) buffer.

For reception, the EMAC driver must allocate memory from the EMACMemoryManager to store the received packets - this is then passed to the link input callback, which will free it. By preference this memory should be allocated using the pool, but if contiguous memory is required it can be allocated from the heap.

EthernetInterface

If your driver is a pure Ethernet driver, there is no further implementation required. The class EthernetInterface can use any EMAC driver to provide an mbed OS NetworkInterface:

MyEMAC my_emac(params);
EthernetInterface net(&my_emac);

net.connect();

This will attach the default network stack (normally lwIP - the other current alternative is Nanostack) to the specified EMAC driver, and provide all the generic NetworkInterface and NetworkStack APIs.

Being the default EMAC / EthernetInterface

To make your EMAC the default for applications you should define the static function EMAC::get_default_instance() to return an instance of your emac, eg:

MBED_WEAK EMAC &EMAC::get_default_instance()
{
    static MyEMAC my_emac(params);
    return &my_emac;
}

This permits this example application code to work:

EthernetInterface net;  // uses EMAC::get_default_instance()
net.connect();

This definition would normally be gated by a target label of some sort. As target code, your definition of EMAC::get_default_instance() must be weak - this permits it to be overridden by application code.

Wi-Fi interfaces

As a Wi-Fi interface, a little more work is required - at a minimum you need to implement the extra configuration calls in WiFiInterface. This is because the network stacks and EMAC APIs are only related to the Ethernet-like data path - they have no knowledge of any other configuration mechanisms and assume they are already set up.

To do this, you should create a C++ class that inherits from both WiFiInterface and EMACInterface. The EMACInterface is a helper class that implements all the core NetworkInterface functionality for you. You then just need to implement the extra WiFiInterface configuration methods.

For reference, note that EthernetInterface also derives from EMACInterface, but has no extra code as there is no extra configuration required.

As a Wi-fi driver, you will not normally be directly exposing your EMAC class - it would not normally be declared as EMAC::get_default_instance, but you would pass it to the constructor of your base EMACInterface. This then will make it visible via the get_emac method. This is for test purposes, meaning the test framework can do:

MyWiFiInterface net;
net.set_credentials();
EMAC &emac = net.get_emac();
do_emac_test(emac);

This must work in your driver - it must be possible to power up and use the built-in EMAC directly without the NetworkInterface::connect() method being invoked, as long as the credentials have been set. This structure will come naturally if you just use the default EMACInterface::connect() implementation.

Note also that your constructor must allow the network stack to be specified using the same form as EthernetInterface:

MyWiFiInterface(OnboardNetworkStack &stack = OnboardNetworkStack::get_default_instance());

OnboardNetworkStack

The precise details of the OnboardNetworkStack API should not concern an EMAC driver writer - it provides the mechanism to bind a driver to a stack, and the APIs needed to implement a NetworkInterface, but this is handled by EMACInterface, either as a base class of your own XXXInterface or as the base of EthernetInterface.

DEVICE_EMAC

At present, as an interim measure, targets providing EMAC::get_default_instance() should add "EMAC" in device_has in their targets.json. This activates network tests in CI builds.

This is subject to change, but is necessary in lieu of the previous typical behaviour of gating tests on FEATURE_LWIP.

Tuning memory allocations

Depending on its use of pool and heap memory, and other factors, a driver might want to tune the configuration of particular network stacks. This can be done via the mbed_lib.json of each network stack, using their target_overrides section.

Testing

The mbed OS tree contains Greentea-based tests that exercise the EMAC API directly, and more general socket tests.

See here for general Greentea information: https://github.com/ARMmbed/greentea

See here for the emac tests: https://github.com/ARMmbed/mbed-os/tree/feature-emac/TESTS/network/emac

Greentea socket tests are at: https://github.com/ARMmbed/mbed-os/tree/feature-emac/TESTS/netsocket

The driver should also be exercised with real-world examples like https://github.com/ARMmbed/mbed-os-example-client

The driver should also be tested with both network stacks available in mbed OS, as they will use the driver somewhat differently - try with the JSON option nsapi.default-stack set to each of LWIP and NANOSTACK.

Nanostack is IPv6 only. IPv6 operation should also be tested with lwIP, as this is likely to reveal problems with multicast filtering that may not be spotted by IPv4 or Nanostack.