From 21228a1868692c34ade648dbb0bc3db0069ab551 Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Wed, 29 Oct 2014 11:15:17 -0700 Subject: CodingStyle: Add a chapter on conditional compilation Document several common practices and conventions regarding conditional compilation, most notably the preference for ifdefs in headers rather than .c files. Signed-off-by: Josh Triplett Acked-by: Geert Uytterhoeven Signed-off-by: Jonathan Corbet --- Documentation/CodingStyle | 43 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) (limited to 'Documentation') diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle index 3171822c22a5..9f28b140dc89 100644 --- a/Documentation/CodingStyle +++ b/Documentation/CodingStyle @@ -845,6 +845,49 @@ next instruction in the assembly output: : /* outputs */ : /* inputs */ : /* clobbers */); + Chapter 20: Conditional Compilation + +Wherever possible, don't use preprocessor conditionals (#if, #ifdef) in .c +files; doing so makes code harder to read and logic harder to follow. Instead, +use such conditionals in a header file defining functions for use in those .c +files, providing no-op stub versions in the #else case, and then call those +functions unconditionally from .c files. The compiler will avoid generating +any code for the stub calls, producing identical results, but the logic will +remain easy to follow. + +Prefer to compile out entire functions, rather than portions of functions or +portions of expressions. Rather than putting an ifdef in an expression, factor +out part or all of the expression into a separate helper function and apply the +conditional to that function. + +If you have a function or variable which may potentially go unused in a +particular configuration, and the compiler would warn about its definition +going unused, mark the definition as __maybe_unused rather than wrapping it in +a preprocessor conditional. (However, if a function or variable *always* goes +unused, delete it.) + +Within code, where possible, use the IS_ENABLED macro to convert a Kconfig +symbol into a C boolean expression, and use it in a normal C conditional: + + if (IS_ENABLED(CONFIG_SOMETHING)) { + ... + } + +The compiler will constant-fold the conditional away, and include or exclude +the block of code just as with an #ifdef, so this will not add any runtime +overhead. However, this approach still allows the C compiler to see the code +inside the block, and check it for correctness (syntax, types, symbol +references, etc). Thus, you still have to use an #ifdef if the code inside the +block references symbols that will not exist if the condition is not met. + +At the end of any non-trivial #if or #ifdef block (more than a few lines), +place a comment after the #endif on the same line, noting the conditional +expression used. For instance: + +#ifdef CONFIG_SOMETHING +... +#endif /* CONFIG_SOMETHING */ + Appendix I: References -- cgit v1.2.3-59-g8ed1b From 70c036347fe6675dcd87fd9c2f3159f90233a0ed Mon Sep 17 00:00:00 2001 From: Masanari Iida Date: Wed, 22 Oct 2014 08:36:07 +0900 Subject: Documentation: Fix a typo in mailbox.txt This patch fix a typo in Documentation/mailbox.txt "bool async" is defined in struct demo_client. Signed-off-by: Masanari Iida Signed-off-by: Jonathan Corbet --- Documentation/mailbox.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/mailbox.txt b/Documentation/mailbox.txt index 60f43ff629aa..1092ad9578da 100644 --- a/Documentation/mailbox.txt +++ b/Documentation/mailbox.txt @@ -53,7 +53,7 @@ static void message_from_remote(struct mbox_client *cl, void *mssg) { struct demo_client *dc = container_of(mbox_client, struct demo_client, cl); - if (dc->aysnc) { + if (dc->async) { if (is_an_ack(mssg)) { /* An ACK to our last sample sent */ return; /* Or do something else here */ -- cgit v1.2.3-59-g8ed1b From 747029a566e5d637ef4972afd2cb7202f7b7ca7c Mon Sep 17 00:00:00 2001 From: Fabian Frederick Date: Thu, 6 Nov 2014 19:46:50 +0100 Subject: ipv4: add kernel parameter tcpmhash_entries This patch also adds a reference to ip-sysctl.txt where TCP metrics setup is described Signed-off-by: Fabian Frederick Signed-off-by: Jonathan Corbet --- Documentation/kernel-parameters.txt | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'Documentation') diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt index 4c81a860cc2b..e8066db54d3d 100644 --- a/Documentation/kernel-parameters.txt +++ b/Documentation/kernel-parameters.txt @@ -3412,6 +3412,13 @@ bytes respectively. Such letter suffixes can also be entirely omitted. neutralize any effect of /proc/sys/kernel/sysrq. Useful for debugging. + tcpmhash_entries= [KNL,NET] + Set the number of tcp_metrics_hash slots. + Default value is 8192 or 16384 depending on total + ram pages. This is used to specify the TCP metrics + cache size. See Documentation/networking/ip-sysctl.txt + "tcp_no_metrics_save" section for more details. + tdfx= [HW,DRM] test_suspend= [SUSPEND][,N] -- cgit v1.2.3-59-g8ed1b From c0d7305cb3e5e77dba822706e21898314e893fb7 Mon Sep 17 00:00:00 2001 From: Masanari Iida Date: Fri, 7 Nov 2014 00:31:15 +0900 Subject: Documentation: vm: Add 1GB large page support information This patch adds 1GB large page support information in Documentation/vm/hugetlbpage.txt Reference: https://lkml.org/lkml/2014/10/31/366 Signed-off-by: Masanari Iida Reviewed-by: Luiz Capitulino Signed-off-by: Jonathan Corbet --- Documentation/vm/hugetlbpage.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/vm/hugetlbpage.txt b/Documentation/vm/hugetlbpage.txt index b64e0af9cc56..f2d3a100fe38 100644 --- a/Documentation/vm/hugetlbpage.txt +++ b/Documentation/vm/hugetlbpage.txt @@ -1,8 +1,8 @@ The intent of this file is to give a brief summary of hugetlbpage support in the Linux kernel. This support is built on top of multiple page size support -that is provided by most modern architectures. For example, i386 -architecture supports 4K and 4M (2M in PAE mode) page sizes, ia64 +that is provided by most modern architectures. For example, x86 CPUs normally +support 4K and 2M (1G if architecturally supported) page sizes, ia64 architecture supports multiple page sizes 4K, 8K, 64K, 256K, 1M, 4M, 16M, 256M and ppc64 supports 4K and 16M. A TLB is a cache of virtual-to-physical translations. Typically this is a very scarce resource on processor. -- cgit v1.2.3-59-g8ed1b From 1f999d14fc7f772fbdd19151ebe5ee081f53dd49 Mon Sep 17 00:00:00 2001 From: Masanari Iida Date: Sat, 8 Nov 2014 17:54:51 +0900 Subject: Documentation: power: Fix typo in Documentation/power This patch fix spelling typos found in Documentation/power. Signed-off-by: Masanari Iida Signed-off-by: Jonathan Corbet --- Documentation/power/runtime_pm.txt | 6 +++--- Documentation/power/suspend-and-interrupts.txt | 2 +- Documentation/power/userland-swsusp.txt | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) (limited to 'Documentation') diff --git a/Documentation/power/runtime_pm.txt b/Documentation/power/runtime_pm.txt index f32ce5419573..0e5ea26b255a 100644 --- a/Documentation/power/runtime_pm.txt +++ b/Documentation/power/runtime_pm.txt @@ -229,13 +229,13 @@ defined in include/linux/pm.h: - if set, the value of child_count is ignored (but still updated) unsigned int disable_depth; - - used for disabling the helper funcions (they work normally if this is + - used for disabling the helper functions (they work normally if this is equal to zero); the initial value of it is 1 (i.e. runtime PM is initially disabled for all devices) int runtime_error; - if set, there was a fatal error (one of the callbacks returned error code - as described in Section 2), so the helper funtions will not work until + as described in Section 2), so the helper functions will not work until this flag is cleared; this is the error code returned by the failing callback @@ -524,7 +524,7 @@ pm_runtime_put_sync_autosuspend() 5. Runtime PM Initialization, Device Probing and Removal Initially, the runtime PM is disabled for all devices, which means that the -majority of the runtime PM helper funtions described in Section 4 will return +majority of the runtime PM helper functions described in Section 4 will return -EAGAIN until pm_runtime_enable() is called for the device. In addition to that, the initial runtime PM status of all devices is diff --git a/Documentation/power/suspend-and-interrupts.txt b/Documentation/power/suspend-and-interrupts.txt index 69663640dea5..2f9c5a5fcb25 100644 --- a/Documentation/power/suspend-and-interrupts.txt +++ b/Documentation/power/suspend-and-interrupts.txt @@ -77,7 +77,7 @@ Calling enable_irq_wake() causes suspend_device_irqs() to treat the given IRQ in a special way. Namely, the IRQ remains enabled, by on the first interrupt it will be disabled, marked as pending and "suspended" so that it will be re-enabled by resume_device_irqs() during the subsequent system resume. Also -the PM core is notified about the event which casues the system suspend in +the PM core is notified about the event which causes the system suspend in progress to be aborted (that doesn't have to happen immediately, but at one of the points where the suspend thread looks for pending wakeup events). diff --git a/Documentation/power/userland-swsusp.txt b/Documentation/power/userland-swsusp.txt index 0e870825c1b9..bbfcd1bbedc5 100644 --- a/Documentation/power/userland-swsusp.txt +++ b/Documentation/power/userland-swsusp.txt @@ -99,7 +99,7 @@ SNAPSHOT_S2RAM - suspend to RAM; using this call causes the kernel to The device's read() operation can be used to transfer the snapshot image from the kernel. It has the following limitations: - you cannot read() more than one virtual memory page at a time -- read()s across page boundaries are impossible (ie. if ypu read() 1/2 of +- read()s across page boundaries are impossible (ie. if you read() 1/2 of a page in the previous call, you will only be able to read() _at_ _most_ 1/2 of the page in the next call) -- cgit v1.2.3-59-g8ed1b From 690b0543a813b0ecfc51b0374c0ce6c8275435f0 Mon Sep 17 00:00:00 2001 From: Maisa Roponen Date: Mon, 24 Nov 2014 09:54:17 +0200 Subject: Documentation: fix formatting to make 's' happy "That letter [the last s] is sad because all the others have those things [=] below them and it does not." This patch fixes the tragedy so all the letters can be happy again. Signed-off-by: Maisa Roponen [The author being 4 years old needed some assistance] Signed-off-by: Tero Roponen Signed-off-by: Jonathan Corbet --- Documentation/filesystems/proc.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/filesystems/proc.txt b/Documentation/filesystems/proc.txt index eb8a10e22f7c..aae9dd13c91f 100644 --- a/Documentation/filesystems/proc.txt +++ b/Documentation/filesystems/proc.txt @@ -1272,7 +1272,7 @@ softirq. 1.9 Ext4 file system parameters ------------------------------- +------------------------------- Information about mounted ext4 file systems can be found in /proc/fs/ext4. Each mounted filesystem will have a directory in -- cgit v1.2.3-59-g8ed1b From 3c415707b37f1e4483c418c77f57692b89bcfd5e Mon Sep 17 00:00:00 2001 From: Tim Bird Date: Wed, 19 Nov 2014 16:16:16 -0800 Subject: kselftest: Move the docs to the Documentation dir Also, adjust the formatting a bit, and expand the section about using TARGETS= on the make command line. Signed-off-by: Tim Bird Acked-by: Shuah Khan Signed-off-by: Jonathan Corbet --- Documentation/kselftest.txt | 69 ++++++++++++++++++++++++++++++++++++++ tools/testing/selftests/README.txt | 61 --------------------------------- 2 files changed, 69 insertions(+), 61 deletions(-) create mode 100644 Documentation/kselftest.txt delete mode 100644 tools/testing/selftests/README.txt (limited to 'Documentation') diff --git a/Documentation/kselftest.txt b/Documentation/kselftest.txt new file mode 100644 index 000000000000..a87d840bacfe --- /dev/null +++ b/Documentation/kselftest.txt @@ -0,0 +1,69 @@ +Linux Kernel Selftests + +The kernel contains a set of "self tests" under the tools/testing/selftests/ +directory. These are intended to be small unit tests to exercise individual +code paths in the kernel. + +On some systems, hot-plug tests could hang forever waiting for cpu and +memory to be ready to be offlined. A special hot-plug target is created +to run full range of hot-plug tests. In default mode, hot-plug tests run +in safe mode with a limited scope. In limited mode, cpu-hotplug test is +run on a single cpu as opposed to all hotplug capable cpus, and memory +hotplug test is run on 2% of hotplug capable memory instead of 10%. + +Running the selftests (hotplug tests are run in limited mode) +============================================================= + +To build the tests: + $ make -C tools/testing/selftests + + +To run the tests: + $ make -C tools/testing/selftests run_tests + +To build and run the tests with a single command, use: + $ make kselftest + +- note that some tests will require root privileges. + + +Running a subset of selftests +======================================== +You can use the "TARGETS" variable on the make command line to specify +single test to run, or a list of tests to run. + +To run only tests targeted for a single subsystem: + $ make -C tools/testing/selftests TARGETS=ptrace run_tests + +You can specify multiple tests to build and run: + $ make TARGETS="size timers" kselftest + +See the top-level tools/testing/selftests/Makefile for the list of all +possible targets. + + +Running the full range hotplug selftests +======================================== + +To build the hotplug tests: + $ make -C tools/testing/selftests hotplug + +To run the hotplug tests: + $ make -C tools/testing/selftests run_hotplug + +- note that some tests will require root privileges. + + +Contributing new tests +====================== + +In general, the rules for for selftests are + + * Do as much as you can if you're not root; + + * Don't take too long; + + * Don't break the build on any architecture, and + + * Don't cause the top-level "make run_tests" to fail if your feature is + unconfigured. diff --git a/tools/testing/selftests/README.txt b/tools/testing/selftests/README.txt deleted file mode 100644 index 2660d5ff9179..000000000000 --- a/tools/testing/selftests/README.txt +++ /dev/null @@ -1,61 +0,0 @@ -Linux Kernel Selftests - -The kernel contains a set of "self tests" under the tools/testing/selftests/ -directory. These are intended to be small unit tests to exercise individual -code paths in the kernel. - -On some systems, hot-plug tests could hang forever waiting for cpu and -memory to be ready to be offlined. A special hot-plug target is created -to run full range of hot-plug tests. In default mode, hot-plug tests run -in safe mode with a limited scope. In limited mode, cpu-hotplug test is -run on a single cpu as opposed to all hotplug capable cpus, and memory -hotplug test is run on 2% of hotplug capable memory instead of 10%. - -Running the selftests (hotplug tests are run in limited mode) -============================================================= - -To build the tests: - - $ make -C tools/testing/selftests - - -To run the tests: - - $ make -C tools/testing/selftests run_tests - -- note that some tests will require root privileges. - -To run only tests targeted for a single subsystem: (including -hotplug targets in limited mode) - - $ make -C tools/testing/selftests TARGETS=cpu-hotplug run_tests - -See the top-level tools/testing/selftests/Makefile for the list of all possible -targets. - -Running the full range hotplug selftests -======================================== - -To build the tests: - - $ make -C tools/testing/selftests hotplug - -To run the tests: - - $ make -C tools/testing/selftests run_hotplug - -- note that some tests will require root privileges. - -Contributing new tests -====================== - -In general, the rules for for selftests are - - * Do as much as you can if you're not root; - - * Don't take too long; - - * Don't break the build on any architecture, and - - * Don't cause the top-level "make run_tests" to fail if your feature is - unconfigured. -- cgit v1.2.3-59-g8ed1b From ea04036032edda6f771c1381d03832d2ed0f6c31 Mon Sep 17 00:00:00 2001 From: Dan Carpenter Date: Tue, 2 Dec 2014 11:59:50 +0300 Subject: CodingStyle: add some more error handling guidelines I added a paragraph on choosing label names, and updated the example code to use a better label name. I also cleaned up the example code to more modern style by moving the allocation out of the initializer and changing the NULL check. Perhaps the most common type of error handling bug in the kernel is "one err bugs". CodingStyle already says that we should "avoid nesting" by using error labels and one err style error handling tends to have multiple indent levels, so this was already bad style. But I've added a new paragraph explaining how to avoid one err bugs by using multiple error labels which is, hopefully, more clear. Signed-off-by: Dan Carpenter Acked-by: Julia Lawall [jc: added GFP_KERNEL to kmalloc() call] Signed-off-by: Jonathan Corbet --- Documentation/CodingStyle | 27 ++++++++++++++++++++++----- 1 file changed, 22 insertions(+), 5 deletions(-) (limited to 'Documentation') diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle index 9f28b140dc89..618a33c940df 100644 --- a/Documentation/CodingStyle +++ b/Documentation/CodingStyle @@ -392,7 +392,12 @@ The goto statement comes in handy when a function exits from multiple locations and some common work such as cleanup has to be done. If there is no cleanup needed then just return directly. -The rationale is: +Choose label names which say what the goto does or why the goto exists. An +example of a good name could be "out_buffer:" if the goto frees "buffer". Avoid +using GW-BASIC names like "err1:" and "err2:". Also don't name them after the +goto location like "err_kmalloc_failed:" + +The rationale for using gotos is: - unconditional statements are easier to understand and follow - nesting is reduced @@ -403,9 +408,10 @@ The rationale is: int fun(int a) { int result = 0; - char *buffer = kmalloc(SIZE); + char *buffer; - if (buffer == NULL) + buffer = kmalloc(SIZE, GFP_KERNEL); + if (!buffer) return -ENOMEM; if (condition1) { @@ -413,14 +419,25 @@ int fun(int a) ... } result = 1; - goto out; + goto out_buffer; } ... -out: +out_buffer: kfree(buffer); return result; } +A common type of bug to be aware of it "one err bugs" which look like this: + +err: + kfree(foo->bar); + kfree(foo); + return ret; + +The bug in this code is that on some exit paths "foo" is NULL. Normally the +fix for this is to split it up into two error labels "err_bar:" and "err_foo:". + + Chapter 8: Commenting Comments are good, but there is also a danger of over-commenting. NEVER -- cgit v1.2.3-59-g8ed1b From 04a3302b5ff4225ac59302c5995276cacdd6da4a Mon Sep 17 00:00:00 2001 From: Richard Leitner Date: Tue, 2 Dec 2014 17:44:36 +0100 Subject: Documentation/email-clients.txt: add info about Claws Mail Claws Mail GUI client works. The client is available at http://www.claws-mail.org Signed-off-by: Richard Leitner Signed-off-by: Jonathan Corbet --- Documentation/email-clients.txt | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'Documentation') diff --git a/Documentation/email-clients.txt b/Documentation/email-clients.txt index 9af538be3751..eede6088f978 100644 --- a/Documentation/email-clients.txt +++ b/Documentation/email-clients.txt @@ -76,6 +76,17 @@ When composing the message, the cursor should be placed where the patch should appear, and then pressing CTRL-R let you specify the patch file to insert into the message. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Claws Mail (GUI) + +Works. Some people use this successfully for patches. + +To insert a patch use Message->Insert File (CTRL+i) or an external editor. + +If the inserted patch has to be edited in the Claws composition window +"Auto wrapping" in Configuration->Preferences->Compose->Wrapping should be +disabled. + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Evolution (GUI) -- cgit v1.2.3-59-g8ed1b From 845502d26301f8c37e2a57ad867672f306e674fb Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Wed, 3 Dec 2014 20:53:44 +0900 Subject: cgroups: Documentation: fix wrong cgroupfs paths Few paths used as example to describe cgroupfs usage have been wrong from f6e07d38078e ("Documentation: update cgroupfs mount point") by mistake. This patch fix those trivial wrong paths. Signed-off-by: SeongJae Park Signed-off-by: Jonathan Corbet --- Documentation/cgroups/cgroups.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/cgroups/cgroups.txt b/Documentation/cgroups/cgroups.txt index 10c949b293e4..f935fac1e73b 100644 --- a/Documentation/cgroups/cgroups.txt +++ b/Documentation/cgroups/cgroups.txt @@ -312,10 +312,10 @@ the "cpuset" cgroup subsystem, the steps are something like: 2) mkdir /sys/fs/cgroup/cpuset 3) mount -t cgroup -ocpuset cpuset /sys/fs/cgroup/cpuset 4) Create the new cgroup by doing mkdir's and write's (or echo's) in - the /sys/fs/cgroup virtual file system. + the /sys/fs/cgroup/cpuset virtual file system. 5) Start a task that will be the "founding father" of the new job. 6) Attach that task to the new cgroup by writing its PID to the - /sys/fs/cgroup/cpuset/tasks file for that cgroup. + /sys/fs/cgroup/cpuset tasks file for that cgroup. 7) fork, exec or clone the job tasks from this founding father task. For example, the following sequence of commands will setup a cgroup -- cgit v1.2.3-59-g8ed1b From d47fb4ec7e101a63754939fa49d75fd7e81e94f8 Mon Sep 17 00:00:00 2001 From: Ashutosh Dixit Date: Thu, 4 Dec 2014 13:27:29 -0800 Subject: Documentation: Build mic/mpssd only for x86_64 mic/mpssd along with MIC drivers are currently only usable on x86_64. So build mic/mpssd only for x86_64 to avoid build breaks on big-endian systems. Reported-by: Daniel Borkmann Reported-by: Dan Streetman Suggested-by: Peter Foley Signed-off-by: Ashutosh Dixit Signed-off-by: Jonathan Corbet --- Documentation/mic/mpssd/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/mic/mpssd/Makefile b/Documentation/mic/mpssd/Makefile index 0f3156888048..f47fe6ba7300 100644 --- a/Documentation/mic/mpssd/Makefile +++ b/Documentation/mic/mpssd/Makefile @@ -1,5 +1,5 @@ # List of programs to build -hostprogs-y := mpssd +hostprogs-$(CONFIG_X86_64) := mpssd mpssd-objs := mpssd.o sysfs.o -- cgit v1.2.3-59-g8ed1b From 5469b196507a72cba35aad9db657562d809fd383 Mon Sep 17 00:00:00 2001 From: Daniel Dressler Date: Mon, 10 Nov 2014 16:18:18 +0900 Subject: Input: xpad - update docs to reflect current state The last time this documentation was accurate was just over 8 years ago. In this time we've added support for two new generations of Xbox console controllers and dozens of third-party controllers. This patch unifies terminology and makes it explicit which model of controller a sentence refers to. It also expands certain sections to address the latest versions of Xbox controllers. Thus this documentation should now be useful to end users and not contain out-right untruths. This is the patch's second revision. Prior versions of this patch altered the driver's TODO list. That change has been pulled out of this documentation update patch. Signed-off-by: Daniel Dressler Signed-off-by: Jonathan Corbet --- Documentation/input/xpad.txt | 123 +++++++++++++++++++++++++++++-------------- 1 file changed, 83 insertions(+), 40 deletions(-) (limited to 'Documentation') diff --git a/Documentation/input/xpad.txt b/Documentation/input/xpad.txt index 7cc9a436e6a1..d1b23f295db4 100644 --- a/Documentation/input/xpad.txt +++ b/Documentation/input/xpad.txt @@ -1,18 +1,22 @@ -xpad - Linux USB driver for X-Box gamepads +xpad - Linux USB driver for Xbox compatible controllers -This is the very first release of a driver for X-Box gamepads. -Basically, this was hacked away in just a few hours, so don't expect -miracles. +This driver exposes all first-party and third-party Xbox compatible +controllers. It has a long history and has enjoyed considerable usage +as Window's xinput library caused most PC games to focus on Xbox +controller compatibility. -In particular, there is currently NO support for the rumble pack. -You won't find many ff-aware linux applications anyway. +Due to backwards compatibility all buttons are reported as digital. +This only effects Original Xbox controllers. All later controller models +have only digital face buttons. + +Rumble is supported on some models of Xbox 360 controllers but not of +Original Xbox controllers nor on Xbox One controllers. As of writing +the Xbox One's rumble protocol has not been reverse engineered but in +the future could be supported. 0. Notes -------- - -Driver updated for kernel 2.6.17.11. (Based on a patch for 2.6.11.4.) - The number of buttons/axes reported varies based on 3 things: - if you are using a known controller - if you are using a known dance pad @@ -20,12 +24,16 @@ The number of buttons/axes reported varies based on 3 things: module configuration for "Map D-PAD to buttons rather than axes for unknown pads" (module option dpad_to_buttons) -If you set dpad_to_buttons to 0 and you are using an unknown device (one -not listed below), the driver will map the directional pad to axes (X/Y), -if you said N it will map the d-pad to buttons, which is needed for dance -style games to function correctly. The default is Y. +If you set dpad_to_buttons to N and you are using an unknown device +the driver will map the directional pad to axes (X/Y). +If you said Y it will map the d-pad to buttons, which is needed for dance +style games to function correctly. The default is Y. + +dpad_to_buttons has no effect for known pads. A erroneous commit message +claimed dpad_to_buttons could be used to force behavior on known devices. +This is not true. Both dpad_to_buttons and triggers_to_buttons only affect +unknown controllers. -dpad_to_buttons has no effect for known pads. 0.1 Normal Controllers ---------------------- @@ -80,17 +88,29 @@ to the list of supported devices, ensuring that it will work out of the box in the future. -1. USB adapter +1. USB adapters -------------- +All generations of Xbox controllers speak USB over the wire. +- Original Xbox controllers use a proprietary connector and require adapters. +- Wireless Xbox 360 controllers require a 'Xbox 360 Wireless Gaming Receiver + for Windows' +- Wired Xbox 360 controllers use standard USB connectors. +- Xbox One controllers can be wireless but speak Wi-Fi Direct and are not + yet supported. +- Xbox One controllers can be wired and use standard Micro-USB connectors. + -Before you can actually use the driver, you need to get yourself an -adapter cable to connect the X-Box controller to your Linux-Box. You -can buy these online fairly cheap, or build your own. + +1.1 Original Xbox USB adapters +-------------- +Using this driver with an Original Xbox controller requires an +adapter cable to break out the proprietary connector's pins to USB. +You can buy these online fairly cheap, or build your own. Such a cable is pretty easy to build. The Controller itself is a USB compound device (a hub with three ports for two expansion slots and the controller device) with the only difference in a nonstandard connector -(5 pins vs. 4 on standard USB connector). +(5 pins vs. 4 on standard USB 1.0 connectors). You just need to solder a USB connector onto the cable and keep the yellow wire unconnected. The other pins have the same order on both @@ -102,26 +122,41 @@ original one. You can buy an extension cable and cut that instead. That way, you can still use the controller with your X-Box, if you have one ;) + 2. Driver Installation ---------------------- -Once you have the adapter cable and the controller is connected, you need -to load your USB subsystem and should cat /proc/bus/usb/devices. -There should be an entry like the one at the end [4]. +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]. + + -Currently (as of version 0.0.6), the following devices are included: - original Microsoft XBOX controller (US), vendor=0x045e, product=0x0202 - smaller Microsoft XBOX controller (US), vendor=0x045e, product=0x0289 +3. Supported Controllers +------------------------ +For a full list of supported controllers and associated vendor and product +IDs see the xpad_device[] array[6]. + +As of the historic version 0.0.6 (2006-10-10) the following devices +were supported: + original Microsoft XBOX controller (US), vendor=0x045e, product=0x0202 + smaller Microsoft XBOX controller (US), vendor=0x045e, product=0x0289 original Microsoft XBOX controller (Japan), vendor=0x045e, product=0x0285 - InterAct PowerPad Pro (Germany), vendor=0x05fd, product=0x107a - RedOctane Xbox Dance Pad (US), vendor=0x0c12, product=0x8809 + InterAct PowerPad Pro (Germany), vendor=0x05fd, product=0x107a + RedOctane Xbox Dance Pad (US), vendor=0x0c12, product=0x8809 + +Unrecognized models of Xbox controllers should function as Generic +Xbox controllers. Unrecognized Dance Pad controllers require setting +the module option 'dpad_to_buttons'. + +If you have an unrecognized controller please see 0.3 - Unknown Controllers -The driver should work with xbox pads not listed above as well, however -you will need to do something extra for dance pads to work. -If you have a controller not listed above, see 0.3 - Unknown Controllers +4. Manual Testing +----------------- +To test this driver's functionality you may use 'jstest'. -If you compiled and installed the driver, test the functionality: +For example: > modprobe xpad > modprobe joydev > jstest /dev/js0 @@ -134,7 +169,8 @@ show 20 inputs (6 axes, 14 buttons). It works? Voila, you're done ;) -3. Thanks + +5. Thanks --------- I have to thank ITO Takayuki for the detailed info on his site @@ -145,14 +181,14 @@ His useful info and both the usb-skeleton as well as the iforce input driver the basic functionality. -4. 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/ +6. References +------------- -4. /proc/bus/usb/devices - dump from InterAct PowerPad Pro (Germany): +[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): 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 @@ -162,7 +198,7 @@ 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]: /proc/bus/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 @@ -173,7 +209,12 @@ 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 + + + +7. Historic Edits +----------------- Marko Friedemann 2002-07-16 - original doc @@ -181,3 +222,5 @@ Marko Friedemann Dominic Cerquetti 2005-03-19 - added stuff for dance pads, new d-pad->axes mappings + +Later changes may be viewed with 'git log Documentation/input/xpad.txt' -- cgit v1.2.3-59-g8ed1b From 9b64c09bb960b4ccae2a42e204cd70f83b115e3d Mon Sep 17 00:00:00 2001 From: John de la Garza Date: Sat, 6 Dec 2014 16:38:57 -0500 Subject: kobject: grammar fix Signed-off-by: John de la Garza Signed-off-by: Jonathan Corbet --- Documentation/kobject.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/kobject.txt b/Documentation/kobject.txt index f87241dfed87..1be59a3a521c 100644 --- a/Documentation/kobject.txt +++ b/Documentation/kobject.txt @@ -173,7 +173,7 @@ This should be done only after any attributes or children of the kobject have been initialized properly, as userspace will instantly start to look for them when this call happens. -When the kobject is removed from the kernel (details on how to do that is +When the kobject is removed from the kernel (details on how to do that are below), the uevent for KOBJ_REMOVE will be automatically created by the kobject core, so the caller does not have to worry about doing that by hand. -- cgit v1.2.3-59-g8ed1b