Linux设备驱动程序学习－USB 驱动程序_fs入口

struct usb_driver { 
    const char * name;     
    /*指向驱动程序名字的指针. 它必须在内核所有的 USB 驱动中是唯一的(通常被设为和驱动模块名相同).当驱动在内核中运行时,会出现在/sys/bus/usb/drivers目录中 */ 

    int ( * probe) ( struct usb_interface * intf, 
         const struct usb_device_id * id) ; 
    /* 指向 USB 驱动中探测函数指针. 当USB 核心认为它有一个本驱动可处理的 struct usb_interface时此函数将被调用. USB 核心用来做判断的 struct usb_device_id 指针也被传递给此函数.如果这个 USB 驱动确认传递给它的 struct usb_interface, 它应当正确地初始化设备并返回 0. 如果驱动没有确认这个设备或发生错误,则返回负错误值 */ 

    void ( * disconnect) ( struct usb_interface * intf) ; 
    /*指向 USB 驱动的断开函数指针.当 struct usb_interface 从系统中清除或驱动 USB 核心卸载时,函数将被 USB 核心调用*/ 

    int ( * ioctl) ( struct usb_interface * intf, unsigned int code, 
            void * buf) ; 
    /*指向 USB 驱动的 ioctl 函数指针. 若此函数存在, 在用户空间程序对usbfs 文件系统关联的设备调用 ioctl 时,此函数将被调用. 实际上,当前只有 USB 集线器驱动使用这个 ioctl*/ 

    int ( * suspend) ( struct usb_interface * intf, pm_message_t message) ; 
    /*指向 USB 驱动中挂起函数的指针*/ 
    int ( * resume) ( struct usb_interface * intf) ; 
    /*指向 USB 驱动中恢复函数的指针*/ 
    int ( * reset_resume) ( struct usb_interface * intf) ; 
    /*要复位一个已经被挂起的USB设备时调用此函数*/ 

    int ( * pre_reset) ( struct usb_interface * intf) ; 
    /*在设备被复位之前由usb_reset_composite_device()调用*/ 
    int ( * post_reset) ( struct usb_interface * intf) ; 
    /*在设备被复位之后由usb_reset_composite_device()调用*/ 

    const struct usb_device_id * id_table; 
    /*指向 struct usb_device_id 表的指针*/ 

    struct usb_dynids dynids; 
    struct usbdrv_wrap drvwrap; 
    /*是struct device_driver driver的再包装,struct device_driver 包含 struct module *owner;*/ 
    unsigned int no_dynamic_id: 1; 
    unsigned int supports_autosuspend: 1; 
    unsigned int soft_unbind: 1; 
} ; 
# define     to_usb_driver( d) container_of( d, struct usb_driver, drvwrap. driver)

static struct usb_driver skel_driver = { 
 . name = "skeleton" , 
 . id_table = skel_table, 
 . probe = skel_probe, 
 . disconnect = skel_disconnect, 
} ;

//向 USB 核心注册 struct usb_driver 
static int __init usb_skel_init( void ) 
{ 
        int result; 
        /* register this driver with the USB subsystem */ 
        result = usb_register( & skel_driver) ; 
        if ( result) 
                err( "usb_register failed. Error number %d" , result) ; 
        return result; 
} 

/*当 USB 驱动被卸载, struct usb_driver 需要从内核注销(代码如下). 当以下调用发生, 当前绑定到这个驱动的任何 USB 接口将会断开, 并调用断开函数*/ 
static void __exit usb_skel_exit( void ) 
{ 
        /* deregister this driver with the USB subsystem */ 
        usb_deregister( & skel_driver) ; 
}

    /* set up the endpoint information */ 
    /* use only the first bulk-in and bulk-out endpoints */ 
    iface_desc = interface- > cur_altsetting;         //从输入的interface中提取当前接口的端点总数 
    for ( i = 0; i < iface_desc- > desc. bNumEndpoints; + + i) {         
    /*轮询所有端点*/ 
        endpoint = & iface_desc- > endpoint[ i] . desc;     //获得端点的数据结构指针

        if ( ! dev- > bulk_in_endpointAddr & & 
         usb_endpoint_is_bulk_in( endpoint) ) {     //如果是批量输入端点，
            /* we found a bulk in endpoint */ 
            buffer_size = le16_to_cpu( endpoint- > wMaxPacketSize) ; 
            dev- > bulk_in_size = buffer_size;     //获得端点大小 
            dev- > bulk_in_endpointAddr = endpoint- > bEndpointAddress;     //获得端点地址 
            dev- > bulk_in_buffer = kmalloc( buffer_size, GFP_KERNEL) ;     //为此端点创建缓冲区

            if ( ! dev- > bulk_in_buffer) { 
                err( "Could not allocate bulk_in_buffer" ) ; 
                goto error ; 
            } 
        } 

        if ( ! dev- > bulk_out_endpointAddr & & 
         usb_endpoint_is_bulk_out( endpoint) ) {     如果是批量输出端点
            /* we found a bulk out endpoint */ 
            dev- > bulk_out_endpointAddr = endpoint- > bEndpointAddress;     //获得端点地址 
        } 
    } 
    if ( ! ( dev- > bulk_in_endpointAddr & & dev- > bulk_out_endpointAddr) ) {     //如果不是这两种端点，报错 
        err( "Could not find both bulk-in and bulk-out endpoints" ) ; 
        goto error ; 
    } 

