[PATCH 0/8] input: Documentation: corrections to Doc/input/ files

[PATCH 0/8] input: Documentation: corrections to Doc/input/ files

[Randy Dunlap]

Update several Documentation/input/ files for wording, punctutation,
struct info, and file names.

Cc: Dmitry Torokhov <dmitry.torokhov@gmail.com>
Cc: linux-input@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org

 [PATCH 1/8] input: Documentation: corrections for input.rst
 [PATCH 2/8] input: Documentation: corrections for event-codes.rst
 [PATCH 3/8 RESEND] input: Documentation: update related file names in ff.rst
 [PATCH 4/8] input: Documentation: corrections for gameport-programming.rst
 [PATCH 5/8] input: Documentation: corrections for multi-touch-protocol.rst
 [PATCH 6/8] input: Documentation: corrections for notifier.rst
 [PATCH 7/8] input: Documentation: corrections for input-programming.rst
 [PATCH 8/8] input: Documentation: corrections for uinput.rst

 Documentation/input/event-codes.rst          |   10 ++--
 Documentation/input/ff.rst                   |    6 +-
 Documentation/input/gameport-programming.rst |   35 +++++++++++------
 Documentation/input/input-programming.rst    |   20 ++++-----
 Documentation/input/input.rst                |    8 +--
 Documentation/input/multi-touch-protocol.rst |    8 +--
 Documentation/input/notifier.rst             |    3 -
 Documentation/input/uinput.rst               |    2 
 8 files changed, 52 insertions(+), 40 deletions(-)

[PATCH 1/8] input: Documentation: corrections for input.rst

[Randy Dunlap]

Fix grammar, punctuation, and spelling.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Dmitry Torokhov <dmitry.torokhov@gmail.com>
Cc: linux-input@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
---
 Documentation/input/input.rst |    8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

--- linux-next-20210202.orig/Documentation/input/input.rst
+++ linux-next-20210202/Documentation/input/input.rst
@@ -9,7 +9,7 @@ Introduction
 Architecture
 ============
 
-Input subsystem  a collection of drivers that is designed to support
+Input subsystem is a collection of drivers that is designed to support
 all input devices under Linux. Most of the drivers reside in
 drivers/input, although quite a few live in drivers/hid and
 drivers/platform.
@@ -50,7 +50,7 @@ will be available as a character device
 
 	crw-r--r--   1 root     root      13,  63 Mar 28 22:45 mice
 
-This device usually created automatically by the system. The commands
+This device is usually created automatically by the system. The commands
 to create it by hand are::
 
 	cd /dev
@@ -180,7 +180,7 @@ whole suite. It handles all HID devices,
 wide variety of them, and because the USB HID specification isn't
 simple, it needs to be this big.
 
-Currently, it handles USB mice, joysticks, gamepads, steering wheels
+Currently, it handles USB mice, joysticks, gamepads, steering wheels,
 keyboards, trackballs and digitizers.
 
 However, USB uses HID also for monitor controls, speaker controls, UPSs,
@@ -268,7 +268,7 @@ events on a read. Their layout is::
     };
 
 ``time`` is the timestamp, it returns the time at which the event happened.
-Type is for example EV_REL for relative moment, EV_KEY for a keypress or
+Type is for example EV_REL for relative movement, EV_KEY for a keypress or
 release. More types are defined in include/uapi/linux/input-event-codes.h.
 
 ``code`` is event code, for example REL_X or KEY_BACKSPACE, again a complete

[PATCH 2/8] input: Documentation: corrections for event-codes.rst

[Randy Dunlap]

Fix hyphenation, typos, capitalization, and a referenced file name
(.txt -> .rst).

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Dmitry Torokhov <dmitry.torokhov@gmail.com>
Cc: linux-input@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
---
 Documentation/input/event-codes.rst |   10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

--- linux-next-20210202.orig/Documentation/input/event-codes.rst
+++ linux-next-20210202/Documentation/input/event-codes.rst
@@ -246,9 +246,9 @@ A few EV_ABS codes have special meanings
 
      A device should set the resolution of the axis to indicate whether the
      pressure is in measurable units. If the resolution is zero, the
