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.

Example 1. Connect Syntax

ethlink0.connect device=phy0:PHYIface

Example 2. Disconnect Syntax

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:

  1. 40GBASE T FD

  2. 25GBASE T FD

  3. 10GBASE T FD

  4. 5GBASE T FD

  5. 2.5GBASE T FD

  6. 1000BASE T FD

  7. 1000BASE T HD

  8. 100BASE T2 FD

  9. 100BASE TX FD

  10. 100BASE T2 HD

  11. 100BASE T4

  12. 100BASE TX HD

  13. 10BASE T FD

  14. 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.

Example 3. TEMU 3 Command Syntax

ethlink0.enableCapture file="foo.pcap"

Example 4. Legacy Global Command (TEMU 2) Syntax

ethernet-link-enable-capture link=ethlink0 file="foo.pcap"

@EthernetLink Reference

Properties

Name Type Description

Class

*void

Class object

Component

*void

Pointer to component object if part of component

LoggingFlags

uint64_t

Flags for logging info

Name

*char

Object name

TimeSource

*void

Time source object

Commands

Name Description

delete

Dispose instance of @EthernetLink

new

Create new instance of EthernetLink

Command new Arguments

Name Type Required Description

name

string

yes

Name of object to create

EthernetLink Reference

Properties

Name Type Description

Class

*void

Class object

Component

*void

Pointer to component object if part of component

LoggingFlags

uint64_t

Flags for logging info

Name

*char

Object name

TimeSource

*void

Time source object

Interfaces

Name Type Description

EthernetIface

temu::EthernetIface

Commands

Name Description

connect

Connect device to ethernet link

delete

Dispose instance of EthernetLink

disconnect

Disconnect device from ethernet link

enableCapture

Enable capture to PCAPNG file

Command connect Arguments

Name Type Required Description

device

interface

yes

Device to connect

Command disconnect Arguments

Name Type Required Description

device

interface

yes

Device to connect

Command enableCapture Arguments

Name Type Required Description

file

path

yes

Name of capure file.

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

Properties

Name Type Description

Class

*void

Class object

Component

*void

Pointer to component object if part of component

LoggingFlags

uint64_t

Flags for logging info

Name

*char

Object name

TimeSource

*void

Time source object

Commands

Name Description

delete

Dispose instance of @GenericPHY

new

Create new instance of GenericPHY

Command new Arguments

Name Type Required Description

name

string

yes

Name of object to create

GenericPHY Reference

Properties

Name Type Description

Class

*void

Class object

Component

*void

Pointer to component object if part of component

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

Interfaces

Name Type Description

MDIOIface

temu::MDIOIface

PHYIface

temu::PHYIface

Commands

Name Description

delete

Dispose instance of GenericPHY

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

Properties

Name Type Description

Class

*void

Class object

Component

*void

Pointer to component object if part of component

LoggingFlags

uint64_t

Flags for logging info

Name

*char

Object name

TimeSource

*void

Time source object

Commands

Name Description

delete

Dispose instance of @MDIOBus

new

Create new instance of MDIOBus

Command new Arguments

Name Type Required Description

name

string

yes

Name of object to create

MDIOBus Reference

Properties

Name Type Description

Class

*void

Class object

Component

*void

Pointer to component object if part of component

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.

Interfaces

Name Type Description

MDIOIface

temu::MDIOIface

Commands

Name Description

delete

Dispose instance of MDIOBus

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.