Ethernet.h

Go to the documentation of this file.

//===------------------------------------------------------------*- C++ -*-===//
//
// TEMU: The Terma Emulator
// (c) Terma 2020
// Authors: Mattias Holm <maho (at) terma.com>
//
//===----------------------------------------------------------------------===//
 
#ifndef TEMU_ETHERNET_H
#define TEMU_ETHERNET_H
 
#include "temu-c/Support/Bitmanip.h"
#include "temu-c/Support/Buffer.h"
#include "temu-c/Support/Objsys.h"
 
#include <stdint.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
/*
  The ethernet device interface is EXPERIMENTAL and UNSTABLE at the
  moment.
 
  MAC addresses are 6 bytes, as convention here, we encode these in a
  uint64_t field, where the two MSBs are set to 0. The, MAC address
  will be in host endianess.
 
  Ethernet simulation is based on the transmission of frames. Frames
  do not need to have valid CRCs, but the CRC data bytes should be
  allocated for the frames. This speeds up simulation significantly.
 
  CRC errors can instead be efficiently injected by flipping the
  relevant bit in the flags field.
 
  Ethernet is not a point to point protocol (although in practice,
  these days it is P2P thanks to switches which are collission free),
  but we could immagine some one simulating an ethernet link via coax
  in which case there may be multiple nodes connected to the same
  cable. It is possible to tap the ethernet object by adding an
  ethernet device to it that listens to all addresses (i.e. it
  notifies the bus model about being "promiscuous").
 
  ETH support is split using multiple levels, i.e. a MAC and a PHY
  controller. The PHY controller implements the PHY interface and
  usually also the MII interface (there is a generic MII device that
  can be used which implements both PHY and MII). PHY is used for
  connecting to other PHY controllers, when sending a frame, the MAC
  will (using e.g. DMA) get the frame data, assemble a temu_EthFrame
  and send this to the PHY controller, the PHY controller in turn
  forwards the frame to the destination PHY. In addition, there is an
  MIIBus model which lets a single master control multiple PHY
  devices. The MIIBus model implements the MII interface only and
  simply routes the calls to the correct attached PHY device.
 
  So, the use is typically:
 
    MAC -> PHY -> ETH -> PHY -> MAC
 */
 
// Flag bits
#define TEMU_ETH_CRC_ERR 1
 
#define TEMU_ETH_ETH_CRC_NOT_SET (1 << 1)
#define TEMU_ETH_IP_CRC_NOT_SET (1 << 2)
#define TEMU_ETH_UDP_CRC_NOT_SET (1 << 3)
#define TEMU_ETH_TCP_CRC_NOT_SET (1 << 4)
#define TEMU_ETH_NON_STANDARD_PREAMBLE (1 << 5)
#define TEMU_ETH_PREAMBLE_LENGTH_MASK (0xf << 6)
#define TEMU_ETH_PREAMBLE_LENGTH_SHIFT 6
 
typedef struct {
  uint32_t Flags;       //!< Flags used for error injection
  temu_Buff Data;       //!< ETH frame data
  uint8_t Preamble[15]; //!< Preamble bits, normally 0x[aa aa aa aa aa aa aa]
  uint8_t Sfd;          //!< Start frame delimiter, normally 0xab
} temu_EthFrame;
 
typedef struct temu_PHYIface temu_PHYIface;
typedef struct temu_MACIface temu_MACIface;
typedef struct temu_EthernetIface temu_EthernetIface;
TEMU_IFACE_REFERENCE_TYPE(temu_MAC);
TEMU_IFACE_REFERENCE_TYPE(temu_PHY);
TEMU_IFACE_REFERENCE_TYPE(temu_Ethernet);
 
struct temu_MACIface {
  void (*connected)(
      void *Dev); // Called when link is connected (i.e. cable inserted)
  void (*disconnected)(
      void *Dev); // Called when link is disconnected (i.e. cable removed)
  void (*up)(void *Dev);   // Called when link goes up
  void (*down)(void *Dev); // Called when link goes down
 
  int (*receive)(void *Dev, temu_EthFrame *Frame); // Receive frame
  uint64_t (*getMAC)(void *Dev);                   // Get MAC address
  void (*setMAC)(void *Dev, uint64_t MAC);         // Set MAC address
};
#define TEMU_MAC_IFACE_TYPE "temu::MACIface"
 
