Module capsules_extra::net::udp::udp_port_table

In-kernel structure for tracking UDP ports bound by capsules.

When kernel capsules wish to send or receive UDP packets, the UDP sending / receiving capsules will only allow this if the capsule has bound to the port it wishes to send from / receive on. Binding to a port is accomplished via calls on the UdpPortManager struct defined in this file. Calls to bind on this table enforce that only one capsule can be bound to a given port at any time. Once capsules successfully bind using this table, they receive back binding structures (UdpPortBindingTx/UdpPortBindingRx) that act as proof that the holder is bound to that port. These structures can only be created within this file, and calls to unbind must consume these structures, enforcing this invariant. The UDP tx/rx capsules require these bindings be passed in order to send/receive on a given port. Separate bindings are used for sending and receiving because the UdpReceiver must hold onto the binding for as long as a capsule wishes to receive packets on a port, so a separate binding must be available to enable sending packets on a port while listening on the same port.

To reduce the size of data structures required for this task, a fixed size array is used to store bindings in the kernel. This means that a limited number of bindings can be stored at any point in time. Reserving a slot in this table is done by requesting a socket, which represents a reserved slot. These sockets are then used to request bindings on a particular port.

This file only stores information about which ports are bound by capsules. The files udp_send.rs and udp_recv.rs enforce that only capsules possessing the correct bindings can actually send / recv on a given port.

Userspace port bindings are managed separately by the userspace UDP driver (capsules/src/net/udp/driver.rs), because apps can be dynamically added or removed. Bindings for userspace apps are stored in the grant regions of each app, such that removing an app automatically unbinds it. This file is able to query the userspace UDP driver to check which ports are bound, and vice-versa, such that exclusive access to ports between userspace apps and capsules is still enforced.

Structs

• UdpPortBindingRx
  An opaque descriptor that allows the holder to obtain a binding on a port for receiving UDP packets.
• UdpPortBindingTx
  An opaque descriptor that allows the holder to obtain a binding on a port for sending UDP packets.
• UdpPortManager
  The UdpPortManager maintains a reference to the port_array, which manages what ports are bound at any given moment, and user_ports, which provides a handle to userspace port bindings in the UDP driver.
• UdpSocket
  A UdpSocket provides a handle into the bound port table. When binding to a port, the socket is consumed and Udp{Sender, Receiver}Binding structs are returned. When undbinding, the socket is returned and can be used to bind to other ports.

Enums

• SocketBindingEntry
  The SocketBindingEntry struct is stored in the PORT_TABLE and conveys what port is bound at the given index if one is bound. If no port is bound, the value stored at that location in the table is Unbound.

Constants

• MAX_NUM_BOUND_PORTS

Traits

• PortQuery
  The PortQuery trait enables the UdpPortManager to query the userspace bound ports in the UDP driver. The UDP driver struct implements this trait.