path: root/Documentation/networking/netdevices.txt
diff options
authorLinus Torvalds <>2005-04-16 15:20:36 -0700
committerLinus Torvalds <>2005-04-16 15:20:36 -0700
commit1da177e4c3f41524e886b7f1b8a0c1fc7321cac2 (patch)
tree0bba044c4ce775e45a88a51686b5d9f90697ea9d /Documentation/networking/netdevices.txt
Initial git repository build. I'm not bothering with the full history, even though we have it. We can create a separate "historical" git archive of that later if we want to, and in the meantime it's about 3.2GB when imported into git - space that would just make the early git days unnecessarily complicated, when we don't have a lot of good infrastructure for it. Let it rip!
Diffstat (limited to 'Documentation/networking/netdevices.txt')
1 files changed, 75 insertions, 0 deletions
diff --git a/Documentation/networking/netdevices.txt b/Documentation/networking/netdevices.txt
new file mode 100644
index 00000000000..1509f3aff96
--- /dev/null
+++ b/Documentation/networking/netdevices.txt
@@ -0,0 +1,75 @@
+Network Devices, the Kernel, and You!
+The following is a random collection of documentation regarding
+network devices.
+struct net_device allocation rules
+Network device structures need to persist even after module is unloaded and
+must be allocated with kmalloc. If device has registered successfully,
+it will be freed on last use by free_netdev. This is required to handle the
+pathologic case cleanly (example: rmmod mydriver </sys/class/net/myeth/mtu )
+There are routines in net_init.c to handle the common cases of
+alloc_etherdev, alloc_netdev. These reserve extra space for driver
+private data which gets freed when the network device is freed. If
+separately allocated data is attached to the network device
+(dev->priv) then it is up to the module exit handler to free that.
+struct net_device synchronization rules
+ Synchronization: rtnl_lock() semaphore.
+ Context: process
+ Synchronization: rtnl_lock() semaphore.
+ Context: process
+ Note1: netif_running() is guaranteed false
+ Note2: dev->poll() is guaranteed to be stopped
+ Synchronization: rtnl_lock() semaphore.
+ Context: process
+ Synchronization: dev_base_lock rwlock.
+ Context: nominally process, but don't sleep inside an rwlock
+ Synchronization: dev->xmit_lock spinlock.
+ When the driver sets NETIF_F_LLTX in dev->features this will be
+ called without holding xmit_lock. In this case the driver
+ has to lock by itself when needed. It is recommended to use a try lock
+ for this and return -1 when the spin lock fails.
+ The locking there should also properly protect against
+ set_multicast_list
+ Context: BHs disabled
+ Notes: netif_queue_stopped() is guaranteed false
+ Return codes:
+ o NETDEV_TX_OK everything ok.
+ o NETDEV_TX_BUSY Cannot transmit packet, try later
+ Usually a bug, means queue start/stop flow control is broken in
+ the driver. Note: the driver must NOT put the skb in its DMA ring.
+ o NETDEV_TX_LOCKED Locking failed, please retry quickly.
+ Only valid when NETIF_F_LLTX is set.
+ Synchronization: dev->xmit_lock spinlock.
+ Context: BHs disabled
+ Notes: netif_queue_stopped() is guaranteed true
+ Synchronization: dev->xmit_lock spinlock.
+ Context: BHs disabled
+ Synchronization: __LINK_STATE_RX_SCHED bit in dev->state. See
+ dev_close code and comments in net/core/dev.c for more info.
+ Context: softirq