struct temu_PHYIface {
  void (*connected)(
      void *Dev,
      temu_EthernetIfaceRef
          Link); // Called when link is connected (i.e. cable inserted)
  void (*disconnected)(
      void *Dev,
      temu_EthernetIfaceRef
          Link); // Called when link is disconnected (i.e. cable removed), note
                 // that the PHY must remove the MACs from the link
  void (*up)(void *Dev);   // Called when link goes up
  void (*down)(void *Dev); // Called when link goes down
 
  int (*send)(void *Dev, temu_EthFrame *Frame);    // Send frame from MAC
  int (*receive)(void *Dev, temu_EthFrame *Frame); // Receive frame
 
  // PHY should clear bits not related to its capabilities in the status and
  // ext status registers
  uint32_t (*autoNegotiate)(void *Obj, uint32_t Caps); // Do auto-negotiatio
  void (*autoNegotiateDone)(void *Obj, uint32_t Caps);
};
#define TEMU_PHY_IFACE_TYPE "temu::PHYIface"
 
// These bits should be transferred using auto-negotiation requests
// Matches MII status reg (reg 1), but needs to be shifted 8 bits up
#define TEMU_ETH_100BASE_T4 (1 << (15 - 8))
#define TEMU_ETH_100BASE_X_FD (1 << (14 - 8))
#define TEMU_ETH_100BASE_X_HD (1 << (13 - 8))
#define TEMU_ETH_10BASE_FD (1 << (12 - 8))
#define TEMU_ETH_10BASE_HD (1 << (11 - 8))
#define TEMU_ETH_100BASE_T2_FD (1 << (10 - 8))
#define TEMU_ETH_100BASE_T2_HD (1 << (9 - 8))
 
// Matches MII extended status register (reg 15)
#define TEMU_ETH_1000BASE_X_FD (1 << 15)
#define TEMU_ETH_1000BASE_X_HD (1 << 14)
#define TEMU_ETH_1000BASE_T_FD (1 << 13)
#define TEMU_ETH_1000BASE_T_HD (1 << 12)
 
// Interface for the actual link, a link can be a switch, hub, or a
// direct connection, note that ETH is not seen as a Point to Point
// connection for the reason of supporting HUBs, splitters etc.
struct temu_EthernetIface {
  void (*connect)(void *Obj,
                  temu_PHYIfaceRef Dev); // Called to connect a device
  void (*disconnect)(void *Obj,
                     temu_PHYIfaceRef Dev); // Called to disconnect link
 
  // Ensure the device receives messages for this MAC address
  // Note, do not forget to add broadcast and multicast bits
  void (*addMAC)(void *Obj, temu_PHYIfaceRef Dev, uint64_t MAC);
  void (*removeMAC)(void *Obj, temu_PHYIfaceRef Dev, uint64_t MAC);
  void (*setPromiscuous)(void *Obj, temu_PHYIfaceRef Dev, int PromiscuousMode);
 
  // Do auto-negotiation, this results in queries on all attached devices
  // that determines the shared link speed
  uint32_t (*autoNegotiate)(void *Obj, uint32_t Caps);
 
  // Send frame to virtual ethernet cable return non zero if frame is
  // accepted, link will route the frame to relevant devices
  int (*send)(void *Obj, temu_EthFrame *Frame);
};
#define TEMU_ETHERNET_IFACE_TYPE "temu::EthernetIface"
 
// I.e. Eth::connect() -> MAC::connected()
// I.e. Phy::send() -> Eth::receive()
 
// MDIO interface
// The MDIO interface is for creating devices connected to an MDIO bus
// or to simulate an MDIO, note that we do not actually
// simulate MDIO per see, but do support mulpiple PHY controllers to
// be attached to the same bus.
typedef struct {
  // The readReg returns negative if the call failed, it can fail if
  // the access is to a bus and the PHY_ID is invalid or if the
  // address is invalid. A successful means that the result can be
  // safely be converted to a uint16_t.
  int32_t (*readReg)(void *Obj, unsigned PHY_ID, uint16_t Addr);
  int (*writeReg)(void *Obj, unsigned PHY_ID, uint16_t Addr, uint16_t Value);
} temu_MDIOIface;
#define TEMU_MDIO_IFACE_TYPE "temu::MDIOIface"
TEMU_IFACE_REFERENCE_TYPE(temu_MDIO);
 
