usb鼠標驅動

USB 總線引出兩個重要的鏈表！
一個 USB 總線引出兩個重要的鏈表，一個爲 USB 設備鏈表，一個爲 USB 驅動鏈表。設備鏈表包含各種系統中的 USB 設備以及這些設備的所有接口，驅動鏈表包含 USB 設備驅動程序（usb device driver）和 USB 驅動程序（usb driver）。

 

USB 設備驅動程序（usb device driver）和 USB 驅動程序（usb driver）的區別是什麼？
USB 設備驅動程序包含 USB 設備的一些通用特性，將與所有 USB 設備相匹配。在 USB core 定義了：struct usb_device_driver usb_generic_driver。usb_generic_driver 是 USB 子系統中唯一的一個設備驅動程序對象。而 USB 驅動程序則是與接口相匹配，接口是一個完成特定功能的端點的集合。

 

設備是如何添加到設備鏈表上去的？
在設備插入 USB 控制器之後，USB core 即會將設備在系統中註冊，添加到 USB 設備鏈表上去。

 

USB 設備驅動程序（usb device driver）是如何添加到驅動鏈表上去的？
在系統啓動註冊 USB core 時，USB 設備驅動程序即將被註冊，也就添加到驅動鏈表上去了。

 

接口是如何添加到設備鏈表上去的？
在 USB 設備驅動程序和 USB 設備的匹配之後，USB core 會對設備進行配置，分析設備的結構之後會將設備所有接口都添加到設備鏈表上去。比如鼠標設備中有一個接口，USB core 對鼠標設備配置後，會將這個接口添加到設備鏈表上去。

 

USB 驅動程序（usb driver）是如何添加到驅動鏈表上去的？
在每個 USB 驅動程序的被註冊時，USB 驅動程序即會添加到驅動鏈表上去。比如鼠標驅動程序，usb_mouse_init 函數將通過 usb_register(&usb_mouse_driver) 將鼠標驅動程序註冊到 USB core 中，然後就添加到驅動鏈表中去了。其中 usb_mouse_driver 是描述鼠標驅動程序的結構體。

 

已配置狀態（configured status）之後話
當鼠標的設備、接口都添加到設備鏈表，並且鼠標驅動程序也添加到驅動鏈表上去了，系統就進入一種叫做已配置（configured）的狀態。要達到已配置狀態，將經歷複雜的過程，USB core 爲 USB 設備奉獻着無怨無悔。在這個過程中，系統將會建立起該設備的的設備、配置、接口、設置、端點的描述信息，它們分別被 usb_device、usb_configuration、usb_interface、usb_host_interface、usb_host_endpoint 結構體描述。
設備達到已配置狀態後，首先當然就要進行 USB 驅動程序和相應接口的配對，對於鼠標設備來說則是鼠標驅動程序和鼠標中的接口的配對。USB core 會調用 usb_device_match 函數，通過比較設備中的接口信息和 USB 驅動程序中的 id_table，來初步決定該 USB 驅動程序是不是跟相應接口相匹配。通過這一道關卡後，USB core 會認爲這個設備應該由這個驅動程序負責。
然而，僅僅這一步是不夠的，接着，將會調用 USB 驅動程序中的 probe 函數對相應接口進行進一步檢查。如果該驅動程序確實適合設備接口，對設備做一些初始化工作，分配 urb 準備數據傳輸。
當鼠標設備在用戶空間打開時，將提交 probe 函數構建的 urb 請求塊，urb 將開始爲傳送數據而忙碌了。urb 請求塊就像一個裝東西的“袋子”，USB 驅動程序把“空袋子”提交給 USB core，然後再交給主控制器，主控制器把數據放入這個“袋子”後再將裝滿數據的“袋子”通過 USB core 交還給 USB 驅動程序，這樣一次數據傳輸就完成了。

 

以下是完全註釋後的鼠標驅動程序代碼 usbmouse.c

/*
 * $Id: usbmouse.c,v 1.15 2001/12/27 10:37:41 vojtech Exp $
 *
 *  Copyright (c) 1999-2001 Vojtech Pavlik
 *
 *  USB HIDBP Mouse support
 */

#include <linux/kernel.h>
#include <linux/slab.h>
#include <linux/module.h>
#include <linux/init.h>
#include <linux/usb/input.h>
#include <linux/hid.h>

/*
 * Version Information
 */
