Changes between Version 1 and Version 2 of nic_device_api

Timestamp:

Jan 26, 2020, 7:41:37 PM (5 years ago)

Author:

alain

Comment:

--

nic_device_api

@@ -1 @@
-= TBD =
+= NIC device API =
+
+[[PageOutline]]
+
+== __A) General principles__ ==
+
+
+This device provide access to an external generic Gigabit Ethernet network controller. It assume that the NIC hardware peripheral has a DMA capability, and can access two packets queues in kernel memory for sent (TX) and received (RX) packets. Packets are (Ethernet/IPV4).
+
+The NIC device is handling two (infinite) streams of packets to or from the network. It is the driver responsibility to move the RX packets from the NIC to the RX queue, and the TX packets from the TX queue to the NIC.
+
+AS the RX and TX queues are independant, there is one NIC-RX device descriptor to handle RX packets, and another NIC-TX device descriptor to handle TX packets. In order to improve throughput, the hardware NIC controller can (optionnally) implements multiple (N) channels:
+ * The RX channels are indexed by an hash key derived from the source IP address.
+ * The TX channels are indexed by an hash key derived from the destination IP address.
+These 2*N chdev descriptors, and 2*N associated server threads, are distributed in  clusters.
+The  2*N server threads implement the protocols stack. The RX server threads block and deschedule when the RX queue is empty. The TX server threads block and deschedule when the TX queue is full. 
+
+It is the driver responsibily to re-activate a blocked server thread when the queue state is modified: not full for TX, or not empty for RX.
+
+The WTI mailboxes used by the driver ro receive events from the NIC hardware (available RX packet, or free TX slot, for a given channel), must be statically allocated during the kernel initialisation phase, and must be routed to the cluster containing the associated device descriptor and server thread.
+
+ Finally, the generic NIC device "kernel" API defines four command types, that are detailed in section C.
+ * '''READABLE''' : returns true if at least one RX paquet is available in RX queue.
+ * '''WRITABLE : returns true if at least one empty slot is available in TX queue.
+ * '''READ'''     : consume one packet from the RX queue.
+ * '''WRITE'''    : produce one packet to the TX queue.
+
+All RX or TX paquets are sent or received in standard 2 Kbytes kernel buffers, that are dynamically allocated by the protocols stack. The structure ''pkd_t'' defining a packet descriptor contains the buffer pointer and the actual Ethernet packet length in bytes.
+
+The actual TX an RX queues structures depends on the hardware NIC implementation, and must be defined by the driver code. 
+
+To access the various drivers, the NIC device defines a lower-level "driver" API, that is detailed in section D below.
+
+All NIC device structures and access functions are defined in the [https://www-soc.lip6.fr/trac/almos-mkh/browser/trunk/kernel/devices/dev_nic.c  dev_nic.c] et [https://www-soc.lip6.fr/trac/almos-mkh/browser/trunk/kernel/devices/dev_nic.h dev_nic.h] files.