summaryrefslogtreecommitdiffstats
path: root/Documentation/networking/netdevices.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/networking/netdevices.txt')
-rw-r--r--Documentation/networking/netdevices.txt75
1 files changed, 75 insertions, 0 deletions
diff --git a/Documentation/networking/netdevices.txt b/Documentation/networking/netdevices.txt
new file mode 100644
index 000000000000..1509f3aff968
--- /dev/null
+++ b/Documentation/networking/netdevices.txt
@@ -0,0 +1,75 @@
+
+Network Devices, the Kernel, and You!
+
+
+Introduction
+============
+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
+=======================================
+dev->open:
+ Synchronization: rtnl_lock() semaphore.
+ Context: process
+
+dev->stop:
+ Synchronization: rtnl_lock() semaphore.
+ Context: process
+ Note1: netif_running() is guaranteed false
+ Note2: dev->poll() is guaranteed to be stopped
+
+dev->do_ioctl:
+ Synchronization: rtnl_lock() semaphore.
+ Context: process
+
+dev->get_stats:
+ Synchronization: dev_base_lock rwlock.
+ Context: nominally process, but don't sleep inside an rwlock
+
+dev->hard_start_xmit:
+ 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.
+
+dev->tx_timeout:
+ Synchronization: dev->xmit_lock spinlock.
+ Context: BHs disabled
+ Notes: netif_queue_stopped() is guaranteed true
+
+dev->set_multicast_list:
+ Synchronization: dev->xmit_lock spinlock.
+ Context: BHs disabled
+
+dev->poll:
+ 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
+