#define DRIVER_VERSION "v1.6"
#define DRIVER_AUTHOR "Vojtech Pavlik <[email protected]>"
#define DRIVER_DESC "USB HID Boot Protocol mouse driver"
#define DRIVER_LICENSE "GPL"

MODULE_AUTHOR(DRIVER_AUTHOR);
MODULE_DESCRIPTION(DRIVER_DESC);
MODULE_LICENSE(DRIVER_LICENSE);

/*
 * 鼠標結構體，用於描述鼠標設備。
 */
struct usb_mouse
{
    /* 鼠標設備的名稱，包括生產廠商、產品類別、產品等信息 */
    char name[128];
    /* 設備節點名稱 */
    char phys[64];
    /* USB 鼠標是一種 USB 設備，需要內嵌一個 USB 設備結構體來描述其 USB 屬性 */
    struct usb_device *usbdev;
    /* USB 鼠標同時又是一種輸入設備，需要內嵌一個輸入設備結構體來描述其輸入設備的屬性 */
    struct input_dev *dev;
    /* URB 請求包結構體，用於傳送數據 */
    struct urb *irq;
    /* 普通傳輸用的地址 */
    signed char *data;
    /* dma 傳輸用的地址 */
    dma_addr_t data_dma;
};

/*
 * urb 回調函數，在完成提交 urb 後，urb 回調函數將被調用。
 * 此函數作爲 usb_fill_int_urb 函數的形參，爲構建的 urb 制定的回調函數。
 */
static void usb_mouse_irq(struct urb *urb)
{
    /*
     * urb 中的 context 指針用於爲 USB 驅動程序保存一些數據。比如在這個回調函數的形參沒有傳遞在 probe
     * 中爲 mouse 結構體分配的那塊內存的地址指針，而又需要用到那塊內存區域中的數據，context 指針則幫了
     * 大忙了！
     * 在填充 urb 時將 context 指針指向 mouse 結構體數據區，在這又創建一個局部 mouse 指針指向在 probe
     * 函數中爲 mouse 申請的那塊內存，那塊內存保存着非常重要數據。
     * 當 urb 通過 USB core 提交給 hc 之後，如果結果正常，mouse->data 指向的內存區域將保存着鼠標的按鍵
     * 和移動座標信息，系統則依靠這些信息對鼠標的行爲作出反應。
     * mouse 中內嵌的 dev 指針，指向 input_dev 所屬於的內存區域。
     */
    struct usb_mouse *mouse = urb->context;
    signed char *data = mouse->data;
    struct input_dev *dev = mouse->dev;
    int status;

    /*
     * status 值爲 0 表示 urb 成功返回，直接跳出循環把鼠標事件報告給輸入子系統。
     * ECONNRESET 出錯信息表示 urb 被 usb_unlink_urb 函數給 unlink 了，ENOENT 出錯信息表示 urb 被
     * usb_kill_urb 函數給 kill 了。usb_kill_urb 表示徹底結束 urb 的生命週期，而 usb_unlink_urb 則
     * 是停止 urb，這個函數不等 urb 完全終止就會返回給回調函數。這在運行中斷處理程序時或者等待某自旋鎖
     * 時非常有用，在這兩種情況下是不能睡眠的，而等待一個 urb 完全停止很可能會出現睡眠的情況。
     * ESHUTDOWN 這種錯誤表示 USB 主控制器驅動程序發生了嚴重的錯誤，或者提交完 urb 的一瞬間設備被拔出。
     * 遇見除了以上三種錯誤以外的錯誤，將申請重傳 urb。
     */
    switch (urb->status)
    {
    case 0:     /* success */
        break;
    case -ECONNRESET:   /* unlink */
    case -ENOENT:
    case -ESHUTDOWN:
        return;
    /* -EPIPE:  should clear the halt */
    default:        /* error */
        goto resubmit;
    }

    /*
     * 向輸入子系統彙報鼠標事件情況，以便作出反應。
     * data 數組的第0個字節：bit 0、1、2、3、4分別代表左、右、中、SIDE、EXTRA鍵的按下情況；
     * data 數組的第1個字節：表示鼠標的水平位移；
     * data 數組的第2個字節：表示鼠標的垂直位移；
     * data 數組的第3個字節：REL_WHEEL位移。
     */
    input_report_key(dev, BTN_LEFT,   data[0] & 0x01);
    input_report_key(dev, BTN_RIGHT,  data[0] & 0x02);
    input_report_key(dev, BTN_MIDDLE, data[0] & 0x04);
    input_report_key(dev, BTN_SIDE,   data[0] & 0x08);
    input_report_key(dev, BTN_EXTRA,  data[0] & 0x10);
    input_report_rel(dev, REL_X,     data[1]);
    input_report_rel(dev, REL_Y,     data[2]);
    input_report_rel(dev, REL_WHEEL, data[3]);

    /*
     * 這裏是用於事件同步。上面幾行是一次完整的鼠標事件，包括按鍵信息、絕對座標信息和滾輪信息，輸入子
     * 系統正是通過這個同步信號來在多個完整事件報告中區分每一次完整事件報告。示意如下：
     * 按鍵信息 座標位移信息 滾輪信息 EV_SYC | 按鍵信息 座標位移信息 滾輪信息 EV_SYC ...
     */
    input_sync(dev);

    /*
     * 系統需要週期性不斷地獲取鼠標的事件信息，因此在 urb 回調函數的末尾再次提交 urb 請求塊，這樣又會
     * 調用新的回調函數，週而復始。
     * 在回調函數中提交 urb 一定只能是 GFP_ATOMIC 優先級的，因爲 urb 回調函數運行於中斷上下文中，在提
     * 交 urb 過程中可能會需要申請內存、保持信號量，這些操作或許會導致 USB core 睡眠，一切導致睡眠的行
     * 爲都是不允許的。
     */
resubmit:
    status = usb_submit_urb (urb, GFP_ATOMIC);
    if (status)
        err ("can't resubmit intr, %s-%s/input0, status %d",
                mouse->usbdev->bus->bus_name,
                mouse->usbdev->devpath, status);
}

