Skip to content

File syn_eth.h

FileList > net > syn_eth.h

Go to the source code of this file

Zero-Heap Native Ethernet II & ARP Protocol Engine. More...

  • #include "syntropic/common/syn_defs.h"
  • #include <stdbool.h>
  • #include <stddef.h>
  • #include <stdint.h>
  • #include "port/syn_port_eth.h"
  • #include "syntropic/pt/syn_pt.h"

Classes

Type Name
struct SYN_ETH
struct SYN_ETH_ArpEntry
struct SYN_ETH_Header

Public Functions

Type Name
SYN_Status syn_eth_arp_lookup (SYN_ETH * eth, uint32_t ip, uint8_t mac_out)
Lookup MAC address in local ARP cache table.
SYN_Status syn_eth_arp_update (SYN_ETH * eth, uint32_t ip, const uint8_t mac)
Update or insert an entry into the local ARP cache table.
SYN_Status syn_eth_build_frame (SYN_ETH * eth, const uint8_t dst_mac, uint16_t ethertype, const uint8_t * payload, size_t payload_len, uint8_t * frame_out, size_t * frame_len)
Build and transmit an outbound Ethernet II frame.
SYN_Status syn_eth_generate_mac (const void * uid_bytes, size_t uid_len, uint8_t mac_out)
Generate a deterministic Locally Administered MAC address from MCU Unique ID.
struct SYN_ICMP * syn_eth_get_icmp_instance (void)
Weak hook — override to inject an ICMP engine into the Ethernet dispatcher.
struct SYN_TCP * syn_eth_get_tcp_instance (void)
Weak hook — override to inject a TCP engine into the Ethernet dispatcher.
SYN_Status syn_eth_init (SYN_ETH * eth, const uint8_t mac_addr, uint32_t ip_addr)
Initialize Native Ethernet Engine.
size_t syn_eth_pack_header (uint8_t * buf, size_t buf_size, const uint8_t dst_mac, const uint8_t src_mac, uint16_t ethertype)
Pack Ethernet II Header (14 bytes) into target buffer.
SYN_Status syn_eth_process_frame (SYN_ETH * eth, const uint8_t * frame, size_t len, uint8_t * tx_buf, size_t * tx_len)
Process incoming Ethernet II frame.
uint16_t syn_ip_checksum (const void * buf, size_t len)
Calculate 16-bit Internet Checksum (RFC 1071) over buffer.
size_t syn_ip_pack_header (uint8_t * buf, size_t buf_size, uint32_t src_ip, uint32_t dst_ip, uint8_t proto, uint16_t payload_len, uint16_t id)
Pack standard 20-byte IPv4 Header into target buffer.

Macros

