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