1Haiku Network Stack Architecture 2================================ 3 4The Haiku Network Stack is a modular and layered networking stack, very 5similar to what you may know as BONE. 6 7The entry point when talking to the stack is through a dedicated device 8driver that publish itself in /dev/net. The userland library 9libnetwork.so (which combines libsocket.so, and libbind.so) directly 10talks to this driver, mostly via ioctl()\ `1 <#foot1>`__. 11 12The driver either creates sockets, or passes on every command to the 13socket module\ `2 <#foot2>`__. Depending on the address family and type 14of the sockets, the lower layers will be loaded and connected. 15 16For example, with a TCP/IP socket, the stack could look like this: 17 18+------------------+--------------------------------------------------------+ 19| **Socket** | 20+------------------+--------------------------------------------------------+ 21| TCP | Protocols defined by the socket (address family, type) | 22+------------------+ | 23| IPv4 | (session, transport, network layers) | 24+------------------+--------------------------------------------------------+ 25| **Datalink** | 26+------------------+--------------------------------------------------------+ 27| ARP | Datalink Protocols defined by the interface | 28| | (IP address, device) | 29+------------------+ | 30| Ethernet framing | (datalink layer) | 31+------------------+--------------------------------------------------------+ 32| Ethernet device | (physical layer) | 33+------------------+--------------------------------------------------------+ 34 35Where TCP, and IPv4 are net_protocol modules, and ARP, and the Ethernet 36framing are net_datalink_protocol modules. All modules are connected in 37a chain, even though the datalink layer introduces more than one path 38(one for each interface). 39 40When sending data through a socket, a net_buffer is created in the 41socket module, and passed on to the lower levels where each protocol 42processes it, before passing it on to the next protocol in the chain. 43The last protocol in the chain is always a domain protocol - it will 44directly forward the buffers to the datalink module. When the buffer 45reaches the datalink level, an accompanied net_route object will 46determine for which interface (which determines the datalink protocols 47in the chain) the buffer is destined. The route has to be specified by 48the upper protocols before the buffer gets into the datalink level - if 49a buffer comes in without a valid route, it is discarded. 50 51The protocol modules are loaded and unloaded as needed. The stack itself 52stays loaded as long as there are interfaces defined - as soon as the 53last interface is removed, the stack gets unloaded (which is, of course, 54not yet implemented). 55 56The Structures and Classes 57~~~~~~~~~~~~~~~~~~~~~~~~~~ 58 59net_domain 60^^^^^^^^^^ 61 62Every supported address family gets its own domain. A domain comprises 63such a family, a net_protocol module that handles this domain, and a 64list of interfaces and routes. It also gets a name: for example, the 65IPv4 module registers the "internet" domain (AF_INET). 66 67The domain protocol module is responsible for managing the domain; it 68has to register it when it's loaded, and it has to unregister it when it 69is unloaded by the networking stack. 70 71net_interface 72^^^^^^^^^^^^^ 73 74An interface makes an underlying net_device accessible by the stack. 75When creating a new interface, you have to specify a domain, and a 76device to be used. The stack will then look through the registered 77datalink protocols, and builds a chain of them for that interface. 78 79The interface usually gets a network address, and a route that directs 80buffers to be sent to it. If there is no route to an interface, it will 81never be used for outgoing data, but may well receive data from other 82hosts. 83 84An interface can be "up" (when ``IFF_UP`` is set in its ``flags`` 85member) in which case it accepts data - when that flag is not set, it 86will discard all data it gets. The interface also specifies the maximum 87buffer size that can be sent over this interface (the ``mtu`` member, 88a.k.a. maximum transmission unit). 89 90Interfaces are configured via ioctl()s (SIOCAIFADDR, ...). You can use 91the command line tool "ifconfig" to do this for you. 92 93net_device 94^^^^^^^^^^ 95 96A networking device is used to actually send and receive the buffers. It 97either points to an actual hardware device (in case of ethernet), or to 98a virtual device (in case of loopback). Every device has a unique name 99that identifies it. When creating a device, the name also decides which 100net_device module will be chosen; for example, everything that starts 101with "loop" will end up in the loopback device, while the ethernet 102device accepts names that start with "/dev/net/". 103 104A device can be shared by many interfaces at the same time. The device 105to be used by an interface is specified at the time an interface is 106created. It also has an ``mtu`` member that determines the upper limit 107of an interface's ``mtu`` as well. 108 109net_buffer 110^^^^^^^^^^ 111 112A buffer holds exactly one packet, and has a source as well as a 113destination address. The addresses may be changed in every layer the 114buffer passes through. For example, the datalink protocols usually use 115sockaddr_dl structures with family AF_DLI, while the upper levels may 116use sockaddr_in structures with family AF_INET. Every protocol only 117supports a small number of address types, and it's the requirement of 118the upper protocols to prepare the address for use in the lower 119protocols (and that's also a reason why it wouldn't work to arbitrarily 120stack protocols onto each other). 121 122The net_buffer module can be used to access the data within the buffer, 123append new data to the buffer, or remove chunks of data from it. 124Internally, the buffer consists of usually fixed size (2048 byte) 125buffers that can be shared or connected as needed. 126 127net_socket 128^^^^^^^^^^ 129 130The socket is only of interest for the net_protocol modules, as it 131stores options that may have an effect on the protocol's performance. 132It's the direct counterpart to a socket file descriptor in userland, but 133it has only little logic bound to it. 134 135When a socket is created, the networking stack creates a chain of 136net_protocol modules for the socket that will then do the real work. 137When the socket is closed, the net_protocol chain is freed, and the 138modules are eventually unloaded (if they are no longer in use). 139 140net_protocol 141^^^^^^^^^^^^ 142 143The protocols are bound to a specific socket, process the outgoing 144buffers as needed (ie. add or remove headers, compute checksums, ...), 145and pass it on to the next protocol. The last protocol in the chain is 146always a domain protocol that will forward the calls to the datalink 147module directly, if needed. 148 149A domain protocol is a net_protocol that registered a domain, ie. IPv4. 150Other than usual protocols, domain protocols have some special 151requirements: 152 153- they need to be able to execute send_data(), and get_domain() without 154 a pointer to its net_protocol object, as those may be called outside 155 of the socket context. 156- as mentioned, they also don't talk to the next protocol in the chain 157 (as they are always the last one), but to the datalink module 158 directly. 159 160Similar to the need to perform send_data() outside of the socket 161context, all protocols that can receive data need to handle incoming 162data without the socket context: incoming data is always handled outside 163of the socket context, as the actual target socket is unknown during 164processing. 165 166Only the top-most protocol will be able to forward the packet to the 167target socket(s). To receive incoming data, a protocol must register 168itself as receiving protocol with the networking stack. The domain 169protocol is usually registered automatically by a net_datalink_protocol 170module that knows about both ends (for example, the ARP module is both 171IPv4 and ethernet specific, and therefore registers the AF_INET domain 172to receive ethernet packets of type IP). 173 174net_datalink_protocol 175^^^^^^^^^^^^^^^^^^^^^ 176 177The datalink protocols are bound to a specific net_interface, and 178therefore to a specific net_device as well. Outgoing data is processed 179so that it can be sent via the net_device. For example, the ARP protocol 180will replace sockaddr_in structures in the buffer with sockaddr_dl 181structures describing the ethernet MAC address of the source and 182destination hosts, the ethernet_frame protocol will add the usual 183ethernet header, etc. 184 185The last protocol in the chain is also a special device interface bridge 186protocol, that redirects the calls to the underlying net_device. 187 188Incoming data is handled differently again; when you want to receive 189data directly coming from a device, you can either register a deframing 190function for it, or a handler that will be called depending on what data 191type the deframing module reported. For example, the ethernet_frame 192module registers an ethernet deframing function, while the ARP module 193registers a handler for ethernet ARP packets with the device. When the 194deframing function reports a ``ETHER_TYPE_ARP`` packet, the ARP 195receiving function will be called. 196 197net_route 198^^^^^^^^^ 199 200A route determines the target interface of an outgoing packet. A route 201is always owned by a specific domain, and the route is chosen by 202comparing the networking address of the outgoing buffer with the mask 203and address of the route. 204 205A protocol will usually not use the routes directly, but use a 206net_route_info object (see below), that will make sure that the route is 207updated automatically whenever the routing table is changed. 208 209net_route_info 210^^^^^^^^^^^^^^ 211 212A routing helper for protocol usage: it stores the target address as 213well as the route to be used, and has to be registered with the 214networking stack via ``register_route_info()``. 215 216Then, the stack will automatically update the route as needed, whenever 217the routing table of the domain changes; it will always matches the 218address specified there. When the routing is no longer needed, you must 219unregister the net_route_info again. 220 221-------------- 222 223| 1 You can find the definition of the driver interface in 224 `headers/private/net/net_stack_interface.h <https://git.haiku-os.org/haiku/tree/headers/private/net>`__, 225 as well as the driver itself at 226 `src/add-ons/kernel/drivers/network <https://git.haiku-os.org/haiku/tree/src/add-ons/kernel/drivers/network>`__ 227| 2\ `src/add-ons/kernel/network/stack/ <https://git.haiku-os.org/haiku/tree/src/add-ons/kernel/network/stack>`__ 228