1<!--
2     Copyright 2020, Data61
3     Commonwealth Scientific and Industrial Research Organisation (CSIRO)
4     ABN 41 687 119 230.
5
6     This software may be distributed and modified according to the terms of
7     the BSD 2-Clause license. Note that NO WARRANTY is provided.
8     See "LICENSE_BSD2.txt" for details.
9
10     @TAG(DATA61_BSD)
11-->
12
13# Ethdriver
14
15This is a a CAmkES component that is intended to abstract over a platform's
16Ethernet device and multiplex client access to it.
17
18## Dependencies
19
20This component needs to be used with the `single-threaded` module that performs
21the initialisation process, and client request routing the component relies on.
22The `picotcp-ethernet-async` module is an optional dependency which provides
23helper CAmkES macros and an asynchronous data transfer interface for clients.
24
25## Usage
26
27For clients to use the functionality exposed by the component, the clients will have to connect to this CAmkES interface using the `seL4Ethdriver` connector.
28
29```c
30provides Ethdriver client;
31```
32
33There are also some additional configuration options for the DMA that need to
34be set. To set this, change the following to be a page aligned number, and
35replace `name` with the name of the Ethdriver instance.
36
37```c
38name.dma_pool = <desired DMA pool size>;
39```
40
41To use the asynchronous data transfer interface, the `picotcp-ethernet-async`
42optional module provides several macros to add these extra interfaces, connect
43the client to the component, and configure the necessary options as well. These
44are:
45
46```c
47picotcp_ethernet_async_server_interfaces(name)
48
49picotcp_ethernet_async_connections(name, client, driver)
50
51picotcp_ethernet_async_configurations(name, client, driver)
52```
53
54## Supported platforms
55
56Currently, this component supports the following platforms:
57  - i.MX6
58  - i.MX8MQ Evaluation Kit
59  - TX2
60  - Zynq7000
61  - pc99, specifically the Intel 82574 and 82580 Ethernet controllers
62
63Additional platforms require a corresponding clock system driver to be
64implemented in the libplatsupport library of the
65[`util_libs`](https://github.com/seL4/util_libs) repository, and the following
66CPP defintions to be created in the `include` folder of this component (if the
67platform is ARM-based):
68  - `HARDWARE_ETHERNET_INTERFACES`
69  - `HARDWARE_ETHERNET_INTERFACES`
70  - `HARDWARE_ETHERNET_ATTRIBUTES`
71  - `HARDWARE_ETHERNET_COMPOSITION`
72  - `HARDWARE_ETHERNET_CONFIG`
73  - and possibly, `HARDWARE_ETHERNET_EXTRA_IMPORTS`
74
75## Limitations
76
77Network performance may be an issue for network-demanding applications that
78require throughputs close to Gigabit. This is because the Ethdriver by default
79runs in its own address space and data transfer is done via copying in and out
80to and from shared memory channels between the Ethdriver and the clients.
81