smoltcp/
lib.rs

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

smoltcp/
lib.rs
