Message-ID: <44C46F5B.8080506@ccoss.com.cn>
Date:	Mon, 24 Jul 2006 14:57:31 +0800
From:	liyu <liyu@...ss.com.cn>
To:	Peter <peter@...bp.freeserve.co.uk>,
	thedoctor@...dis.homelinux.org,
	LKML <linux-kernel@...r.kernel.org>, Greg KH <greg@...ah.com>
Subject: [PATCH] USBHID: HID device simple driver interface

==================================
HID device simple driver interface
==================================

------------------------
Version
------------------------

    This is the second version, this patch can apply on 2.6.17.6 kernel 
tree.

    The last version can find here:

        http://www.gossamer-threads.com/lists/linux/kernel/603843.

    I am sorry I just see Greg KH reply. The traffic of LKML is so great :)

------------------------
Goal
------------------------

    Let us write HID device driver more easier.


------------------------
Basic idea
------------------------

    Under current HID device driver development technique, We need write 
one new interrupt handler for each new HID device to report event to 
input subsystem. However, the most of them have only some extended keys, 
e.g. many remote controllers. I think it seem break a fly on the wheel, 
which write one new interrupt handler for this reason.
    My idea is reuse the interrupt handler in hid-core.c. so  writing 
driver for new simple HID device will be more easier, quickly, and need 
not touch hid core.
    In essence, this interface just is some hooks in HID core.
        
------------------------
Limitation
------------------------
    
    In the last version of this interface, Each driver use this 
interface only can work with one device at same time. As the Greg KH 
words, this limitation make this interface too useless. e.g. we often 
can find there are two joysticks connected with one host. In this 
version, the driver can work with more than one device at same time. 
However, I still do not recommend you use this interface, if your driver 
need handle a lot of devices (e.g. more than 20) at same time, beacause 
of I used simple algorithm to search/insert/delete each device.
    
    This interface can not support the more drivers handle one device at 
same time yet. I can not sure if we need this feature? What do you 
think, Greg KH?


------------------------    
Testing
------------------------

    Tested on i386.

        
------------------------
The driver use this interface
------------------------
    
    I wrote a driver for MS Natural Ergonomic Keyboard 4000. This driver 
also get some improvements for this new version simple driver interface:
    
    1. These five "My Favorites" keys map FN_F{1,2,3,4,5}_KEY directly, 
instead of map them to KEY_VENDOR hacking means.
    2. Support left paren key "(", right paren key ")", equal key "=" on 
right-top keypad. In fact, this keyboard generate KEYPAD_XXX usage code 
for them, but I find many applications can not handle them on default 
configuration, especially X.org. To get the most best usability, I use a 
bit magic here: map them to "Shift+9" and "Shift+0".

------------------------
Usage
------------------------    

    Although this simple driver have not direct relation with Linux 
device driver architecture, but I still make its API like it on purpose.

    The simple driver have five methods:

1.    int (*connect)(struct hid_device *, struct hid_input *);
2.    void (*disconnect)(struct hid_device *, struct hid_input *);

    When you simple driver is to bind with one real HID device, we will 
call connect() method first. To return 0 flag if it complete its mission 
successfully, so we can continue, return any other value is looked as 
error. any thing do not happen.
    When the HID device that your simple driver connect with is down, or 
you unregister this simple driver, we will call disconnect() method, it 
have none return value.
    Note: the these method may be called more times on one device. 
beacause of some device will yield more than one hid_device/hid_input 
instances. of course, you can ignore them that you do not interest.
    
3.    void (*setup_usage)(struct hid_field *,   struct hid_usage *);
4.    void (*clear_usage)(struct hid_field *,   struct hid_usage *);
    
    The setup_usage() method is like hidinput_configure_usage() in 
hid_input.c. You also can setup input_dev here. In most time, I think 
you should be fill the pointer slot for this method, elsewise the 
event() method do not work for you at all. Please see example in "MS 
Natural Ergonomic Keyboard 4000" driver.
    The clear_usage() method is used to clear side-effect that came from 
setup_usage() method, if they are there. Of course, you can do same 
things in disconnect() method, but this method let your life more 
simpler.    

6.    int (*pre_event)(const struct hid_device *, const struct hid_field 
*, const struct hid_usage *, const __s32, const struct pt_regs *regs);

    First, you can use this method send event to input subsystem, 
moreover, you can use this as one usage code filter: if it return 
non-zero , any event handling method do not be called , even the 
hidinput_hid_event().
    If this method return zero, the normally event handling process will 
continue.
    Note again, if you do not correctly configure usage in 
setup_usage(), this method do not work as you want.

7.    void (*post_event)(const struct hid_device *, const struct 
hid_field *, const struct hid_usage *, const __s32, const struct pt_regs 
*regs);

    Its behavior like with hidinput_hid_event() exactly. but if 
pre_event() return non-zero value, this method also do not called at all.
    Note again, if you do not correctly configure usage in 
setup_usage(), this method do not work as you want.
    This method have not return value.
    
    All these methods are optional, but if they are all NULL pointers, 
what are you want? If you do not supply one method, We see as it 
complete its task successfully.

    For detailed usage, you can find out in the MS Natural Ergonomic 
Keyboard 4000 driver , usbnek4k.c. it is in my other patch.

------------------------
The most simplest demo
------------------------

/* NOTE: As another HID driver, you must place this source in 
drivers/usb/input directory before build it. */
#include <linux/kernel.h>
#include <linux/input.h>
#include "hid.h"
#include "hid-simple.h"
 
#define VENDOR_ID 0x1234
#define PRODUCT_ID 0x5678
 
static struct usb_device_id my_id_table[] = {
        { USB_DEVICE(VENDOR_ID, PRODUCT_ID) },
        {}
};
 
static int process_your_device_input_event(const struct hid_device *hid, 
const struct hid_field *field, const struct hid_usage * usage, const 
__s32 value, const struct pt_regs *regs)
{
        struct hid_input *hidinput = field->hidinput;
        struct input_dev *input = hidinput->input;
 
        /* send event that you want to send to input subsystem here */
        return 0;
}
 
static struct hidinput_simple_driver nek4k_driver = {
        .name = "DEMO",
        .pre_event = process_your_device_input_event,
        .id_table = my_id_table,
};
 
static int __init nek4k_init(void)
{
        int result;
 
        result = hidinput_register_simple_driver(&nek4k_driver);
 
        switch (result) {
                case 0:
                        return 0;
                default:
                        return -ENODEV;
        };
}
                                                                                                  
 
static void __exit nek4k_exit(void)
{
        hidinput_unregister_simple_driver(&nek4k_driver);
}
                                                                                                  
 
module_init(nek4k_init);
module_exit(nek4k_exit);
/* demo end */
------------------------
post_event()
------------------------

    The last words that I want to say are sorry, this new version have 
not compatibility with the last version.
        
    Good luck.
    
EOF.


View attachment "usbnek4k.patch" of type "text/x-patch" (12136 bytes)

View attachment "simple.patch" of type "text/x-patch" (17802 bytes)

Powered by blists - more mailing lists