Skip to content

Commit

Permalink
Merge branch 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel…
Browse files Browse the repository at this point in the history 
…/git/jikos/hid

Pull HID updates from Jiri Kosina:
 "The list of changes worth pointing out explicitly:

  - We are getting 'UHID', which is a new framework for implementing HID
    transport drivers in userspace (this is different from HIDRAW, which
    is transport-independent and provides report parsing facilities;
    uhid is for the other (transport) part of the pipeline).

    It's needed for (and currently being used by) Bluetooth-LowEnergy,
    as its specification mandates things we don't want in the kernel.

    Written by David Herrmann.

  - there have been quite a few bugs in runtime suspend/resume paths
    (probably never reported to actually happen in the wild, but still).
    Alan Stern fixed those.

  - a few other driver updates and fixes and random new device support."

* 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/jikos/hid: (45 commits)
  HID: add ASUS AIO keyboard model AK1D
  HID: add support for Cypress barcode scanner 04B4:ED81
  HID: Allow drivers to be their own listener
  HID: usbhid: fix error paths in suspend
  HID: usbhid: check for suspend or reset before restarting
  HID: usbhid: replace HID_REPORTED_IDLE with HID_SUSPENDED
  HID: usbhid: inline some simple routines
  HID: usbhid: fix autosuspend calls
  HID: usbhid: fix use-after-free bug
  HID: hid-core: optimize in case of hidraw
  HID: hidraw: fix list->buffer memleak
  HID: uhid: Fix sending events with invalid data
  HID: roccat: added sensor sysfs attribute for Savu
  HID: Add driver for Holtek based keyboards with broken HID
  HID: Add suport for the brightness control keys on HP keyboards
  HID: magicmouse: Implement Multi-touch Protocol B (MT-B)
  HID: magicmouse: Removing report_touches switch
  HID: roccat: rename roccat_common functions to roccat_common2
  HID: roccat: fix wrong hid_err usage on struct usb_device
  HID: roccat: move functionality to roccat-common
  ...
  • Loading branch information
@torvalds
torvalds committed Jul 24, 2012
2 parents 0cd5ff5 + c062c4d commit e8ff13b
Show file tree
Hide file tree
Showing 40 changed files with 2,983 additions and 554 deletions.
38 changes: 38 additions & 0 deletions Documentation/ABI/testing/sysfs-driver-hid-lenovo-tpkbd
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/press_to_select
Date: July 2011
Contact: [email protected]
Description: This controls if mouse clicks should be generated if the trackpoint is quickly pressed. How fast this press has to be
is being controlled by press_speed.
Values are 0 or 1.

What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/dragging
Date: July 2011
Contact: [email protected]
Description: If this setting is enabled, it is possible to do dragging by pressing the trackpoint. This requires press_to_select to be enabled.
Values are 0 or 1.

What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/release_to_select
Date: July 2011
Contact: [email protected]
Description: For details regarding this setting please refer to http://www.pc.ibm.com/ww/healthycomputing/trkpntb.html
Values are 0 or 1.

What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/select_right
Date: July 2011
Contact: [email protected]
Description: This setting controls if the mouse click events generated by pressing the trackpoint (if press_to_select is enabled) generate
a left or right mouse button click.
Values are 0 or 1.

What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/sensitivity
Date: July 2011
Contact: [email protected]
Description: This file contains the trackpoint sensitivity.
Values are decimal integers from 1 (lowest sensitivity) to 255 (highest sensitivity).

What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/press_speed
Date: July 2011
Contact: [email protected]
Description: This setting controls how fast the trackpoint needs to be pressed to generate a mouse click if press_to_select is enabled.
Values are decimal integers from 1 (slowest) to 255 (fastest).

77 changes: 77 additions & 0 deletions Documentation/ABI/testing/sysfs-driver-hid-roccat-savu
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/savu/roccatsavu<minor>/buttons
Date: Mai 2012
Contact: Stefan Achatz <[email protected]>
Description: The mouse can store 5 profiles which can be switched by the
press of a button. A profile is split into general settings and
button settings. buttons holds informations about button layout.
When written, this file lets one write the respective profile
buttons to the mouse. The data has to be 47 bytes long.
The mouse will reject invalid data.
Which profile to write is determined by the profile number
contained in the data.
Before reading this file, control has to be written to select
which profile to read.
Users: http://roccat.sourceforge.net

What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/savu/roccatsavu<minor>/control
Date: Mai 2012
Contact: Stefan Achatz <[email protected]>
Description: When written, this file lets one select which data from which
profile will be read next. The data has to be 3 bytes long.
This file is writeonly.
Users: http://roccat.sourceforge.net

