2016-12-10 17:23:40 +08:00
|
|
|
smoltcp
|
|
|
|
=======
|
|
|
|
|
|
|
|
_smoltcp_ is a standalone, event-driven TCP/IP stack that is designed for bare-metal,
|
|
|
|
real-time systems. Its design goals are simplicity and robustness. Its design anti-goals
|
|
|
|
include complicated compile-time computations, such as macro or type tricks, even
|
|
|
|
at cost of performance degradation.
|
|
|
|
|
|
|
|
Features
|
|
|
|
--------
|
|
|
|
|
|
|
|
_smoltcp_ is missing many widely deployed features, whether by design or simply because
|
|
|
|
no one implemented them yet. To set expectations right, both implemented and omitted
|
|
|
|
features are listed.
|
|
|
|
|
|
|
|
### Media layer
|
|
|
|
|
|
|
|
The only supported medium is Ethernet.
|
|
|
|
|
2016-12-13 20:31:33 +08:00
|
|
|
* Regular Ethernet II frames are supported.
|
2016-12-13 07:22:59 +08:00
|
|
|
* ARP packets (including gratuitous requests and replies) are supported.
|
2016-12-15 01:39:44 +08:00
|
|
|
* 802.3 and 802.1Q are **not** supported.
|
2016-12-13 04:01:38 +08:00
|
|
|
* Jumbo frames are **not** supported.
|
2016-12-10 17:23:40 +08:00
|
|
|
|
|
|
|
### IP layer
|
|
|
|
|
2016-12-13 04:01:38 +08:00
|
|
|
The only supported internetworking protocol is IPv4.
|
|
|
|
|
|
|
|
* IPv4 header checksum is supported.
|
|
|
|
* IPv4 fragmentation is **not** supported.
|
|
|
|
* IPv4 options are **not** supported.
|
2016-12-15 01:39:44 +08:00
|
|
|
* ICMPv4 header checksum is supported.
|
2016-12-13 07:22:59 +08:00
|
|
|
* ICMPv4 echo requests and replies are supported.
|
2016-12-21 03:18:35 +08:00
|
|
|
* ICMPv4 destination unreachable message is supported.
|
2016-12-13 07:22:59 +08:00
|
|
|
* ICMPv4 parameter problem message is **not** supported.
|
2016-12-10 17:23:40 +08:00
|
|
|
|
|
|
|
### UDP layer
|
|
|
|
|
2016-12-15 01:39:44 +08:00
|
|
|
The UDP protocol is supported over IPv4.
|
|
|
|
|
|
|
|
* UDP header checksum is supported.
|
|
|
|
* UDP sockets are supported.
|
2016-12-10 17:23:40 +08:00
|
|
|
|
|
|
|
### TCP layer
|
|
|
|
|
2016-12-20 21:44:41 +08:00
|
|
|
The TCP protocol is supported over IPv4.
|
|
|
|
|
|
|
|
* TCP header checksum is supported.
|
2016-12-26 22:24:17 +08:00
|
|
|
* TCP options are **not** supported. In particular, the MSS of the remote endpoint
|
|
|
|
is hardcoded at the default value, 536.
|
2016-12-25 19:09:50 +08:00
|
|
|
* Reassembly of out-of-order segments is **not** supported.
|
2016-12-10 17:23:40 +08:00
|
|
|
|
|
|
|
Installation
|
|
|
|
------------
|
|
|
|
|
|
|
|
To use the _smoltcp_ library in your project, add the following to `Cargo.toml`:
|
|
|
|
|
|
|
|
```toml
|
|
|
|
[dependencies]
|
|
|
|
smoltcp = "0.1"
|
|
|
|
```
|
|
|
|
|
|
|
|
Usage example
|
|
|
|
-------------
|
|
|
|
|
2016-12-13 20:31:33 +08:00
|
|
|
_smoltcp_, being a freestanding networking stack, needs to be able to transmit and receive
|
|
|
|
raw frames. For testing purposes, we will use a regular OS, and run _smoltcp_ in
|
|
|
|
a userspace process. Only Linux is supported (right now).
|
|
|
|
|
|
|
|
On *nix OSes, transmiting and receiving raw frames normally requires superuser privileges, but
|
|
|
|
on Linux it is possible to create a _persistent tap interface_ that can be manipulated by
|
|
|
|
a specific user:
|
2016-12-12 15:19:53 +08:00
|
|
|
|
|
|
|
```sh
|
|
|
|
sudo ip tuntap add name tap0 mode tap user $USER
|
|
|
|
sudo ip link set tap0 up
|
2016-12-13 23:18:56 +08:00
|
|
|
sudo ip addr add 192.168.69.100/24 dev tap0
|
2016-12-10 17:23:40 +08:00
|
|
|
```
|
|
|
|
|
2016-12-12 15:19:53 +08:00
|
|
|
### smoltcpdump
|
|
|
|
|
|
|
|
_smoltcpdump_ is a tiny clone of the _tcpdump_ utility.
|
|
|
|
|
|
|
|
Unlike the rest of the examples, it uses raw sockets, and so it can be used on regular interfaces,
|
|
|
|
e.g. `eth0` or `wlan0`, as well as the `tap0` interface we've created above.
|
|
|
|
|
|
|
|
Read its [source code](/examples/smoltcpdump.rs), then run it as:
|
|
|
|
|
|
|
|
```sh
|
|
|
|
cargo build --example smoltcpdump
|
|
|
|
sudo ./target/debug/smoltcpdump eth0
|
|
|
|
```
|
|
|
|
|
|
|
|
### smoltcpserver
|
|
|
|
|
|
|
|
_smoltcpserver_ emulates a network host that can serve requests.
|
|
|
|
|
|
|
|
The host is assigned the hardware address `02-00-00-00-00-01` and IPv4 address `192.168.69.1`.
|
|
|
|
|
|
|
|
Read its [source code](/examples/smoltcpserver.rs), then run it as:
|
|
|
|
|
|
|
|
```sh
|
|
|
|
cargo run --example smoltcpserver -- tap0
|
|
|
|
```
|
|
|
|
|
|
|
|
It responds to:
|
|
|
|
|
2016-12-17 13:12:45 +08:00
|
|
|
* pings (`ping 192.168.69.1`),
|
2016-12-26 22:50:12 +08:00
|
|
|
* UDP packets on port 6969 (`socat stdio udp4-connect:192.168.69.1:6969 <<<"abcdefg"`),
|
|
|
|
* TCP packets on port 6969 (`socat stdio tcp4-connect:192.168.69.1:6969 <<<"abcdefg"`),
|
2016-12-12 15:19:53 +08:00
|
|
|
|
2016-12-10 17:23:40 +08:00
|
|
|
License
|
|
|
|
-------
|
|
|
|
|
|
|
|
_smoltcp_ is distributed under the terms of both the MIT license
|
|
|
|
and the Apache License (Version 2.0).
|
|
|
|
|
|
|
|
See [LICENSE-APACHE](LICENSE-APACHE) and [LICENSE-MIT](LICENSE-MIT)
|
|
|
|
for details.
|