EtherMAC

Package: inet.linklayer.ethernet

EtherMAC

simple module

Ethernet MAC layer. MAC performs transmission and reception of frames. See the IEtherMAC for the Ethernet MAC layer general informations. Doesn't do encapsulation/decapsulation; see EtherLLC and EtherEncap for that.

Supported variations:

  • 10Mb Ethernet (duplex and half-duplex, coaxial cable or twisted pair)
  • 100Mb Ethernet (duplex and half-duplex)
  • 1Gb Ethernet (duplex and half-duplex)
  • 10Gb Ethernet
  • 40Gb Ethernet
  • 100Gb Ethernet

Supports all three Ethernet frame types. (It handles EtherFrame message class; specific frame classes (Ethernet-II, IEEE 802.3) are subclassed from that one.) RAW mode (only used by the IPX protocol) is not supported.

Expected environment:

  • phys$i and phys$o should be connected to the "network"
  • upperLayerIn and upperLayerOut are usually connected to EtherLLC (in hosts) or MACRelayUnit (in a switch)

Operation

Processing of frames received from higher layers:

  • if src address in the frame is empty, fill it out
  • frames get queued up until transmission
  • transmit according to the CSMA/CD protocol
  • can send PAUSE message if requested by higher layers (PAUSE protocol, used in switches).

Processing of frames incoming from the network:

  • receive according to the CSMA/CD protocol
  • CRC checking (frames with the error bit set are discarded).
  • respond to PAUSE frames
  • in promiscuous mode, pass up all received frames; otherwise, only frames with matching MAC addresses and broadcast frames are passed up.

The module does not perform encapsulation or decapsulation of frames -- this is done by higher layers (EtherLLC or EtherEncap).

When a frame is received from the higher layers, it must be an EtherFrame, and with all protocol fields filled out (including the destination MAC address). The source address, if left empty, will be filled in. Then frame is queued and transmitted according to the CSMA/CD protocol.

Data frames received from the network are EtherFrames. They are passed to the higher layers without modification. Also, the module properly responds to PAUSE frames, but never sends them by itself -- however, it transmits PAUSE frames received from upper layers. See PAUSE handling for more info.

For more info see Ethernet Model Overview.

Disabling and disconnecting

If the MAC is not connected to the network ("cable unplugged"), it will start up in "disabled" mode. A disabled MAC simply discards any messages it receives. It is currently not supported to dynamically connect/disconnect a MAC.

Queueing

In routers, MAC relies on an external queue module (see IOutputQueue) to model finite buffer, implement QoS and/or RED, and requests packets from this external queue one-by-one.

In hosts, no such queue is used, so MAC contains an internal queue named txQueue to queue up packets waiting for transmission. Conceptually, txQueue is of infinite size, but for better diagnostics one can specify a hard limit in the txQueueLimit parameter -- if this is exceeded, the simulation stops with an error.

Physical layer messaging

Please see Messaging on the physical layer.

See also: EtherMACFullDuplex, EthernetInterface, IOutputQueue, EtherEncap, EtherLLC

See also: EtherFrame, EthernetIIFrame, EtherFrameWithLLC, Ieee802Ctrl

Inheritance diagram

The following diagram shows inheritance relationships for this type. Unresolved types are missing from the diagram.

Parameters

Name Type Default value Description
interfaceTableModule string

The path to the InterfaceTable module

promiscuous bool false

if true, all packets are received, otherwise only the ones with matching destination MAC address

address string "auto"

MAC address as hex string (12 hex digits), or "auto". "auto" values will be replaced by a generated MAC address in init stage 0.

duplexMode bool true

selects full-duplex (true) or half-duplex (false) operation

txQueueLimit int 1000

maximum number of frames queued up for transmission in the internal queue (only used if queueModule==""); additional frames cause a runtime error

queueModule string ""

name of optional external queue module

frameBursting bool true

enable/disable frame bursting mode in Gigabit Ethernet

mtu int 1500B

Properties

Name Value Description
display i=block/rxtx

Gates

Name Direction Size Description
upperLayerIn input

to EtherLLC or EtherEncap or IMACRelayUnit

upperLayerOut output

to EtherLLC or EtherEncap or IMACRelayUnit

phys inout

to physical layer or the network

Signals