What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/savu/roccatsavu<minor>/general
Date: Mai 2012
Contact: Stefan Achatz <[email protected]>
Description: The mouse can store 5 profiles which can be switched by the
press of a button. A profile is split into general settings and
button settings. profile holds informations like resolution, sensitivity
and light effects.
When written, this file lets one write the respective profile
settings back to the mouse. The data has to be 43 bytes long.
The mouse will reject invalid data.
Which profile to write is determined by the profile number
contained in the data.
This file is writeonly.
Users: http://roccat.sourceforge.net

What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/savu/roccatsavu<minor>/info
Date: Mai 2012
Contact: Stefan Achatz <[email protected]>
Description: When read, this file returns general data like firmware version.
The data is 8 bytes long.
This file is readonly.
Users: http://roccat.sourceforge.net

What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/savu/roccatsavu<minor>/macro
Date: Mai 2012
Contact: Stefan Achatz <[email protected]>
Description: When written, this file lets one store macros with max 500
keystrokes for a specific button for a specific profile.
Button and profile numbers are included in written data.
The data has to be 2083 bytes long.
Before reading this file, control has to be written to select
which profile and key to read.
Users: http://roccat.sourceforge.net

What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/savu/roccatsavu<minor>/profile
Date: Mai 2012
Contact: Stefan Achatz <[email protected]>
Description: The mouse can store 5 profiles which can be switched by the
press of a button. profile holds number of actual profile.
This value is persistent, so its value determines the profile
that's active when the mouse is powered on next time.
When written, the mouse activates the set profile immediately.
The data has to be 3 bytes long.
The mouse will reject invalid data.
Users: http://roccat.sourceforge.net

What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/savu/roccatsavu<minor>/sensor
Date: July 2012
Contact: Stefan Achatz <[email protected]>
Description: The mouse has a Avago ADNS-3090 sensor.
This file allows reading and writing of the mouse sensors registers.
The data has to be 4 bytes long.
Users: http://roccat.sourceforge.net

169 changes: 169 additions & 0 deletions Documentation/hid/uhid.txt
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,169 @@
UHID - User-space I/O driver support for HID subsystem
========================================================

The HID subsystem needs two kinds of drivers. In this document we call them:

1. The "HID I/O Driver" is the driver that performs raw data I/O to the
low-level device. Internally, they register an hid_ll_driver structure with
the HID core. They perform device setup, read raw data from the device and
push it into the HID subsystem and they provide a callback so the HID
subsystem can send data to the device.

2. The "HID Device Driver" is the driver that parses HID reports and reacts on
them. There are generic drivers like "generic-usb" and "generic-bluetooth"
which adhere to the HID specification and provide the standardizes features.
But there may be special drivers and quirks for each non-standard device out
there. Internally, they use the hid_driver structure.

Historically, the USB stack was the first subsystem to provide an HID I/O
Driver. However, other standards like Bluetooth have adopted the HID specs and
may provide HID I/O Drivers, too. The UHID driver allows to implement HID I/O
Drivers in user-space and feed the data into the kernel HID-subsystem.

This allows user-space to operate on the same level as USB-HID, Bluetooth-HID
and similar. It does not provide a way to write HID Device Drivers, though. Use
hidraw for this purpose.

There is an example user-space application in ./samples/uhid/uhid-example.c

The UHID API
------------

UHID is accessed through a character misc-device. The minor-number is allocated
dynamically so you need to rely on udev (or similar) to create the device node.
This is /dev/uhid by default.

If a new device is detected by your HID I/O Driver and you want to register this
device with the HID subsystem, then you need to open /dev/uhid once for each
device you want to register. All further communication is done by read()'ing or
write()'ing "struct uhid_event" objects. Non-blocking operations are supported
by setting O_NONBLOCK.

struct uhid_event {
__u32 type;
union {
struct uhid_create_req create;
struct uhid_data_req data;
...
} u;
};

The "type" field contains the ID of the event. Depending on the ID different
payloads are sent. You must not split a single event across multiple read()'s or
multiple write()'s. A single event must always be sent as a whole. Furthermore,
only a single event can be sent per read() or write(). Pending data is ignored.
If you want to handle multiple events in a single syscall, then use vectored
I/O with readv()/writev().

The first thing you should do is sending an UHID_CREATE event. This will
register the device. UHID will respond with an UHID_START event. You can now
start sending data to and reading data from UHID. However, unless UHID sends the
UHID_OPEN event, the internally attached HID Device Driver has no user attached.
That is, you might put your device asleep unless you receive the UHID_OPEN
event. If you receive the UHID_OPEN event, you should start I/O. If the last
user closes the HID device, you will receive an UHID_CLOSE event. This may be
followed by an UHID_OPEN event again and so on. There is no need to perform
reference-counting in user-space. That is, you will never receive multiple
UHID_OPEN events without an UHID_CLOSE event. The HID subsystem performs
ref-counting for you.
You may decide to ignore UHID_OPEN/UHID_CLOSE, though. I/O is allowed even
though the device may have no users.

