From: Antonio Ospite on
On Thu, 17 Jun 2010 23:38:03 -0400
Alan Ott <alan(a)signal11.us> wrote:

> Documenation for the hidraw driver.
>
> Signed-off-by: Alan Ott <alan(a)signal11.us>
> ---
> The information in this patch relies on:
> [PATCH v2] HID: Add Support for Setting and Getting Feature Reports from hidraw
> which has been applied by Jiri Kosina.
>
> Please provide comments. I'm sure someone here will have a better idea where
> to put this than the root of Documentation/. I didn't see a better place, as
> hidraw is used for both Bluetooth and USB.
>

Maybe both hidraw.txt and hiddev.txt can be moved to
Documentation/hid/?

From a first read the document is OK tho. Thanks.

> Documentation/hidraw.txt | 283 ++++++++++++++++++++++++++++++++++++++++++++++
> 1 files changed, 283 insertions(+), 0 deletions(-)
> create mode 100644 Documentation/hidraw.txt
>
> diff --git a/Documentation/hidraw.txt b/Documentation/hidraw.txt
> new file mode 100644
> index 0000000..7153a06
> --- /dev/null
> +++ b/Documentation/hidraw.txt
> @@ -0,0 +1,283 @@
[...]
> +
> +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.
> +

Is the encoding specified in the HID spec?

[...]
>
> +Example
> +---------
> +The following code 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.
> +

Just a very minimal remark, maybe the code should follow the kernel
coding style (early return on error, no braces for one line conditional
blocks) even if it is a userspace application. Being it in the
kernel Documentation I assume people reading it would be used to kernel
style more.

> +---- Begin Code ----
[...]
> +---- End Code ----
> +
> +Document by:
> + Alan Ott <alan(a)signal11.us>
> --
> 1.7.0.4

Regards,
Antonio

--
Antonio Ospite
http://ao2.it

PGP public key ID: 0x4553B001

A: Because it messes up the order in which people normally read text.
See http://en.wikipedia.org/wiki/Posting_style
Q: Why is top-posting such a bad thing?
A: Top-posting.
Q: What is the most annoying thing in e-mail?
From: Jiri Kosina on
On Thu, 17 Jun 2010, Alan Ott wrote:

> Documenation for the hidraw driver.

Thanks a lot for writing this up, Alan. It's something that has been
lingering on my TODO for just too long, it's great that someone finally
got fed up with it and wrote it :)

>
> Signed-off-by: Alan Ott <alan(a)signal11.us>
> ---
> The information in this patch relies on:
> [PATCH v2] HID: Add Support for Setting and Getting Feature Reports from hidraw
> which has been applied by Jiri Kosina.
>
> Please provide comments. I'm sure someone here will have a better idea where
> to put this than the root of Documentation/. I didn't see a better place, as
> hidraw is used for both Bluetooth and USB.

Either Documentation/input comes to mind, or we could even establish
Documentation/hid directory as well.

> Documentation/hidraw.txt | 283 ++++++++++++++++++++++++++++++++++++++++++++++
> 1 files changed, 283 insertions(+), 0 deletions(-)
> create mode 100644 Documentation/hidraw.txt
>
> diff --git a/Documentation/hidraw.txt b/Documentation/hidraw.txt
> new file mode 100644
> index 0000000..7153a06
> --- /dev/null
> +++ b/Documentation/hidraw.txt
> @@ -0,0 +1,283 @@
> + 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
> +received are not parsed by the HID parser, but are sent to and received from
> +the device unmodified.

The important point behind hidraw (compared to hiddev), always has been
that it's in fact completely independent on underlying hardware transport
protocol. Currently there are no other implementations of HID than the
ones using Bluetooth or USB, but there is no general obstacle to using
hidraw once any vendor comes with HID-over-FibreChannel :) for example.

This basic principle might be worth mentioning as well.

> +Hidraw should be used if the userspace application knows exactly how to
> +communicate with the hardware device, and is able to construct the HID
> +reports manually. This is often the case when making userspace drivers for
> +custom HID devices.
> +
> +Hidraw is also useful for communicating with non-conformant HID devices
> +which send and receive data in a way that is inconsistent with their report
> +descriptors. Because hiddev parses reports which are sent and received
> +through it and checks them against the device's report descriptor, such
> +communication with these non-conformant devices is impossible using hiddev.

