--- linux-2.6.17.7/Documentation/input/simple-hid.txt.noexist
1970-01-01 08:00:00.000000000 +0800
+++ linux-2.6.17.7/Documentation/input/simple-hid.txt 2006-08-17
20:24:36.000000000 +0800
@@ -0,0 +1,236 @@
+==================================
+HID device simple driver interface
+==================================
+
+------------------------
+Version
+------------------------
+
+ This is the version 0.3.1
+
+--------------------------
+Overview
+--------------------------
+
+ Under current HID device driver development means, We need write
+one new interrupt handler for each new HID device to report event to
+input subsystem. However, although the most of they can not merge into
+mainstream kernel tree, they 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 basic idea is reuse the interrupt handler in hid-core.c. so writing
+driver for new simple HID device will be more easier, quickly, and do not
+need touch hid core.
+
+ In essence, this interface just is some hooks in HID input core.
+
+ The hid-simple.h include this API. Before you use this interface,
you must
+include hid.h first.
+
+------------------------
+What's you will get from this interface.
+------------------------
+
+ Use me, you can:
+
+ 1. Write the driver of USB input device without write code take
care of
+ details of setup and clear usage.
+ 2. A driver use this interface can be as a HID device input filter.
+ 3. Write USB force-feed driver without touch hid-input core.
however, this
+ feature is confilct with HID_FF.
+
+ This interface can not support the more drivers handle one device
at same time
+yet. I can not sure if we really need this feature.
+
+------------------------
+The driver use this interface
+------------------------
+
+ So far, there are two drivers:
+ 1. MS Natural Ergonomic Keyboard 4000 driver. (usbnek4k.c)
+ 2. Betop BTP-2118 joystick force-feed driver. (btp2118.c)
+
+-------------------------
+Requires
+-------------------------
+
+ Before use this interface, you must turn on these kernel configuration
+items:
+
+ CONFIG_HID_SIMPLE : HID simple driver interface
+ CONFIG_HID_SIMPLE_FF : HID simple driver interface force feedback
support
+
+ Note: You can see the latter only if you turn off CONFIG_HID_FF and
turn
+on CONFIG_HID_SIMPLE.
+
+--------------------------
+Register and unregister
+--------------------------
+
+1. Register a simple driver.
+
+ int hidinput_register_simple_driver(struct hidinput_simple_driver
*simple)
+
+ Like any driver register function, it register your driver to kernel,
+when the chance that match device come, your driver can probe it. At
least, you
+must fill the member of parameter simple : name.
+ It return 0 mean register successfully. elsewise mean there have some
+failures in register process.
+ So far, this function only can return 0 and -EINVAL.
+
+2. Unregister a simple driver.
+
+ void hidinput_unregister_simple_driver(struct
hidinput_simple_driver *simple)
+
+ Like any driver register function, it clean your driver from
kernel, and
+in this process, your driver will disconnect any device which it
matched. However,
+it do not free your memory of driver structure, that's your task.
+
+----------------------------------
+Usage
+----------------------------------
+
+ Each simple driver have one data structure hidinput_simple_driver:
+
+struct hidinput_simple_driver {
+ /*
+ * The members for implement only are ignored here,
+ * please do not depend on them
+ */
+ /* public */
+ struct module *owner;
+ char *name;
+ int (*connect)(struct hid_device *, struct hid_input *);
+ void (*disconnect)(struct hid_device *, struct hid_input *);
+ void (*setup_usage)(struct hid_field *, struct hid_usage *);
+ void (*clear_usage)(struct hid_field *, struct hid_usage *);
+ int (*pre_event)(const struct hid_device *, const struct hid_field *,
+ const struct hid_usage *, const __s32,
+ const struct pt_regs *regs);
+ int (*post_event)(const struct hid_device *, const struct hid_field *,
+ const struct hid_usage *, const __s32,
+ const struct pt_regs *regs);
+
+ int (*open)(struct input_dev *dev);
+ void (*close)(struct input_dev *dev);
+ int (*upload_effect)(struct input_dev *dev, struct ff_effect
*effect);
+ int (*erase_effect)(struct input_dev *dev, int effect_id);
+ int (*flush)(struct input_dev *dev, struct file *file);
+ int (*ff_event)(struct input_dev *dev, int type, int code, int
value);
+
+ void *private;
+ struct usb_device_id *id_table;
+ struct usage_page_block *usage_page_table;
+};
+
+The data member description:
+
+ struct module *owner;
+
+ In most cases, set this member to THIS_MODULE is your want to.
+
+ char *name;
+
+ The name of your driver. you must fill this member before register it.
+
+ void *private;
+
+ You can save the data that your driver use only here. HID simple
driver
+core do not care this.
+
+ struct usb_device_id *id_table;
+
+ As same with other USB device driver. Only until the HID simple driver
+core find out there is one or more devices can matche with USB ID
suppied by your
+simple driver, it just call probe()/connect() methods of your driver.
+ In general, you always want to fill this member with something.
+
+ struct usage_page_block *usage_page_table;
+
+ Totally, there are three means you can complete setup and clean HID
usage work, which use this member is one
+of them. Moreover, this means is the most simplest one. By fill this
member, kernel will complete setup and clean usage
+work automatically.
+ For detailed explain, it will spend many words, I think the best
documentation about this is example code, you can
+ find them in usbnek4k.c and btp2118.c. I believe you have enough
intelligence to understand it, if you had familiar
+ with HID. :) When you read these examples, you also will find out some
new data structures, however, they are too simple to not discuss them.
+
+--------------------------------
+Generic Methods
+--------------------------------
+
+The simple driver methods description:
+
+ 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 follow 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. anything do not continue.
+ When the HID device that your simple driver connect with is down, or
+you unregister this simple driver, we will call disconnect() method
first, 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 if you do not interest with.
+
+3. void (*setup_usage)(struct hid_field *, struct hid_usage *);
+4. void (*clear_usage)(struct hid_field *, struct hid_usage *);
+
+ The setup_usage() method like hidinput_configure_usage() in
+hid_input.c. You also can setup input_dev here. I think
+you should be fill the pointer slot for this method, or fill
usage_page_table member of
+hidinput_simple_driver, 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 when one driver disconnect one device.
+ Of course, you can do same things in connect/disconnect() method, but
+these method can make your life more simpler.
+ At last, you can use these two methods and usage_page_table member
+at same time. These two methods always will be called after kernel process
+usage_page_table.
+
+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 setup usage correctly, even this method
+do not be called.
+
+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. however, it is
called
+after hidinput_hid_event(). 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.
+
+8. int (*open)(struct input_dev *dev);
+9. void (*close)(struct input_dev *dev);
+
+ They are same with corresponding methods of struct input_dev. I assume
+you already familiar with them.
+
+---------------------------
+Force-feed support Methods
+---------------------------
+Follow methods are valid only if you turn on CONFIG_HID_SIMPLE_FF:
+
+10. int (*upload_effect)(struct input_dev *dev, struct ff_effect
*effect);
+11. int (*erase_effect)(struct input_dev *dev, int effect_id);
+12. int (*flush)(struct input_dev *dev, struct file *file);
+13. int (*ff_event)(struct input_dev *dev, int type, int code,
int value);
+
+ They are same with corresponding methods of struct input_dev. I assume
+you already familiar with them.
-------------------------------------------------------------------------
Using Tomcat but need to do more? Need to support web services, security?
Get stuff done quickly with pre-integrated technology to make your job easier
Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo
http://sel.as-us.falkag.net/sel?cmd=lnk&kid=120709&bid=263057&dat=121642
_______________________________________________
linux-usb-devel@lists.sourceforge.net
To unsubscribe, use the last form field at:
https://lists.sourceforge.net/lists/listinfo/linux-usb-devel