If you want to send data to the HID subsystem, you send an HID_INPUT event with
your raw data payload. If the kernel wants to send data to the device, you will
read an UHID_OUTPUT or UHID_OUTPUT_EV event.

If your device disconnects, you should send an UHID_DESTROY event. This will
unregister the device. You can now send UHID_CREATE again to register a new
device.
If you close() the fd, the device is automatically unregistered and destroyed
internally.

write()
-------
write() allows you to modify the state of the device and feed input data into
the kernel. The following types are supported: UHID_CREATE, UHID_DESTROY and
UHID_INPUT. The kernel will parse the event immediately and if the event ID is
not supported, it will return -EOPNOTSUPP. If the payload is invalid, then
-EINVAL is returned, otherwise, the amount of data that was read is returned and
the request was handled successfully.

UHID_CREATE:
This creates the internal HID device. No I/O is possible until you send this
event to the kernel. The payload is of type struct uhid_create_req and
contains information about your device. You can start I/O now.

UHID_DESTROY:
This destroys the internal HID device. No further I/O will be accepted. There
may still be pending messages that you can receive with read() but no further
UHID_INPUT events can be sent to the kernel.
You can create a new device by sending UHID_CREATE again. There is no need to
reopen the character device.

UHID_INPUT:
You must send UHID_CREATE before sending input to the kernel! This event
contains a data-payload. This is the raw data that you read from your device.
The kernel will parse the HID reports and react on it.

UHID_FEATURE_ANSWER:
If you receive a UHID_FEATURE request you must answer with this request. You
must copy the "id" field from the request into the answer. Set the "err" field
to 0 if no error occured or to EIO if an I/O error occurred.
If "err" is 0 then you should fill the buffer of the answer with the results
of the feature request and set "size" correspondingly.

read()
------
read() will return a queued ouput report. These output reports can be of type
UHID_START, UHID_STOP, UHID_OPEN, UHID_CLOSE, UHID_OUTPUT or UHID_OUTPUT_EV. No
reaction is required to any of them but you should handle them according to your
needs. Only UHID_OUTPUT and UHID_OUTPUT_EV have payloads.

UHID_START:
This is sent when the HID device is started. Consider this as an answer to
UHID_CREATE. This is always the first event that is sent.

