对scull字符设备的注解

#ifndef __SCULL_H__
#define __SCULL_H__

#ifndef SCULL_MAJOR
#define SCULL_MAJOR 0
#endif

#ifndef SCULL_MINOR
#define SCULL_MINOR 0
#endif

typedef struct _scull_dev_ {
    void **data;  /*数据存储区*/
       int quantum;  /*每块数据存储区的大小*/
       int qset;     /*数据存储区的块数*/
       unsigned long size;    /*数据量*/
       struct semaphore sem;
    struct cdev cdev;

} SCULL_DEV,pSCULL_DEV;

#endif




#ifndef __KERNEL__
#  define __KERNEL__
#endif
#ifndef MODULE
#  define MODULE
#endif

#include <linux/init.h>
#include <linux/module.h>
#include <linux/cdev.h>
#include <linux/slab.h>
#include <linux/kernel.h>   /* printk() */
#include <linux/fs.h>       /* everything... */
#include <linux/errno.h>    /* error codes */
#include <linux/types.h>    /* size_t */
#include <linux/proc_fs.h>
#include <linux/fcntl.h>    /* O_ACCMODE */
#include <asm/system.h>     /* cli(), *_flags */
#include <asm/uaccess.h>

#include "scull.h"          /* local definitions */


int scull_major = SCULL_MAJOR;
int scull_minor    = SCULL_MINOR;
int scull_mn_dev = 1;
int scull_quantum = 4000;    /*每个指针所指向存储单元的大小*/
int scull_qset = 4000;    /*指针数组的大小*/
static pSCULL_DEV *pscull_dev = NULL;


int scull_trim(SCULL_DEV *pscull)
{
    int i = 0;
    int qset = pscull->qset;

    if (pscull->data)
    {
        for(i = 0; i < qset; i++)
        {
            if (pscull->data[i])
                kfree(pscull->data[i]);
        }

        kfree(pscull->data);
        pscull->data=NULL;
    }

    pscull->size = 0;
    pscull->quantum = scull_quantum;
    pscull->qset = scull_qset;

    return 0;
}

/*open方法提供给驱动程序以初始化的能力。它应完成如下工作：1、检查设备特定的错误；2、如果设备是首次打开，则对其进行初始化；3、如有必要，更新f_op指针；4、分配并填写置于filp->private_data里的数据结构。*/
int scull_open(struct inode *inode, struct file *filp)
{
    SCULL_DEV *pscull = NULL;

    /*获取我们自定义结构的指针*/
    pscull = container_of(inode->i_cdev,pSCULL_DEV,cdev);
    /*将自定义结构的指针保存到file结构的private_data字段中，这样可以方便以后对该指针的访问*/
    filp->private_data = pscull;
    if ( (filp->f_flags & O_ACCMODE) == O_WRONLY)
    {
        scull_trim(pscull);
    }

    return 0;
}

/*release主要的工作是：1、释放由open分配的、保存在filp->private_data中的所有内容；2、在最后一次关闭操作时关闭设备。*/
int scull_release(struct inode *inode, struct file *filp)
{
    return 0;
}