Name Type Unit
rxPkFromHL inet::EtherFrame
packetReceivedFromLower inet::EtherFrame
packetReceivedFromUpper inet::EtherFrame
backoff long
txPausePkUnits inet::long
txPk inet::EtherFrame
dropPkBitError inet::EtherFrame
rxPausePkUnits inet::long
dropPkFromHLIfaceDown inet::EtherFrame
dropPkNotForUs inet::EtherFrame
collision long
rxPkOk inet::EtherFrame
transmitState long
receiveState long
packetSentToLower inet::EtherFrame
packetSentToUpper inet::EtherFrame
dropPkIfaceDown inet::EtherFrame

Statistics

Name Title Source Record Unit Interpolation Mode
passedUpPk packets passed to higher layer packetSentToUpper count, sum(packetBytes), vector(packetBytes) none
rxPkFromHL packet bytes from higher layer rxPkFromHL count, sum(packetBytes), vector(packetBytes) none
droppedPkBitError packets dropped/bit error dropPkBitError count, sum(packetBytes), vector(packetBytes) none
collision collision count, vector none
droppedPkIfaceDown packets dropped/interface down dropPkIfaceDown count, sum(packetBytes), vector(packetBytes) none
rxPkOk packets received OK rxPkOk count, sum(packetBytes), vector(packetBytes) none
backoff backoff count, vector none
txPausePkUnits pause units sent count, sum, vector none
droppedPkNotForUs packets dropped/not for us dropPkNotForUs count, sum(packetBytes), vector(packetBytes) none
txPk packets transmitted txPk count, sum(packetBytes), vector(packetBytes) none
rxPausePkUnits pause units received count, sum, vector none

Source code

