Re: [PATCH] docs: conf.py: increase recursion limit
Em Thu, 13 Apr 2017 18:25:12 +0200
Markus Heiser escreveu:
> Am 13.04.2017 um 15:29 schrieb Mauro Carvalho Chehab
> :
>
> > Em Thu, 13 Apr 2017 14:55:03 +0200
> > Markus Heiser escreveu:
> >
> >> On 13.04.2017 12:42, Mauro Carvalho Chehab wrote:
> >>> The default recursion limit is not good enough to handle
> >>> complex books. I'm sometimes receiving this error message:
> >>>
> >>> sphinx.errors.SphinxParallelError: RecursionError: maximum recursion
> >>> depth exceeded while pickling an object
> >>>
> >>> or those:
> >>>
> >>> maximum recursion depth exceeded while calling a Python object
> >>> This can happen with very large or deeply nested source files. You can
> >>> carefully increase the default Python recursion limit of 1000 in conf.py
> >>> with e.g.:
> >>> import sys; sys.setrecursionlimit(1500)
> >>>
> >>
> >> Is this behavior reproducible?
> >
> > I noticed the issue when building the docs with Sphinx 1.4.9 with
> > my ABI patches, after adding xref links to it.
> >
> > What I suspect is that Sphinx use some sort of fragile recursion
> > algorithm to parse cross references.
>
>Or the the generated refs are absurd ;)
>
> I haven't found the technical problem in detail, but I made some
> test and this is what I observed; Sometimes even a "clean":
>
> make DOCBOOKS= clean htmldocs
>
> fails with recursion error. I also realized that this behavior
> is only about the generated ABI docs. So I looked at what the
> Perl script generates:
>
> ./scripts/get_abi.pl rest --dir Documentation/ABI/testing
>
> It generates horrible titles, containing more than 4000 characters!
> I mean titles like the one shown in "" below.
> Which ends in HTML links like the one below.
>
> OK, we can discuss why Sphinx have problems handling such titles
> and refs but:
>
> at this point I stop digging any deeper ;)
>
> IMO: this is not the way, we can include ABI into the reST doc
The problem is that a few ABI files define a single description
for a lot of different symbols. That's true, for example on
this ABI file:
Documentation/ABI/testing/sysfs-bus-iio
One alternative is to replace the titles by a table, like
what the attached patch does.
IMHO, the result looks OK:
https://mchehab.fedorapeople.org/kernel_docs/admin-guide/abi.html
I added it to my development tree:
https://git.linuxtv.org//mchehab/experimental.git/log/?h=abi_docs_v3
With this change, I removed the setrecursionlimit() call and did a
clean build. It worked fine. So, perhaps it solved the issue.
Regards,
Mauro
---
scripts/get_abi.pl: represent what in tables
Several entries at the ABI have multiple What: with the same
description.
Instead of showing those symbols as sections, let's show them
as tables. That makes easier to read on the final output,
and avoid too much recursion at Sphinx parsing.
We need to put file references at the end, as we don't want
non-file tables to be mangled with other entries.
Signed-off-by: Mauro Carvalho Chehab
diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index eb62385630e6..7856d5db44d1 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -193,16 +193,19 @@ sub parse_abi {
#
# Outputs the book on ReST format
#
+
sub output_rest {
- foreach my $what (sort keys %data) {
+ foreach my $what (sort {
+ ($data{$a}->{type} eq "File") cmp
($data{$b}->{type} eq "File") ||
+ $a cmp $b
+ } keys %data) {
my $type = $data{$what}->{type};
my $file = $data{$what}->{file};
+ my $filepath = $data{$what}->{filepath};
my $w = $what;
$w =~ s/([\(\)\_\-\*\=\^\~\\])/\\$1/g;
- my $bar = $w;
- $bar =~ s/./-/g;
foreach my $p (@{$data{$what}->{label}}) {
my ($content, $label) = @{$p};
@@ -222,9 +225,37 @@ sub output_rest {
last;
}
- print "$w\n$bar\n\n";
- print "- defined on file $file (type: $type)\n\n" if ($type ne
"File");
+ $filepath =~ s,.*/(.*/.*),\1,;;
+ $filepath =~ s,[/\-],_,g;;
+ my $fileref = "abi_file_".$filepath;
+
+ if ($type eq "File") {
+ my $bar = $w;
+ $bar =~ s/./-/g;
+
+ print ".. _$fileref:\n\n";
+ print "$w\n$bar\n\n";
+ } else {
+ my @names = split /\s*,\s*/,$w;
+
+ my $len = 0;
+
+ foreach my $name (@names) {
+ $len = length($name) if (length($name) > $len);
+ }
+
+ print "What:\n\n";
+
+ print "+-" . "-" x $len . "-+\n";
+ foreach my $name (@names) {
+
Re: [PATCH v4 3/5] input: add a EV_SW event for ratchet switch
Hi Mauro,
On Tue, Apr 11, 2017 at 10:29:40AM -0300, Mauro Carvalho Chehab wrote:
> Some mice have a switch on their wheel, allowing to switch
> between ratchet and free wheel mode. Add support for it.
>
> Signed-off-by: Mauro Carvalho Chehab
> ---
> Documentation/input/event-codes.txt| 12
> include/linux/mod_devicetable.h| 2 +-
> include/uapi/linux/input-event-codes.h | 4 +++-
> 3 files changed, 16 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/input/event-codes.txt
> b/Documentation/input/event-codes.txt
> index 50352ab5f6d4..5dbd45db9bf6 100644
> --- a/Documentation/input/event-codes.txt
> +++ b/Documentation/input/event-codes.txt
> @@ -206,6 +206,18 @@ Upon resume, if the switch state is the same as before
> suspend, then the input
> subsystem will filter out the duplicate switch state reports. The driver does
> not need to keep the state of the switch at any time.
>
> +A few EV_SW codes have special meanings:
> +
> +* SW_RATCHET:
> +
> + - Some mice have a special switch for their wheel that allows to change
> +between free wheel mode and ratchet mode. When the switch is ratchet
> +mode (ON state), the wheel will offer some resistance for movements. It
> +may also provide a tactile feedback when scrolled.
> +
> +Note that some mice have a ratchet switch that does not generate a
> +software event.
So it is still not clear to me why we need the 2 discrete events. Either
we key off the behavior off the new REL event, or from switch, but not
both.
Also, it is unclear to me if allocating a new event for "hires" wheel is
optimal. This still does not solve the question about resolution (how
high is "hires" and what to do if Logitech will come out with
ultra-high-resolution wheel next year, or if we need to express
resolution for other relative events).
Thanks.
> +
> EV_MSC:
> --
> EV_MSC events are used for input and output events that do not fall under
> other
> diff --git a/include/linux/mod_devicetable.h b/include/linux/mod_devicetable.h
> index a3e8c572a046..79dd7dbf5442 100644
> --- a/include/linux/mod_devicetable.h
> +++ b/include/linux/mod_devicetable.h
> @@ -292,7 +292,7 @@ struct pcmcia_device_id {
> #define INPUT_DEVICE_ID_LED_MAX 0x0f
> #define INPUT_DEVICE_ID_SND_MAX 0x07
> #define INPUT_DEVICE_ID_FF_MAX 0x7f
> -#define INPUT_DEVICE_ID_SW_MAX 0x0f
> +#define INPUT_DEVICE_ID_SW_MAX 0x1f
>
> #define INPUT_DEVICE_ID_MATCH_BUS1
> #define INPUT_DEVICE_ID_MATCH_VENDOR 2
> diff --git a/include/uapi/linux/input-event-codes.h
> b/include/uapi/linux/input-event-codes.h
> index da48d4079511..da83e231e93d 100644
> --- a/include/uapi/linux/input-event-codes.h
> +++ b/include/uapi/linux/input-event-codes.h
> @@ -789,7 +789,9 @@
> #define SW_LINEIN_INSERT 0x0d /* set = inserted */
> #define SW_MUTE_DEVICE 0x0e /* set = device disabled */
> #define SW_PEN_INSERTED 0x0f /* set = pen inserted */
> -#define SW_MAX 0x0f
> +#define SW_RATCHET 0x10 /* set = ratchet mode,
> + unset: free wheel */
> +#define SW_MAX 0x1f
> #define SW_CNT (SW_MAX+1)
>
> /*
> --
> 2.9.3
>
--
Dmitry
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Contributing to the docs
Hello everyone, I've found a typo in ioctl-numbers.txt and decided to snoop around, find some more slips and maybe send a bigger patch then. Which kernel tree should I use for patching the docs? If any other questions arise, what would be the best place to look for answers without troubling the community? Stan -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Contributing to the docs
On 04/15/17 12:14, Stan Drozd wrote: > Hello everyone, > I've found a typo in ioctl-numbers.txt and decided to snoop around, find some > more slips and maybe send a bigger patch then. Which kernel tree should I use > for patching the docs? If any other questions arise, what would be the best > place to look for answers without troubling the community? tree: >From the MAINTAINERS file, for DOCUMENTATION: git git://git.lwn.net/linux.git docs-next Other questions: a. source code b. man pages c. google search but asking on mailing lists is also OK. -- ~Randy -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH] docs: swat a bunch of trivial typos
This patch corrects a couple mistakes I've found when reading through Documentation/. This is my first submission and I hope to send more meaningful fixes in the future. Stan Signed-off-by: Stan Drozd --- Documentation/ioctl/ioctl-number.txt | 2 +- Documentation/memory-barriers.txt | 2 +- Documentation/static-keys.txt | 2 +- Documentation/vfio-mediated-device.txt | 6 +++--- Documentation/zorro.txt| 2 +- 5 files changed, 7 insertions(+), 7 deletions(-) diff --git a/Documentation/ioctl/ioctl-number.txt b/Documentation/ioctl/ioctl-number.txt index 08244bea5048..a77ead911956 100644 --- a/Documentation/ioctl/ioctl-number.txt +++ b/Documentation/ioctl/ioctl-number.txt @@ -212,7 +212,7 @@ Code Seq#(hex) Include File Comments 'c' 00-1F linux/chio.h conflict! 'c' 80-9F arch/s390/include/asm/chsc.h conflict! 'c' A0-AF arch/x86/include/asm/msr.h conflict! -'d' 00-FF linux/char/drm/drm/h conflict! +'d' 00-FF linux/char/drm/drm.h conflict! 'd' 02-40 pcmcia/ds.h conflict! 'd' F0-FF linux/digi1.h 'e' all linux/digi1.h conflict! diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt index d2b0a8d81258..d2bd7439a2e9 100644 --- a/Documentation/memory-barriers.txt +++ b/Documentation/memory-barriers.txt @@ -27,7 +27,7 @@ The purpose of this document is twofold: (2) to provide a guide as to how to use the barriers that are available. Note that an architecture can provide more than the minimum requirement -for any particular barrier, but if the architecure provides less than +for any particular barrier, but if the architecture provides less than that, that architecture is incorrect. Note also that it is possible that a barrier may be a no-op for an diff --git a/Documentation/static-keys.txt b/Documentation/static-keys.txt index 32a25fad0c1b..ef419fd0897f 100644 --- a/Documentation/static-keys.txt +++ b/Documentation/static-keys.txt @@ -118,7 +118,7 @@ Or: Keys defined via DEFINE_STATIC_KEY_TRUE(), or DEFINE_STATIC_KEY_FALSE, may be used in either static_branch_likely() or static_branch_unlikely() -statemnts. +statements. Branch(es) can be set true via: diff --git a/Documentation/vfio-mediated-device.txt b/Documentation/vfio-mediated-device.txt index 6f994abd93d0..e5e57b40f8af 100644 --- a/Documentation/vfio-mediated-device.txt +++ b/Documentation/vfio-mediated-device.txt @@ -217,9 +217,9 @@ Directories and files under the sysfs for Each Physical Device * [] - The [] name is created by adding the the device driver string as a - prefix to the string provided by the vendor driver. This format of this name - is as follows: + The [] name is created by adding the device driver string as a prefix + to the string provided by the vendor driver. This format of this name is as + follows: sprintf(buf, "%s-%s", dev_driver_string(parent->dev), group->name); diff --git a/Documentation/zorro.txt b/Documentation/zorro.txt index 90a64d52bea2..d530971beb00 100644 --- a/Documentation/zorro.txt +++ b/Documentation/zorro.txt @@ -11,7 +11,7 @@ Last revised: September 5, 2003 The Zorro bus is the bus used in the Amiga family of computers. Thanks to AutoConfig(tm), it's 100% Plug-and-Play. -There are two types of Zorro busses, Zorro II and Zorro III: +There are two types of Zorro buses, Zorro II and Zorro III: - The Zorro II address space is 24-bit and lies within the first 16 MB of the Amiga's address map. -- 2.12.2 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v4 3/5] input: add a EV_SW event for ratchet switch
Em Sat, 15 Apr 2017 11:04:36 -0700
Dmitry Torokhov escreveu:
> Hi Mauro,
>
> On Tue, Apr 11, 2017 at 10:29:40AM -0300, Mauro Carvalho Chehab wrote:
> > Some mice have a switch on their wheel, allowing to switch
> > between ratchet and free wheel mode. Add support for it.
> >
> > Signed-off-by: Mauro Carvalho Chehab
> > ---
> > Documentation/input/event-codes.txt| 12
> > include/linux/mod_devicetable.h| 2 +-
> > include/uapi/linux/input-event-codes.h | 4 +++-
> > 3 files changed, 16 insertions(+), 2 deletions(-)
> >
> > diff --git a/Documentation/input/event-codes.txt
> > b/Documentation/input/event-codes.txt
> > index 50352ab5f6d4..5dbd45db9bf6 100644
> > --- a/Documentation/input/event-codes.txt
> > +++ b/Documentation/input/event-codes.txt
> > @@ -206,6 +206,18 @@ Upon resume, if the switch state is the same as before
> > suspend, then the input
> > subsystem will filter out the duplicate switch state reports. The driver
> > does
> > not need to keep the state of the switch at any time.
> >
> > +A few EV_SW codes have special meanings:
> > +
> > +* SW_RATCHET:
> > +
> > + - Some mice have a special switch for their wheel that allows to change
> > +between free wheel mode and ratchet mode. When the switch is ratchet
> > +mode (ON state), the wheel will offer some resistance for movements. It
> > +may also provide a tactile feedback when scrolled.
> > +
> > +Note that some mice have a ratchet switch that does not generate a
> > +software event.
>
> So it is still not clear to me why we need the 2 discrete events. Either
> we key off the behavior off the new REL event, or from switch, but not
> both.
The two events are independent. Clicking at the Wheel button just
sets it to free wheel or back to ratchet mode. It doesn't switch
the resolution.
The high resolution events are sent only when userspace sets
the mouse to high resolution mode.
I wrote patch series for Solaar with allows switching between
low resolution and high resolution modes and controls if the
wheel movement is normal or inverted:
https://github.com/pwr/Solaar/pull/351
It uses the hidraw interface to switch between the two modes.
> Also, it is unclear to me if allocating a new event for "hires" wheel is
> optimal. This still does not solve the question about resolution (how
> high is "hires" and what to do if Logitech will come out with
> ultra-high-resolution wheel next year, or if we need to express
> resolution for other relative events).
How "high" is the resolution can be queried on those devices.
Not sure how to report it to userspace, though. Ok, one application
could query it via hidraw interface (my Solaar patches do that
when solaar is called with the "show" parameter).
Perhaps an ioctl? Or do you have a better idea?
>
> Thanks.
>
> > +
> > EV_MSC:
> > --
> > EV_MSC events are used for input and output events that do not fall under
> > other
> > diff --git a/include/linux/mod_devicetable.h
> > b/include/linux/mod_devicetable.h
> > index a3e8c572a046..79dd7dbf5442 100644
> > --- a/include/linux/mod_devicetable.h
> > +++ b/include/linux/mod_devicetable.h
> > @@ -292,7 +292,7 @@ struct pcmcia_device_id {
> > #define INPUT_DEVICE_ID_LED_MAX0x0f
> > #define INPUT_DEVICE_ID_SND_MAX0x07
> > #define INPUT_DEVICE_ID_FF_MAX 0x7f
> > -#define INPUT_DEVICE_ID_SW_MAX 0x0f
> > +#define INPUT_DEVICE_ID_SW_MAX 0x1f
> >
> > #define INPUT_DEVICE_ID_MATCH_BUS 1
> > #define INPUT_DEVICE_ID_MATCH_VENDOR 2
> > diff --git a/include/uapi/linux/input-event-codes.h
> > b/include/uapi/linux/input-event-codes.h
> > index da48d4079511..da83e231e93d 100644
> > --- a/include/uapi/linux/input-event-codes.h
> > +++ b/include/uapi/linux/input-event-codes.h
> > @@ -789,7 +789,9 @@
> > #define SW_LINEIN_INSERT 0x0d /* set = inserted */
> > #define SW_MUTE_DEVICE 0x0e /* set = device disabled */
> > #define SW_PEN_INSERTED0x0f /* set = pen inserted */
> > -#define SW_MAX 0x0f
> > +#define SW_RATCHET 0x10 /* set = ratchet mode,
> > +unset: free wheel */
> > +#define SW_MAX 0x1f
> > #define SW_CNT (SW_MAX+1)
> >
> > /*
> > --
> > 2.9.3
> >
>
Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH 8/8] Input: docs - freshen up introduction
Stop saying that API is experimental and that only USB is supported, acknowledge that evdev is the preferred interface, and remove paragraph encouraging people sending snail mail to Vojtech :) along with his email. Signed-off-by: Dmitry Torokhov --- Documentation/input/event-codes.rst | 2 + Documentation/input/input.rst | 253 +--- Documentation/input/joydev/joystick-api.rst | 2 + Documentation/input/joydev/joystick.rst | 2 + 4 files changed, 127 insertions(+), 132 deletions(-) diff --git a/Documentation/input/event-codes.rst b/Documentation/input/event-codes.rst index 92db50954169..00b88f113bda 100644 --- a/Documentation/input/event-codes.rst +++ b/Documentation/input/event-codes.rst @@ -1,3 +1,5 @@ +.. _input-event-codes: + = Input event codes = diff --git a/Documentation/input/input.rst b/Documentation/input/input.rst index ac7669ad3e76..3b3a22975106 100644 --- a/Documentation/input/input.rst +++ b/Documentation/input/input.rst @@ -1,25 +1,20 @@ .. include:: -=== -Linux Input drivers -=== + +Introduction + :Copyright: |copy| 1999-2001 Vojtech Pavlik - Sponsored by SuSE -Should you need to contact me, the author, you can do so either by e-mail -- mail your message to , or by paper mail: Vojtech Pavlik, -Simunkova 1594, Prague 8, 182 00 Czech Republic - -Introduction +Architecture -This is a collection of drivers that is designed to support all input -devices under Linux. While it is currently used only on for USB input -devices, future use (say 2.5/2.6) is expected to expand to replace -most of the existing input system, which is why it lives in -drivers/input/ instead of drivers/usb/. +Input subsystem 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. -The centre of the input drivers is the input module, which must be +The core of the input subsystem is the input module, which must be loaded before any other of the input modules - it serves as a way of communication between two groups of modules: @@ -32,9 +27,9 @@ events (keystrokes, mouse movements) to the input module. Event handlers -- -These modules get events from input and pass them where needed via -various interfaces - keystrokes to the kernel, mouse movements via a -simulated PS/2 interface to GPM and X and so on. +These modules get events from input core and pass them where needed +via various interfaces - keystrokes to the kernel, mouse movements via +a simulated PS/2 interface to GPM and X, and so on. Simple Usage @@ -45,19 +40,18 @@ kernel):: input mousedev - keybdev usbcore uhci_hcd or ohci_hcd or ehci_hcd usbhid + hid_generic After this, the USB keyboard will work straight away, and the USB mouse will be available as a character device on major 13, minor 63:: crw-r--r-- 1 root root 13, 63 Mar 28 22:45 mice -This device has to be created. - -The commands to create it by hand are:: +This device usually created automatically by the system. The commands +to create it by hand are:: cd /dev mkdir input @@ -81,100 +75,50 @@ When you do all of the above, you can use your USB mouse and keyboard. Detailed Description -Device drivers +Event handlers -- -Device drivers are the modules that generate events. The events are -however not useful without being handled, so you also will need to use some -of the modules from section 3.2. - -usbhid -~~ - -usbhid is the largest and most complex driver of the whole suite. It -handles all HID devices, and because there is a very 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 -keyboards, trackballs and digitizers. - -However, USB uses HID also for monitor controls, speaker controls, UPSs, -LCDs and many other purposes. - -The monitor and speaker controls should be easy to add to the hid/input -interface, but for the UPSs and LCDs it doesn't make much sense. For this, -the hiddev interface was designed. See Documentation/hid/hiddev.txt -for more information about it. - -The usage of the usbhid module is very simple, it takes no parameters, -detects everything automatically and when a HID device is inserted, it -detects it appropriately. - -However, because the devices vary wildly, you might happen to have a -device that doesn't work well. In that case #define DEBUG at the beginning -of hid-core.c and send me the syslog traces. +Event handlers distribute the events from the devices to userspace and +in-kernel consumers, as needed. -usbmouse - - -For embedded systems, for mice with b
[PATCH 5/8] Input: docs - update joystick documentation a bit
Consolidate use instructions and userspace API notes into the same chapter;
remove completely obsolete references, move into a separate subdirectory.
Signed-off-by: Dmitry Torokhov
---
Documentation/input/index.rst | 6 +-
Documentation/input/joydev/index.rst | 18 +
Documentation/input/{ => joydev}/joystick-api.rst | 30 ++--
Documentation/input/{ => joydev}/joystick.rst | 88 ++-
Documentation/input/joystick-parport.rst | 12 ++--
5 files changed, 71 insertions(+), 83 deletions(-)
create mode 100644 Documentation/input/joydev/index.rst
rename Documentation/input/{ => joydev}/joystick-api.rst (89%)
rename Documentation/input/{ => joydev}/joystick.rst (86%)
diff --git a/Documentation/input/index.rst b/Documentation/input/index.rst
index 5887c79173b8..b25a67198a65 100644
--- a/Documentation/input/index.rst
+++ b/Documentation/input/index.rst
@@ -2,8 +2,7 @@
The Linux Input Documentation
=
-Core API
-
+Contents:
.. toctree::
:maxdepth: 2
@@ -12,8 +11,7 @@ Core API
input
input-programming
event-codes
- joystick
- joystick-api
+ joydev/index
multi-touch-protocol
gamepad
gameport-programming
diff --git a/Documentation/input/joydev/index.rst
b/Documentation/input/joydev/index.rst
new file mode 100644
index ..8d9666c7561c
--- /dev/null
+++ b/Documentation/input/joydev/index.rst
@@ -0,0 +1,18 @@
+.. include::
+
+==
+Linux Joystick support
+==
+
+:Copyright: |copy| 1996-2000 Vojtech Pavlik - Sponsored by
SuSE
+
+.. class:: toc-title
+
+ Table of Contents
+
+.. toctree::
+ :maxdepth: 3
+ :numbered:
+
+ joystick
+ joystick-api
diff --git a/Documentation/input/joystick-api.rst
b/Documentation/input/joydev/joystick-api.rst
similarity index 89%
rename from Documentation/input/joystick-api.rst
rename to Documentation/input/joydev/joystick-api.rst
index 9b9d26833086..42edcfc6e8af 100644
--- a/Documentation/input/joystick-api.rst
+++ b/Documentation/input/joydev/joystick-api.rst
@@ -1,16 +1,36 @@
-==
-Joystick API Documentation
-==
+=
+Programming Interface
+=
:Author: Ragnar Hojland Espinosa - 7 Aug 1998
+Introduction
+
+
+.. important::
+ This document describes legacy ``js`` interface. Newer clients are
+ encouraged to switch to the generic event (``evdev``) interface.
+
+The 1.0 driver uses a new, event based approach to the joystick driver.
+Instead of the user program polling for the joystick values, the joystick
+driver now reports only any changes of its state. See joystick-api.txt,
+joystick.h and jstest.c included in the joystick package for more
+information. The joystick device can be used in either blocking or
+nonblocking mode, and supports select() calls.
+
+For backward compatibility the old (v0.x) interface is still included.
+Any call to the joystick driver using the old interface will return values
+that are compatible to the old interface. This interface is still limited
+to 2 axes, and applications using it usually decode only 2 buttons, although
+the driver provides up to 32.
+
Initialization
==
Open the joystick device following the usual semantics (that is, with open).
Since the driver now reports events instead of polling for changes,
immediately after the open it will issue a series of synthetic events
-(JS_EVENT_INIT) that you can read to check the initial state of the
+(JS_EVENT_INIT) that you can read to obtain the initial state of the
joystick.
By default, the device is opened in blocking mode::
@@ -182,7 +202,7 @@ the actual state of the joystick.
.. note::
- As for version 1.2.8, the queue is circular and able to hold 64
+ As of version 1.2.8, the queue is circular and able to hold 64
events. You can increment this size bumping up JS_BUFF_SIZE in
joystick.h and recompiling the driver.
diff --git a/Documentation/input/joystick.rst
b/Documentation/input/joydev/joystick.rst
similarity index 86%
rename from Documentation/input/joystick.rst
rename to Documentation/input/joydev/joystick.rst
index c9c175ffc2ff..b90705eb69b1 100644
--- a/Documentation/input/joystick.rst
+++ b/Documentation/input/joydev/joystick.rst
@@ -1,56 +1,17 @@
.. include::
-
-Linux Joystick driver v2.0.0
-
-
-:Copyright: |copy| 1996-2000 Vojtech Pavlik - Sponsored by
SuSE
-
-
-Disclaimer
-==
-
-This program is free software; you can redistribute it and/or modify it
-under the terms of the GNU General Public License as published by the Free
-Software Foundation; either version 2 of the License, or (at your option)
-any later version.
-
-This program is distributed in the hope that it will be useful, but
-WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILI
[PATCH 7/8] Input: docs - split input docs into kernel- and user-facing
Split input documentation into several groups: kernel- and user-facing, and
notes about individual device drivers. Move device drivers docs into a
separate subdirectory.
Signed-off-by: Dmitry Torokhov
---
Documentation/input/{ => devices}/alps.rst | 2 +-
Documentation/input/{ => devices}/amijoy.rst | 0
Documentation/input/{ => devices}/appletouch.rst | 0
Documentation/input/{ => devices}/atarikbd.rst | 0
Documentation/input/{ => devices}/bcm5974.rst | 0
Documentation/input/{ => devices}/cma3000_d0x.rst | 4 +-
Documentation/input/{ => devices}/cs461x.rst | 8 +---
Documentation/input/{ => devices}/edt-ft5x06.rst | 0
Documentation/input/{ => devices}/elantech.rst | 0
Documentation/input/{ => devices}/gpio-tilt.rst| 8 ++--
.../input/{ => devices}/iforce-protocol.rst| 0
Documentation/input/devices/index.rst | 19 +
.../input/{ => devices}/joystick-parport.rst | 2 +-
Documentation/input/{ => devices}/ntrig.rst| 0
.../input/{ => devices}/rotary-encoder.rst | 0
Documentation/input/{ => devices}/sentelic.rst | 10 ++---
Documentation/input/{ => devices}/walkera0701.rst | 0
Documentation/input/{ => devices}/xpad.rst | 22 +-
Documentation/input/{ => devices}/yealink.rst | 47 --
Documentation/input/gamepad.rst| 10 ++---
Documentation/input/index.rst | 39 ++
Documentation/input/input-programming.rst | 5 +--
Documentation/input/input_kapi.rst | 17
Documentation/input/input_uapi.rst | 21 ++
24 files changed, 107 insertions(+), 107 deletions(-)
rename Documentation/input/{ => devices}/alps.rst (99%)
rename Documentation/input/{ => devices}/amijoy.rst (100%)
rename Documentation/input/{ => devices}/appletouch.rst (100%)
rename Documentation/input/{ => devices}/atarikbd.rst (100%)
rename Documentation/input/{ => devices}/bcm5974.rst (100%)
rename Documentation/input/{ => devices}/cma3000_d0x.rst (97%)
rename Documentation/input/{ => devices}/cs461x.rst (88%)
rename Documentation/input/{ => devices}/edt-ft5x06.rst (100%)
rename Documentation/input/{ => devices}/elantech.rst (100%)
rename Documentation/input/{ => devices}/gpio-tilt.rst (98%)
rename Documentation/input/{ => devices}/iforce-protocol.rst (100%)
create mode 100644 Documentation/input/devices/index.rst
rename Documentation/input/{ => devices}/joystick-parport.rst (99%)
rename Documentation/input/{ => devices}/ntrig.rst (100%)
rename Documentation/input/{ => devices}/rotary-encoder.rst (100%)
rename Documentation/input/{ => devices}/sentelic.rst (99%)
rename Documentation/input/{ => devices}/walkera0701.rst (100%)
rename Documentation/input/{ => devices}/xpad.rst (95%)
rename Documentation/input/{ => devices}/yealink.rst (94%)
create mode 100644 Documentation/input/input_kapi.rst
create mode 100644 Documentation/input/input_uapi.rst
diff --git a/Documentation/input/alps.rst b/Documentation/input/devices/alps.rst
similarity index 99%
rename from Documentation/input/alps.rst
rename to Documentation/input/devices/alps.rst
index 76a71a146e50..6779148e428c 100644
--- a/Documentation/input/alps.rst
+++ b/Documentation/input/devices/alps.rst
@@ -5,7 +5,7 @@ ALPS Touchpad Protocol
Introduction
Currently the ALPS touchpad driver supports seven protocol versions in use by
-ALPS touchpads, called versions 1, 2, 3, 4, 5, 6 and 7.
+ALPS touchpads, called versions 1, 2, 3, 4, 5, 6, 7 and 8.
Since roughly mid-2010 several new ALPS touchpads have been released and
integrated into a variety of laptops and netbooks. These new touchpads
diff --git a/Documentation/input/amijoy.rst
b/Documentation/input/devices/amijoy.rst
similarity index 100%
rename from Documentation/input/amijoy.rst
rename to Documentation/input/devices/amijoy.rst
diff --git a/Documentation/input/appletouch.rst
b/Documentation/input/devices/appletouch.rst
similarity index 100%
rename from Documentation/input/appletouch.rst
rename to Documentation/input/devices/appletouch.rst
diff --git a/Documentation/input/atarikbd.rst
b/Documentation/input/devices/atarikbd.rst
similarity index 100%
rename from Documentation/input/atarikbd.rst
rename to Documentation/input/devices/atarikbd.rst
diff --git a/Documentation/input/bcm5974.rst
b/Documentation/input/devices/bcm5974.rst
similarity index 100%
rename from Documentation/input/bcm5974.rst
rename to Documentation/input/devices/bcm5974.rst
diff --git a/Documentation/input/cma3000_d0x.rst
b/Documentation/input/devices/cma3000_d0x.rst
similarity index 97%
rename from Documentation/input/cma3000_d0x.rst
rename to Documentation/input/devices/cma3000_d0x.rst
index 6f40c17c1aca..8bc8e61487b0 100644
--- a/Documentation/input/cma3000_d0x.rst
+++ b/Documentation/input/devices/cma3000_d0x.rst
@@ -1,5 +1,5 @@
-Kernel driver for CMA3000-D0x
-
[PATCH 4/8] Input: docs - remove disclaimer/GPL notice
This is just a part of kernel documentation, it does not require explicit license notice. Signed-off-by: Dmitry Torokhov --- Documentation/input/index.rst | 21 - 1 file changed, 21 deletions(-) diff --git a/Documentation/input/index.rst b/Documentation/input/index.rst index 32c0515fd24b..5887c79173b8 100644 --- a/Documentation/input/index.rst +++ b/Documentation/input/index.rst @@ -2,27 +2,6 @@ The Linux Input Documentation = -Disclaimer -== - -This program is free software; you can redistribute it and/or modify it -under the terms of the GNU General Public License as published by the Free -Software Foundation; either version 2 of the License, or (at your option) -any later version. - -This program is distributed in the hope that it will be useful, but -WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY -or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for -more details. - -You should have received a copy of the GNU General Public License along -with this program; if not, write to the Free Software Foundation, Inc., 59 -Temple Place, Suite 330, Boston, MA 02111-1307 USA - -For your convenience, the GNU General Public License version 2 is included -in the package: See the file COPYING. - - Core API -- 2.12.2.762.g0e3151a226-goog -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH 6/8] Input: docs - note that MT-A protocol is obsolete
Everyone should be using multitouch protocol B (slotted) now. Signed-off-by: Dmitry Torokhov --- Documentation/input/multi-touch-protocol.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Documentation/input/multi-touch-protocol.rst b/Documentation/input/multi-touch-protocol.rst index 81775d7c1997..8035868c56bc 100644 --- a/Documentation/input/multi-touch-protocol.rst +++ b/Documentation/input/multi-touch-protocol.rst @@ -22,6 +22,9 @@ describes how to send the raw data for all contacts to the receiver. For devices capable of tracking identifiable contacts (type B), the protocol describes how to send updates for individual contacts via event slots. +.. note:: + MT potocol type A is obsolete, all kernel drivers have been + converted to use type B. Protocol Usage -- @@ -400,9 +403,6 @@ in a finger packet must not be recognized as single-touch events. For type A devices, all finger data bypasses input filtering, since subsequent events of the same type refer to different fingers. -For example usage of the type A protocol, see the bcm5974 driver. For -example usage of the type B protocol, see the hid-egalax driver. - .. [#f1] Also, the difference (TOOL_X - POSITION_X) can be used to model tilt. .. [#f2] The list can of course be extended. .. [#f3] The mtdev project: http://bitmath.org/code/mtdev/. -- 2.12.2.762.g0e3151a226-goog -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH 1/8] Input: move documentation for Amiga CD32
Move the documentation for Amiga CD32 together with other parallel port joysticks. Signed-off-by: Dmitry Torokhov --- Documentation/input/cd32.rst | 24 - Documentation/input/index.rst| 1 - Documentation/input/joystick-parport.rst | 37 3 files changed, 37 insertions(+), 25 deletions(-) delete mode 100644 Documentation/input/cd32.rst diff --git a/Documentation/input/cd32.rst b/Documentation/input/cd32.rst deleted file mode 100644 index 935028b957d9.. --- a/Documentation/input/cd32.rst +++ /dev/null @@ -1,24 +0,0 @@ -== -Amiga CD32 -== - -I have written a small patch that let's me use my Amiga CD32 -joypad connected to the parallel port. Thought I'd share it with you so -you can add it to the list of supported joysticks (hopefully someone will -find it useful). - -It needs the following wiring: - -==== -CD32 pad Parallel port -==== -1 (Up) 2 (D0) -2 (Down)3 (D1) -3 (Left)4 (D2) -4 (Right) 5 (D3) -5 (Fire3) 14 (AUTOFD) -6 (Fire1) 17 (SELIN) -7 (+5V) 1 (STROBE) -8 (Gnd)18 (Gnd) -9 (Fire2) 7 (D5) -==== diff --git a/Documentation/input/index.rst b/Documentation/input/index.rst index 153f0d476c3e..32c0515fd24b 100644 --- a/Documentation/input/index.rst +++ b/Documentation/input/index.rst @@ -54,7 +54,6 @@ Input drivers appletouch atarikbd bcm5974 - cd32 cma3000_d0x cs461x edt-ft5x06 diff --git a/Documentation/input/joystick-parport.rst b/Documentation/input/joystick-parport.rst index 0aa0fb17bf48..fa8cab584793 100644 --- a/Documentation/input/joystick-parport.rst +++ b/Documentation/input/joystick-parport.rst @@ -443,6 +443,43 @@ parallel port:: The other pins (Up, Down, Right, Left, Power, Ground) are the same as for Multi joysticks using db9.c +Amiga CD32 +-- + +Amiga CD32 joypad uses the following pinout:: + ++---> Button 3 +| +-> Right +| | +---> Left +| | | +-> Down +| | | | +---> Up +| | | | | + _ +5 \ o o o o o / 1 + \ o o o o / + 9 `~~~' 6 +| | | | +| | | +> Button 1 +| | +--> Power +| +> Ground ++--> Button 2 + +It can be connected to the parallel port and driven by db9.c driver. It needs the following wiring: + + = + CD32 padParallel port + = + 1 (Up) 2 (D0) + 2 (Down) 3 (D1) + 3 (Left) 4 (D2) + 4 (Right)5 (D3) + 5 (Button 3)14 (AUTOFD) + 6 (Button 1)17 (SELIN) + 7 (+5V) 1 (STROBE) + 8 (Gnd) 18 (Gnd) + 9 (Button 2) 7 (D5) + = + The drivers === -- 2.12.2.762.g0e3151a226-goog -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH 3/8] Input: fix "Game console" heading level in joystick documentation
The heading level should be the same as for other devices. Signed-off-by: Dmitry Torokhov --- Documentation/input/joystick.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/input/joystick.rst b/Documentation/input/joystick.rst index 202f5a090675..c9c175ffc2ff 100644 --- a/Documentation/input/joystick.rst +++ b/Documentation/input/joystick.rst @@ -465,7 +465,7 @@ No more joystick types are supported now, but that should change in the future if I get an Amiga in the reach of my fingers. Game console and 8-bit pads and joysticks -~ +- See :ref:`joystick-parport` for more info. -- 2.12.2.762.g0e3151a226-goog -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH 2/8] Input: rotary-encoder - remove references to platform data from docs
The driver has been converted to use generic device properties, so
stop referring to platform data.
Signed-off-by: Dmitry Torokhov
---
Documentation/input/rotary-encoder.rst | 85 ++
1 file changed, 44 insertions(+), 41 deletions(-)
diff --git a/Documentation/input/rotary-encoder.rst
b/Documentation/input/rotary-encoder.rst
index 4695bea67f9b..b07b20a295ac 100644
--- a/Documentation/input/rotary-encoder.rst
+++ b/Documentation/input/rotary-encoder.rst
@@ -81,48 +81,51 @@ Board integration
To use this driver in your system, register a platform_device with the
name 'rotary-encoder' and associate the IRQs and some specific platform
-data with it.
+data with it. Because the driver uses generic device properties, this can
+be done either via device tree, ACPI, or using static board files, like in
+example below:
-struct rotary_encoder_platform_data is declared in
-include/linux/rotary-encoder.h and needs to be filled with the number of
-steps the encoder has and can carry information about externally inverted
-signals (because of an inverting buffer or other reasons). The encoder
-can be set up to deliver input information as either an absolute or relative
-axes. For relative axes the input event returns +/-1 for each step. For
-absolute axes the position of the encoder can either roll over between zero
-and the number of steps or will clamp at the maximum and zero depending on
-the configuration.
+::
-Because GPIO to IRQ mapping is platform specific, this information must
-be given in separately to the driver. See the example below.
+ /* board support file example */
-::
+ #include
+ #include
+ #include
+
+ #define GPIO_ROTARY_A 1
+ #define GPIO_ROTARY_B 2
+
+ static struct gpiod_lookup_table rotary_encoder_gpios = {
+ .dev_id = "rotary-encoder.0",
+ .table = {
+ GPIO_LOOKUP_IDX("gpio-0",
+ GPIO_ROTARY_A, NULL, 0,
GPIO_ACTIVE_LOW),
+ GPIO_LOOKUP_IDX("gpio-0",
+ GPIO_ROTARY_B, NULL, 1,
GPIO_ACTIVE_HIGH),
+ { },
+ },
+ };
+
+ static const struct property_entry rotary_encoder_properties[]
__initconst = {
+ PROPERTY_ENTRY_INTEGER("rotary-encoder,steps-per-period", u32,
24),
+ PROPERTY_ENTRY_INTEGER("linux,axis", u32,
ABS_X),
+ PROPERTY_ENTRY_INTEGER("rotary-encoder,relative_axis",u32,
0),
+ { },
+ };
+
+ static struct platform_device rotary_encoder_device = {
+ .name = "rotary-encoder",
+ .id = 0,
+ };
+
+ ...
+
+ gpiod_add_lookup_table(&rotary_encoder_gpios);
+ device_add_properties(&rotary_encoder_device,
rotary_encoder_properties);
+ platform_device_register(&rotary_encoder_device);
+
+ ...
-/* board support file example */
-
-#include
-#include
-
-#define GPIO_ROTARY_A 1
-#define GPIO_ROTARY_B 2
-
-static struct rotary_encoder_platform_data my_rotary_encoder_info = {
- .steps = 24,
- .axis = ABS_X,
- .relative_axis = false,
- .rollover = false,
- .gpio_a = GPIO_ROTARY_A,
- .gpio_b = GPIO_ROTARY_B,
- .inverted_a = 0,
- .inverted_b = 0,
- .half_period= false,
- .wakeup_source = false,
-};
-
-static struct platform_device rotary_encoder_device = {
- .name = "rotary-encoder",
- .id = 0,
- .dev= {
- .platform_data = &my_rotary_encoder_info,
- }
-};
+Please consult device tree binding documentation to see all properties
+supported by the driver.
--
2.12.2.762.g0e3151a226-goog
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
