smoltcp/
lib.rs

1#![cfg_attr(not(any(test, feature = "std")), no_std)]
2#![deny(unsafe_code)]
3
4//! The _smoltcp_ library is built in a layered structure, with the layers corresponding
5//! to the levels of API abstraction. Only the highest layers would be used by a typical
6//! application; however, the goal of _smoltcp_ is not just to provide a simple interface
7//! for writing applications but also to be a toolbox of networking primitives, so
8//! every layer is fully exposed and documented.
9//!
10//! When discussing networking stacks and layering, often the [OSI model][osi] is invoked.
11//! _smoltcp_ makes no effort to conform to the OSI model as it is not applicable to TCP/IP.
12//!
13//! # The socket layer
14//! The socket layer APIs are provided in the module [socket](socket/index.html); currently,
15//! raw, ICMP, TCP, and UDP sockets are provided. The socket API provides the usual primitives,
16//! but necessarily differs in many from the [Berkeley socket API][berk], as the latter was
17//! not designed to be used without heap allocation.
18//!
19//! The socket layer provides the buffering, packet construction and validation, and (for
20//! stateful sockets) the state machines, but it is interface-agnostic. An application must
21//! use sockets together with a network interface.
22//!
23//! # The interface layer
24//! The interface layer APIs are provided in the module [iface](iface/index.html); currently,
25//! Ethernet interface is provided.
26//!
27//! The interface layer handles the control messages, physical addressing and neighbor discovery.
28//! It routes packets to and from sockets.
29//!
30//! # The physical layer
31//! The physical layer APIs are provided in the module [phy](phy/index.html); currently,
32//! raw socket and TAP interface are provided. In addition, two _middleware_ interfaces
33//! are provided: the _tracer device_, which prints a human-readable representation of packets,
34//! and the _fault injector device_, which randomly introduces errors into the transmitted
35//! and received packet sequences.
36//!
37//! The physical layer handles interaction with a platform-specific network device.
38//!
39//! # The wire layers
40//! Unlike the higher layers, the wire layer APIs will not be used by a typical application.
41//! They however are the bedrock of _smoltcp_, and everything else is built on top of them.
42//!
43//! The wire layer APIs are designed by the principle "make illegal states ir-representable".
44//! If a wire layer object can be constructed, then it can also be parsed from or emitted to
45//! a lower level.
46//!
47//! The wire layer APIs also provide _tcpdump_-like pretty printing.
48//!
49//! ## The representation layer
50//! The representation layer APIs are provided in the module [wire].
51//!
52//! The representation layer exists to reduce the state space of raw packets. Raw packets
53//! may be nonsensical in a multitude of ways: invalid checksums, impossible combinations of flags,
54//! pointers to fields out of bounds, meaningless options... Representations shed all that,
55//! as well as any features not supported by _smoltcp_.
56//!
57//! ## The packet layer
58//! The packet layer APIs are also provided in the module [wire].
59//!
60//! The packet layer exists to provide a more structured way to work with packets than
61//! treating them as sequences of octets. It makes no judgement as to content of the packets,
62//! except where necessary to provide safe access to fields, and strives to implement every
63//! feature ever defined, to ensure that, when the representation layer is unable to make sense
64//! of a packet, it is still logged correctly and in full.
65//!
66//! # Minimum Supported Rust Version (MSRV)
67//!
68//! This crate is guaranteed to compile on stable Rust 1.80 and up with any valid set of features.
69//! It *might* compile on older versions but that may change in any new patch release.
70//!
71//! The exception is when using the `defmt` feature, in which case `defmt`'s MSRV applies, which
72//! is higher.
73//!
74//! [wire]: wire/index.html
75//! [osi]: https://en.wikipedia.org/wiki/OSI_model
76//! [berk]: https://en.wikipedia.org/wiki/Berkeley_sockets
77
78/* XXX compiler bug
79#![cfg(not(any(feature = "socket-raw",
80               feature = "socket-udp",
81               feature = "socket-tcp")))]
82compile_error!("at least one socket needs to be enabled"); */
83
84#![allow(clippy::match_like_matches_macro)]
85#![allow(clippy::redundant_field_names)]
86#![allow(clippy::identity_op)]
87#![allow(clippy::option_map_unit_fn)]
88#![allow(clippy::unit_arg)]
89#![allow(clippy::new_without_default)]
90
91#[cfg(feature = "alloc")]
92extern crate alloc;
93
94#[cfg(not(any(
95    feature = "proto-ipv4",
96    feature = "proto-ipv6",
97    feature = "proto-sixlowpan"
98)))]
99compile_error!("You must enable at least one of the following features: proto-ipv4, proto-ipv6, proto-sixlowpan");
100
101#[cfg(all(
102    feature = "socket",
103    not(any(
104        feature = "socket-raw",
105        feature = "socket-udp",
106        feature = "socket-tcp",
107        feature = "socket-icmp",
108        feature = "socket-dhcpv4",
109        feature = "socket-dns",
110    ))
111))]
112compile_error!("If you enable the socket feature, you must enable at least one of the following features: socket-raw, socket-udp, socket-tcp, socket-icmp, socket-dhcpv4, socket-dns");
113
114#[cfg(all(
115    feature = "socket",
116    not(any(
117        feature = "medium-ethernet",
118        feature = "medium-ip",
119        feature = "medium-ieee802154",
120    ))
121))]
122compile_error!("If you enable the socket feature, you must enable at least one of the following features: medium-ip, medium-ethernet, medium-ieee802154");
123
124#[cfg(all(feature = "defmt", feature = "log"))]
125compile_error!("You must enable at most one of the following features: defmt, log");
126
127#[macro_use]
128mod macros;
129mod parsers;
130mod rand;
131
132#[cfg(test)]
133pub mod config {
134    #![allow(unused)]
135    pub const ASSEMBLER_MAX_SEGMENT_COUNT: usize = 4;
136    pub const DNS_MAX_NAME_SIZE: usize = 255;
137    pub const DNS_MAX_RESULT_COUNT: usize = 1;
138    pub const DNS_MAX_SERVER_COUNT: usize = 1;
139    pub const FRAGMENTATION_BUFFER_SIZE: usize = 4096;
140    pub const IFACE_MAX_ADDR_COUNT: usize = 8;
141    pub const IFACE_MAX_MULTICAST_GROUP_COUNT: usize = 4;
142    pub const IFACE_MAX_ROUTE_COUNT: usize = 4;
143    pub const IFACE_MAX_SIXLOWPAN_ADDRESS_CONTEXT_COUNT: usize = 4;
144    pub const IFACE_NEIGHBOR_CACHE_COUNT: usize = 3;
145    pub const REASSEMBLY_BUFFER_COUNT: usize = 4;
146    pub const REASSEMBLY_BUFFER_SIZE: usize = 1500;
147    pub const RPL_RELATIONS_BUFFER_COUNT: usize = 16;
148    pub const RPL_PARENTS_BUFFER_COUNT: usize = 8;
149    pub const IPV6_HBH_MAX_OPTIONS: usize = 4;
150}
151
152#[cfg(not(test))]
153pub mod config {
154    #![allow(unused)]
155    include!(concat!(env!("OUT_DIR"), "/config.rs"));
156}
157
158#[cfg(any(
159    feature = "medium-ethernet",
160    feature = "medium-ip",
161    feature = "medium-ieee802154"
162))]
163pub mod iface;
164
165pub mod phy;
166#[cfg(feature = "socket")]
167pub mod socket;
168pub mod storage;
169pub mod time;
170pub mod wire;
171
172#[cfg(all(
173    test,
174    any(
175        feature = "medium-ethernet",
176        feature = "medium-ip",
177        feature = "medium-ieee802154"
178    )
179))]
180mod tests;
smoltcp/lib.rs

smoltcp/
lib.rs