//这里端点判断的函数给我们的编程带来了方便： 
/*-------------------------------------------------------------------------*/ 
/**
 * usb_endpoint_num - get the endpoint's number
 * @epd: endpoint to be checked
 *
 * Returns @epd's number: 0 to 15.
 */ 
static inline int usb_endpoint_num( const struct usb_endpoint_descriptor * epd) 
{ 
    return epd- > bEndpointAddress & USB_ENDPOINT_NUMBER_MASK; 
} 

/**
 * usb_endpoint_type - get the endpoint's transfer type
 * @epd: endpoint to be checked
 *
 * Returns one of USB_ENDPOINT_XFER_{CONTROL, ISOC, BULK, INT} according
 * to @epd's transfer type.
 */ 
static inline int usb_endpoint_type( const struct usb_endpoint_descriptor * epd) 
{ 
    return epd- > bmAttributes & USB_ENDPOINT_XFERTYPE_MASK; 
} 

/**
 * usb_endpoint_dir_in - check if the endpoint has IN direction
 * @epd: endpoint to be checked
 *
 * Returns true if the endpoint is of type IN, otherwise it returns false.
 */ 
static inline int usb_endpoint_dir_in( const struct usb_endpoint_descriptor * epd) 
{ 
    return ( ( epd- > bEndpointAddress & USB_ENDPOINT_DIR_MASK) = = USB_DIR_IN) ; 
} 

/**
 * usb_endpoint_dir_out - check if the endpoint has OUT direction
 * @epd: endpoint to be checked
 *
 * Returns true if the endpoint is of type OUT, otherwise it returns false.
 */ 
static inline int usb_endpoint_dir_out( 
                const struct usb_endpoint_descriptor * epd) 
{ 
    return ( ( epd- > bEndpointAddress & USB_ENDPOINT_DIR_MASK) = = USB_DIR_OUT) ; 
} 

/**
 * usb_endpoint_xfer_bulk - check if the endpoint has bulk transfer type
 * @epd: endpoint to be checked
 *
 * Returns true if the endpoint is of type bulk, otherwise it returns false.
 */ 
static inline int usb_endpoint_xfer_bulk( 
                const struct usb_endpoint_descriptor * epd) 
{ 
    return ( ( epd- > bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) = = 
        USB_ENDPOINT_XFER_BULK) ; 
} 

/**
 * usb_endpoint_xfer_control - check if the endpoint has control transfer type
 * @epd: endpoint to be checked
 *
 * Returns true if the endpoint is of type control, otherwise it returns false.
 */ 
static inline int usb_endpoint_xfer_control( 
                const struct usb_endpoint_descriptor * epd) 
{ 
    return ( ( epd- > bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) = = 
        USB_ENDPOINT_XFER_CONTROL) ; 
} 

/**
 * usb_endpoint_xfer_int - check if the endpoint has interrupt transfer type
 * @epd: endpoint to be checked
 *
 * Returns true if the endpoint is of type interrupt, otherwise it returns
 * false.
 */ 
static inline int usb_endpoint_xfer_int( 
                const struct usb_endpoint_descriptor * epd) 
{ 
    return ( ( epd- > bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) = = 
        USB_ENDPOINT_XFER_INT) ; 
} 

/**
 * usb_endpoint_xfer_isoc - check if the endpoint has isochronous transfer type
 * @epd: endpoint to be checked
 *
 * Returns true if the endpoint is of type isochronous, otherwise it returns
 * false.
 */ 
static inline int usb_endpoint_xfer_isoc( 
                const struct usb_endpoint_descriptor * epd) 
{ 
    return ( ( epd- > bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) = = 
        USB_ENDPOINT_XFER_ISOC) ; 
} 

