API.md

wolfIP API Documentation

Overview

wolfIP is a minimal TCP/IP stack designed for resource-constrained embedded systems. It features zero dynamic memory allocation, using pre-allocated buffers and a fixed number of concurrent sockets.

Key Features

• No dynamic memory allocation
• Fixed number of concurrent sockets
• Pre-allocated buffers for packet processing
• BSD-like non-blocking socket API with callbacks
• Protocol Support:
  • ARP (RFC 826)
  • IPv4 (RFC 791)
  • ICMP (RFC 792) - ping replies only
  • DHCP (RFC 2131) - client only
  • DNS (RFC 1035) - client only
  • UDP (RFC 768) - unicast only
  • TCP (RFC 793) with options (Timestamps, MSS)

Core Data Structures

Device Driver Interface

struct wolfIP_ll_dev {
    uint8_t mac[6];          // Device MAC address
    char ifname[16];         // Interface name
    uint8_t non_ethernet;    // L3-only link (no Ethernet header/ARP when set)
    uint32_t mtu;            // Optional internal frame budget, defaults to LINK_MTU
    int (*poll)(struct wolfIP_ll_dev *ll, void *buf, uint32_t len);  // Receive function
    int (*send)(struct wolfIP_ll_dev *ll, void *buf, uint32_t len);  // Transmit function
};

wolfIP maintains an array of these descriptors sized by WOLFIP_MAX_INTERFACES (default 1). Call wolfIP_getdev_ex() to access a specific slot; the legacy wolfIP_getdev() helper targets the first hardware slot (index 0 normally, or 1 when the optional loopback interface is enabled).

When non_ethernet is set, the interface is treated as L3-only point-to-point: the stack skips ARP/neighbor resolution, omits Ethernet headers on transmit, and expects receive buffers to begin at the IP header. The mtu field still describes wolfIP's internal frame budget including Ethernet headroom, so on non-Ethernet links the payload passed to ll->send() is effectively capped at mtu - ETH_HEADER_LEN on Ethernet-enabled builds.

IP Configuration

struct ipconf {
    struct wolfIP_ll_dev *ll;           // Link layer device
    ip4 ip;                  // IPv4 address
    ip4 mask;                // Subnet mask
    ip4 gw;                  // Default gateway
};

Each struct wolfIP instance owns WOLFIP_MAX_INTERFACES ipconf entries—one per link-layer slot. Use the _ex helpers to read or update a specific interface; the legacy accessors operate on the first hardware interface (index 0 unless loopback support is compiled in).

If WOLFIP_ENABLE_FORWARDING is set to 1 at compile time, the stack performs simple IPv4 forwarding between interfaces. Packets received on one interface whose destinations match another configured interface are re-sent with the IP TTL decreased by one (or an ICMP TTL-exceeded response if the TTL would drop to zero).

Enabling WOLFIP_ENABLE_LOOPBACK (requires WOLFIP_MAX_INTERFACES > 1) creates an internal loopback device at index 0 with the fixed address 127.0.0.1/8. Traffic sent to that address is reflected back through the stack so local sockets, pings, and other services behave as they would on a standard loopback interface; the first hardware interface then shifts to index 1 for legacy helpers.

Socket Address Structures

struct wolfIP_sockaddr_in {
    uint16_t sin_family;     // Address family (AF_INET)
    uint16_t sin_port;       // Port number
    struct sin_addr {
        uint32_t s_addr;     // IPv4 address
    } sin_addr;
};

struct wolfIP_sockaddr {
    uint16_t sa_family;      // Address family
};

Socket Interface Functions

Socket Creation and Control

int wolfIP_sock_socket(struct wolfIP *s, int domain, int type, int protocol);

Creates a new socket.

• Parameters:
  • s: wolfIP instance
  • domain: Address family (AF_INET)
  • type: Socket type (SOCK_STREAM/SOCK_DGRAM)
  • protocol: Protocol (usually 0)
• Returns: Socket descriptor or negative error code

int wolfIP_sock_bind(struct wolfIP *s, int sockfd, const struct wolfIP_sockaddr *addr, socklen_t addrlen);

Binds a socket to a local address.

• Parameters:
  • s: wolfIP instance
  • sockfd: Socket descriptor
  • addr: Local address to bind to
  • addrlen: Length of address structure
• Returns: 0 on success, negative error code on failure

int wolfIP_sock_listen(struct wolfIP *s, int sockfd, int backlog);

Marks a socket as passive (listening for connections).

• Parameters:
  • s: wolfIP instance
  • sockfd: Socket descriptor
  • backlog: Maximum length of pending connections queue
• Returns: 0 on success, negative error code on failure

Connection Management

int wolfIP_sock_connect(struct wolfIP *s, int sockfd, const struct wolfIP_sockaddr *addr, socklen_t addrlen);

Initiates a connection on a socket.

• Parameters:
  • s: wolfIP instance
  • sockfd: Socket descriptor
  • addr: Address to connect to
  • addrlen: Length of address structure
• Returns: 0 on success, negative error code on failure

int wolfIP_sock_accept(struct wolfIP *s, int sockfd, struct wolfIP_sockaddr *addr, socklen_t *addrlen);

Accepts a connection on a listening socket.

• Parameters:
  • s: wolfIP instance
  • sockfd: Listening socket descriptor
  • addr: Address of connecting peer
  • addrlen: Length of address structure
• Returns: New socket descriptor or negative error code

Data Transfer

int wolfIP_sock_send(struct wolfIP *s, int sockfd, const void *buf, size_t len, int flags);
int wolfIP_sock_recv(struct wolfIP *s, int sockfd, void *buf, size_t len, int flags);