hidraw is just one of the alternatives here of course. Writing in-kernel
driver also can be done to overcome these obstacles.

Thanks,

--
Jiri Kosina
SUSE Labs, Novell Inc.
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo(a)vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/
From: Alan Ott on
On 06/18/2010 05:57 AM, Antonio Ospite wrote:
>
> Maybe both hidraw.txt and hiddev.txt can be moved to
> Documentation/hid/?
>
>
Antonio,

You and Jiri seem to have the same idea on this one. Sounds good to me.
>> +
>> +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.
>> +
>>
> Is the encoding specified in the HID spec?
>
USB returns strings to the host as Unicode, UTF16LE encoded. The kernel
converts them to UTF-8. See usb_string() in drivers/usb/core/message.c.

>
> Just a very minimal remark, maybe the code should follow the kernel
> coding style (early return on error, no braces for one line conditional
> blocks) even if it is a userspace application. Being it in the
> kernel Documentation I assume people reading it would be used to kernel
> style more.
>
>
Good point. I'll run the style check on it and fix it up.

Alan.

--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo(a)vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/
From: Alan Ott on
On 06/18/2010 07:59 AM, Jiri Kosina wrote:
>> Documenation for the hidraw driver.
>>
> Thanks a lot for writing this up, Alan. It's something that has been
> lingering on my TODO for just too long, it's great that someone finally
> got fed up with it and wrote it :)
>
>
I wouldn't say I was fed up :)
>> I'm sure someone here will have a better idea where
>> to put this than the root of Documentation/. I didn't see a better place, as
>> hidraw is used for both Bluetooth and USB.
>>
> Either Documentation/input comes to mind, or we could even establish
> Documentation/hid directory as well.
>
>
Antonio suggested the same, putting hidraw.txt and hiddev.txt into a new
Documentation/hid/ directory. I'll do this for the next rev unless I
hear otherwise.

>> Documentation/hidraw.txt | 283 ++++++++++++++++++++++++++++++++++++++++++++++
>> 1 files changed, 283 insertions(+), 0 deletions(-)
>> create mode 100644 Documentation/hidraw.txt
>>
>> diff --git a/Documentation/hidraw.txt b/Documentation/hidraw.txt
>> new file mode 100644
>> index 0000000..7153a06
>> --- /dev/null
>> +++ b/Documentation/hidraw.txt
>> @@ -0,0 +1,283 @@
>> + 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
>> +received are not parsed by the HID parser, but are sent to and received from
>> +the device unmodified.
>>
> The important point behind hidraw (compared to hiddev), always has been
> that it's in fact completely independent on underlying hardware transport
> protocol. Currently there are no other implementations of HID than the
> ones using Bluetooth or USB, but there is no general obstacle to using
> hidraw once any vendor comes with HID-over-FibreChannel :) for example.
>
> This basic principle might be worth mentioning as well.
>
>
I'll make sure to put that in.

>> +Hidraw should be used if the userspace application knows exactly how to
>> +communicate with the hardware device, and is able to construct the HID
>> +reports manually. This is often the case when making userspace drivers for
>> +custom HID devices.
>> +
>> +Hidraw is also useful for communicating with non-conformant HID devices
>> +which send and receive data in a way that is inconsistent with their report
>> +descriptors. Because hiddev parses reports which are sent and received
>> +through it and checks them against the device's report descriptor, such
>> +communication with these non-conformant devices is impossible using hiddev.
>>
> hidraw is just one of the alternatives here of course. Writing in-kernel
> driver also can be done to overcome these obstacles.
>
>
Also true. I'll add it.

Thanks,

Alan.


--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo(a)vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/
From: Randy Dunlap on
On Thu, 17 Jun 2010 23:38:03 -0400 Alan Ott wrote:

> Documenation for the hidraw driver.
>
> Signed-off-by: Alan Ott <alan(a)signal11.us>
> ---
>
> Documentation/hidraw.txt | 283 ++++++++++++++++++++++++++++++++++++++++++++++
> 1 files changed, 283 insertions(+), 0 deletions(-)
> create mode 100644 Documentation/hidraw.txt

In the new sub-directory, please split the example/test program into a separate
source file and add a Makefile so that it will build.

There are similar Makefiles in many other Documentation/ sub-directories.

thanks.
---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo(a)vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/