Lib.rs

A standalone library for user-space networking and unikernels.

Table of contents

This is also a recommended reading order but feel free to skip ahead, each chapter tries to be somewhat self-contained.

1. Highlights
2. Design
3. The wire module
   1. Overview of packet representations
   2. Ethernet
   3. Arp
   4. Ip V4/V6
   5. Udp
   6. Tcp
   7. Icmp
4. The layers
   1. Receiving
   2. Sending
   3. Answering
   4. The eth layer
5. Network interfaces
   1. Strucuture of a NIC
   2. Writing a nic
   3. Included software implementations
6. Internals
   1. The managed module
   2. The storage module

Highlights

The most interesting features in overview:

• Zero-copy and bufferless TCP (re-)transmission
• Free choice of policy for packet queueing
• Optional tuntap and raw socket adapters with gigabit data rates

Also, I'm very grateful for @whitequark's smoltcp. The overall structure may be quite different but the large portions of the wire module wouldn't have been possible without and lessons learned from studying it were integral to the design. (Maybe also look at her other projects if you have the time, very often delightful).

Design and relevant core concepts

This library handles network packets with a tree of callbacks. Don't expect builtin socket interface although such adaptors may be written using the library.

Nothing within ethox ever dynamically allocates memory (and there is no arbitrary recursion). It may call user callbacks where you can optionally do so but it is never required for operating. This may seem restrictive at first but in practice it simply means that setup code will explicitely pass in preallocated memory to use instead of it being a runtime choice. The philosophy of upfront, explicitely resource management also extends beyond allocation. If there is any resource that connections may compete for then it tries to partition them prior in a way that some minimum share is guaranteed for each or, where this is not clearly possible, exposes that choice to the caller.