EthernetMacPhy

compound module

Ethernet MAC which supports full-duplex operation ONLY. See the ~IEtherMac for general information.

Most of today's Ethernet networks are switched and operate in full-duplex mode. Full-duplex transmission can be used for point-to-point connections only. Since full-duplex connections cannot be shared, collisions are eliminated. This setup eliminates most of the need for the CSMA/CD access control mechanism because there is no need to determine whether the connection is already being used. This allows for a much simpler simulation model for the MAC. (In "traditional" Ethernet simulations, most of the code deals with the shared medium and the CSMA/CD mechanism.) ~EthernetMacPhy implements Ethernet without shared medium and CSMA/CD. (If you need half-duplex operation, see ~EthernetCsmaMacPhy which is for a full-blown and therefore more complicated Ethernet MAC model.)

~EthernetMacPhy performs transmission and reception of frames. It does not do encapsulation/decapsulation; see ~Ieee8022Llc and ~EthernetEncapsulation for that.

Supported variations:

10Mb Ethernet (full-duplex mode)
100Mb Ethernet (full-duplex mode)
1Gb Ethernet (full-duplex mode)
10Gb Ethernet (full-duplex mode)
40Gb Ethernet (full-duplex mode)
100Gb Ethernet (full-duplex mode)

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.

Operation

Processing of frames received from higher layers:

if the source address in the frame is empty, fill it out
frames get queued up until transmission
transmits the frame when the transmitter is ready
can send a PAUSE message if requested by higher layers (PAUSE protocol, used in switches).

Processing of frames incoming from the network:

receive frame from the network
FCS 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 (~EthernetEncapsulation).

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 the frame is queued and transmitted.

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(1,2,3) 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 ~IPacketQueue) 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 to store packets waiting for transmission. Conceptually, the queue is of infinite size, but for better diagnostics one can specify a hard limit in the queue parameter -- if this is exceeded, the simulation stops with an error.

Physical layer messaging

Please see Messaging on the physical layer.

See also: ~EthernetMacHeader, ~Ieee8022LlcHeader, ~EthernetFcs

Inheritance diagram

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

Extends

Name	Type	Description
Module	compound module	Base module for all INET compound modules.

Parameters

Name	Type	Default value	Description
displayStringTextFormat	string	"rate: %b\nsent: %s, rcvd: %r\nqueue: %q, drop: %d"	Determines the text that is written on top of the submodule, supports displaying pars, watches, and module-specific information
interfaceTableModule	string		The path to the InterfaceTable module
sendRawBytes	bool	false	When true, packets are serialized into a sequence of bytes before sending out
promiscuous	bool	false	If true, all packets are received; otherwise, only the ones with a matching destination MAC address
duplexMode	bool		Must be set to "true", as EthernetMacPhy does not support half-duplex operation (parameter is present to reduce the risk of accidental misconfiguration)
allowNonstandardBitrate	bool	false	Allows any bitrate and uses the first larger bitrate specified parameters
receptionMode	string	"auto"	Receiviving mode of incoming ethernet frames: onStart: receiving on start of frame auto: receiving on start frame when module has any subscribers to receptionStart signal, otherwise receiving on end of frame onEnd: receiving on end of frame, throws error at end of initialize module when has any subscribers to receptionStart signal forceOnEnd: receiving on end of frame, silently skip emit receptionStart signal
mtu	int	1500B
fcsMode	string
stopOperationExtraTime	double	-1s	Extra time after the lifecycle stop operation finished
stopOperationTimeout	double	2s	Timeout value for the lifecycle stop operation

Properties

Name	Value	Description
class	EthernetMacPhy
lifecycleSupport
display	i=block/rxtx

Gates

Name	Direction	Description
upperLayerIn	input	To ~EthernetEncapsulation or ~IMacRelayUnit
upperLayerOut	output	To ~EthernetEncapsulation or ~IMacRelayUnit
phys	inout	To the network

Signals

Name	Type	Description
receptionStateChanged	long	Enum=MacReceiveState
rxPkFromHl	inet::Packet
receptionEnded	inet::physicallayer::Signal
packetReceivedFromLower	inet::Packet
packetReceivedFromUpper	inet::Packet
txPausePkUnits	long
txPk	inet::Packet
rxPausePkUnits	long
transmissionStarted	inet::physicallayer::EthernetSignalBase
rxPkOk	inet::Packet
receptionStarted	inet::physicallayer::Signal
packetDropped	inet::Packet
packetSentToLower	inet::Packet
packetSentToUpper	inet::Packet
transmissionStateChanged	long	Enum=MacTransmitState
transmissionEnded	inet::physicallayer::EthernetSignalBase