/**
 * usb_endpoint_is_bulk_in - check if the endpoint is bulk IN
 * @epd: endpoint to be checked
 *
 * Returns true if the endpoint has bulk transfer type and IN direction,
 * otherwise it returns false.
 */ 
static inline int usb_endpoint_is_bulk_in( 
                const struct usb_endpoint_descriptor * epd) 
{ 
    return ( usb_endpoint_xfer_bulk( epd) & & usb_endpoint_dir_in( epd) ) ; 
} 

/**
 * usb_endpoint_is_bulk_out - check if the endpoint is bulk OUT
 * @epd: endpoint to be checked
 *
 * Returns true if the endpoint has bulk transfer type and OUT direction,
 * otherwise it returns false.
 */ 
static inline int usb_endpoint_is_bulk_out( 
                const struct usb_endpoint_descriptor * epd) 
{ 
    return ( usb_endpoint_xfer_bulk( epd) & & usb_endpoint_dir_out( epd) ) ; 
} 

/**
 * usb_endpoint_is_int_in - check if the endpoint is interrupt IN
 * @epd: endpoint to be checked
 *
 * Returns true if the endpoint has interrupt transfer type and IN direction,
 * otherwise it returns false.
 */ 
static inline int usb_endpoint_is_int_in( 
                const struct usb_endpoint_descriptor * epd) 
{ 
    return ( usb_endpoint_xfer_int( epd) & & usb_endpoint_dir_in( epd) ) ; 
} 

/**
 * usb_endpoint_is_int_out - check if the endpoint is interrupt OUT
 * @epd: endpoint to be checked
 *
 * Returns true if the endpoint has interrupt transfer type and OUT direction,
 * otherwise it returns false.
 */ 
static inline int usb_endpoint_is_int_out( 
                const struct usb_endpoint_descriptor * epd) 
{ 
    return ( usb_endpoint_xfer_int( epd) & & usb_endpoint_dir_out( epd) ) ; 
} 

/**
 * usb_endpoint_is_isoc_in - check if the endpoint is isochronous IN
 * @epd: endpoint to be checked
 *
 * Returns true if the endpoint has isochronous transfer type and IN direction,
 * otherwise it returns false.
 */ 
static inline int usb_endpoint_is_isoc_in( 
                const struct usb_endpoint_descriptor * epd) 
{ 
    return ( usb_endpoint_xfer_isoc( epd) & & usb_endpoint_dir_in( epd) ) ; 
} 

/**
 * usb_endpoint_is_isoc_out - check if the endpoint is isochronous OUT
 * @epd: endpoint to be checked
 *
 * Returns true if the endpoint has isochronous transfer type and OUT direction,
 * otherwise it returns false.
 */ 
static inline int usb_endpoint_is_isoc_out( 
                const struct usb_endpoint_descriptor * epd) 
{ 
    return ( usb_endpoint_xfer_isoc( epd) & & usb_endpoint_dir_out( epd) ) ; 
} 

/*-------------------------------------------------------------------------*/

    /* save our data pointer in this interface device */ 
    usb_set_intfdata( interface, dev) ;

    /* we can register the device now, as it is ready */ 
    retval = usb_register_dev( interface, & skel_class) ; 
    if ( retval) { 
        /* something prevented us from registering this driver */ 
        err( "Not able to get a minor for this device." ) ; 
        usb_set_intfdata( interface, NULL ) ; 
        goto error ; 
    } 

//其中使用到的 struct usb_class_driver 结构体如下： 
/**
 * struct usb_class_driver - identifies a USB driver that wants to use the USB major number
 * @name: the usb class device name for this driver. Will show up in sysfs.
 * @fops: pointer to the struct file_operations of this driver.
 * @minor_base: the start of the minor range for this driver.
 *
 * This structure is used for the usb_register_dev() and
 * usb_unregister_dev() functions, to consolidate a number of the
 * parameters used for them.
 */ 
struct usb_class_driver { 
    char * name;      //sysfs 用来描述设备的名字

    const struct file_operations * fops;      // struct file_operations 结构指针, 驱动定义来注册为字符设备 
    int minor_base; 
     /*给这个驱动安排的次设备号的起始. 所有和这个驱动相关的设备被创建为从这个值开始的唯一的, 递增的次设备号. 只有 16 个设备被允许在任何时刻和这个驱动关联, 除非 CONFIG_USB_DYNAMIC_MINORS 配置选项被打开. 如

果这样, 忽略这个变量, 并且这个设备的所有的次设备号会以先来先服务的方式分配. 建议打开了这个选项的系统使用类似 udev 的程序来产生系统中的设备节点, 因为一个静态的 /dev 树不会正确工作.*/ 
} ; 