Type Name
define PT_ETH_WAIT_ARP (pt, eth, target_ip, mac_out) [**PT\_WAIT\_UNTIL**](syn__pt_8h.md#define-pt_wait_until)(pt, [**syn\_eth\_arp\_lookup**](syn__eth_8c.md#function-syn_eth_arp_lookup)((eth), (target\_ip), (mac\_out)) == SYN\_OK)
Block a protothread coroutine until an IP is resolved in the local ARP cache.
define PT_ETH_WAIT_FRAME (pt, rx_buf, max_len, rx_len) [**PT\_WAIT\_UNTIL**](syn__pt_8h.md#define-pt_wait_until)(pt, [**syn\_port\_eth\_rx**](syn__port__eth_8h.md#function-syn_port_eth_rx)((rx\_buf), (max\_len), (rx\_len)) == SYN\_OK)
Block a protothread coroutine until a raw Ethernet frame is received from PHY.
define SYN_ARP_OP_REPLY 2U
define SYN_ARP_OP_REQUEST 1U
define SYN_ETHTYPE_ARP 0x0806U
define SYN_ETHTYPE_ETHERCAT 0x88A4U
define SYN_ETHTYPE_IPV4 0x0800U
define SYN_ETHTYPE_IPV6 0x86DDU
define SYN_ETH_ARP_CACHE_SIZE 8U
define SYN_ETH_HEADER_LEN 14U
define SYN_ETH_MAC_LEN 6U
define SYN_ETH_MAX_FRAME_LEN 1514U
define SYN_ETH_MIN_FRAME_LEN 60U

Detailed Description

Specifications: * Ethernet II Header: [Dst MAC 6B] + [Src MAC 6B] + [EtherType 2B] * Minimum Frame Size: 60 bytes (padded with zeros if payload < 46B) * Maximum Frame Size: 1514 bytes (excluding 4B FCS) * EtherTypes: * 0x0806: ARP (Address Resolution Protocol) * 0x0800: IPv4 (Internet Protocol v4) * 0x86DD: IPv6 (Internet Protocol v6) * 0x88A4: EtherCAT Industrial Ethernet

Public Functions Documentation

function syn_eth_arp_lookup

Lookup MAC address in local ARP cache table. 

SYN_Status syn_eth_arp_lookup (
    SYN_ETH * eth,
    uint32_t ip,
    uint8_t mac_out
)

Parameters:

  • eth Pointer to Ethernet instance.
  • ip 32-bit IPv4 address to lookup.
  • mac_out Output buffer (6 bytes) to receive resolved MAC.

Returns:

SYN_OK if IP found in cache, SYN_NOT_FOUND if absent.

function syn_eth_arp_update

Update or insert an entry into the local ARP cache table. 

SYN_Status syn_eth_arp_update (
    SYN_ETH * eth,
    uint32_t ip,
    const uint8_t mac
)

Parameters:

  • eth Pointer to Ethernet instance.
  • ip 32-bit IPv4 address.
  • mac Resolved 6-byte MAC address.

Returns:

SYN_OK on success.

function syn_eth_build_frame

Build and transmit an outbound Ethernet II frame. 

SYN_Status syn_eth_build_frame (
    SYN_ETH * eth,
    const uint8_t dst_mac,
    uint16_t ethertype,
    const uint8_t * payload,
    size_t payload_len,
    uint8_t * frame_out,
    size_t * frame_len
)

Parameters:

  • eth Pointer to Ethernet instance.
  • dst_mac Destination MAC address (6 bytes).
  • ethertype EtherType value (e.g. SYN_ETHTYPE_IPV4).
  • payload Pointer to payload buffer.
  • payload_len Payload byte length.
  • frame_out Output frame buffer (must hold at least 1514 bytes).
  • frame_len Pointer to receive final raw Ethernet frame length.

Returns:

SYN_OK on success.

function syn_eth_generate_mac

Generate a deterministic Locally Administered MAC address from MCU Unique ID. 

SYN_Status syn_eth_generate_mac (
    const void * uid_bytes,
    size_t uid_len,
    uint8_t mac_out
)

Parameters:

  • uid_bytes Pointer to hardware unique ID bytes (e.g. STM32 96-bit UID).
  • uid_len Length of unique ID in bytes.
  • mac_out Output buffer to receive generated 6-byte MAC address.

Returns:

SYN_OK on success.

function syn_eth_get_icmp_instance

Weak hook — override to inject an ICMP engine into the Ethernet dispatcher. 

struct SYN_ICMP * syn_eth_get_icmp_instance (
    void
)

When syn_eth_process_frame receives an IPv4/ICMP packet (protocol 1), it calls this to obtain the ICMP instance. Return NULL to silently drop.

Returns:

Pointer to SYN_ICMP instance, or NULL.

function syn_eth_get_tcp_instance

Weak hook — override to inject a TCP engine into the Ethernet dispatcher. 

struct SYN_TCP * syn_eth_get_tcp_instance (
    void
)

When syn_eth_process_frame receives an IPv4/TCP packet (protocol 6), it calls this to obtain the TCP instance. Return NULL to silently drop.

Returns:

Pointer to SYN_TCP instance, or NULL.

function syn_eth_init

Initialize Native Ethernet Engine. 

SYN_Status syn_eth_init (
    SYN_ETH * eth,
    const uint8_t mac_addr,
    uint32_t ip_addr
)

Parameters:

  • eth Pointer to Ethernet instance.
  • mac_addr 6-byte hardware MAC address.
  • ip_addr 32-bit IPv4 address (host byte order).

Returns:

SYN_OK on success.

function syn_eth_pack_header

Pack Ethernet II Header (14 bytes) into target buffer. 

size_t syn_eth_pack_header (
    uint8_t * buf,
    size_t buf_size,
    const uint8_t dst_mac,
    const uint8_t src_mac,
    uint16_t ethertype
)

Parameters:

  • buf Output destination buffer.
  • buf_size Destination buffer capacity.
  • dst_mac Destination 6-byte MAC address.
  • src_mac Source 6-byte MAC address.
  • ethertype 16-bit EtherType (host byte order).

Returns:

Bytes written (14) on success, 0 on invalid param / insufficient buffer.

function syn_eth_process_frame

Process incoming Ethernet II frame. 

SYN_Status syn_eth_process_frame (
    SYN_ETH * eth,
    const uint8_t * frame,
    size_t len,
    uint8_t * tx_buf,
    size_t * tx_len
)

Parameters:

  • eth Pointer to Ethernet instance.
  • frame Pointer to raw frame bytes.
  • len Frame byte length (60..1514 bytes).
  • tx_buf Output buffer to receive immediate ARP reply if generated.
  • tx_len Pointer to receive ARP reply byte length (0 if no reply needed).

Returns:

SYN_OK on success.

function syn_ip_checksum

Calculate 16-bit Internet Checksum (RFC 1071) over buffer. 

uint16_t syn_ip_checksum (
    const void * buf,
    size_t len
)

Parameters:

  • buf Pointer to buffer.
  • len Buffer byte length.

Returns:

16-bit one's complement checksum.

function syn_ip_pack_header

Pack standard 20-byte IPv4 Header into target buffer. 

size_t syn_ip_pack_header (
    uint8_t * buf,
    size_t buf_size,
    uint32_t src_ip,
    uint32_t dst_ip,
    uint8_t proto,
    uint16_t payload_len,
    uint16_t id
)

Parameters:

  • buf Output destination buffer.
  • buf_size Destination buffer capacity.
  • src_ip Source IPv4 address (host byte order).
  • dst_ip Destination IPv4 address (host byte order).
  • proto IP Protocol number (1=ICMP, 2=IGMP, 6=TCP, 17=UDP).
  • payload_len Payload byte length after IPv4 header.
  • id 16-bit IP identification field.

Returns:

Bytes written (20) on success, 0 on invalid param / insufficient buffer.

Macro Definition Documentation

define PT_ETH_WAIT_ARP

Block a protothread coroutine until an IP is resolved in the local ARP cache. 

#define PT_ETH_WAIT_ARP (
    pt,
    eth,
    target_ip,
    mac_out
) `PT_WAIT_UNTIL (pt, syn_eth_arp_lookup ((eth), (target_ip), (mac_out)) == SYN_OK )`

Parameters:

  • pt Protothread context.
  • eth Pointer to Ethernet instance.
  • target_ip Target IPv4 address.
  • mac_out Output buffer (6 bytes).

define PT_ETH_WAIT_FRAME

Block a protothread coroutine until a raw Ethernet frame is received from PHY. 

#define PT_ETH_WAIT_FRAME (
    pt,
    rx_buf,
    max_len,
    rx_len
) `PT_WAIT_UNTIL (pt, syn_port_eth_rx ((rx_buf), (max_len), (rx_len)) == SYN_OK )`