/*
 * 打開鼠標設備時，開始提交在 probe 函數中構建的 urb，進入 urb 週期。
 */
static int usb_mouse_open(struct input_dev *dev)
{
    struct usb_mouse *mouse = dev->private;

    mouse->irq->dev = mouse->usbdev;
    if (usb_submit_urb(mouse->irq, GFP_KERNEL))
        return -EIO;

    return 0;
}

/*
 * 關閉鼠標設備時，結束 urb 生命週期。
 */
static void usb_mouse_close(struct input_dev *dev)
{
    struct usb_mouse *mouse = dev->private;

    usb_kill_urb(mouse->irq);
}

/*
 * 驅動程序的探測函數
 */
static int usb_mouse_probe(struct usb_interface *intf, const struct usb_device_id *id)
{
    /*
     * 接口結構體包含於設備結構體中，interface_to_usbdev 是通過接口結構體獲得它的設備結構體。
     * usb_host_interface 是用於描述接口設置的結構體，內嵌在接口結構體 usb_interface 中。
     * usb_endpoint_descriptor 是端點描述符結構體，內嵌在端點結構體 usb_host_endpoint 中，而端點
     * 結構體內嵌在接口設置結構體中。
     */
    struct usb_device *dev = interface_to_usbdev(intf);
    struct usb_host_interface *interface;
    struct usb_endpoint_descriptor *endpoint;
    struct usb_mouse *mouse;
    struct input_dev *input_dev;
    int pipe, maxp;

    interface = intf->cur_altsetting;

    /* 鼠標僅有一個 interrupt 類型的 in 端點，不滿足此要求的設備均報錯 */
    if (interface->desc.bNumEndpoints != 1)
        return -ENODEV;

    endpoint = &interface->endpoint[0].desc;
    if (!usb_endpoint_is_int_in(endpoint))
        return -ENODEV;

    /*
     * 返回對應端點能夠傳輸的最大的數據包，鼠標的返回的最大數據包爲4個字節，數據包具體內容在 urb
     * 回調函數中有詳細說明。
     */
    pipe = usb_rcvintpipe(dev, endpoint->bEndpointAddress);
    maxp = usb_maxpacket(dev, pipe, usb_pipeout(pipe));

    /* 爲 mouse 設備結構體分配內存 */
    mouse = kzalloc(sizeof(struct usb_mouse), GFP_KERNEL);
    /* input_dev */
    input_dev = input_allocate_device();
    if (!mouse || !input_dev)
        goto fail1;

    /*
     * 申請內存空間用於數據傳輸，data 爲指向該空間的地址，data_dma 則是這塊內存空間的 dma 映射，
     * 即這塊內存空間對應的 dma 地址。在使用 dma 傳輸的情況下，則使用 data_dma 指向的 dma 區域，
     * 否則使用 data 指向的普通內存區域進行傳輸。
     * GFP_ATOMIC 表示不等待，GFP_KERNEL 是普通的優先級，可以睡眠等待，由於鼠標使用中斷傳輸方式，
     * 不允許睡眠狀態，data 又是週期性獲取鼠標事件的存儲區，因此使用 GFP_ATOMIC 優先級，如果不能
     * 分配到內存則立即返回 0。
     */
    mouse->data = usb_buffer_alloc(dev, 8, GFP_ATOMIC, &mouse->data_dma);
    if (!mouse->data)
        goto fail1;

    /*
     * 爲 urb 結構體申請內存空間，第一個參數表示等時傳輸時需要傳送包的數量，其它傳輸方式則爲0。
     * 申請的內存將通過下面即將見到的 usb_fill_int_urb 函數進行填充。
     */
    mouse->irq = usb_alloc_urb(0, GFP_KERNEL);
    if (!mouse->irq)
        goto fail2;

    /* 填充 usb 設備結構體和輸入設備結構體 */
    mouse->usbdev = dev;
    mouse->dev = input_dev;

    /* 獲取鼠標設備的名稱 */
    if (dev->manufacturer)
        strlcpy(mouse->name, dev->manufacturer, sizeof(mouse->name));

    if (dev->product)
    {
        if (dev->manufacturer)
            strlcat(mouse->name, " ", sizeof(mouse->name));
        strlcat(mouse->name, dev->product, sizeof(mouse->name));
    }

    if (!strlen(mouse->name))
        snprintf(mouse->name, sizeof(mouse->name),
             "USB HIDBP Mouse %04x:%04x",
             le16_to_cpu(dev->descriptor.idVendor),
             le16_to_cpu(dev->descriptor.idProduct));

    /*
     * 填充鼠標設備結構體中的節點名。usb_make_path 用來獲取 USB 設備在 Sysfs 中的路徑，格式
     * 爲：usb-usb 總線號-路徑名。
     */
    usb_make_path(dev, mouse->phys, sizeof(mouse->phys));
    strlcat(mouse->phys, "/input0", sizeof(mouse->phys));

    /* 將鼠標設備的名稱賦給鼠標設備內嵌的輸入子系統結構體 */
    input_dev->name = mouse->name;
    /* 將鼠標設備的設備節點名賦給鼠標設備內嵌的輸入子系統結構體 */
    input_dev->phys = mouse->phys;
    /*
     * input_dev 中的 input_id 結構體，用來存儲廠商、設備類型和設備的編號，這個函數是將設備描述符
     * 中的編號賦給內嵌的輸入子系統結構體
     */
    usb_to_input_id(dev, &input_dev->id);
    /* cdev 是設備所屬類別（class device） */
    input_dev->cdev.dev = &intf->dev;

    /* evbit 用來描述事件，EV_KEY 是按鍵事件，EV_REL 是相對座標事件 */
    input_dev->evbit[0] = BIT(EV_KEY) | BIT(EV_REL);
    /* keybit 表示鍵值，包括左鍵、右鍵和中鍵 */
    input_dev->keybit[LONG(BTN_MOUSE)] = BIT(BTN_LEFT) | BIT(BTN_RIGHT) | BIT(BTN_MIDDLE);
    /* relbit 用於表示相對座標值 */
    input_dev->relbit[0] = BIT(REL_X) | BIT(REL_Y);
    /* 有的鼠標還有其它按鍵 */
    input_dev->keybit[LONG(BTN_MOUSE)] |= BIT(BTN_SIDE) | BIT(BTN_EXTRA);
    /* 中鍵滾輪的滾動值 */
    input_dev->relbit[0] |= BIT(REL_WHEEL);

    /* input_dev 的 private 數據項用於表示當前輸入設備的種類，這裏將鼠標結構體對象賦給它 */
    input_dev->private = mouse;
    /* 填充輸入設備打開函數指針 */
    input_dev->open = usb_mouse_open;
    /* 填充輸入設備關閉函數指針 */
    input_dev->close = usb_mouse_close;

    /*
     * 填充構建 urb，將剛纔填充好的 mouse 結構體的數據填充進 urb 結構體中，在 open 中遞交 urb。
     * 當 urb 包含一個即將傳輸的 DMA 緩衝區時應該設置 URB_NO_TRANSFER_DMA_MAP。USB核心使用
     * transfer_dma變量所指向的緩衝區，而不是transfer_buffer變量所指向的。
     * URB_NO_SETUP_DMA_MAP 用於 Setup 包，URB_NO_TRANSFER_DMA_MAP 用於所有 Data 包。
     */
    usb_fill_int_urb(mouse->irq, dev, pipe, mouse->data,
             (maxp > 8 ? 8 : maxp),
             usb_mouse_irq, mouse, endpoint->bInterval);
    mouse->irq->transfer_dma = mouse->data_dma;
    mouse->irq->transfer_flags |= URB_NO_TRANSFER_DMA_MAP;

    /* 向系統註冊輸入設備 */
    input_register_device(mouse->dev);

    /*
     * 一般在 probe 函數中，都需要將設備相關信息保存在一個 usb_interface 結構體中，以便以後通過
     * usb_get_intfdata 獲取使用。這裏鼠標設備結構體信息將保存在 intf 接口結構體內嵌的設備結構體中
     * 的 driver_data 數據成員中，即 intf->dev->dirver_data = mouse。
     */
    usb_set_intfdata(intf, mouse);
    return 0;

fail2:  usb_buffer_free(dev, 8, mouse->data, mouse->data_dma);
fail1:  input_free_device(input_dev);
    kfree(mouse);
    return -ENOMEM;
}