//而在usb-skeleton的设置如下： 
static const struct file_operations skel_fops = { 
    . owner =     THIS_MODULE, 
    . read =         skel_read, 
    . write =     skel_write, 
    . open =         skel_open, 
    . release =     skel_release, 
    . flush =     skel_flush, 
} ; 
/*
 * usb class driver info in order to get a minor number from the usb core,
 * and to have the device registered with the driver core
 */ 
static struct usb_class_driver skel_class = { 
    . name =         "skel%d" , 
    . fops =         & skel_fops, 
    . minor_base =     USB_SKEL_MINOR_BASE, 
} ;

static void skel_disconnect( struct usb_interface * interface) 
{ 
    struct usb_skel * dev; 
    int minor = interface- > minor; 

    dev = usb_get_intfdata( interface) ; 
    usb_set_intfdata( interface, NULL ) ; 

    /* give back our minor */ 
    usb_deregister_dev( interface, & skel_class) ; 

    /* prevent more I/O from starting */ 
    mutex_lock( & dev- > io_mutex) ; 
    dev- > interface = NULL ; 
    mutex_unlock( & dev- > io_mutex) ; 

    usb_kill_anchored_urbs( & dev- > submitted) ; 

    /* decrement our usage count */ 
    kref_put( & dev- > kref, skel_delete) ; 

    info( "USB Skeleton #%d now disconnected" , minor) ; 
}

static ssize_t skel_write( struct file * file , const char * user_buffer, size_t count , loff_t * ppos) 
{ 
    struct usb_skel * dev; 
    int retval = 0; 
    struct urb * urb = NULL ; 
    char * buf = NULL ; 
    size_t writesize = min ( count , ( size_t ) MAX_TRANSFER) ; 

    dev = ( struct usb_skel * ) file - > private_data; 

    /* verify that we actually have some data to write */ 
    if ( count = = 0) 
        goto exit ; 

    /* limit the number of URBs in flight to stop a user from using up all RAM */ 
    if ( down_interruptible( & dev- > limit_sem) ) { 
        retval = - ERESTARTSYS; 
        goto exit ; 
    } 

    spin_lock_irq( & dev- > err_lock) ; 
    if ( ( retval = dev- > errors) < 0) { 
        /* any error is reported once */ 
        dev- > errors = 0; 
        /* to preserve notifications about reset */ 
        retval = ( retval = = - EPIPE) ? retval : - EIO; 
    } 
    spin_unlock_irq( & dev- > err_lock) ; 
    if ( retval < 0) 
        goto error ; 

    /* create a urb, and a buffer for it, and copy the data to the urb */ 
    /*当驱动有数据发送到 USB 设备，首先分配一个 urb */ 
    urb = usb_alloc_urb( 0, GFP_KERNEL) ; 
    if ( ! urb) { 
        retval = - ENOMEM; 
        goto error ; 
    } 

    /*以最有效的方式是创建一个 DMA 缓冲区来发送数据到设备, 并拷贝数据到缓冲区*/ 
    buf = usb_buffer_alloc( dev- > udev, writesize, GFP_KERNEL, & urb- > transfer_dma) ; 
    if ( ! buf) { 
        retval = - ENOMEM; 
        goto error ; 
    } 

    if ( copy_from_user( buf, user_buffer, writesize) ) { 
        retval = - EFAULT; 
        goto error ; 
    } 

    /* this lock makes sure we don't submit URBs to gone devices */ 
    mutex_lock( & dev- > io_mutex) ; 
    if ( ! dev- > interface) {         /* disconnect() was called */ 
        mutex_unlock( & dev- > io_mutex) ; 
        retval = - ENODEV; 
        goto error ; 
    } 

    /* initialize the urb properly */ 
    /*在将urb提交给 USB 核心之前，正确初始化 urb */ 
    usb_fill_bulk_urb( urb, dev- > udev, 
             usb_sndbulkpipe( dev- > udev, dev- > bulk_out_endpointAddr) , 
             buf, writesize, skel_write_bulk_callback, dev) ; 
    urb- > transfer_flags | = URB_NO_TRANSFER_DMA_MAP; 
    usb_anchor_urb( urb, & dev- > submitted) ; 

    /* send the data out the bulk port */ 
    /*提交 urb 给 USB 核心, 由它将 urb 传递给设备*/ 
    retval = usb_submit_urb( urb, GFP_KERNEL) ; 
    mutex_unlock( & dev- > io_mutex) ; 
    if ( retval) { 
        err( "%s - failed submitting write urb, error %d" , __func__ , retval) ; 
        goto error_unanchor; 
    } 

    /* release our reference to this urb, the USB core will eventually free it entirely */ 
    usb_free_urb( urb) ; 


    return writesize; 

error_unanchor: 
    usb_unanchor_urb( urb) ; 
error : 
    if ( urb) { 
        usb_buffer_free( dev- > udev, writesize, buf, urb- > transfer_dma) ; 
        usb_free_urb( urb) ; 
    } 
    up( & dev- > limit_sem) ; 

exit : 
    return retval; 
} 