// Interface for adding a delay object in the connection
// between eth link and eth device
struct temu_EthDelayIface {
  void (*addDelay)(temu_Object *link, temu_Object *device, temu_Object *delay,
      double seconds); // Called to connect a delay object
};
#define TEMU_ETH_DELAY_IFACE_TYPE "temu::EthDelayIface"
 
#define TEMU_ETH_MIN_PAYLOAD 46
#define TEMU_ETH_MAX_PAYLOAD 1500
#define TEMU_ETH_LAYER1_HEADER_LENGTH (7 + 1 + 12 + 2)
#define TEMU_ETH_LAYER2_HEADER_LENGTH (6 + 6 + 2)
#define TEMU_ETH_CRC_LENGTH 4
#define TEMU_ETH_INTERPACKET_GAP 12
#define TEMU_ETH_PAYLOAD_OFFSET (6 + 6 + 2)
#define TEMU_ETH_MAX_FRAME_LENGTH 1518
#define TEMU_ETH_802_1Q_TAG_BYTES 4
#define TEMU_ETH_802_1Q_MAX_FRAME_LENGTH 1522
 
// An assortment of ethertype constants, non exhaustive.
// See: https://www.iana.org/assignments/ieee-802-numbers/ieee-802-numbers.xhtml
// for a more complete list.
#define TEMU_ETHTYPE_IPV4 0x0800
#define TEMU_ETHTYPE_ARP 0x0806
#define TEMU_ETHTYPE_WAKE_ON_LAN 0x0842
#define TEMU_ETHTYPE_SRP 0x22ea
#define TEMU_ETHTYPE_RARP 0x8035
#define TEMU_ETHTYPE_802_1Q 0x8100
#define TEMU_ETHTYPE_IPV6 0x86dd
#define TEMU_ETHTYPE_PTP 0x88f7
#define TEMU_ETHTYPE_TTE_CTRL 0x891d
 
// Note, this excludes 802.1Q field
#define TEMU_ETH_IPV4_VERS_IHL_OFFSET (TEMU_ETH_PAYLOAD_OFFSET + 0)
#define TEMU_ETH_IPV4_DSCP_ECN_OFFSET (TEMU_ETH_PAYLOAD_OFFSET + 1)
#define TEMU_ETH_IPV4_TOTAL_LENGTH_OFFSET (TEMU_ETH_PAYLOAD_OFFSET + 2)
#define TEMU_ETH_IPV4_FRAGMENTATION_INFO_OFFSET (TEMU_ETH_PAYLOAD_OFFSET + 6)
#define TEMU_ETH_IPV4_TTL_OFFSET (TEMU_ETH_PAYLOAD_OFFSET + 8)
#define TEMU_ETH_IPV4_PROTOCOL_OFFSET (TEMU_ETH_PAYLOAD_OFFSET + 9)
#define TEMU_ETH_IPV4_CRC_OFFSET (TEMU_ETH_PAYLOAD_OFFSET + 10)
#define TEMU_ETH_IPV4_SRC_IP_OFFSET (TEMU_ETH_PAYLOAD_OFFSET + 12)
#define TEMU_ETH_IPV4_DST_IP_OFFSET (TEMU_ETH_PAYLOAD_OFFSET + 16)
 
#define TEMU_IP_PROT_TCP 0x06
#define TEMU_IP_PROT_UDP 0x11
 
// Relative to start of TCP/UDP headers
#define TEMU_TCP_CRC_OFFSET 16
#define TEMU_UDP_CRC_OFFSET 6
 
static inline uint64_t
temu_ethGetDestMAC(temu_EthFrame *Frame)
{
  uint64_t MAC = 0;
  const uint8_t *Data = temu_buffReadableData(&Frame->Data);
 
  for (int i = 0; i < 6; ++i) {
    MAC <<= 8;
    MAC |= Data[i];
  }
  return MAC;
}
 
