HID: fix up .raw_event() documentation

linusw · Jiri Kosina · commit aa9b760cec23 · 2018-11-06T13:59:08.000+01:00
The documentation for the .raw_event() callback says that if the
driver return 1, there will be no further processing of the event,
but this is not true, the actual code in hid-core.c looks like this:

  if (hdrv &amp;&amp; hdrv-&gt;raw_event &amp;&amp; hid_match_report(hid, report)) {
           ret = hdrv-&gt;raw_event(hid, report, data, size);
           if (ret &lt; 0)
                   goto unlock;
   }

   ret = hid_report_raw_event(hid, type, data, size, interrupt);

The only return value that has any effect on the processing is
a negative error.

Correct this as it seems to confuse people: I found bogus code in
the Razer out-of-tree driver attempting to return 1 here.

Signed-off-by: Linus Walleij &lt;linus.walleij@linaro.org&gt;
Signed-off-by: Jiri Kosina &lt;jkosina@suse.cz&gt;
diff --git a/include/linux/hid.h b/include/linux/hid.h
@@ -722,8 +722,8 @@ struct hid_usage_id {
  * input will not be passed to raw_event unless hid_device_io_start is
  * called.
  *
- * raw_event and event should return 0 on no action performed, 1 when no
- * further processing should be done and negative on error
+ * raw_event and event should return negative on error, any other value will
+ * pass the event on to .event() typically return 0 for success.
  *
  * input_mapping shall return a negative value to completely ignore this usage
  * (e.g. doubled or invalid usage), zero to continue with parsing of this

Original file line number	Diff line number	Diff line change
`@@ -722,8 +722,8 @@ struct hid_usage_id {`
`722`	`722`	`* input will not be passed to raw_event unless hid_device_io_start is`
`723`	`723`	`* called.`
`724`	`724`	`*`
`725`		`- * raw_event and event should return 0 on no action performed, 1 when no`
`726`		`- * further processing should be done and negative on error`
	`725`	`+ * raw_event and event should return negative on error, any other value will`
	`726`	`+ * pass the event on to .event() typically return 0 for success.`
`727`	`727`	`*`
`728`	`728`	`* input_mapping shall return a negative value to completely ignore this usage`
`729`	`729`	`* (e.g. doubled or invalid usage), zero to continue with parsing of this`