Overview
Theuknetdev library provides a generalized interface between network device drivers and network stack implementations or low-level network applications in Unikraft. It abstracts network device operations and provides a consistent API for packet transmission, reception, and device management.
The library is derived from DPDK’s rte_ethdev and provides a clean separation between device drivers and applications, making it easy to support multiple network backends.
Architecture
Device States
Network devices in Unikraft progress through four states:- UK_NETDEV_UNPROBED - Initial state after registration
- UK_NETDEV_UNCONFIGURED - After successful probing
- UK_NETDEV_CONFIGURED - After device and queue configuration
- UK_NETDEV_RUNNING - Device started and operational
Core Components
- uk_netdev - Main device structure containing operations and state
- uk_netbuf - Network buffer abstraction for packet data
- RX/TX Queues - Separate queues for receiving and transmitting packets
- Device Operations - Function pointers for driver-specific implementations
Device Initialization
Devices must be initialized in the following order:Key API Functions
Device Management
uk_netdev_count
uk_netdev_get
[0, n-1] where n is the device count.
Source: lib/uknetdev/include/uk/netdev.h:94
uk_netdev_probe
0on success<0error code from driver
lib/uknetdev/include/uk/netdev.h:141
uk_netdev_configure
lib/uknetdev/include/uk/netdev.h:193
uk_netdev_start
lib/uknetdev/include/uk/netdev.h:302
Queue Configuration
uk_netdev_rxq_configure
dev- Network device in configured statequeue_id- Queue index[0, nb_rx_queues-1]nb_desc- Number of descriptors (0 for driver default)rx_conf- Queue configuration including allocator and callback
lib/uknetdev/include/uk/netdev.h:240
uk_netdev_txq_configure
lib/uknetdev/include/uk/netdev.h:284
Packet Operations
uk_netdev_rx_one
UK_NETDEV_STATUS_SUCCESS- Packet received successfullyUK_NETDEV_STATUS_MORE- More packets availableUK_NETDEV_STATUS_UNDERRUN- Buffer allocation failed<0- Error from driver
lib/uknetdev/include/uk/netdev.h:476
Example:
uk_netdev_tx_one
UK_NETDEV_STATUS_SUCCESS- Packet queued for transmissionUK_NETDEV_STATUS_MORE- Queue has space for more packets<0- Error from driver
lib/uknetdev/include/uk/netdev.h:546
Device Properties
uk_netdev_hwaddr_get
lib/uknetdev/include/uk/netdev.h:313
uk_netdev_mtu_get / uk_netdev_mtu_set
lib/uknetdev/include/uk/netdev.h:363, lib/uknetdev/include/uk/netdev.h:377
uk_netdev_promiscuous_get / uk_netdev_promiscuous_set
lib/uknetdev/include/uk/netdev.h:338, lib/uknetdev/include/uk/netdev.h:353
Interrupt Management
uk_netdev_rxq_intr_enable / uk_netdev_rxq_intr_disable
0- Success1- (enable only) More packets queued, interrupts not enabled yet-ENOTSUP- Driver doesn’t support interrupts
lib/uknetdev/include/uk/netdev.h:395, lib/uknetdev/include/uk/netdev.h:424
Network Buffers (uk_netbuf)
Structure Overview
Theuk_netbuf structure represents a packet buffer with the following layout:
Allocation Functions
uk_netbuf_alloc_buf
lib/uknetdev/include/uk/netbuf.h:315
Buffer Manipulation
uk_netbuf_header
lib/uknetdev/include/uk/netbuf.h:559
uk_netbuf_headroom / uk_netbuf_tailroom
lib/uknetdev/include/uk/netbuf.h:520, lib/uknetdev/include/uk/netbuf.h:536
Chain Management
Netbufs can be chained for scatter-gather operations:lib/uknetdev/include/uk/netbuf.h:404, lib/uknetdev/include/uk/netbuf.h:445
Driver API
For implementing network device drivers, use the functions inuk/netdev_driver.h:
uk_netdev_drv_register
lib/uknetdev/include/uk/netdev_driver.h:69
uk_netdev_drv_rx_event
lib/uknetdev/include/uk/netdev_driver.h:81
Features
Hardware Offloading
The API supports various hardware offload features:- UK_NETDEV_F_RXQ_INTR - RX queue interrupts
- UK_NETDEV_F_TXQ_INTR - TX queue interrupts
- UK_NETDEV_F_PARTIAL_CSUM - Partial checksum offload
- UK_NETDEV_F_TSO4 - TCP Segmentation Offload for IPv4
- UK_NETDEV_F_LRO - Large Receive Offload
lib/uknetdev/include/uk/netdev_core.h:134-152
Configuration Options
Key configuration macros:CONFIG_LIBUKNETDEV_MAXNBQUEUES- Maximum number of queues per deviceCONFIG_LIBUKNETDEV_DISPATCHERTHREADS- Enable dispatcher threads for eventsCONFIG_LIBUKNETDEV_STATS- Enable statistics collection