Statistics

Name	Title	Source	Record	Unit	Interpolation Mode
passedUpPk	packets passed to higher layer	packetSentToUpper	count, sum(packetBytes), vector(packetBytes)		none
packetDropInterfaceDown	packet drop: interface down	packetDropReasonIsInterfaceDown(packetDropped)	count, sum(packetBytes), vector(packetBytes)		none
rxPkOk	packets received OK	rxPkOk	count, sum(packetBytes), vector(packetBytes)		none
packetDropNotAddressedToUs	packet drop: not addressed to us	packetDropReasonIsNotAddressedToUs(packetDropped)	count, sum(packetBytes), vector(packetBytes)		none
packetReceivedFromUpper	packet bytes from higher layer	packetReceivedFromUpper	count, sum(packetBytes), vector(packetBytes)		none
txPausePkUnits	pause units sent		count, sum, vector		none
transmitting	transmitting state	count(transmissionStarted) - count(transmissionEnded)	vector		sample-hold
txPk	packets transmitted	packetSentToLower	count, sum(packetBytes), vector(packetBytes)		none
utilization	utilization	100 * utilization(count(transmissionStarted) - count(transmissionEnded))	vector, histogram	%	linear
throughput	throughput	throughput(transmissionEnded)	vector, histogram	bps	linear
rxPausePkUnits	pause units received		count, sum, vector		none
packetDropIncorrectlyReceived	packet drop: incorrectly received	packetDropReasonIsIncorrectlyReceived(packetDropped)	count, sum(packetBytes), vector(packetBytes)		none

Source code

//
// Ethernet MAC which supports full-duplex operation ONLY.
// See the ~IEtherMac for general information.
//
// Most of today's Ethernet networks are switched and operate
// in full-duplex mode. Full-duplex transmission can be used for
// point-to-point connections only. Since full-duplex connections
// cannot be shared, collisions are eliminated. This setup eliminates
// most of the need for the CSMA/CD access control mechanism because
// there is no need to determine whether the connection is already
// being used. This allows for a much simpler simulation model
// for the MAC. (In "traditional" Ethernet simulations, most of the code
// deals with the shared medium and the CSMA/CD mechanism.)
// ~EthernetMacPhy implements Ethernet without shared medium and CSMA/CD.
// (If you need half-duplex operation, see ~EthernetCsmaMacPhy which is for a full-blown
// and therefore more complicated Ethernet MAC model.)
//
// ~EthernetMacPhy performs transmission and reception of frames.
// It does not do encapsulation/decapsulation; see ~Ieee8022Llc and ~EthernetEncapsulation
// for that.
//
// Supported variations:
// - 10Mb Ethernet (full-duplex mode)
// - 100Mb Ethernet (full-duplex mode)
// - 1Gb Ethernet (full-duplex mode)
// - 10Gb Ethernet (full-duplex mode)
// - 40Gb Ethernet (full-duplex mode)
// - 100Gb Ethernet (full-duplex mode)
//
// 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.
//
// <b>Operation</b>
//
// Processing of frames received from higher layers:
// - if the source address in the frame is empty, fill it out
// - frames get queued up until transmission
// - transmits the frame when the transmitter is ready
// - can send a PAUSE message if requested by higher layers (PAUSE protocol,
//   used in switches).
//
// Processing of frames incoming from the network:
// - receive frame from the network
// - FCS 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 (~EthernetEncapsulation).
//
// 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 the frame is queued and transmitted.
//
// 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 ~IPacketQueue)
// 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 to store packets waiting for transmission.
// Conceptually, the queue is of infinite size, but for better diagnostics
// one can specify a hard limit in the queue 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 ~EthernetCsmaMacPhy, ~EthernetInterface, ~IPacketQueue, ~EthernetEncapsulation, ~Ieee8022Llc
// @see ~EthernetMacHeader, ~Ieee8022LlcHeader, ~EthernetFcs
//
module EthernetMacPhy extends Module like IEtherMac
{
    parameters:
        string interfaceTableModule;        // The path to the InterfaceTable module
        displayStringTextFormat = default("rate: %b\nsent: %s, rcvd: %r\nqueue: %q, drop: %d");
        bool sendRawBytes = default(false); // When true, packets are serialized into a sequence of bytes before sending out
        bool promiscuous = default(false);  // If true, all packets are received; otherwise, only the
                                            // ones with a matching destination MAC address
        bool duplexMode;                    // Must be set to "true", as EthernetMacPhy does not support half-duplex operation
                                            // (parameter is present to reduce the risk of accidental misconfiguration)
        bool allowNonstandardBitrate = default(false); // Allows any bitrate and uses the first larger bitrate specified parameters

