Ethernet Simulation
TEMU provides support for Ethernet bus based devices. To support the development of custom MAC controllers, TEMU provides three generic models.
The MDIOBus model implements MDIO routing.
As multiple MDIO devices can be connected to the same bus, a bus model is needed.
A GenericPHY model is implemented to expose the MDIO interface to the MAC models.
The GenericPHY model can be attached to the EthernetLink model.
EthernetLink is responsible for routing EthernetFrames between registered nodes.
It has two routing lists.
Firstly, a list of promiscuous nodes that will receive all messages.
Secondly, a routing map for non-promiscuous nodes.
When the EthernetLink model receives a frame,
it forwards the frame to all the promiscous nodes.
Then, it routes it to the destination MAC.
The EthernetLink assumes unique MACs,
thus it will emit a warning in the case of a MAC address collission.
Connecting Devices
An ethernet link must be connected to its attached PHYs.
Connection is done using the connect command.
ethlink0.connect device=phy0:PHYIface
ethlink0.connect device=phy0:PHYIface
Checksums
Ethernet frames typically have a checksum that is generated and checked by hardware. To optimise the bus model, it is expected that MAC models supports opt in control on checksum generation and checking. This applies to all checksums, including Ethernet frame CRCs and IP header, TCP, UDP checksums. Since the Ethernet link is fully virtual, data cannot normally be corrupted in transit. Thus checksum checking and generation would be a waste of cycles.
There are still several usecases where one want to enable checksums:
-
When viewing capture files with Wireshark, the tool will complain if ethernet CRCs are invalid.
-
When receiving frames in a device which do not have hardware assisted CRC checking.
Thus, normally Ethernet CRC generation and checking will be disabled, while TCP/UDP/IP checksum generation (but not hardware checking) will be enabled.
Auto Negotiation
The ethernet model supports autonegotiation for transfer speed capabilities.
The process is based on issuing an auto-negotiation request to the ethernet link model.
The link will then issue auto-negotiation requests to each attached PHY,
and finally call autonegotiateDone for all attached PHYs.
Each PHY will be called with the current known capabilities. It should return the same capabilities with potentially some of them cleared.
The actual final capabilities are reported with autonegotiateDone.
There, a PHY will select the highest priority common mode. Which by the standard is:
-
40GBASE T FD
-
25GBASE T FD
-
10GBASE T FD
-
5GBASE T FD
-
2.5GBASE T FD
-
1000BASE T FD
-
1000BASE T HD
-
100BASE T2 FD
-
100BASE TX FD
-
100BASE T2 HD
-
100BASE T4
-
100BASE TX HD
-
10BASE T FD
-
10BASE T HD
| TEMU does not support emulation of 2.5 GBASE and above at this moment. |
Ethernet Frames
Ethernet frames in TEMU are structs containing a flag field, data and an optional preamble.
The data field is a COW buffer which contains the level 2 ethernet frame data.
The preamble will typically be ignored and not set for most MACs.
However if it is set to somthing non-standard,
a device can indicate this by setting the flag TEMU_ETH_NON_STANDARD_PREAMBLE.
Ethernet Link
Frame Capture
The ethernet link can be instructed to dump all traffic to a PCAPNG file.
| Wireshark may flag frames as having invalid CRCs. To avoid this you can enable CRC generation in the MAC, or turn off checking in Wireshark. |
To enable capture execute the enableCapture command ont he ethernet link.
ethlink0.enableCapture file="foo.pcap"
ethernet-link-enable-capture link=ethlink0 file="foo.pcap"
Live Monitoring
TEMU 4.5 added the option to monitor Ethernet traffic live. This is done using:
ethlink0.enableCapture file="foo.pcap" named-pipe=1
When adding the named pipe option, the command will block until Wireshark connects to the pipe. For more information on how to connect Wireshark to a named pipe see the Wireshark Wiki (external link).
@EthernetLink Reference
EthernetLink Reference
Properties
| Name | Type | Description |
|---|---|---|
Class |
*void |
Class object |
Component |
*void |
Pointer to component object if part of component |
LocalName |
*char |
Local name (in component, if applicable) |
LoggingFlags |
uint64_t |
Flags for logging info |
Name |
*char |
Object name |
TimeSource |
*void |
Time source object |
bitRate |
uint64_t |
Bit rate in bit/s |
bytesSent |
uint64_t |
Total bytes sent on link |
bytesSentInLastReport |
uint64_t |
Last reported data |
framesSent |
uint64_t |
Number of frames sent |
Interfaces
| Name | Type | Description |
|---|---|---|
EthernetIface |
temu::EthernetIface |
|
LinkDelayIface |
temu::EthDelayIface |
Commands
| Name | Description |
|---|---|
add-delay |
Add delay for a device with given MAC |
connect |
Connect device to ethernet link |
delete |
Dispose instance of EthernetLink |
disconnect |
Disconnect device from ethernet link |
down |
Bring link down |
enableCapture |
Enable capture to PCAPNG file |
inject |
Inject frame with given paramteres MAC |
plink |
Print link info |
up |
Bring link up |
Command add-delay Arguments
| Name | Type | Required | Description |
|---|---|---|---|
delay-object |
object |
yes |
Delay object to connect |
mac |
string |
yes |
Mac of the device to delay |
seconds |
double |
no |
Delay value in seconds |
Command enableCapture Arguments
| Name | Type | Required | Description |
|---|---|---|---|
file |
path |
yes |
Name of capure file. |
named-pipe |
int |
no |
Capture to named pipe for wireshark live capture. |
Generic PHY
The GenericPHY is a PHY / MII device which supports both the MDIO interface
and the PHY interface for sending/receiving ethernet frames.
The GenericPHY device class by default enables support for BASE10, BASE100
and BASE1000 transfers.
To only enable specific speed modes, the constructor accepts arguments:
-
base10:1
-
base100:1
-
base1000:1
If any of these are set, the unset ones will be disabled.
Thus by default a PHY supports all BASE10, BASE100 and BASE1000 modes. By setting the base10 argument, only BASE10 modes will be supported. By setting base10 and base 100 arguments, only BASE10 and BASE100 will be supported.
At present it is not possible to control the support on a lower level.
@GenericPHY Reference
GenericPHY Reference
Properties
| Name | Type | Description |
|---|---|---|
Class |
*void |
Class object |
Component |
*void |
Pointer to component object if part of component |
LocalName |
*char |
Local name (in component, if applicable) |
LoggingFlags |
uint64_t |
Flags for logging info |
Name |
*char |
Object name |
TimeSource |
*void |
Time source object |
autoNegAdvertisment |
uint16_t |
Auto negotiation advertisment register |
autoNegotiationExpansion |
uint16_t |
Auto negotiation expansion register |
basicModeConfig |
uint16_t |
Basic mode config register |
basicModeStatus |
uint16_t |
Basic mode status register |
ethernetLink |
temu_IfaceRef/ <unknown> |
Ethernet link. |
linkPartnerAbility |
uint16_t |
Link partner ability register |
macDevice |
temu_IfaceRef/ <unknown> |
MAC device. |
phyID |
[uint16_t; 2] |
Physical ID registers |
MDIO Bus
The MDIO bus distributes MDIO control messages and supports routing of them. The MDIO bus use the same interface as an MDIO device. Thus, if only one MDIO device (e.g. GenericPHY) is available no MDIO bus instance is needed.
@MDIOBus Reference
MDIOBus Reference
Properties
| Name | Type | Description |
|---|---|---|
Class |
*void |
Class object |
Component |
*void |
Pointer to component object if part of component |
LocalName |
*char |
Local name (in component, if applicable) |
LoggingFlags |
uint64_t |
Flags for logging info |
Name |
*char |
Object name |
TimeSource |
*void |
Time source object |
macDevice |
temu_IfaceRef/ <unknown> |
MAC controller. |
phyDevices |
[temu_IfaceRef; 32]/ <unknown> |
MDIO interface of PHYs. |
Implementing a MAC Model
TEMU comes with some bundled MAC models. In some cases it will be needed to implement additional project specific MAC models.
Consult the eth-device example for more info.
Host Network Integration
The NAT bridge supports the routing of network packets between an external real network and the simulated Ethernet link.
This enables for example Telnet or custom network applications to be used for testing target software. A target OS supporting GDB RSP could provide direct intrusive debugging support via the GDB RSP protocol, DAP or TCF.
Currently the NAT bridge only support IPv4 and TCP, it does not support IPv6 and/or UDP.
@NATBridge Reference
NATBridge Reference
Properties
| Name | Type | Description |
|---|---|---|
Class |
*void |
Class object |
Component |
*void |
Pointer to component object if part of component |
LocalName |
*char |
Local name (in component, if applicable) |
LoggingFlags |
uint64_t |
Flags for logging info |
Name |
*char |
Object name |
TimeSource |
*void |
Time source object |
config.frameDelay |
uint64_t |
Delay for each frame in nanoseconds. |
config.ipv4.nat.externalSegmentSize |
uint32_t |
Max size of data read from external ports and forwarded in single frames. |
config.ipv4.tcp.ackDelay |
uint32_t |
ACK delay (how many packets between acks): 0 = immediate (every packet is acked) |
config.ipv4.tcp.ackDelayTimeout |
uint32_t |
ACK delay timeout in ms, if ACKs are not sent immediately, a timeout is set to ensure acks within a maximum time window |
config.ipv4.tcp.finTimeout |
uint32_t |
2 Maximum Segment Lifetime in seconds. Controls waiting after FIN reception. |
config.ipv4.tcp.maxRetransmissions |
uint32_t |
Number of retransmissions to do before giving up. |
config.ipv4.tcp.retransmissionTimeout |
uint32_t |
Retransmission timeout in ms |
config.ipv4.tcp.roundTripTime |
uint32_t |
Measured round-trip time. |
config.ipv4.tcp.windowSize |
uint16_t |
Base TCP window size |
ethernetLink |
temu_IfaceRef/ <unknown> |
Ethernet link. |
Interfaces
| Name | Type | Description |
|---|---|---|
PHYIface |
temu::PHYIface |
PHY interface for Ethernet frames |
StreamIface |
temu::streamIface |
TCP stream interface |
Commands
| Name | Description |
|---|---|
add-nat |
Add NAT mapping |
delete |
Dispose instance of NATBridge |
do-arp-request |
Send an ARP request message |
enable-arp-dumps |
Enable ARP frame dumps |
enable-crlf-substitution |
Enable CRLF substitution on incoming packets, replaces CRLF sequences with '\0' which can simplify protocol debugging using Telnet |
parp |
Print ARP resolutions |
pmap |
Print port maps |
set-ip |
Set IP address |
set-mac |
Set MAC address |
start-nat |
Create stat NAT server |
Command add-nat Arguments
| Name | Type | Required | Description |
|---|---|---|---|
external-port |
int |
yes |
External port (real network) |
internal-addr |
string |
yes |
IP address of target |
internal-port |
int |
yes |
Internal port (TEMU network) |
name |
string |
yes |
Name of TAP device |