//当urb被成功传递到 USB 设备(或者在传输中发生了错误), urb 回调函数将被 USB 核心调用.也就是上面初始化 urb 中的 skel_write_bulk_callback 
static void skel_write_bulk_callback( struct urb * urb) 
{ 
    struct usb_skel * dev; 

    dev = urb- > context; 

    /* sync/async unlink faults aren't errors */ 
    /*检查 urb 的状态，判断这个 urb 是否成功完成传输*/ 
    if ( urb- > status) { 
        if ( ! ( urb- > status = = - ENOENT | | 
         urb- > status = = - ECONNRESET | | 
         urb- > status = = - ESHUTDOWN) ) 
            err( "%s - nonzero write bulk status received: %d" , 
             __func__ , urb- > status) ; 

        spin_lock( & dev- > err_lock) ; 
        dev- > errors = urb- > status; 
        spin_unlock( & dev- > err_lock) ; 
    } 

    /* free up our allocated buffer */ 
    /*释放分配给这个 urb 的缓冲区.*/ 
    usb_buffer_free( urb- > dev, urb- > transfer_buffer_length, 
            urb- > transfer_buffer, urb- > transfer_dma) ; 
    up( & dev- > limit_sem) ; 
}

int usb_bulk_msg( struct usb_device * usb_dev, unsigned int pipe, 
         void * data, int len, int * actual_length, int timeout) 
/*创建批量 urb 并发送到指定的设备, 接着在返回之前等待完成.*/ 
//struct usb_device *usb_dev :目标 USB 设备指针 
//unsigned int pipe :目标 USB 设备的特定端点. 必须使用特定的宏创建. 
//void *data :如果是 OUT 端点, 指向要发送到设备的数据的指针. 如果是 IN 端点, 这是从设备读取的数据的缓冲区指针. 
//int len : data 参数指向的缓冲的长度 
//int *actual_length :指向函数放置真实字节数的指针,根据端点方向,这些字节要么是被发送到设备的,要么是从设备中读取的. 
//int timeout :时钟嘀哒数, 应等待的时间. 如果为 0, 函数永远等待操作完成. 
//成功返回0,actual_length 参数包含被传送或从设备中读取的字节数.否则返回负的错误值. 

int usb_control_msg( struct usb_device * dev, unsigned int pipe, __u8 request, 
         __u8 requesttype, __u16 value, __u16 index, void * data, 
         __u16 size, int timeout) 
/*创建控制 urb 并发送到指定的设备, 接着在返回之前等待完成.*/ 
//struct usb_device *usb_dev :目标 USB 设备指针 
//unsigned int pipe :目标 USB 设备的特定端点. 必须使用特定的宏创建. 
//__u8 request :控制消息的 USB 请求值. 
//__u8 requesttype :控制消息的 USB 请求类型. 
//__u16 value :控制消息的 USB 消息值. 
//__u16 index :控制消息的 USB 消息索引值. 
//void *data :如果是 OUT 端点, 指向要发送到设备的数据的指针. 如果是 IN 端点, 这是从设备读取的数据的缓冲区指针. 
//__u16 size : data 参数指向的缓冲的长度 
//int timeout :时钟嘀哒数, 应等待的时间. 如果为 0, 函数永远等待操作完成. 
//成功返回被传送到或从设备读取的字节数.否则返回负的错误值. 

int usb_interrupt_msg( struct usb_device * usb_dev, unsigned int pipe, void * data, int len, int * actual_length, int timeout) 
/*创建中断 urb 并发送到指定的设备, 接着在返回之前等待完成.其实就是usb_bulk_msg的包装,所有参数和usb_bulk_msg一样使用*/