Merge branch 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/hid/hid

==========================

ALPS HID Touchpad Protocol

----------------------

==========================

Introduction

------------

Currently ALPS HID driver supports U1 Touchpad device.

U1 devuce basic information.

U1 device basic information.

==========	======

Vender ID	0x044E

Product ID	0x120B

Version ID	0x0121

==========	======

HID Descriptor

------------

--------------

=======	====================	=====	=======================================

Byte	Field			Value	Notes

=======	====================	=====	=======================================

0	wHIDDescLength		001E	Length of HID Descriptor : 30 bytes

2	bcdVersion		0100	Compliant with Version 1.00

4	wReportDescLength	00B2	Report Descriptor is 178 Bytes (0x00B2)

22	wProductID		120B	Product ID 0x120B

24	wVersionID		0121	Version 01.21

26	RESERVED		0000	RESERVED

=======	====================	=====	=======================================

Report ID

------------

---------

==========	=================  =========================================

ReportID-1	(Input Reports)	   (HIDUsage-Mouse) for TP&SP

ReportID-2	(Input Reports)	   (HIDUsage-keyboard) for TP

ReportID-3	(Input Reports)	   (Vendor Usage: Max 10 finger data) for TP

ReportID-5	(Feature Reports)  Feature Reports

ReportID-6	(Input Reports)	   (Vendor Usage: StickPointer data) for SP

ReportID-7	(Feature Reports)  Flash update (Bootloader)

==========	=================  =========================================

Data pattern

------------

=====	==========	=====	=================

Case1	ReportID_1	TP/SP	Relative/Relative

Case2	ReportID_3	TP	Absolute

	ReportID_6	SP	Absolute

=====	==========	=====	=================

Command Read/Write

------------------

To read/write to RAM, need to send a commands to the device.

The command format is as below.

DataByte(SET_REPORT)

=====	======================

Byte1	Command Byte

Byte2	Address - Byte 0 (LSB)

Byte3	Address - Byte 1

Byte5	Address - Byte 3 (MSB)

Byte6	Value Byte

Byte7	Checksum

=====	======================

Command Byte is read=0xD1/write=0xD2 .

Address is read/write RAM address.

Value Byte is writing data when you send the write commands.

When you read RAM, there is no meaning.

DataByte(GET_REPORT)

=====	======================

Byte1	Response Byte

Byte2	Address - Byte 0 (LSB)

Byte3	Address - Byte 1

Byte5	Address - Byte 3 (MSB)

Byte6	Value Byte

Byte7	Checksum

=====	======================

Read value is stored in Value Byte.

Packet Format

Touchpad data byte

------------------

	b7	b6	b5	b4	b3	b2	b1	b0

======= ======= ======= ======= ======= ======= ======= ======= =====

-	b7	b6	b5	b4	b3	b2	b1	b0

======= ======= ======= ======= ======= ======= ======= ======= =====

1	0	0	SW6	SW5	SW4	SW3	SW2	SW1

2	0	0	0	Fcv	Fn3	Fn2	Fn1	Fn0

3	Xa0_7	Xa0_6	Xa0_5	Xa0_4	Xa0_3	Xa0_2	Xa0_1	Xa0_0

25	Ya4_7	Ya4_6	Ya4_5	Ya4_4	Ya4_3	Ya4_2	Ya4_1	Ya4_0

26	Ya4_15	Ya4_14	Ya4_13	Ya4_12	Ya4_11	Ya4_10	Ya4_9	Ya4_8

27	LFB4	Zs4_6	Zs4_5	Zs4_4	Zs4_3	Zs4_2	Zs4_1	Zs4_0

======= ======= ======= ======= ======= ======= ======= ======= =====

SW1-SW6:	SW ON/OFF status

Xan_15-0(16bit):X Absolute data of the "n"th finger

Yan_15-0(16bit):Y Absolute data of the "n"th finger

Zsn_6-0(7bit):	Operation area of the "n"th finger

SW1-SW6:

	SW ON/OFF status

Xan_15-0(16bit):

	X Absolute data of the "n"th finger

Yan_15-0(16bit):

	Y Absolute data of the "n"th finger

Zsn_6-0(7bit):

	Operation area of the "n"th finger

StickPointer data byte

------------------

	b7	b6	b5	b4	b3	b2	b1	b0

----------------------

======= ======= ======= ======= ======= ======= ======= ======= =====

-	b7	b6	b5	b4	b3	b2	b1	b0

======= ======= ======= ======= ======= ======= ======= ======= =====

Byte1	1	1	1	0	1	SW3	SW2	SW1