/*
 * 鼠標設備拔出時的處理函數
 */
static void usb_mouse_disconnect(struct usb_interface *intf)
{
    /* 獲取鼠標設備結構體 */
    struct usb_mouse *mouse = usb_get_intfdata (intf);

    /* intf->dev->dirver_data = NULL，將接口結構體中的鼠標設備指針置空。*/
    usb_set_intfdata(intf, NULL);
    if (mouse)
    {
        /* 結束 urb 生命週期 */
        usb_kill_urb(mouse->irq);
        /* 將鼠標設備從輸入子系統中註銷 */
        input_unregister_device(mouse->dev);
        /* 釋放 urb 存儲空間 */
        usb_free_urb(mouse->irq);
        /* 釋放存放鼠標事件的 data 存儲空間 */
        usb_buffer_free(interface_to_usbdev(intf), 8, mouse->data, mouse->data_dma);
        /* 釋放存放鼠標結構體的存儲空間 */
        kfree(mouse);
    }
}

/*
 * usb_device_id 結構體用於表示該驅動程序所支持的設備，USB_INTERFACE_INFO 可以用來匹配特定類型的接口，
 * 這個宏的參數意思爲 (類別, 子類別, 協議)。
 * USB_INTERFACE_CLASS_HID 表示是一種 HID (Human Interface Device)，即人機交互設備類別；
 * USB_INTERFACE_SUBCLASS_BOOT 是子類別，表示是一種 boot 階段使用的 HID；
 * USB_INTERFACE_PROTOCOL_MOUSE 表示是鼠標設備，遵循鼠標的協議。
 */