        // Receiviving mode of incoming ethernet frames:
        //   - onStart: receiving on start of frame
        //   - auto: receiving on start frame when module has any subscribers to receptionStart signal, otherwise receiving on end of frame
        //   - onEnd: receiving on end of frame, throws error at end of initialize module when has any subscribers to receptionStart signal
        //   - forceOnEnd: receiving on end of frame, silently skip emit receptionStart signal
        string receptionMode @enum("onStart","auto","onEnd","forceOnEnd") = default("auto");

        int mtu @unit(B) = default(1500B);
        string fcsMode @enum("declared","computed");
        @lifecycleSupport;
        double stopOperationExtraTime @unit(s) = default(-1s);    // Extra time after the lifecycle stop operation finished
        double stopOperationTimeout @unit(s) = default(2s);    // Timeout value for the lifecycle stop operation
        @class(EthernetMacPhy);
        @display("i=block/rxtx");

        @signal[txPk](type=inet::Packet);
        @signal[rxPkOk](type=inet::Packet);
        @signal[txPausePkUnits](type=long);
        @signal[rxPausePkUnits](type=long);
        @signal[rxPkFromHl](type=inet::Packet);
        @signal[packetDropped](type=inet::Packet);
        @signal[packetSentToLower](type=inet::Packet);
        @signal[packetReceivedFromLower](type=inet::Packet);
        @signal[packetSentToUpper](type=inet::Packet);
        @signal[packetReceivedFromUpper](type=inet::Packet);
        @signal[transmissionStateChanged](type=long); // Enum=MacTransmitState
        @signal[receptionStateChanged](type=long); // Enum=MacReceiveState
        @signal[transmissionStarted](type=inet::physicallayer::EthernetSignalBase);
        @signal[transmissionEnded](type=inet::physicallayer::EthernetSignalBase);
        @signal[receptionStarted](type=inet::physicallayer::Signal);
        @signal[receptionEnded](type=inet::physicallayer::Signal);

        @statistic[transmitting](title="transmitting state"; type=int; source=count(transmissionStarted) - count(transmissionEnded); record=vector; interpolationmode=sample-hold);
        @statistic[throughput](title="throughput"; unit=bps; source=throughput(transmissionEnded); record=vector,histogram; interpolationmode=linear);
        @statistic[utilization](title="utilization"; unit=%; source=100 * utilization(count(transmissionStarted) - count(transmissionEnded)); record=vector,histogram; interpolationmode=linear);
        @statistic[txPk](title="packets transmitted"; source=packetSentToLower; 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[packetReceivedFromUpper](title="packet bytes from higher layer"; source=packetReceivedFromUpper; record=count,"sum(packetBytes)","vector(packetBytes)"; interpolationmode=none);
        @statistic[packetDropIncorrectlyReceived](title="packet drop: incorrectly received"; source=packetDropReasonIsIncorrectlyReceived(packetDropped); record=count,sum(packetBytes),vector(packetBytes); interpolationmode=none);
        @statistic[packetDropInterfaceDown](title="packet drop: interface down"; source=packetDropReasonIsInterfaceDown(packetDropped); record=count,sum(packetBytes),vector(packetBytes); interpolationmode=none);
        @statistic[packetDropNotAddressedToUs](title="packet drop: not addressed to us"; source=packetDropReasonIsNotAddressedToUs(packetDropped); record=count,sum(packetBytes),vector(packetBytes); interpolationmode=none);

    gates:
        input upperLayerIn @labels(EtherFrame);    // To ~EthernetEncapsulation or ~IMacRelayUnit
        output upperLayerOut @labels(EtherFrame);  // To ~EthernetEncapsulation or ~IMacRelayUnit
        inout phys @labels(EthernetSignal);        // To the network
}

File: src/inet/linklayer/ethernet/basic/EthernetMacPhy.ned