/*
 *调用程序对read的返回值解释如下：
 *1、如果返回值等于传递给read系统调用的count参数，则说明所请求的字节数传输成功完成了。
 *2、如果返回值是正的，但是比count小，则说明只有部分数据成功传送。这种情况因为设备的不同可能有许多原因。大部分情况下，程序会重新读数据。例如，如果用fread函数读数据，这个库函数就会不断调用系统调用，直至所请求的数据传输完毕为止。
 *3、如果返回值为0，则表示已经到达了文件尾。
 *4、负值意味着发生了错误，该值指明了发生什么错误，错误码在<linux/errno.h>中定义
*/
ssize_t scull_read(struct file *filp, char *buf, size_t count,loff_t *f_pos)
{
    SCULL_DEV *pscull = filp->private_data;
    int quantum = pscull->quantum;
    int qset = pscull->qset;
    int s_pos = 0, q_pos = 0;
    ssize_t ret = 0;

    if(down_interruptible(&pscull->sem))
        return -ERESTARTSYS;

    if(*f_pos >= pscull->size)
        goto out;

    if(*f_pos + count > pscull->size)
        count = pscull->size - *f_pos;

    s_pos = (long)*f_pos/quantum;
    q_pos = (long)*f_pos%quantum;

    if(s_pos > qset)
        goto out;

    if(!pscull->data)
        goto out;

    if(!pscull->data[s_pos])
        goto out;

    if(count > quantum-q_pos)
        count = quantum-q_pos;

    /*将内核空间的数据拷贝到用户空间*/
    if(copy_to_user(buf, pscull->data[s_pos]+q_pos, count))
    {
        ret = -EFAULT;
        goto out;
    }

    *f_pos += count;
    ret = count;

out:
    up(&pscull->sem);

    return ret;
}

/*
 *调用程序对write的返回值解释如下：
 *1、如果返回值等于count，则完成了所请求数目的字节传送。
 *2、如果返回值是正的，但小于count，则只传送了部分数据。程序很可能再次试图写入余下的数据。
 *3、如果值为0，意味着什么也没有写入。这个结果不是错误，而且也没有理由返回一个错误码。
 *4、负值意味着发生了错误。
*/
ssize_t scull_write(struct file *filp, const char *buf, size_t count,loff_t *f_pos)
{
    SCULL_DEV *pscull = filp->private_data;
    int quantum = pscull->quantum;
    int qset = pscull->qset;
    int s_pos,q_pos;
    ssize_t ret = -ENOMEM;

    if(down_interruptible(&pscull->sem))
        return -ERESTARTSYS;

    s_pos = (long)*f_pos/quantum;
    q_pos = (long)*f_pos%quantum;

    if(!pscull->data)
    {
        pscull->data = kmalloc(qset*sizeof(char *), GFP_KERNEL);
        if (!pscull->data)
            goto out;
        memset(pscull->data, 0, qset*sizeof(char *));
    }

    if(!pscull->data[s_pos])
    {
        pscull->data[s_pos] = kmalloc(quantum, GFP_KERNEL);
        if (!pscull->data[s_pos])
            goto out;
        memset(pscull->data[s_pos],0,quantum);
    }

    if(count > quantum-q_pos)
        count = quantum-q_pos;

    /*将用户空间的数据拷贝到内核空间*/
    if(copy_from_user(pscull->data[s_pos]+q_pos, buf, count))
    {
        ret = -EFAULT;
        goto out;
    }

    *f_pos += count;
    ret = count;

    if(pscull->size < *f_pos)
        pscull->size = *f_pos;

out:
    up(&pscull->sem);

    return ret;
}

int scull_ioctl(struct inode *inode, struct file *filp,unsigned int cmd, unsigned long arg)
{
    return 0;
}

loff_t scull_llseek(struct file *filp, loff_t off, int whence)
{
    return 0;
}

struct file_operations scull_fops = {
    .owner     =    THIS_MODULE,
    .llseek    =    scull_llseek,
    .read    =    scull_read,
    .write    =    scull_write,
    .ioctl    =    scull_ioctl,
    .open    =    scull_open,
    .release =    scull_release,
};

/*模块的清除函数*/
static void scull_cleanup_module(void)
{
    dev_t dev;

    /*获取起始设备号*/
    dev = MKDEV(scull_major,scull_minor);
    /*从系统中移除一个字符设备*/
    cdev_del(&pscull_dev->cdev);
    /*释放不再使用的设备编号，第一个参数是起始设备编号，第二个参数是需要释放的连续编号数*/
    unregister_chrdev_region(dev,scull_mn_dev);
    scull_trim(pscull_dev);
    kfree(pscull_dev);
    pscull_dev = NULL;

    return;
}