Parameters:

  • pt Protothread context.
  • rx_buf Buffer to receive frame.
  • max_len Capacity.
  • rx_len Pointer to receive length.

define SYN_ARP_OP_REPLY

#define SYN_ARP_OP_REPLY `2U`

ARP Operation: Reply (2)

define SYN_ARP_OP_REQUEST

#define SYN_ARP_OP_REQUEST `1U`

ARP Operation: Request (1)

define SYN_ETHTYPE_ARP

#define SYN_ETHTYPE_ARP `0x0806U`

EtherType for ARP packets (0x0806)

define SYN_ETHTYPE_ETHERCAT

#define SYN_ETHTYPE_ETHERCAT `0x88A4U`

EtherType for EtherCAT frames (0x88A4)

define SYN_ETHTYPE_IPV4

#define SYN_ETHTYPE_IPV4 `0x0800U`

EtherType for IPv4 packets (0x0800)

define SYN_ETHTYPE_IPV6

#define SYN_ETHTYPE_IPV6 `0x86DDU`

EtherType for IPv6 packets (0x86DD)

define SYN_ETH_ARP_CACHE_SIZE

#define SYN_ETH_ARP_CACHE_SIZE `8U`

Default ARP cache table capacity

define SYN_ETH_HEADER_LEN

#define SYN_ETH_HEADER_LEN `14U`

Ethernet II header length in bytes

define SYN_ETH_MAC_LEN

#define SYN_ETH_MAC_LEN `6U`

Ethernet MAC address length in bytes

define SYN_ETH_MAX_FRAME_LEN

#define SYN_ETH_MAX_FRAME_LEN `1514U`

Maximum standard Ethernet frame length

define SYN_ETH_MIN_FRAME_LEN

#define SYN_ETH_MIN_FRAME_LEN `60U`

Minimum Ethernet frame length with padding

The documentation for this class was generated from the following file src/syntropic/net/syn_eth.h