Byte2	X7	X6	X5	X4	X3	X2	X1	X0

Byte3	X15	X14	X13	X12	X11	X10	X9	X8

Byte5	Y15	Y14	Y13	Y12	Y11	Y10	Y9	Y8

Byte6	Z7	Z6	Z5	Z4	Z3	Z2	Z1	Z0

Byte7	T&P	Z14	Z13	Z12	Z11	Z10	Z9	Z8

SW1-SW3:	SW ON/OFF status

Xn_15-0(16bit):X Absolute data

Yn_15-0(16bit):Y Absolute data

Zn_14-0(15bit):Z

======= ======= ======= ======= ======= ======= ======= ======= =====

SW1-SW3:

	SW ON/OFF status

Xn_15-0(16bit):

	X Absolute data

Yn_15-0(16bit):

	Y Absolute data

Zn_14-0(15bit):

	Z

=====================

HID Sensors Framework

======================

=====================

HID sensor framework provides necessary interfaces to implement sensor drivers,

which are connected to a sensor hub. The sensor hub is a HID device and it provides

a report descriptor conforming to HID 1.12 sensor usage tables.

This specification describes many usage IDs, which describe the type of sensor

and also the individual data fields. Each sensor can have variable number of

data fields. The length and order is specified in the report descriptor. For

example a part of report descriptor can look like:

example a part of report descriptor can look like::

     INPUT(1)[INPUT]

   ..

Implementation

=================

==============

This specification defines many different types of sensors with different sets of

data fields. It is difficult to have a common input event to user space applications,

for different sensors. For example an accelerometer can send X,Y and Z data, whereas

an ambient light sensor can send illumination data.

So the implementation has two parts:

- Core hid driver

- Individual sensor processing part (sensor drivers)

The core driver registers (hid-sensor-hub) registers as a HID driver. It parses

report descriptors and identifies all the sensors present. It adds an MFD device

with name HID-SENSOR-xxxx (where xxxx is usage id from the specification).

For example

For example:

HID-SENSOR-200073 is registered for an Accelerometer 3D driver.

So if any driver with this name is inserted, then the probe routine for that

function will be called. So an accelerometer processing driver can register

with this name and will be probed if there is an accelerometer-3D detected.

functions, which get and set each input/feature/output report.

Individual sensor processing part (sensor drivers)

-----------

--------------------------------------------------

The processing driver will use an interface provided by the core driver to parse

the report and get the indexes of the fields and also can get events. This driver

can use IIO interface to use the standard ABI defined for a type of sensor.

Core driver Interface

=====================

Callback structure:

Callback structure::

  Each processing driver can use this structure to set some callbacks.

	int (*suspend)(..): Callback when HID suspend is received

	int (*resume)(..): Callback when HID resume is received

	int (*send_event)(..): One complete event is received which can have

                               multiple data fields.

Registration functions:

Registration functions::

  int sensor_hub_register_callback(struct hid_sensor_hub_device *hsdev,

			u32 usage_id,

			struct hid_sensor_hub_callbacks *usage_callback):

Registers callbacks for an usage id. The callback functions are not allowed

to sleep.