//
// Ethernet MAC layer. MAC performs transmission and reception of frames.
// See the ~IEtherMAC for the Ethernet MAC layer general informations.
// Doesn't do encapsulation/decapsulation; see ~EtherLLC and ~EtherEncap for
// that.
//
// Supported variations:
// - 10Mb Ethernet (duplex and half-duplex, coaxial cable or twisted pair)
// - 100Mb Ethernet (duplex and half-duplex)
// - 1Gb Ethernet (duplex and half-duplex)
// - 10Gb Ethernet
// - 40Gb Ethernet
// - 100Gb Ethernet
//
// Supports all three Ethernet frame types. (It handles ~EtherFrame message class;
// specific frame classes (Ethernet-II, IEEE 802.3) are subclassed from that one.)
// RAW mode (only used by the IPX protocol) is not supported.
//
// Expected environment:
// - phys$i and phys$o should be connected to the "network"
// - upperLayerIn and upperLayerOut are usually connected to ~EtherLLC (in hosts)
//   or ~MACRelayUnit (in a switch)
//
// <b>Operation</b>
//
// Processing of frames received from higher layers:
// - if src address in the frame is empty, fill it out
// - frames get queued up until transmission
// - transmit according to the CSMA/CD protocol
// - can send PAUSE message if requested by higher layers (PAUSE protocol,
//   used in switches).
//
// Processing of frames incoming from the network:
// - receive according to the CSMA/CD protocol
// - CRC checking (frames with the error bit set are discarded).
// - respond to PAUSE frames
// - in promiscuous mode, pass up all received frames;
//   otherwise, only frames with matching MAC addresses and
//   broadcast frames are passed up.
//
// The module does not perform encapsulation or decapsulation of frames --
// this is done by higher layers (~EtherLLC or ~EtherEncap).
//
// When a frame is received from the higher layers, it must be an ~EtherFrame,
// and with all protocol fields filled out
// (including the destination MAC address). The source address, if left empty,
// will be filled in. Then frame is queued and transmitted according
// to the CSMA/CD protocol.
//
// Data frames received from the network are EtherFrames. They are passed to
// the higher layers without modification.
// Also, the module properly responds to PAUSE frames, but never sends them
// by itself -- however, it transmits PAUSE frames received from upper layers.
// See <a href="ether-pause.html">PAUSE handling</a> for more info.
//
// For more info see <a href="ether-overview.html">Ethernet Model Overview</a>.
//
// <b>Disabling and disconnecting</b>
//
// If the MAC is not connected to the network ("cable unplugged"), it will
// start up in "disabled" mode. A disabled MAC simply discards any messages
// it receives. It is currently not supported to dynamically connect/disconnect
// a MAC.
//
//
// <b>Queueing</b>
//
// In routers, MAC relies on an external queue module (see ~IOutputQueue)
// to model finite buffer, implement QoS and/or RED, and requests packets
// from this external queue one-by-one.
//
// In hosts, no such queue is used, so MAC contains an internal
// queue named txQueue to queue up packets waiting for transmission.
// Conceptually, txQueue is of infinite size, but for better diagnostics
// one can specify a hard limit in the txQueueLimit parameter -- if this is
// exceeded, the simulation stops with an error.
//
//
// <b>Physical layer messaging</b>
//
// Please see <a href="physical.html">Messaging on the physical layer</a>.
//
// @see ~EtherMACFullDuplex, ~EthernetInterface, ~IOutputQueue, ~EtherEncap, ~EtherLLC
// @see ~EtherFrame, ~EthernetIIFrame, ~EtherFrameWithLLC, ~Ieee802Ctrl
//
simple EtherMAC like IEtherMAC
{
    parameters:
        string interfaceTableModule;   // The path to the InterfaceTable module
        bool promiscuous = default(false);  // if true, all packets are received, otherwise only the
                                            // ones with matching destination MAC address
        string address @mutable = default("auto");   // MAC address as hex string (12 hex digits), or
                                                     // "auto". "auto" values will be replaced by
                                                     // a generated MAC address in init stage 0.
        bool duplexMode = default(true);    // selects full-duplex (true) or half-duplex (false) operation
        int txQueueLimit = default(1000);   // maximum number of frames queued up for transmission in the internal queue (only used if queueModule==""); additional frames cause a runtime error
        string queueModule = default("");   // name of optional external queue module
        bool frameBursting = default(true); // enable/disable frame bursting mode in Gigabit Ethernet
        int mtu @unit("B") = default(1500B);
        @display("i=block/rxtx");

        @signal[txPk](type=inet::EtherFrame);
        @signal[rxPkOk](type=inet::EtherFrame);
        @signal[txPausePkUnits](type=inet::long);
        @signal[rxPausePkUnits](type=inet::long);
        @signal[rxPkFromHL](type=inet::EtherFrame);
        @signal[dropPkNotForUs](type=inet::EtherFrame);
        @signal[dropPkBitError](type=inet::EtherFrame);
        @signal[dropPkFromHLIfaceDown](type=inet::EtherFrame);
        @signal[dropPkIfaceDown](type=inet::EtherFrame);        // emitted at begin of receiving
        @signal[packetSentToLower](type=inet::EtherFrame);
        @signal[packetReceivedFromLower](type=inet::EtherFrame);
        @signal[packetSentToUpper](type=inet::EtherFrame);
        @signal[packetReceivedFromUpper](type=inet::EtherFrame);
        @signal[collision](type=long);
        @signal[backoff](type=long);
        @signal[transmitState](type=long); // enum=MACTransmitState
        @signal[receiveState](type=long); // enum=MACReceiveState

        @statistic[txPk](title="packets transmitted"; source=txPk; record=count,"sum(packetBytes)","vector(packetBytes)"; interpolationmode=none);
        @statistic[rxPkOk](title="packets received OK"; source=rxPkOk; record=count,"sum(packetBytes)","vector(packetBytes)"; interpolationmode=none);
        @statistic[passedUpPk](title="packets passed to higher layer"; source=packetSentToUpper; record=count,"sum(packetBytes)","vector(packetBytes)"; interpolationmode=none);
        @statistic[txPausePkUnits](title="pause units sent"; record=count,sum,vector; interpolationmode=none);
        @statistic[rxPausePkUnits](title="pause units received"; record=count,sum,vector; interpolationmode=none);
        @statistic[rxPkFromHL](title="packet bytes from higher layer"; source=rxPkFromHL; record=count,"sum(packetBytes)","vector(packetBytes)"; interpolationmode=none);
        @statistic[droppedPkIfaceDown](title="packets dropped/interface down"; source=dropPkIfaceDown; record=count,"sum(packetBytes)","vector(packetBytes)"; interpolationmode=none);
        @statistic[droppedPkBitError](title="packets dropped/bit error"; source=dropPkBitError; record=count,"sum(packetBytes)","vector(packetBytes)"; interpolationmode=none);
        @statistic[droppedPkNotForUs](title="packets dropped/not for us"; source=dropPkNotForUs; record=count,"sum(packetBytes)","vector(packetBytes)"; interpolationmode=none);
        @statistic[collision](title="collision"; record=count,vector; interpolationmode=none);
        @statistic[backoff](title="backoff"; record=count,vector; interpolationmode=none);

    gates:
        input upperLayerIn @labels(EtherFrame);    // to ~EtherLLC or ~EtherEncap or ~IMACRelayUnit
        output upperLayerOut @labels(EtherFrame);  // to ~EtherLLC or ~EtherEncap or ~IMACRelayUnit
        inout phys @labels(EtherFrame); // to physical layer or the network
}

File: src/inet/linklayer/ethernet/EtherMAC.ned