/*模块的初始化函数*/
static int scull_init_module(void)
{
    /*在内核的2.6.0版本中，dev_t是一个32位的数，其中12位用来表示主设备号，而其余20位用来表示次设备号*/
    dev_t dev;
    int result = -1;

    pscull_dev = kmalloc(sizeof(SCULL_DEV),GFP_KERNEL);
    if(pscull_dev == NULL)
    {
        printk(KERN_WARNING"scull: can't kmalloc memory\n");
        result = -ENOMEM;
        return result;
    }
    memset(pscull_dev,0,sizeof(SCULL_DEV));
    pscull_dev->data = NULL;
    pscull_dev->quantum = scull_quantum;
    pscull_dev->qset = scull_qset;

    /*创建信号量，并将信号量的初始值赋值为1*/
    sema_init(&pscull_dev->sem,1);

    /*用来获取主设备号，可由程序指定（或在insmod的时候指定相应值）或采用内核动态分配的方式*/
    if(scull_major)
    {
        /*将主设备号和次设备号转换成dev_t*/
        dev = MKDEV(scull_major,scull_minor);
        /*获得设备的一个或多个编号，该种方式是由程序指定设备号，函数的第一个参数是设备号的起始值（通常次设备号都被设置成0），第二个参数表示所请求的连续设备编号的个数，第三个参数是和该编号范围关联的设备名称，它将出现在/proc/devices和sysfs中*/
        result = register_chrdev_region(dev,scull_mn_dev,"scull");
    }
    else
    {
        /*通常情况下，我们都不知道使用哪个设备号。使用以下的函数，内核将恰当的为我们分配所需的主设备号，第一个参数仅用于输出的参数，在成功完成调用后将保存已分配范围的第一个编号，第二个参数是要使用的被请求的第一个次设备号，第三个参数表示所请求的连续设备编号的个数，第四个参数是和该编号范围关联的设备名称，它将出现在/proc/devices和sysfs中*/
        result = alloc_chrdev_region(&dev,scull_minor,scull_mn_dev,"scull");
        /*获取主设备号，采用MINOR（dev）可以获取到次设备号*/
        scull_major = MAJOR(dev);
    }

    if(result < 0)
    {
        printk(KERN_WARNING"scull: can't get major %d\n",scull_major);
        return result;
    }

    /*在内核内部，使用struct cdev结构来表示字符设备，以下函数可以初始化已分配到的cdev结构。因为本例中我们将cdev结构嵌入到自己的特定设备结构中，所以采用下面的函数。也可以使用cdev_alloc()来分配一个cdev字符设备结构*/
    cdev_init(&pscull_dev->cdev,&scull_fops);
    /*初始化cdev结构的所有者字段*/
    pscull_dev->cdev.owner = THIS_MODULE;
    /*初始化设备的文件操作接口结构的指针*/
    pscull_dev->cdev.ops = &scull_fops;
    /*将cdev结构告诉内核，第一个参数是struct cdev机构，第二个是该设备对应的第一个设备编号，第三个参数是和该设备关联的设备编号的数量。在使用cdev_add时，需要注意：首先，这个调用可能会失败。如果它返回一个负的错误码，则设备不会被添加到系统中。但这个调用总是会成功返回。只要cdev_add成功返回了，设备就启动了，它的操作就会被内核调用。因此，在驱动程序还没有完全准备好处理设备上的操作时，就不能调用cdev_add。*/
    result = cdev_add(&pscull_dev->cdev,dev,1);
    if(result)
    {
        printk(KERN_NOTICE"Error %d add scull device\n",result);
        goto fail;
    }

    return 0;

fail:
    scull_cleanup_module();

    return result;
}



/*用于指定模块的初始化和清除函数的宏*/
module_init(scull_init_module);
module_exit(scull_cleanup_module);

/*在目标文件中添加关于模块的文档信息*/
MODULE_AUTHOR("txgcwm");
MODULE_VERSION("scull_v1.0");
MODULE_LICENSE("GPL");