static struct usb_device_id usb_mouse_id_table [] = {
    { USB_INTERFACE_INFO(USB_INTERFACE_CLASS_HID, USB_INTERFACE_SUBCLASS_BOOT,
        USB_INTERFACE_PROTOCOL_MOUSE) },
    { } /* Terminating entry */
};

/*
 * 這個宏用來讓運行在用戶空間的程序知道這個驅動程序能夠支持的設備，對於 USB 驅動程序來說，第一個參數必須
 * 是 usb。
 */
MODULE_DEVICE_TABLE (usb, usb_mouse_id_table);

/*
 * 鼠標驅動程序結構體
 */
static struct usb_driver usb_mouse_driver = {
    .name       = "usbmouse",
    .probe      = usb_mouse_probe,
    .disconnect = usb_mouse_disconnect,
    .id_table   = usb_mouse_id_table,
};

/*
 * 驅動程序生命週期的開始點，向 USB core 註冊這個鼠標驅動程序。
 */
static int __init usb_mouse_init(void)
{
    int retval = usb_register(&usb_mouse_driver);
    if (retval == 0)
        info(DRIVER_VERSION ":" DRIVER_DESC);
    return retval;
}

/*
 * 驅動程序生命週期的結束點，向 USB core 註銷這個鼠標驅動程序。
 */
static void __exit usb_mouse_exit(void)
{
    usb_deregister(&usb_mouse_driver);
}

module_init(usb_mouse_init);
module_exit(usb_mouse_exit);