Some documentation fixes

PATCH Applied Mauro Carvalho Chehab 2 participants 8 messages Apr 17, 2017 – Apr 18, 2017

Subsystems (3)

Documentation IIO Input drivers

lore

Share & tools

lore

Mauro Carvalho Chehab

author

2017-04-17 12:47 UTC #0 lore raw

cover Some documentation fixes

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

Signature · 1 line

2.9.3

Mauro Carvalho Chehab

author

2017-04-17 12:46 UTC #1 lore raw

PATCH 1/4 input: xpad.rst: usb/devices is now at /sys/kernel/debug/

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(-)

Documentation/input/devices/xpad.rst +3 -3

index 80028433b460..e19669fe5a80 100644
@@ -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):
 
  ::

Signature · 1 line

2.9.3

Dmitry Torokhov

maintainer Applied

2017-04-18 03:11 UTC #2 lore raw

Re: [PATCH 1/4] input: xpad.rst: usb/devices is now at /sys/kernel/debug/

Quoted 5 lines · Mauro Carvalho Chehab

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.

Quoted 38 lines

---
 Documentation/input/devices/xpad.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

Documentation/input/devices/xpad.rst +3 -3

index 80028433b460..e19669fe5a80 100644
@@ -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):
 
  ::

Signature · 1 line

2.9.3

Signature · 1 line

Dmitry

Mauro Carvalho Chehab

author

2017-04-17 12:46 UTC #3 lore raw

PATCH 2/4 input: xpad.rst: Don't use literal blocks inside footnotes

In reply to Mauro Carvalho Chehab

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(-)

Documentation/input/devices/xpad.rst +25 ~~-26~~

index e19669fe5a80..c7c4e154bd34 100644
@@ -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

Signature · 1 line

2.9.3

Dmitry Torokhov

maintainer Applied

2017-04-18 03:11 UTC #4 lore raw

Re: [PATCH 2/4] input: xpad.rst: Don't use literal blocks inside footnotes

Quoted 6 lines · Mauro Carvalho Chehab

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.

Quoted 83 lines

---
 Documentation/input/devices/xpad.rst | 51 ++++++++++++++++++------------------
 1 file changed, 25 insertions(+), 26 deletions(-)

Documentation/input/devices/xpad.rst +25 ~~-26~~

index e19669fe5a80..c7c4e154bd34 100644
@@ -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

Signature · 1 line

2.9.3

Signature · 1 line

Dmitry

Mauro Carvalho Chehab

author

2017-04-17 12:46 UTC #5 lore raw

PATCH 3/4 input: xpad.rst: proc/bus/usb was renamed to dev/bus/usb

In reply to Mauro Carvalho Chehab

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(-)

Documentation/input/devices/xpad.rst +1 -1

index c7c4e154bd34..3c74c185be7d 100644
@@ -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.

Signature · 1 line

2.9.3

Dmitry Torokhov

maintainer

2017-04-18 03:11 UTC #6 lore raw

Re: [PATCH 3/4] input: xpad.rst: proc/bus/usb was renamed to dev/bus/usb

Hi Mauro,

Quoted 3 lines · Mauro Carvalho Chehab

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.

Quoted 22 lines

Signed-off-by Mauro Carvalho Chehab <[email protected]>

---
 Documentation/input/devices/xpad.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

Documentation/input/devices/xpad.rst +1 -1

index c7c4e154bd34..3c74c185be7d 100644
@@ -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.

Signature · 1 line

2.9.3

Signature · 1 line

Dmitry

Mauro Carvalho Chehab

author

2017-04-17 12:47 UTC #7 lore raw

RFC PATCH 4/4 input: add kAPI and uAPI kernel-doc stuff at the input book

In reply to Mauro Carvalho Chehab

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

Documentation/driver-api/iio/intro.rst +2 -2

index 3653fbd57069..696f7f99a459 100644
@@ -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.

Documentation/driver-api/index.rst +0 -1

index 60db00d1532b..d7bc5e8bf3a1 100644
@@ -25,7 +25,6 @@ available subsections can be seen below.
    frame-buffer
    regulator
    iio/index
-   input
    usb
    spi
    i2c

Documentation/input/input_kapi.rst +1 -0

index 41f1b7e6b78e..b3ee24881773 100644
@@ -15,3 +15,4 @@ Linux Input Subsystem kernel API
    input-programming
    gameport-programming
    notifier
+   input_kapi_symbols

Documentation/input/input_kapi_symbols.rst renamed from Documentation/driver-api/input.rst +4 -2

similarity index 93%
rename from Documentation/driver-api/input.rst
rename to Documentation/input/input_kapi_symbols.rst
index d05bf58fa83e..b85b34303f72 100644
@@ -1,5 +1,7 @@
-Input Subsystem
-===============
+.. _input_kapi:
+
+Input kAPI reference
+====================
 
 Input core
 ----------

Documentation/input/input_uapi.rst +1 -0

index 12ef8974a773..59596af7e01f 100644
@@ -19,3 +19,4 @@ Linux Input Subsystem userspace API
    ff
    joydev/index
    userio
+   input_uapi_symbols

Documentation/input/input_uapi_symbols.rst new file +4 -0

new file mode 100644
index 000000000000..9cb29d10e483
@@ -0,0 +1,4 @@
+Input uAPI reference
+====================
+
+.. kernel-doc:: include/uapi/linux/input.h

Signature · 1 line

2.9.3