to sleep::

  int sensor_hub_remove_callback(struct hid_sensor_hub_device *hsdev,

Removes callbacks for an usage id.

Parsing function:

Parsing function::

  int sensor_hub_input_get_attribute_info(struct hid_sensor_hub_device *hsdev,

			u8 type,

			u32 usage_id, u32 attr_usage_id,

These indexes avoid searching every time and getting field index to get or set.

Set Feature report

Set Feature report::

  int sensor_hub_set_feature(struct hid_sensor_hub_device *hsdev, u32 report_id,

			u32 field_index, s32 value);

This interface is used to set a value for a field in feature report. For example

if there is a field report_interval, which is parsed by a call to

sensor_hub_input_get_attribute_info before, then it can directly set that individual

field.

sensor_hub_input_get_attribute_info before, then it can directly set that

individual field::

  int sensor_hub_get_feature(struct hid_sensor_hub_device *hsdev, u32 report_id,

This interface is used to get a value for a field in input report. For example

if there is a field report_interval, which is parsed by a call to

sensor_hub_input_get_attribute_info before, then it can directly get that individual

field value.

sensor_hub_input_get_attribute_info before, then it can directly get that

individual field value::

  int sensor_hub_input_attr_get_raw_value(struct hid_sensor_hub_device *hsdev,

----------

HID Custom and generic Sensors

------------------------------

HID Sensor specification defines two special sensor usage types. Since they

don't represent a standard sensor, it is not possible to define using Linux IIO

To allow application to utilize these sensors, here they are exported uses sysfs

attribute groups, attributes and misc device interface.

An example of this representation on sysfs:

An example of this representation on sysfs::

  /sys/devices/pci0000:00/INT33C2:00/i2c-0/i2c-INT33D1:00/0018:8086:09FA.0001/HID-SENSOR-2000e1.6.auto$ tree -R

  .

????????? enable_sensor

????????? feature-0-200316

??????? ????????? feature-0-200316-maximum

??????? ????????? feature-0-200316-minimum

??????? ????????? feature-0-200316-name

??????? ????????? feature-0-200316-size

??????? ????????? feature-0-200316-unit-expo

??????? ????????? feature-0-200316-units

??????? ????????? feature-0-200316-value

????????? feature-1-200201

??????? ????????? feature-1-200201-maximum

??????? ????????? feature-1-200201-minimum

??????? ????????? feature-1-200201-name

??????? ????????? feature-1-200201-size

??????? ????????? feature-1-200201-unit-expo

??????? ????????? feature-1-200201-units

??????? ????????? feature-1-200201-value

????????? input-0-200201

??????? ????????? input-0-200201-maximum

??????? ????????? input-0-200201-minimum

??????? ????????? input-0-200201-name

??????? ????????? input-0-200201-size

??????? ????????? input-0-200201-unit-expo

??????? ????????? input-0-200201-units

??????? ????????? input-0-200201-value

????????? input-1-200202

??????? ????????? input-1-200202-maximum

??????? ????????? input-1-200202-minimum

??????? ????????? input-1-200202-name

??????? ????????? input-1-200202-size

??????? ????????? input-1-200202-unit-expo

??????? ????????? input-1-200202-units

??????? ????????? input-1-200202-value

  │   ├──  enable_sensor

  │   │   ├── feature-0-200316

  │   │   │   ├── feature-0-200316-maximum

  │   │   │   ├── feature-0-200316-minimum

  │   │   │   ├── feature-0-200316-name

  │   │   │   ├── feature-0-200316-size

  │   │   │   ├── feature-0-200316-unit-expo

  │   │   │   ├── feature-0-200316-units

  │   │   │   ├── feature-0-200316-value

  │   │   ├── feature-1-200201

  │   │   │   ├── feature-1-200201-maximum

  │   │   │   ├── feature-1-200201-minimum

  │   │   │   ├── feature-1-200201-name

  │   │   │   ├── feature-1-200201-size

  │   │   │   ├── feature-1-200201-unit-expo

  │   │   │   ├── feature-1-200201-units

  │   │   │   ├── feature-1-200201-value

  │   │   ├── input-0-200201

  │   │   │   ├── input-0-200201-maximum

  │   │   │   ├── input-0-200201-minimum

  │   │   │   ├── input-0-200201-name

  │   │   │   ├── input-0-200201-size

  │   │   │   ├── input-0-200201-unit-expo

  │   │   │   ├── input-0-200201-units

  │   │   │   ├── input-0-200201-value

  │   │   ├── input-1-200202

  │   │   │   ├── input-1-200202-maximum

  │   │   │   ├── input-1-200202-minimum

  │   │   │   ├── input-1-200202-name

  │   │   │   ├── input-1-200202-size

  │   │   │   ├── input-1-200202-unit-expo

  │   │   │   ├── input-1-200202-units

  │   │   │   ├── input-1-200202-value

Here there is a custom sensors with four fields, two feature and two inputs.

Each field is represented by a set of attributes. All fields except the "value"

are read only. The value field is a RW field.

Example

Example::

  /sys/bus/platform/devices/HID-SENSOR-2000e1.6.auto/feature-0-200316$ grep -r . *

  feature-0-200316-maximum:6

  feature-0-200316-minimum:0

  feature-0-200316-value:1

How to enable such sensor?

^^^^^^^^^^^^^^^^^^^^^^^^^^

By default sensor can be power gated. To enable sysfs attribute "enable" can be

used.

used::

	$ echo 1 > enable_sensor

Once enabled and powered on, sensor can report value using HID reports.

These reports are pushed using misc device interface in a FIFO order.

These reports are pushed using misc device interface in a FIFO order::

	/dev$ tree | grep HID-SENSOR-2000e1.6.auto

??????? ????????? 10:53 -> ../HID-SENSOR-2000e1.6.auto

????????? HID-SENSOR-2000e1.6.auto

	│   │   │   ├── 10:53 -> ../HID-SENSOR-2000e1.6.auto

	│   ├──  HID-SENSOR-2000e1.6.auto

Each reports can be of variable length preceded by a header. This header

consist of a 32 bit usage id, 64 bit time stamp and 32 bit length field of raw

=========================

HID I/O Transport Drivers

                         ===========================

=========================

The HID subsystem is independent of the underlying transport driver. Initially,

only USB was supported, but other specifications adopted the HID design and

report-parsing, report interpretation and the user-space API. Device specifics

and quirks are handled by all layers depending on the quirk.

::

 +-----------+  +-----------+            +-----------+  +-----------+

 | Device #1 |  | Device #i |            | Device #j |  | Device #k |

 +-----------+  +-----------+            +-----------+  +-----------+

 +----------------+  +-----------+  +------------------+  +------------------+

Example Drivers:

  I/O: USB, I2C, Bluetooth-l2cap

  Transport: USB-HID, I2C-HID, BT-HIDP

  - I/O: USB, I2C, Bluetooth-l2cap

  - Transport: USB-HID, I2C-HID, BT-HIDP

Everything below "HID Core" is simplified in this graph as it is only of

interest to HID device drivers. Transport drivers do not need to know the

-------------------

Transport drivers normally use the following procedure to register a new device

with HID core:

with HID core::

	struct hid_device *hid;

	int ret;

"custom_ll_driver". Note that fields like "country" can be ignored by underlying

transport-drivers if not supported.

To unregister a device, use:

To unregister a device, use::

	hid_destroy_device(hid);

-----------------------------

The available HID callbacks are:

 - int (*start) (struct hid_device *hdev)

   ::

      int (*start) (struct hid_device *hdev)

   Called from HID device drivers once they want to use the device. Transport

   drivers can choose to setup their device in this callback. However, normally

   devices are already set up before transport drivers register them to HID core

   so this is mostly only used by USB-HID.

 - void (*stop) (struct hid_device *hdev)

   ::

      void (*stop) (struct hid_device *hdev)

   Called from HID device drivers once they are done with a device. Transport

   drivers can free any buffers and deinitialize the device. But note that

   ->start() might be called again if another HID device driver is loaded on the

   device.

   Transport drivers are free to ignore it and deinitialize devices after they

   destroyed them via hid_destroy_device().

 - int (*open) (struct hid_device *hdev)

   ::

      int (*open) (struct hid_device *hdev)

   Called from HID device drivers once they are interested in data reports.

   Usually, while user-space didn't open any input API/etc., device drivers are

   not interested in device data and transport drivers can put devices asleep.

   However, once ->open() is called, transport drivers must be ready for I/O.

   ->open() calls are nested for each client that opens the HID device.

 - void (*close) (struct hid_device *hdev)

   ::

      void (*close) (struct hid_device *hdev)

   Called from HID device drivers after ->open() was called but they are no

   longer interested in device reports. (Usually if user-space closed any input

   devices of the driver).

   Transport drivers can put devices asleep and terminate any I/O of all

   ->open() calls have been followed by a ->close() call. However, ->start() may

   be called again if the device driver is interested in input reports again.

 - int (*parse) (struct hid_device *hdev)

   ::

      int (*parse) (struct hid_device *hdev)

   Called once during device setup after ->start() has been called. Transport

   drivers must read the HID report-descriptor from the device and tell HID core

   about it via hid_parse_report().

 - int (*power) (struct hid_device *hdev, int level)

   ::

      int (*power) (struct hid_device *hdev, int level)

   Called by HID core to give PM hints to transport drivers. Usually this is

   analogical to the ->open() and ->close() hints and redundant.

 - void (*request) (struct hid_device *hdev, struct hid_report *report,

   ::

      void (*request) (struct hid_device *hdev, struct hid_report *report,

		       int reqtype)

   Send an HID request on the ctrl channel. "report" contains the report that

   should be sent and "reqtype" the request type. Request-type can be

   HID_REQ_SET_REPORT or HID_REQ_GET_REPORT.

   This callback is optional. If not provided, HID core will assemble a raw

   report following the HID specs and send it via the ->raw_request() callback.

   The transport driver is free to implement this asynchronously.

 - int (*wait) (struct hid_device *hdev)

   ::

      int (*wait) (struct hid_device *hdev)

   Used by HID core before calling ->request() again. A transport driver can use

   it to wait for any pending requests to complete if only one request is

   allowed at a time.

 - int (*raw_request) (struct hid_device *hdev, unsigned char reportnum,

   ::

      int (*raw_request) (struct hid_device *hdev, unsigned char reportnum,

                          __u8 *buf, size_t count, unsigned char rtype,

                          int reqtype)

   Same as ->request() but provides the report as raw buffer. This request shall

   be synchronous. A transport driver must not use ->wait() to complete such

   requests. This request is mandatory and hid core will reject the device if

   it is missing.

 - int (*output_report) (struct hid_device *hdev, __u8 *buf, size_t len)

   ::

      int (*output_report) (struct hid_device *hdev, __u8 *buf, size_t len)

   Send raw output report via intr channel. Used by some HID device drivers

   which require high throughput for outgoing requests on the intr channel. This

   must not cause SET_REPORT calls! This must be implemented as asynchronous

   output report on the intr channel!

 - int (*idle) (struct hid_device *hdev, int report, int idle, int reqtype)

   ::

      int (*idle) (struct hid_device *hdev, int report, int idle, int reqtype)

   Perform SET/GET_IDLE request. Only used by USB-HID, do not implement!

2.3) Data Path

Acknowledgements to SET_REPORT requests are not of interest to HID core.

----------------------------------------------------

Written 2013, David Herrmann <dh.herrmann@gmail.com>

================================================================

HIDRAW - Raw Access to USB and Bluetooth Human Interface Devices

     ==================================================================

================================================================

The hidraw driver provides a raw interface to USB and Bluetooth Human

Interface Devices (HIDs).  It differs from hiddev in that reports sent and

and udev rule-dependent, applications should use libudev to locate hidraw

devices attached to the system.  There is a tutorial on libudev with a

working example at:

	http://www.signal11.us/oss/udev/

The HIDRAW API

will begin at the first byte.

write()

--------

-------

The write() function will write a report to the device. For USB devices, if

the device has an INTERRUPT OUT endpoint, the report will be sent on that

endpoint. If it does not, the report will be sent over the control endpoint,

be set to 0. The report data itself should begin at the second byte.

ioctl()

--------

-------

Hidraw supports the following ioctls:

HIDIOCGRDESCSIZE: Get Report Descriptor Size

HIDIOCGRDESCSIZE:

	Get Report Descriptor Size

This ioctl will get the size of the device's report descriptor.

HIDIOCGRDESC: Get Report Descriptor

HIDIOCGRDESC:

	Get Report Descriptor

This ioctl returns the device's report descriptor using a

hidraw_report_descriptor struct.  Make sure to set the size field of the

hidraw_report_descriptor struct to the size returned from HIDIOCGRDESCSIZE.

HIDIOCGRAWINFO: Get Raw Info

HIDIOCGRAWINFO:

	Get Raw Info

This ioctl will return a hidraw_devinfo struct containing the bus type, the

vendor ID (VID), and product ID (PID) of the device. The bus type can be one

of:

	BUS_USB

	BUS_HIL

	BUS_BLUETOOTH

	BUS_VIRTUAL

of::

	- BUS_USB

	- BUS_HIL

	- BUS_BLUETOOTH

	- BUS_VIRTUAL

which are defined in uapi/linux/input.h.

HIDIOCGRAWNAME(len): Get Raw Name

HIDIOCGRAWNAME(len):

	Get Raw Name

This ioctl returns a string containing the vendor and product strings of

the device.  The returned string is Unicode, UTF-8 encoded.

HIDIOCGRAWPHYS(len): Get Physical Address

HIDIOCGRAWPHYS(len):

	Get Physical Address

This ioctl returns a string representing the physical address of the device.

For USB devices, the string contains the physical path to the device (the

USB controller, hubs, ports, etc).  For Bluetooth devices, the string

contains the hardware (MAC) address of the device.

HIDIOCSFEATURE(len): Send a Feature Report

HIDIOCSFEATURE(len):

	Send a Feature Report

This ioctl will send a feature report to the device.  Per the HID

specification, feature reports are always sent using the control endpoint.

Set the first byte of the supplied buffer to the report number.  For devices

begins in the second byte. Make sure to set len accordingly, to one more

than the length of the report (to account for the report number).

HIDIOCGFEATURE(len): Get a Feature Report

HIDIOCGFEATURE(len):

	Get a Feature Report

This ioctl will request a feature report from the device using the control

endpoint.  The first byte of the supplied buffer should be set to the report

number of the requested report.  For devices which do not use numbered

the first byte of the buffer (ie: the report number is not returned).

Example

---------

-------

In samples/, find hid-example.c, which shows examples of read(), write(),

and all the ioctls for hidraw.  The code may be used by anyone for any

purpose, and can serve as a starting point for developing applications using

hidraw.

Document by:

	Alan Ott <alan@signal11.us>, Signal 11 Software