UHID_STOP:
This is sent when the HID device is stopped. Consider this as an answer to
UHID_DESTROY.
If the kernel HID device driver closes the device manually (that is, you
didn't send UHID_DESTROY) then you should consider this device closed and send
an UHID_DESTROY event. You may want to reregister your device, though. This is
always the last message that is sent to you unless you reopen the device with
UHID_CREATE.

UHID_OPEN:
This is sent when the HID device is opened. That is, the data that the HID
device provides is read by some other process. You may ignore this event but
it is useful for power-management. As long as you haven't received this event
there is actually no other process that reads your data so there is no need to
send UHID_INPUT events to the kernel.

UHID_CLOSE:
This is sent when there are no more processes which read the HID data. It is
the counterpart of UHID_OPEN and you may as well ignore this event.

UHID_OUTPUT:
This is sent if the HID device driver wants to send raw data to the I/O
device. You should read the payload and forward it to the device. The payload
is of type "struct uhid_data_req".
This may be received even though you haven't received UHID_OPEN, yet.

UHID_OUTPUT_EV:
Same as UHID_OUTPUT but this contains a "struct input_event" as payload. This
is called for force-feedback, LED or similar events which are received through
an input device by the HID subsystem. You should convert this into raw reports
and send them to your device similar to events of type UHID_OUTPUT.

UHID_FEATURE:
This event is sent if the kernel driver wants to perform a feature request as
described in the HID specs. The report-type and report-number are available in
the payload.
The kernel serializes feature requests so there will never be two in parallel.
However, if you fail to respond with a UHID_FEATURE_ANSWER in a time-span of 5
seconds, then the requests will be dropped and a new one might be sent.
Therefore, the payload also contains an "id" field that identifies every
request.

Document by:
David Herrmann <[email protected]>
7 changes: 7 additions & 0 deletions MAINTAINERS
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6965,6 +6965,13 @@ S: Maintained
F: Documentation/filesystems/ufs.txt
F: fs/ufs/

UHID USERSPACE HID IO DRIVER:
M: David Herrmann <[email protected]>
L: [email protected]
S: Maintained
F: drivers/hid/uhid.c
F: include/linux/uhid.h

ULTRA-WIDEBAND (UWB) SUBSYSTEM:
L: [email protected]
S: Orphan
Expand Down
40 changes: 38 additions & 2 deletions drivers/hid/Kconfig
View file
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,27 @@ config HIDRAW

If unsure, say Y.

config UHID
tristate "User-space I/O driver support for HID subsystem"
depends on HID
default n
---help---
Say Y here if you want to provide HID I/O Drivers from user-space.
This allows to write I/O drivers in user-space and feed the data from
the device into the kernel. The kernel parses the HID reports, loads the
corresponding HID Device Driver or provides input devices on top of your
user-space device.

This driver cannot be used to parse HID-reports in user-space and write
special HID-drivers. You should use hidraw for that.
Instead, this driver allows to write the transport-layer driver in
user-space like USB-HID and Bluetooth-HID do in kernel-space.

If unsure, say N.

To compile this driver as a module, choose M here: the
module will be called uhid.

config HID_GENERIC
tristate "Generic HID driver"
depends on HID
Expand Down Expand Up @@ -193,10 +214,12 @@ config HID_EZKEY
Support for Ezkey BTC 8193 keyboard.

config HID_HOLTEK
tristate "Holtek On Line Grip based game controller support"
tristate "Holtek HID devices"
depends on USB_HID
---help---
Say Y here if you have a Holtek On Line Grip based game controller.
Support for Holtek based devices:
- Holtek On Line Grip based game controller
- Trust GXT 18 Gaming Keyboard

config HOLTEK_FF
bool "Holtek On Line Grip force feedback support"
Expand Down Expand Up @@ -261,6 +284,19 @@ config HID_LCPOWER
---help---
Support for LC-Power RC1000MCE RF remote control.

config HID_LENOVO_TPKBD
tristate "Lenovo ThinkPad USB Keyboard with TrackPoint"
depends on USB_HID
select NEW_LEDS
select LEDS_CLASS
---help---
Support for the Lenovo ThinkPad USB Keyboard with TrackPoint.

Say Y here if you have a Lenovo ThinkPad USB Keyboard with TrackPoint
and would like to use device-specific features like changing the
sensitivity of the trackpoint, using the microphone mute button or
controlling the mute and microphone mute LEDs.

config HID_LOGITECH
tristate "Logitech devices" if EXPERT
depends on USB_HID
Expand Down
6 changes: 5 additions & 1 deletion drivers/hid/Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ ifdef CONFIG_DEBUG_FS
endif

obj-$(CONFIG_HID) += hid.o
obj-$(CONFIG_UHID) += uhid.o

obj-$(CONFIG_HID_GENERIC) += hid-generic.o

Expand Down Expand Up @@ -48,12 +49,14 @@ obj-$(CONFIG_HID_EMS_FF) += hid-emsff.o
obj-$(CONFIG_HID_ELECOM) += hid-elecom.o
obj-$(CONFIG_HID_EZKEY) += hid-ezkey.o
obj-$(CONFIG_HID_GYRATION) += hid-gyration.o
obj-$(CONFIG_HID_HOLTEK) += hid-holtek-kbd.o
obj-$(CONFIG_HID_HOLTEK) += hid-holtekff.o
obj-$(CONFIG_HID_HYPERV_MOUSE) += hid-hyperv.o
obj-$(CONFIG_HID_KENSINGTON) += hid-kensington.o
obj-$(CONFIG_HID_KEYTOUCH) += hid-keytouch.o
obj-$(CONFIG_HID_KYE) += hid-kye.o
obj-$(CONFIG_HID_LCPOWER) += hid-lcpower.o
obj-$(CONFIG_HID_LENOVO_TPKBD) += hid-lenovo-tpkbd.o
obj-$(CONFIG_HID_LOGITECH) += hid-logitech.o
obj-$(CONFIG_HID_LOGITECH_DJ) += hid-logitech-dj.o
obj-$(CONFIG_HID_MAGICMOUSE) += hid-magicmouse.o
Expand All @@ -69,7 +72,8 @@ obj-$(CONFIG_HID_PICOLCD) += hid-picolcd.o
obj-$(CONFIG_HID_PRIMAX) += hid-primax.o
obj-$(CONFIG_HID_ROCCAT) += hid-roccat.o hid-roccat-common.o \
hid-roccat-arvo.o hid-roccat-isku.o hid-roccat-kone.o \
hid-roccat-koneplus.o hid-roccat-kovaplus.o hid-roccat-pyra.o
hid-roccat-koneplus.o hid-roccat-kovaplus.o hid-roccat-pyra.o \
hid-roccat-savu.o
obj-$(CONFIG_HID_SAITEK) += hid-saitek.o
obj-$(CONFIG_HID_SAMSUNG) += hid-samsung.o
obj-$(CONFIG_HID_SMARTJOYPLUS) += hid-sjoy.o
Expand Down
Loading

0 comments on commit e8ff13b

Please sign in to comment.