-     pressure data is in arbitrary units. If the resolution is nonzero, the
+     pressure data is in arbitrary units. If the resolution is non-zero, the
      pressure data is in units/gram. For example, a value of 10 with a
-     resolution of 1 represents 10 gram, a value of 10 with a resolution on
+     resolution of 1 represents 10 gram, a value of 10 with a resolution of
      1000 represents 10 microgram.
 
 EV_SW
@@ -344,7 +344,7 @@ INPUT_PROP_BUTTONPAD
 
 For touchpads where the button is placed beneath the surface, such that
 pressing down on the pad causes a button click, this property should be
-set. Common in clickpad notebooks and macbooks from 2009 and onwards.
+set. Common in Clickpad notebooks and Macbooks from 2009 and onwards.
 
 Originally, the buttonpad property was coded into the bcm5974 driver
 version field under the name integrated button. For backwards
@@ -356,7 +356,7 @@ INPUT_PROP_SEMI_MT
 Some touchpads, most common between 2008 and 2011, can detect the presence
 of multiple contacts without resolving the individual positions; only the
 number of contacts and a rectangular shape is known. For such
-touchpads, the semi-mt property should be set.
+touchpads, the SEMI_MT property should be set.
 
 Depending on the device, the rectangle may enclose all touches, like a
 bounding box, or just some of them, for instance the two most recent
@@ -394,7 +394,7 @@ Guidelines
 ==========
 
 The guidelines below ensure proper single-touch and multi-finger functionality.
-For multi-touch functionality, see the multi-touch-protocol.txt document for
+For multi-touch functionality, see the multi-touch-protocol.rst document for
 more information.
 
 Mice

[PATCH 3/8 RESEND] input: Documentation: update related file names in ff.rst

[Randy Dunlap]

Change other related documentation file names from .txt to .rst
and be more explicit about their paths/locations.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Dmitry Torokhov <dmitry.torokhov@gmail.com>
Cc: linux-input@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Cc: Johann Deneux <johann.deneux@gmail.com>
Cc: Anssi Hannula <anssi.hannula@gmail.com>
---
where is fftest mentioned here found? I only found one place:
  https://github.com/flosse/linuxconsole/blob/master/utils/fftest.c

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

--- linux-next-20210202.orig/Documentation/input/ff.rst
+++ linux-next-20210202/Documentation/input/ff.rst
@@ -16,8 +16,8 @@ goal is not to support these devices as
 (as it is already the case), but to really enable the rendering of force
 effects.
 This document only describes the force feedback part of the Linux input
-interface. Please read joystick.txt and input.txt before reading further this
-document.
+interface. Please read joydev/joystick.rst and input.rst before reading further
+this document.
 
 Instructions to the user
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -36,7 +36,7 @@ should keep a hand on your device, in or
 something goes wrong.
 
 If you have a serial iforce device, you need to start inputattach. See
-joystick.txt for details.
+joydev/joystick.rst for details.
 
 Does it work ?
 --------------

[PATCH 4/8] input: Documentation: corrections for gameport-programming.rst

[Randy Dunlap]

Use "E.g." instead of "Eg.".
Use correct index for buttons[] array.
Update all of struct gameport's descriptions.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Dmitry Torokhov <dmitry.torokhov@gmail.com>
Cc: linux-input@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
---
 Documentation/input/gameport-programming.rst |   35 +++++++++++------
 1 file changed, 23 insertions(+), 12 deletions(-)

--- linux-next-20210202.orig/Documentation/input/gameport-programming.rst
+++ linux-next-20210202/Documentation/input/gameport-programming.rst
@@ -21,7 +21,7 @@ choose which one to program the hardware
 addresses is preferred, because the likelihood of clashing with the standard
 0x201 address is smaller.
 