Send/receive data on a connected socket.

• Parameters:
  • s: wolfIP instance
  • sockfd: Socket descriptor
  • buf: Data buffer
  • len: Buffer length
  • flags: Operation flags
• Returns: Number of bytes transferred or negative error code

int wolfIP_sock_sendto(struct wolfIP *s, int sockfd, const void *buf, size_t len, int flags, const struct wolfIP_sockaddr *dest_addr, socklen_t addrlen);
int wolfIP_sock_recvfrom(struct wolfIP *s, int sockfd, void *buf, size_t len, int flags, struct wolfIP_sockaddr *src_addr, socklen_t *addrlen);

Send/receive data on a datagram socket.

• Parameters similar to send/recv with additional address parameters

Stack Interface Functions

void wolfIP_init(struct wolfIP *s);

Initializes the TCP/IP stack.

• Parameters:
  • s: wolfIP instance to initialize

void wolfIP_init_static(struct wolfIP **s);

Initializes a static wolfIP instance.

• Parameters:
  • s: Pointer to wolfIP instance pointer

size_t wolfIP_instance_size(void);

Returns the size (in bytes) required to store a struct wolfIP. Use this when allocating stacks from custom memory managers.

int wolfIP_poll(struct wolfIP *s, uint64_t now);

Processes pending network events.

• Parameters:
  • s: wolfIP instance
  • now: Current timestamp
• Returns: Number of events processed

void wolfIP_recv(struct wolfIP *s, void *buf, uint32_t len);
void wolfIP_recv_ex(struct wolfIP *s, unsigned int if_idx, void *buf, uint32_t len);

Pass inbound frames to the stack. _ex allows the caller to specify which interface slot produced the frame.

void wolfIP_ipconfig_set(struct wolfIP *s, ip4 ip, ip4 mask, ip4 gw);
void wolfIP_ipconfig_get(struct wolfIP *s, ip4 *ip, ip4 *mask, ip4 *gw);

Set/get IP configuration.

• Parameters:
  • s: wolfIP instance
  • ip: IPv4 address
  • mask: Subnet mask
  • gw: Default gateway

void wolfIP_ipconfig_set_ex(struct wolfIP *s, unsigned int if_idx, ip4 ip, ip4 mask, ip4 gw);
void wolfIP_ipconfig_get_ex(struct wolfIP *s, unsigned int if_idx, ip4 *ip, ip4 *mask, ip4 *gw);

Per-interface versions of the IP configuration helpers. The legacy functions target interface 0.

struct wolfIP_ll_dev *wolfIP_getdev(struct wolfIP *s);
struct wolfIP_ll_dev *wolfIP_getdev_ex(struct wolfIP *s, unsigned int if_idx);
int wolfIP_mtu_set(struct wolfIP *s, unsigned int if_idx, uint32_t mtu);
int wolfIP_mtu_get(struct wolfIP *s, unsigned int if_idx, uint32_t *mtu);

Access the link-layer descriptor(s) that should be wired to hardware drivers. _ex returns NULL if if_idx exceeds WOLFIP_MAX_INTERFACES. wolfIP_mtu_set() updates the effective per-interface MTU, treating 0 as the default LINK_MTU and clamping to [LINK_MTU_MIN, LINK_MTU]. wolfIP_mtu_get() returns the effective MTU currently used by the stack. For non_ethernet devices this value remains the internal frame budget; the maximum IP bytes handed to the driver are reduced by ETH_HEADER_LEN when Ethernet support is compiled in.

• Returns: wolfIP_getdev()/wolfIP_getdev_ex() return a pointer to the link-layer descriptor or NULL on invalid interface index; wolfIP_mtu_set() returns 0 on success or a negative error code on failure; wolfIP_mtu_get() returns 0 on success or a negative error code on failure and stores the effective MTU in *mtu.

DHCP Client Functions

int dhcp_client_init(struct wolfIP *s);

Initializes DHCP client.

• Parameters:
  • s: wolfIP instance
• Returns: 0 on success, negative error code on failure

int dhcp_bound(struct wolfIP *s);

Checks if DHCP client is bound.

• Parameters:
  • s: wolfIP instance
• Returns: 1 if bound, 0 otherwise

DNS Client Functions

int nslookup(struct wolfIP *s, const char *name, uint16_t *id, void (*lookup_cb)(uint32_t ip));

Performs DNS lookup.

• Parameters:
  • s: wolfIP instance
  • name: Hostname to resolve
  • id: Transaction ID
  • lookup_cb: Callback function for result
• Returns: 0 on success, negative error code on failure

Utility Functions

uint32_t atou(const char *s);

Converts ASCII string to unsigned integer.

ip4 atoip4(const char *ip);

Converts dotted decimal IP address string to 32-bit integer.

void iptoa(ip4 ip, char *buf);

Converts 32-bit IP address to dotted decimal string.

Event Callback Registration

void wolfIP_register_callback(struct wolfIP *s, int sock_fd, void (*cb)(int sock_fd, uint16_t events, void *arg), void *arg);

Registers event callback for a socket.

• Parameters:
  • s: wolfIP instance
  • sock_fd: Socket descriptor
  • cb: Callback function
  • arg: User data for callback

Event flags:

• CB_EVENT_READABLE (0x01): Data available or connection accepted
• CB_EVENT_TIMEOUT (0x02): Operation timed out
• CB_EVENT_WRITABLE (0x04): Connected or space available to send
• CB_EVENT_CLOSED (0x10): Connection closed by peer