This patch series address a few issues at the documentation, after
applying this patch series:
https://lkml.org/lkml/2017/4/16/2
The first patch solves a limitation with Sphinx and literal blocks
inside a footnote.
The next two patches fix issues with xpad.rst documentation, with
mentions /proc/bus/usb/, with used to be part of usbfs. When usbfs
got removed, the old location changed. So, update accordingly.
The final patch is RFC: it adds the uapi input.h file to the
documentation and groups the kAPI documentation generated from the
source code together with the kAPI part of the linux-input book.
We need to discuss it with documentation maintainers, to get an
agreement if this is the best way to handle it.
Mauro Carvalho Chehab (4):
input: xpad.rst: usb/devices is now at /sys/kernel/debug/
input: xpad.rst: Don't use literal blocks inside footnotes
input: xpad.rst: proc/bus/usb was renamed to dev/bus/usb
[RFC] input: add kAPI and uAPI kernel-doc stuff at the input book
Documentation/driver-api/iio/intro.rst | 4 +-
Documentation/driver-api/index.rst | 1 -
Documentation/input/devices/xpad.rst | 53 +++++++++++-----------
Documentation/input/input_kapi.rst | 1 +
.../input.rst => input/input_kapi_symbols.rst} | 6 ++-
Documentation/input/input_uapi.rst | 1 +
Documentation/input/input_uapi_symbols.rst | 4 ++
7 files changed, 38 insertions(+), 32 deletions(-)
rename Documentation/{driver-api/input.rst => input/input_kapi_symbols.rst} (93%)
create mode 100644 Documentation/input/input_uapi_symbols.rst
--
2.9.3
xpad.rst requests a dump of the USB description, as found
on the USB character device. When we got rid of usbfs,
its location change. Update it.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/input/devices/xpad.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/input/devices/xpad.rst b/Documentation/input/devices/xpad.rst
index c7c4e154bd34..3c74c185be7d 100644
--- a/Documentation/input/devices/xpad.rst
+++ b/Documentation/input/devices/xpad.rst
@@ -89,7 +89,7 @@ HOWEVER if you have an unknown dance pad not listed below, it will not
work UNLESS you set "dpad_to_buttons" to 1 in the module configuration.
PLEASE, if you have an unknown controller, email Dom <[email protected]> with
-a dump from /proc/bus/usb and a description of the pad (manufacturer, country,
+a dump from /dev/bus/usb and a description of the pad (manufacturer, country,
whether it is a dance pad or normal controller) so that we can add your pad
to the list of supported devices, ensuring that it will work out of the
box in the future.
--
2.9.3
Unfortunately, Sphinx (or LaTeX) can't handle literal blocks
inside footnotes. So, just use normal text for the two
literal code-blocks that documents the output of
/sys/kernel/debug/usb/devices for xpad devices.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/input/devices/xpad.rst | 51 ++++++++++++++++++------------------
1 file changed, 25 insertions(+), 26 deletions(-)
diff --git a/Documentation/input/devices/xpad.rst b/Documentation/input/devices/xpad.rst
index e19669fe5a80..c7c4e154bd34 100644
--- a/Documentation/input/devices/xpad.rst
+++ b/Documentation/input/devices/xpad.rst
@@ -138,15 +138,37 @@ Driver Installation
Once you have the adapter cable, if needed, and the controller connected
the xpad module should be auto loaded. To confirm you can cat
-/sys/kernel/debug/usb/devices. There should be an entry like the one at the end [4]_.
+/sys/kernel/debug/usb/devices. There should be an entry like those:
+.. code-block:: none
+ :caption: dump from InterAct PowerPad Pro (Germany)
+
+ T: Bus=01 Lev=03 Prnt=04 Port=00 Cnt=01 Dev#= 5 Spd=12 MxCh= 0
+ D: Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS=32 #Cfgs= 1
+ P: Vendor=05fd ProdID=107a Rev= 1.00
+ C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA
+ I: If#= 0 Alt= 0 #EPs= 2 Cls=58(unk. ) Sub=42 Prot=00 Driver=(none)
+ E: Ad=81(I) Atr=03(Int.) MxPS= 32 Ivl= 10ms
+ E: Ad=02(O) Atr=03(Int.) MxPS= 32 Ivl= 10ms
+
+.. code-block:: none
+ :caption: dump from Redoctane Xbox Dance Pad (US)
+
+ T: Bus=01 Lev=02 Prnt=09 Port=00 Cnt=01 Dev#= 10 Spd=12 MxCh= 0
+ D: Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
+ P: Vendor=0c12 ProdID=8809 Rev= 0.01
+ S: Product=XBOX DDR
+ C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA
+ I: If#= 0 Alt= 0 #EPs= 2 Cls=58(unk. ) Sub=42 Prot=00 Driver=xpad
+ E: Ad=82(I) Atr=03(Int.) MxPS= 32 Ivl=4ms
+ E: Ad=02(O) Atr=03(Int.) MxPS= 32 Ivl=4ms
Supported Controllers
=====================
For a full list of supported controllers and associated vendor and product
-IDs see the xpad_device[] array[6].
+IDs see the xpad_device[] array\ [4]_.
As of the historic version 0.0.6 (2006-10-10) the following devices
were supported::
@@ -202,30 +224,7 @@ References
.. [1] http://euc.jp/periphs/xbox-controller.ja.html (ITO Takayuki)
.. [2] http://xpad.xbox-scene.com/
.. [3] http://www.markosweb.com/www/xboxhackz.com/
-.. [4] /sys/kernel/debug/usb/devices - dump from InterAct PowerPad Pro (Germany):
-
- ::
-
- T: Bus=01 Lev=03 Prnt=04 Port=00 Cnt=01 Dev#= 5 Spd=12 MxCh= 0
- D: Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS=32 #Cfgs= 1
- P: Vendor=05fd ProdID=107a Rev= 1.00
- C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA
- I: If#= 0 Alt= 0 #EPs= 2 Cls=58(unk. ) Sub=42 Prot=00 Driver=(none)
- E: Ad=81(I) Atr=03(Int.) MxPS= 32 Ivl= 10ms
- E: Ad=02(O) Atr=03(Int.) MxPS= 32 Ivl= 10ms
-.. [5] /sys/kernel/debug/usb/devices - dump from Redoctane Xbox Dance Pad (US):
-
- ::
-
- T: Bus=01 Lev=02 Prnt=09 Port=00 Cnt=01 Dev#= 10 Spd=12 MxCh= 0
- D: Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
- P: Vendor=0c12 ProdID=8809 Rev= 0.01
- S: Product=XBOX DDR
- C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA
- I: If#= 0 Alt= 0 #EPs= 2 Cls=58(unk. ) Sub=42 Prot=00 Driver=xpad
- E: Ad=82(I) Atr=03(Int.) MxPS= 32 Ivl=4ms
- E: Ad=02(O) Atr=03(Int.) MxPS= 32 Ivl=4ms
-.. [6] http://lxr.free-electrons.com/ident?i=xpad_device
+.. [4] http://lxr.free-electrons.com/ident?i=xpad_device
Historic Edits
--
2.9.3
The /proc/bus/usb/devices got moved to sysfs. It is now
sitting at:
/sys/kernel/debug/usb/devices
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/input/devices/xpad.rst | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/Documentation/input/devices/xpad.rst b/Documentation/input/devices/xpad.rst
index 80028433b460..e19669fe5a80 100644
--- a/Documentation/input/devices/xpad.rst
+++ b/Documentation/input/devices/xpad.rst
@@ -138,7 +138,7 @@ Driver Installation
Once you have the adapter cable, if needed, and the controller connected
the xpad module should be auto loaded. To confirm you can cat
-/proc/bus/usb/devices. There should be an entry like the one at the end [4]_.
+/sys/kernel/debug/usb/devices. There should be an entry like the one at the end [4]_.
@@ -202,7 +202,7 @@ References
.. [1] http://euc.jp/periphs/xbox-controller.ja.html (ITO Takayuki)
.. [2] http://xpad.xbox-scene.com/
.. [3] http://www.markosweb.com/www/xboxhackz.com/
-.. [4] /proc/bus/usb/devices - dump from InterAct PowerPad Pro (Germany):
+.. [4] /sys/kernel/debug/usb/devices - dump from InterAct PowerPad Pro (Germany):
::
@@ -213,7 +213,7 @@ References
I: If#= 0 Alt= 0 #EPs= 2 Cls=58(unk. ) Sub=42 Prot=00 Driver=(none)
E: Ad=81(I) Atr=03(Int.) MxPS= 32 Ivl= 10ms
E: Ad=02(O) Atr=03(Int.) MxPS= 32 Ivl= 10ms
-.. [5] /proc/bus/usb/devices - dump from Redoctane Xbox Dance Pad (US):
+.. [5] /sys/kernel/debug/usb/devices - dump from Redoctane Xbox Dance Pad (US):
::
--
2.9.3
Move the kAPI kernel-doc produced documentation to
Documentation/input and add uAPI documentation there too.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/driver-api/iio/intro.rst | 4 ++--
Documentation/driver-api/index.rst | 1 -
Documentation/input/input_kapi.rst | 1 +
.../{driver-api/input.rst => input/input_kapi_symbols.rst} | 6 ++++--
Documentation/input/input_uapi.rst | 1 +
Documentation/input/input_uapi_symbols.rst | 4 ++++
6 files changed, 12 insertions(+), 5 deletions(-)
rename Documentation/{driver-api/input.rst => input/input_kapi_symbols.rst} (93%)
create mode 100644 Documentation/input/input_uapi_symbols.rst
diff --git a/Documentation/driver-api/iio/intro.rst b/Documentation/driver-api/iio/intro.rst
index 3653fbd57069..696f7f99a459 100644
--- a/Documentation/driver-api/iio/intro.rst
+++ b/Documentation/driver-api/iio/intro.rst
@@ -8,9 +8,9 @@ The main purpose of the Industrial I/O subsystem (IIO) is to provide support
for devices that in some sense perform either
analog-to-digital conversion (ADC) or digital-to-analog conversion (DAC)
or both. The aim is to fill the gap between the somewhat similar hwmon and
-:doc:`input <../input>` subsystems. Hwmon is directed at low sample rate
+:ref:`input <input_kapi>` subsystems. Hwmon is directed at low sample rate
sensors used to monitor and control the system itself, like fan speed control
-or temperature measurement. :doc:`Input <../input>` is, as its name suggests,
+or temperature measurement. :ref:`Input <input_kapi>` is, as its name suggests,
focused on human interaction input devices (keyboard, mouse, touchscreen).
In some cases there is considerable overlap between these and IIO.
diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index 60db00d1532b..d7bc5e8bf3a1 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -25,7 +25,6 @@ available subsections can be seen below.
frame-buffer
regulator
iio/index
- input
usb
spi
i2c
diff --git a/Documentation/input/input_kapi.rst b/Documentation/input/input_kapi.rst
index 41f1b7e6b78e..b3ee24881773 100644
--- a/Documentation/input/input_kapi.rst
+++ b/Documentation/input/input_kapi.rst
@@ -15,3 +15,4 @@ Linux Input Subsystem kernel API
input-programming
gameport-programming
notifier
+ input_kapi_symbols
diff --git a/Documentation/driver-api/input.rst b/Documentation/input/input_kapi_symbols.rst
similarity index 93%
rename from Documentation/driver-api/input.rst
rename to Documentation/input/input_kapi_symbols.rst
index d05bf58fa83e..b85b34303f72 100644
--- a/Documentation/driver-api/input.rst
+++ b/Documentation/input/input_kapi_symbols.rst
@@ -1,5 +1,7 @@
-Input Subsystem
-===============
+.. _input_kapi:
+
+Input kAPI reference
+====================
Input core
----------
diff --git a/Documentation/input/input_uapi.rst b/Documentation/input/input_uapi.rst
index 12ef8974a773..59596af7e01f 100644
--- a/Documentation/input/input_uapi.rst
+++ b/Documentation/input/input_uapi.rst
@@ -19,3 +19,4 @@ Linux Input Subsystem userspace API
ff
joydev/index
userio
+ input_uapi_symbols
diff --git a/Documentation/input/input_uapi_symbols.rst b/Documentation/input/input_uapi_symbols.rst
new file mode 100644
index 000000000000..9cb29d10e483
--- /dev/null
+++ b/Documentation/input/input_uapi_symbols.rst
@@ -0,0 +1,4 @@
+Input uAPI reference
+====================
+
+.. kernel-doc:: include/uapi/linux/input.h
--
2.9.3
Hi Mauro,
On Mon, Apr 17, 2017 at 09:46:15AM -0300, Mauro Carvalho Chehab wrote:
> xpad.rst requests a dump of the USB description, as found
> on the USB character device. When we got rid of usbfs,
> its location change. Update it.
I have not heard from Dom ever so I think the best option is to remove
this entire paragraph.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
> ---
> Documentation/input/devices/xpad.rst | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/input/devices/xpad.rst b/Documentation/input/devices/xpad.rst
> index c7c4e154bd34..3c74c185be7d 100644
> --- a/Documentation/input/devices/xpad.rst
> +++ b/Documentation/input/devices/xpad.rst
> @@ -89,7 +89,7 @@ HOWEVER if you have an unknown dance pad not listed below, it will not
> work UNLESS you set "dpad_to_buttons" to 1 in the module configuration.
>
> PLEASE, if you have an unknown controller, email Dom <[email protected]> with
> -a dump from /proc/bus/usb and a description of the pad (manufacturer, country,
> +a dump from /dev/bus/usb and a description of the pad (manufacturer, country,
> whether it is a dance pad or normal controller) so that we can add your pad
> to the list of supported devices, ensuring that it will work out of the
> box in the future.
> --
> 2.9.3
>
--
Dmitry
On Mon, Apr 17, 2017 at 09:46:13AM -0300, Mauro Carvalho Chehab wrote:
> The /proc/bus/usb/devices got moved to sysfs. It is now
> sitting at:
> /sys/kernel/debug/usb/devices
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Applied, thank you.
> ---
> Documentation/input/devices/xpad.rst | 6 +++---
> 1 file changed, 3 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/input/devices/xpad.rst b/Documentation/input/devices/xpad.rst
> index 80028433b460..e19669fe5a80 100644
> --- a/Documentation/input/devices/xpad.rst
> +++ b/Documentation/input/devices/xpad.rst
> @@ -138,7 +138,7 @@ Driver Installation
>
> Once you have the adapter cable, if needed, and the controller connected
> the xpad module should be auto loaded. To confirm you can cat
> -/proc/bus/usb/devices. There should be an entry like the one at the end [4]_.
> +/sys/kernel/debug/usb/devices. There should be an entry like the one at the end [4]_.
>
>
>
> @@ -202,7 +202,7 @@ References
> .. [1] http://euc.jp/periphs/xbox-controller.ja.html (ITO Takayuki)
> .. [2] http://xpad.xbox-scene.com/
> .. [3] http://www.markosweb.com/www/xboxhackz.com/
> -.. [4] /proc/bus/usb/devices - dump from InterAct PowerPad Pro (Germany):
> +.. [4] /sys/kernel/debug/usb/devices - dump from InterAct PowerPad Pro (Germany):
>
> ::
>
> @@ -213,7 +213,7 @@ References
> I: If#= 0 Alt= 0 #EPs= 2 Cls=58(unk. ) Sub=42 Prot=00 Driver=(none)
> E: Ad=81(I) Atr=03(Int.) MxPS= 32 Ivl= 10ms
> E: Ad=02(O) Atr=03(Int.) MxPS= 32 Ivl= 10ms
> -.. [5] /proc/bus/usb/devices - dump from Redoctane Xbox Dance Pad (US):
> +.. [5] /sys/kernel/debug/usb/devices - dump from Redoctane Xbox Dance Pad (US):
>
> ::
>
> --
> 2.9.3
>
--
Dmitry
On Mon, Apr 17, 2017 at 09:46:14AM -0300, Mauro Carvalho Chehab wrote:
> Unfortunately, Sphinx (or LaTeX) can't handle literal blocks
> inside footnotes. So, just use normal text for the two
> literal code-blocks that documents the output of
> /sys/kernel/debug/usb/devices for xpad devices.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Applied, thank you.
> ---
> Documentation/input/devices/xpad.rst | 51 ++++++++++++++++++------------------
> 1 file changed, 25 insertions(+), 26 deletions(-)
>
> diff --git a/Documentation/input/devices/xpad.rst b/Documentation/input/devices/xpad.rst
> index e19669fe5a80..c7c4e154bd34 100644
> --- a/Documentation/input/devices/xpad.rst
> +++ b/Documentation/input/devices/xpad.rst
> @@ -138,15 +138,37 @@ Driver Installation
>
> Once you have the adapter cable, if needed, and the controller connected
> the xpad module should be auto loaded. To confirm you can cat
> -/sys/kernel/debug/usb/devices. There should be an entry like the one at the end [4]_.
> +/sys/kernel/debug/usb/devices. There should be an entry like those:
>
> +.. code-block:: none
> + :caption: dump from InterAct PowerPad Pro (Germany)
> +
> + T: Bus=01 Lev=03 Prnt=04 Port=00 Cnt=01 Dev#= 5 Spd=12 MxCh= 0
> + D: Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS=32 #Cfgs= 1
> + P: Vendor=05fd ProdID=107a Rev= 1.00
> + C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA
> + I: If#= 0 Alt= 0 #EPs= 2 Cls=58(unk. ) Sub=42 Prot=00 Driver=(none)
> + E: Ad=81(I) Atr=03(Int.) MxPS= 32 Ivl= 10ms
> + E: Ad=02(O) Atr=03(Int.) MxPS= 32 Ivl= 10ms
> +
> +.. code-block:: none
> + :caption: dump from Redoctane Xbox Dance Pad (US)
> +
> + T: Bus=01 Lev=02 Prnt=09 Port=00 Cnt=01 Dev#= 10 Spd=12 MxCh= 0
> + D: Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
> + P: Vendor=0c12 ProdID=8809 Rev= 0.01
> + S: Product=XBOX DDR
> + C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA
> + I: If#= 0 Alt= 0 #EPs= 2 Cls=58(unk. ) Sub=42 Prot=00 Driver=xpad
> + E: Ad=82(I) Atr=03(Int.) MxPS= 32 Ivl=4ms
> + E: Ad=02(O) Atr=03(Int.) MxPS= 32 Ivl=4ms
>
>
> Supported Controllers
> =====================
>
> For a full list of supported controllers and associated vendor and product
> -IDs see the xpad_device[] array[6].
> +IDs see the xpad_device[] array\ [4]_.
>
> As of the historic version 0.0.6 (2006-10-10) the following devices
> were supported::
> @@ -202,30 +224,7 @@ References
> .. [1] http://euc.jp/periphs/xbox-controller.ja.html (ITO Takayuki)
> .. [2] http://xpad.xbox-scene.com/
> .. [3] http://www.markosweb.com/www/xboxhackz.com/
> -.. [4] /sys/kernel/debug/usb/devices - dump from InterAct PowerPad Pro (Germany):
> -
> - ::
> -
> - T: Bus=01 Lev=03 Prnt=04 Port=00 Cnt=01 Dev#= 5 Spd=12 MxCh= 0
> - D: Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS=32 #Cfgs= 1
> - P: Vendor=05fd ProdID=107a Rev= 1.00
> - C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA
> - I: If#= 0 Alt= 0 #EPs= 2 Cls=58(unk. ) Sub=42 Prot=00 Driver=(none)
> - E: Ad=81(I) Atr=03(Int.) MxPS= 32 Ivl= 10ms
> - E: Ad=02(O) Atr=03(Int.) MxPS= 32 Ivl= 10ms
> -.. [5] /sys/kernel/debug/usb/devices - dump from Redoctane Xbox Dance Pad (US):
> -
> - ::
> -
> - T: Bus=01 Lev=02 Prnt=09 Port=00 Cnt=01 Dev#= 10 Spd=12 MxCh= 0
> - D: Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
> - P: Vendor=0c12 ProdID=8809 Rev= 0.01
> - S: Product=XBOX DDR
> - C:* #Ifs= 1 Cfg#= 1 Atr=80 MxPwr=100mA
> - I: If#= 0 Alt= 0 #EPs= 2 Cls=58(unk. ) Sub=42 Prot=00 Driver=xpad
> - E: Ad=82(I) Atr=03(Int.) MxPS= 32 Ivl=4ms
> - E: Ad=02(O) Atr=03(Int.) MxPS= 32 Ivl=4ms
> -.. [6] http://lxr.free-electrons.com/ident?i=xpad_device
> +.. [4] http://lxr.free-electrons.com/ident?i=xpad_device
>
>
> Historic Edits
> --
> 2.9.3
>
--
Dmitry