static inline uint64_t
temu_ethGetSourceMAC(temu_EthFrame *Frame)
{
  uint64_t MAC = 0;
  const uint8_t *Data = temu_buffReadableData(&Frame->Data);
 
  for (int i = 6; i < 12; ++i) {
    MAC <<= 8;
    MAC |= Data[i];
  }
  return MAC;
}
 
/*!
 * Get length / EtherType field.
 * By ethernet standard, the size field which is 16 bit, will be a length if it
 * is <= 1500 and an ethertype tag if it is >= 1536.
 */
static inline uint16_t
temu_ethGetEthTypeSizeField(temu_EthFrame *Frame)
{
  uint16_t Size = 0;
  const uint8_t *Data = temu_buffReadableData(&Frame->Data);
 
  for (int i = 12; i < 14; ++i) {
    Size <<= 8;
    Size |= Data[i];
  }
 
  if (Size == TEMU_ETHTYPE_802_1Q) {
    Size = 0;
    for (int i = 12 + TEMU_ETH_802_1Q_TAG_BYTES;
         i < 14 + TEMU_ETH_802_1Q_TAG_BYTES; ++i) {
      Size <<= 8;
      Size |= Data[i];
    }
  }
 
  return Size;
}
 
static inline bool
temu_ethIs8021Q(temu_EthFrame *Frame)
{
  uint16_t TagStart = 0;
  const uint8_t *Data = temu_buffReadableData(&Frame->Data);
 
  for (int i = 12; i < 14; ++i) {
    TagStart <<= 8;
    TagStart |= Data[i];
  }
 
  return TagStart == TEMU_ETHTYPE_802_1Q;
}
 
static inline uint16_t
temu_eth8021QTagBytes(temu_EthFrame *Frame)
{
  return temu_ethIs8021Q(Frame) ? TEMU_ETH_802_1Q_TAG_BYTES : 0;
}
 
static inline uint16_t
temu_ethGetLength(temu_EthFrame *Frame)
{
  // Should compute number of bits / bytes for the whole frame
  // including headers
  return temu_buffLen(&Frame->Data);
}
 
/*!
 * Get a readable pointer to the payload.
 * Note that the first bytes will often be an LLC header, it may not be your
 * actual data payload.
 */
static inline const uint8_t *
temu_ethGetPayload(temu_EthFrame *Frame)
{
  const uint8_t *Data = temu_buffReadableData(&Frame->Data);
  return &Data[TEMU_ETH_PAYLOAD_OFFSET + temu_eth8021QTagBytes(Frame)];
}
 
// Return actual payload size (including padding)
static inline const uint16_t
temu_ethGetPayloadAndPaddingSize(temu_EthFrame *Frame)
{
  return temu_ethGetLength(Frame) - TEMU_ETH_PAYLOAD_OFFSET -
         TEMU_ETH_CRC_LENGTH - temu_eth8021QTagBytes(Frame);
}
 
#define ETH_BCAST_ADDR UINT64_C(0xffffffffffff)
 
static inline int
temu_ethIsBroadcastFrame(temu_EthFrame *Frame)
{
  uint64_t MAC = temu_ethGetDestMAC(Frame);
  if (MAC == ETH_BCAST_ADDR) {
    return 1;
  }
 
  return 0;
}
 
// Return 1 if frame is multicast (OR BROADCAST)
static inline int
temu_ethIsMulticastFrame(temu_EthFrame *Frame)
{
  const uint8_t *Data = temu_buffReadableData(&Frame->Data);
 
  if (Data[0] & 1)
    return 1;
  return 0;
}
 
// Len field specify ethertype if larger or equal to this value
#define ETH_ETHERTYPE_MIN 1536
 
#define ETH_CRC_MAGIC 0xC704DD7B
#define ETH_CRC_POLY_NORM 0x04C11DB7
#define ETH_CRC_POLY_REV 0xEDB88320
#define ETH_CRC_POLY_REV_RECIP 0x82608EDB
 
#define ETH_CRC_POLY_LE 0xedb88320
#define ETH_CRC_POLY_BE 0x04c11db6
 
#ifdef __cplusplus
}
#endif
#endif /* !TEMU_ETHERNET_H */