《Linux设备驱劝程序第三版》网卡驱动的注释笔记 （1）（转载）

《Linux设备驱劝程序第三版》网卡驱动的范例，讲述了网卡驱动编写的一般方法，脱离了实际硬件的束缚，是一个入门的好例子，在读懂了这个例子，再补充：
1、PCI驱动方面的知识；
2、硬件读写控制方面的知识；
就可以去阅读实际的网卡驱动范例了。幸运的是，《Linux设备驱劝程序》这些方面的知识讲解还是非常到位的。以下是九贱读完这个范例代码的笔记，以做阅读本章内容的补充：


CODE:
/*
* snull.c -- the Simple Network Utility
*
* Copyright (C) 2001 Alessandro Rubini and Jonathan Corbet
* Copyright (C) 2001 O'Reilly & Associates
*
* The source code in this file can be freely used, adapted,
* and redistributed in source or binary form, so long as an
* acknowledgment appears in derived source files. The citation
* should list that the code comes from the book "Linux Device
* Drivers" by Alessandro Rubini and Jonathan Corbet, published
* by O'Reilly & Associates. No warranty is attached;
* we cannot take responsibility for errors or fitness for use.
*
* $Id: snull.c,v 1.21 2004/11/05 02:36:03 rubini Exp $
*/

#include
#include
#include
#include

#include
#include /* printk() */
#include /* kmalloc() */
#include /* error codes */
#include /* size_t */
#include /* mark_bh */

#include
#include /* struct device, and other headers */
#include /* eth_type_trans */
#include /* struct iphdr */
#include /* struct tcphdr */
#include

#include "snull.h"

#include
#include

MODULE_AUTHOR("Alessandro Rubini, Jonathan Corbet");
MODULE_LICENSE("Dual BSD/GPL");


/*
* Transmitter lockup simulation, normally disabled.
*/
static int lockup = 0;
module_param(lockup, int, 0);

static int timeout = SNULL_TIMEOUT;
module_param(timeout, int, 0);

/*
* Do we run in NAPI mode?
*/
static int use_napi = 0;
module_param(use_napi, int, 0);


/*
* A structure representing an in-flight packet.
*/
struct snull_packet {
struct snull_packet *next;
struct net_device *dev;
int datalen;
u8 data[ETH_DATA_LEN];
};

int pool_size = 8;
module_param(pool_size, int, 0);

/*
* This structure is private to each device. It is used to pass
* packets in and out, so there is place for a packet
*/

struct snull_priv {
struct net_device_stats stats;
int status;
struct snull_packet *ppool;
struct snull_packet *rx_queue; /* List of incoming packets */
int rx_int_enabled;
int tx_packetlen;
u8 *tx_packetdata;
struct sk_buff *skb;
spinlock_t lock;
};

static void snull_tx_timeout(struct net_device *dev);
static void (*snull_interrupt)(int, void *, struct pt_regs *);

/*
* 设置设备的包缓冲池.
* 当需要使用NAPI，而非中断处理的时候，设备需要能够保存多个数据包的能力，这个保存所需的缓存，
* 或者在板卡上，或者在内核的DMA环中。
* 作者这里的演示程序，根据pool_size的大小，分配pool_size个大小为struct snull_packet的缓冲区，
* 这个缓冲池用链表组织，“私有数据”结构的ppool成员指针指向链表首部。
*/
void snull_setup_pool(struct net_device *dev)
{
struct snull_priv *priv = netdev_priv(dev);
int i;
struct snull_packet *pkt;

priv->ppool = NULL;
for (i = 0; i < pool_size; i++) {
pkt = kmalloc (sizeof (struct snull_packet), GFP_KERNEL);
if (pkt == NULL) {
printk (KERN_NOTICE "Ran out of memory allocating packet pool\n");
return;
}
pkt->dev = dev;
pkt->next = priv->ppool;
priv->ppool = pkt;
}
}

/*因为snull_setup_pool分配了pool_size个struct snull_packet，所以，驱动退出时，需要释放内存*/
void snull_teardown_pool(struct net_device *dev)
{
struct snull_priv *priv = netdev_priv(dev);
struct snull_packet *pkt;

while ((pkt = priv->ppool)) {
priv->ppool = pkt->next;
kfree (pkt);
/* FIXME - in-flight packets ? */
}
}

/*
* 获取设备要传输的第一个包，传输队列首部相应的移动到下一个数据包.
*/
struct snull_packet *snull_get_tx_buffer(struct net_device *dev)
{
struct snull_priv *priv = netdev_priv(dev);
unsigned long flags;
struct snull_packet *pkt;

spin_lock_irqsave(&priv->lock, flags);
pkt = priv->ppool;
priv->ppool = pkt->next;
if (priv->ppool == NULL) {
printk (KERN_INFO "Pool empty\n");
netif_stop_queue(dev);
}
spin_unlock_irqrestore(&priv->lock, flags);
return pkt;
}

/*将包缓存交还给缓存池*/
void snull_release_buffer(struct snull_packet *pkt)
{
unsigned long flags;
struct snull_priv *priv = netdev_priv(pkt->dev);

spin_lock_irqsave(&priv->lock, flags);
pkt->next = priv->ppool;
priv->ppool = pkt;
spin_unlock_irqrestore(&priv->lock, flags);
if (netif_queue_stopped(pkt->dev) && pkt->next == NULL)
netif_wake_queue(pkt->dev);
}

/*将要传输的包加入到设备dev的传输队列首部，当然，这只是一个演示，这样一来，就变成先进先出了*/
void snull_enqueue_buf(struct net_device *dev, struct snull_packet *pkt)
{
unsigned long flags;
struct snull_priv *priv = netdev_priv(dev);

spin_lock_irqsave(&priv->lock, flags);
pkt->next = priv->rx_queue; /* FIXME - misorders packets */
priv->rx_queue = pkt;
spin_unlock_irqrestore(&priv->lock, flags);
}

/*取得传输队列中的第一个数据包*/
struct snull_packet *snull_dequeue_buf(struct net_device *dev)
{
struct snull_priv *priv = netdev_priv(dev);
struct snull_packet *pkt;
unsigned long flags;

spin_lock_irqsave(&priv->lock, flags);
pkt = priv->rx_queue;
if (pkt != NULL)
priv->rx_queue = pkt->next;
spin_unlock_irqrestore(&priv->lock, flags);
return pkt;
}

/*
* 打开/关闭接收中断.
*/
static void snull_rx_ints(struct net_device *dev, int enable)
{
struct snull_priv *priv = netdev_priv(dev);
priv->rx_int_enabled = enable;
}


/*
* 设备打开函数，是驱动最重要的函数之一，它应该注册所有的系统资源（I/O端口，IRQ、DMA等等），
* 并对设备执行其他所需的设置。
* 因为这个例子中，并没有真正的物理设备，所以，它最重要的工作就是启动传输队列。
*/

int snull_open(struct net_device *dev)
{
/* request_region(), request_irq(), .... (like fops->open) */

/*
* Assign the hardware address of the board: use "\0SNULx", where
* x is 0 or 1. The first byte is '\0' to avoid being a multicast
* address (the first byte of multicast addrs is odd).
*/
memcpy(dev->dev_addr, "\0SNUL0", ETH_ALEN);
if (dev == snull_devs[1])
dev->dev_addr[ETH_ALEN-1]++; /* \0SNUL1 */
netif_start_queue(dev);
return 0;
}

/*设备停止函数，这里的工作就是停止传输队列*/
int snull_release(struct net_device *dev)
{
/* release ports, irq and such -- like fops->close */

netif_stop_queue(dev); /* can't transmit any more */
return 0;
}