ethox/
lib.rs

1//! A standalone library for user-space networking and unikernels.
2//!
3//! ## Table of contents
4//!
5//! This is also a recommended reading order but feel free to skip ahead, each chapter tries to be
6//! somewhat self-contained.
7//!
8//! 1. [Highlights](#highlights)
9//! 2. [Design](#design-and-relevant-core-concepts)
10//! 3. [The wire module](wire/index.html)
11//!    1. [Overview of packet representations](wire/index.html#an-overview-over-packet-representations)
12//!    1. [Ethernet](layer/eth/index.html)
13//!    1. [Arp](layer/arp/index.html)
14//!    1. [Ip V4/V6](layer/ip/index.html)
15//!    1. [Udp](layer/udp/index.html)
16//!    1. [Tcp](layer/tcp/index.html)
17//!    1. [Icmp](layer/icmp/index.html)
18//! 4. [The layers](layer/index.html)
19//!    1. [Receiving](layer/index.html#receiving)
20//!    1. [Sending](layer/index.html#sending)
21//!    1. [Answering](layer/index.html#answering)
22//!    1. [The eth layer](layer/eth/index.html)
23//! 5. [Network interfaces](nic/index.html)
24//!    1. [Strucuture of a NIC](#TODO)
25//!    1. [Writing a nic](#TODO)
26//!    1. [Included software implementations](#TODO)
27//! 6. Internals
28//!    1. [The managed module](managed/index.html)
29//!    2. [The storage module](storage/index.html)
30//!
31//! ## Highlights
32//!
33//! The most interesting features in overview:
34//!
35//! * Zero-copy and bufferless TCP (re-)transmission
36//! * Free choice of policy for packet queueing
37//! * Optional tuntap and raw socket adapters with gigabit data rates
38//!
39//! Also, I'm very grateful for @whitequark's [`smoltcp`]. The overall structure may be quite
40//! different but the large portions of the `wire` module wouldn't have been possible without and
41//! lessons learned from studying it were integral to the design.  (Maybe also look at her other
42//! projects if you have the time, very often delightful).
43//!
44//! [`smoltcp`]: https://github.com/m-labs/smoltcp
45//!
46//! ## Design and relevant core concepts
47//!
48//! This library handles network packets with a tree of callbacks. Don't expect builtin socket
49//! interface although such adaptors may be written using the library.
50//!
51//! Nothing within `ethox` *ever* dynamically allocates memory (and there is no arbitrary
52//! recursion). It may call user callbacks where you can *optionally* do so but it is never
53//! required for operating. This may seem restrictive at first but in practice it simply means that
54//! setup code will explicitely pass in preallocated memory to use instead of it being a runtime
55//! choice. The philosophy of upfront, explicitely resource management also extends beyond
56//! allocation. If there is any resource that connections may compete for then it tries to
57//! partition them prior in a way that some minimum share is guaranteed for each or, where this is
58//! not clearly possible, exposes that choice to the caller.
59#![warn(missing_docs)]
60#![warn(unreachable_pub)]
61
62// tests should be able to use `std`
63#![cfg_attr(all(
64    not(feature = "std"),
65    not(test),
66    not(doctest)),
67no_std)]
68
69pub mod nic;
70pub mod layer;
71pub mod managed;
72#[macro_use] mod macros;
73pub mod storage;
74pub mod time;
75pub mod wire;
76
77/// The `alloc` crate, or a replacement without feature `"std"`.
78#[cfg(any(
79    feature = "alloc",
80    test,
81    doctest))]
82pub extern crate alloc;
83
84#[cfg(all(
85    not(feature = "alloc"),
86    not(test),
87    not(doctest)))]
88pub use self::managed::alloc;
ethox/lib.rs

ethox/
lib.rs