-Eg. if your driver supports addresses 0x200, 0x208, 0x210 and 0x218, then
+E.g. if your driver supports addresses 0x200, 0x208, 0x210 and 0x218, then
 0x218 would be the address of first choice.
 
 If your hardware supports a gameport address that is not mapped to ISA io
@@ -78,7 +78,7 @@ the gameport. To register a cooked gamep
 
 		for (i = 0; i < 4; i++)
 			axes[i] = my_mmio[i];
-		buttons[i] = my_mmio[4];
+		buttons[0] = my_mmio[4];
 	}
 
 	int my_open(struct gameport *gameport, int mode)
@@ -117,25 +117,28 @@ Simple::
 The gameport structure
 ~~~~~~~~~~~~~~~~~~~~~~
 
-.. note::
-
-    This section is outdated. There are several fields here that don't
-    match what's there at include/linux/gameport.h.
-
 ::
 
     struct gameport {
 
-	void *private;
+	void *port_data;
 
 A private pointer for free use in the gameport driver. (Not the joystick
 driver!)
 
 ::
 
-	int number;
+	char name[32];
+
+Driver's name as set by driver calling gameport_set_name(). Informational
+purpose only.
+
+::
+
+	char phys[32];
 
-Number assigned to the gameport when registered. Informational purpose only.
+gameport's physical name/description as set by driver calling gameport_set_phys().
+Informational purpose only.
 
 ::
 
@@ -210,8 +213,16 @@ gameport.
 
 ::
 
-	struct gameport_dev *dev;
-	struct gameport *next;
+	struct timer_list poll_timer;
+	unsigned int poll_interval;     /* in msecs */
+	spinlock_t timer_lock;
+	unsigned int poll_cnt;
+	void (*poll_handler)(struct gameport *);
+	struct gameport *parent, *child;
+	struct gameport_driver *drv;
+	struct mutex drv_mutex;		/* protects serio->drv so attributes can pin driver */
+	struct device dev;
+	struct list_head node;
 
 For internal use by the gameport layer.
 

[PATCH 5/8] input: Documentation: corrections for multi-touch-protocol.rst

[Randy Dunlap]

Correct hyphenation, spelling, and capitalization.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Dmitry Torokhov <dmitry.torokhov@gmail.com>
Cc: linux-input@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Cc: Henrik Rydberg <rydberg@bitmath.org>
---
 Documentation/input/multi-touch-protocol.rst |    8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

--- linux-next-20210202.orig/Documentation/input/multi-touch-protocol.rst
+++ linux-next-20210202/Documentation/input/multi-touch-protocol.rst
@@ -261,7 +261,7 @@ ABS_MT_PRESSURE
     signal intensity distribution.
 
     If the resolution is zero, the pressure data is in arbitrary units.
-    If the resolution is nonzero, the pressure data is in units/gram. See
+    If the resolution is non-zero, the pressure data is in units/gram. See
     :ref:`input-event-codes` for details.
 
 ABS_MT_DISTANCE
@@ -279,14 +279,14 @@ ABS_MT_ORIENTATION
     max should be returned; when aligned with the X axis in the negative
     direction, the range -max should be returned.
 
-    Touch ellipsis are symmetrical by default. For devices capable of true 360
+    Touch ellipses are symmetrical by default. For devices capable of true 360
     degree orientation, the reported orientation must exceed the range max to
     indicate more than a quarter of a revolution. For an upside-down finger,
     range max * 2 should be returned.
 
     Orientation can be omitted if the touch area is circular, or if the
     information is not available in the kernel driver. Partial orientation
-    support is possible if the device can distinguish between the two axis, but
+    support is possible if the device can distinguish between the two axes, but
     not (uniquely) any values in between. In such cases, the range of
     ABS_MT_ORIENTATION should be [0, 1] [#f4]_.
 
@@ -356,7 +356,7 @@ The range of ABS_MT_ORIENTATION should b
 the device can distinguish between a finger along the Y axis (0) and a
 finger along the X axis (1).
 
-For win8 devices with both T and C coordinates, the position mapping is::
+For Win8 devices with both T and C coordinates, the position mapping is::
 
    ABS_MT_POSITION_X := T_X
    ABS_MT_POSITION_Y := T_Y

[PATCH 6/8] input: Documentation: corrections for notifier.rst

[Randy Dunlap]

Add 'ledstate' to the keyboard_notifier_param struct info and tell
which header file contains that struct.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Dmitry Torokhov <dmitry.torokhov@gmail.com>
Cc: linux-input@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
---
 Documentation/input/notifier.rst |    3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

--- linux-next-20210202.orig/Documentation/input/notifier.rst
+++ linux-next-20210202/Documentation/input/notifier.rst
@@ -4,11 +4,12 @@ Keyboard notifier
 
 One can use register_keyboard_notifier to get called back on keyboard
 events (see kbd_keycode() function for details).  The passed structure is
-keyboard_notifier_param:
+keyboard_notifier_param (see <linux/keyboard.h>):
 
 - 'vc' always provide the VC for which the keyboard event applies;
 - 'down' is 1 for a key press event, 0 for a key release;
 - 'shift' is the current modifier state, mask bit indexes are KG_*;
+- 'ledstate' is the current LED state;
 - 'value' depends on the type of event.
 
 - KBD_KEYCODE events are always sent before other events, value is the keycode.

[PATCH 7/8] input: Documentation: corrections for input-programming.rst

[Randy Dunlap]

Drop a repeated word.
Fix punctuation of "eg." to "e.g."
Fix punctuation of "ie" to "i.e."
Add hyphentation to non-zero.
Capitalize PM (for Power Management).
Capitalize ID (for Identifier).
Change "," in a run-on sentence to ";".

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Dmitry Torokhov <dmitry.torokhov@gmail.com>
Cc: linux-input@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
---
 Documentation/input/input-programming.rst |   20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

--- linux-next-20210202.orig/Documentation/input/input-programming.rst
+++ linux-next-20210202/Documentation/input/input-programming.rst
@@ -120,7 +120,7 @@ Then there is the::
 
 call to tell those who receive the events that we've sent a complete report.
 This doesn't seem important in the one button case, but is quite important
-for for example mouse movement, where you don't want the X and Y values
+for example for mouse movement, where you don't want the X and Y values
 to be interpreted separately, because that'd result in a different movement.
 
 dev->open() and dev->close()
@@ -128,7 +128,7 @@ dev->open() and dev->close()
 
 In case the driver has to repeatedly poll the device, because it doesn't
 have an interrupt coming from it and the polling is too expensive to be done
-all the time, or if the device uses a valuable resource (eg. interrupt), it
+all the time, or if the device uses a valuable resource (e.g. interrupt), it
 can use the open and close callback to know when it can stop polling or
 release the interrupt and when it must resume polling or grab the interrupt
 again. To do that, we would add this to our example driver::
@@ -161,7 +161,7 @@ makes sure that dev->open() is called on
 to the device and that dev->close() is called when the very last user
 disconnects. Calls to both callbacks are serialized.
 
-The open() callback should return a 0 in case of success or any nonzero value
+The open() callback should return a 0 in case of success or any non-zero value
 in case of failure. The close() callback (which is void) must always succeed.
 
 Inhibiting input devices
@@ -182,8 +182,8 @@ providing events to the input core.
 
 Calling the device's close() method on inhibit (if there are users) allows the
 driver to save power. Either by directly powering down the device or by
-releasing the runtime-pm reference it got in open() when the driver is using
-runtime-pm.
+releasing the runtime-PM reference it got in open() when the driver is using
+runtime-PM.
 
 Inhibiting and uninhibiting are orthogonal to opening and closing the device by
 input handlers. Userspace might want to inhibit a device in anticipation before
@@ -219,8 +219,8 @@ It's reported to the input system via::
 	input_report_key(struct input_dev *dev, int code, int value)
 
 See uapi/linux/input-event-codes.h for the allowable values of code (from 0 to
-KEY_MAX). Value is interpreted as a truth value, ie any nonzero value means key
-pressed, zero value means key released. The input code generates events only
+KEY_MAX). Value is interpreted as a truth value, i.e. any non-zero value means
+key pressed, zero value means key released. The input code generates events only
 in case the value is different from before.
 
 In addition to EV_KEY, there are two more basic event types: EV_REL and
@@ -231,12 +231,12 @@ because it doesn't have any absolute coo
 events are namely for joysticks and digitizers - devices that do work in an
 absolute coordinate systems.
 
-Having the device report EV_REL buttons is as simple as with EV_KEY, simply
+Having the device report EV_REL buttons is as simple as with EV_KEY; simply
 set the corresponding bits and call the::
 
 	input_report_rel(struct input_dev *dev, int code, int value)
 
-function. Events are generated only for nonzero value.
+function. Events are generated only for non-zero values.
 
 However EV_ABS requires a little special care. Before calling
 input_register_device, you have to fill additional fields in the input_dev
@@ -280,7 +280,7 @@ device driver. It's a string like 'Gener
 user friendly name of the device.
 
 The id* fields contain the bus ID (PCI, USB, ...), vendor ID and device ID
-of the device. The bus IDs are defined in input.h. The vendor and device ids
+of the device. The bus IDs are defined in input.h. The vendor and device IDs
 are defined in pci_ids.h, usb_ids.h and similar include files. These fields
 should be set by the input device driver before registering it.
 

[PATCH 8/8] input: Documentation: corrections for uinput.rst

[Randy Dunlap]

Fix a typo (supportinf -> supporting).

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Dmitry Torokhov <dmitry.torokhov@gmail.com>
Cc: linux-input@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
---
 Documentation/input/uinput.rst |    2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

--- linux-next-20210202.orig/Documentation/input/uinput.rst
+++ linux-next-20210202/Documentation/input/uinput.rst
@@ -179,7 +179,7 @@ uinput old interface
 --------------------
 
 Before uinput version 5, there wasn't a dedicated ioctl to set up a virtual
-device. Programs supportinf older versions of uinput interface need to fill
+device. Programs supporting older versions of uinput interface need to fill
 a uinput_user_dev structure and write it to the uinput file descriptor to
 configure the new uinput device. New code should not use the old interface
 but interact with uinput via ioctl calls, or use libevdev.

Re: [PATCH 0/8] input: Documentation: corrections to Doc/input/ files

[Jonathan Corbet]

Randy Dunlap <rdunlap@infradead.org> writes:

> Update several Documentation/input/ files for wording, punctutation,
> struct info, and file names.
>
> Cc: Dmitry Torokhov <dmitry.torokhov@gmail.com>
> Cc: linux-input@vger.kernel.org
> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: linux-doc@vger.kernel.org
>
>  [PATCH 1/8] input: Documentation: corrections for input.rst
>  [PATCH 2/8] input: Documentation: corrections for event-codes.rst
>  [PATCH 3/8 RESEND] input: Documentation: update related file names in ff.rst
>  [PATCH 4/8] input: Documentation: corrections for gameport-programming.rst
>  [PATCH 5/8] input: Documentation: corrections for multi-touch-protocol.rst
>  [PATCH 6/8] input: Documentation: corrections for notifier.rst
>  [PATCH 7/8] input: Documentation: corrections for input-programming.rst
>  [PATCH 8/8] input: Documentation: corrections for uinput.rst
>
>  Documentation/input/event-codes.rst          |   10 ++--
>  Documentation/input/ff.rst                   |    6 +-
>  Documentation/input/gameport-programming.rst |   35 +++++++++++------
>  Documentation/input/input-programming.rst    |   20 ++++-----
>  Documentation/input/input.rst                |    8 +--
>  Documentation/input/multi-touch-protocol.rst |    8 +--
>  Documentation/input/notifier.rst             |    3 -
>  Documentation/input/uinput.rst               |    2 
>  8 files changed, 52 insertions(+), 40 deletions(-)

Set applied, thanks.

jon