Docs changes for the 3.19 merge window

-----BEGIN PGP SIGNATURE-----
 Version: GnuPG v1
 
 iQIcBAABAgAGBQJUiaPRAAoJEI3ONVYwIuV68qQP/2j93CDahLEXlpbimdHCOyKO
 xLKYwSIOxpzCTv8mQouNH4czVDheSSrq+xDUafioaMRlM80fb1EdhC9Nhr/xT/O+
 fCsgfLETlpxAS4j6gjn60H8QYdnBgcz0p2hOgvysf8WHZ0PHzSnfE78BGS1Mnugs
 gjF97y5pa3p+uTNNxHA7aB+Rg3/JbsuDXH0CtdzjpsS0bM/MBnGV0AQLLZ3qdzvf
 6bSwb8LyV54cRjYrs0SZT0OWrPXlUc0AxjrQjq2IcyL+s5Uwu/Eb1RoZ69C14ohC
 h5A1C87v4asqrzsC0VCqG48wi36+2k7zfVT7wSkHfERXWGtjpd7Uy3lccMMPLg/H
 Mnt6EKDVn4L2b8VOM1wl8pj0kIbln/g2whJ6x40Q3R4uO8o94Vy0HpeTTeNxdwyY
 iERVkHPuRAZ2SLrz4BheiGRgcePgocMrofyGcJ3/ezMGcq3sUZnAJYmJYF+S5jkZ
 Q94ee8jgypgEvuQHX52n3AiqJspNpqAGqXE5ZY4PgLt4KlwbT1yQ5hXUX34ou+3u
 sLkFO8vNUQa4o1TTfwCzkPun/Aoy+Rb8BCzgbml/FlPgidXpNcofO/g5BWRjXwOX
 mpUCNPiMhryx0aTrEgl1GChholqToakS6RTvqdxUKC3honKWBQ93zsWSDkEzS+3h
 +qxzXDCN3u3Py9r/XvPK
 =Pq+D
 -----END PGP SIGNATURE-----

Merge tag 'docs-for-linus' of git://git.lwn.net/linux-2.6

Pull documentation update from Jonathan Corbet:
 "Here's my set of accumulated documentation changes for 3.19.

  It includes a couple of additions to the coding style document, some
  fixes for minor build problems within the documentation tree, the
  relocation of the kselftest docs, and various tweaks and additions.

  A couple of changes reach outside of Documentation/; they only make
  trivial comment changes and I did my best to get the required acks.

  Complete with a shiny signed tag this time around"

* tag 'docs-for-linus' of git://git.lwn.net/linux-2.6:
  kobject: grammar fix
  Input: xpad - update docs to reflect current state
  Documentation: Build mic/mpssd only for x86_64
  cgroups: Documentation: fix wrong cgroupfs paths
  Documentation/email-clients.txt: add info about Claws Mail
  CodingStyle: add some more error handling guidelines
  kselftest: Move the docs to the Documentation dir
  Documentation: fix formatting to make 's' happy
  Documentation: power: Fix typo in Documentation/power
  Documentation: vm: Add 1GB large page support information
  ipv4: add kernel parameter tcpmhash_entries
  Documentation: Fix a typo in mailbox.txt
  treewide: Fix typo in Documentation/DocBook/device-drivers
  CodingStyle: Add a chapter on conditional compilation
This commit is contained in:
Linus Torvalds 2014-12-12 14:42:48 -08:00
commit 823e334ecd
17 changed files with 202 additions and 73 deletions

View File

@ -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
@ -845,6 +862,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

View File

@ -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

View File

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

View File

@ -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

View File

@ -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
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.
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 a controller not listed above, see 0.3 - Unknown Controllers
If you have an unrecognized controller please see 0.3 - Unknown Controllers
If you compiled and installed the driver, test the functionality:
4. Manual Testing
-----------------
To test this driver's functionality you may use 'jstest'.
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
6. References
-------------
1. http://euc.jp/periphs/xbox-controller.ja.html (ITO Takayuki)
2. http://xpad.xbox-scene.com/
3. http://www.markosweb.com/www/xboxhackz.com/
4. /proc/bus/usb/devices - dump from InterAct PowerPad Pro (Germany):
[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 <mfr@bmx-chemnitz.de>
2002-07-16
- original doc
@ -181,3 +222,5 @@ Marko Friedemann <mfr@bmx-chemnitz.de>
Dominic Cerquetti <binary1230@yahoo.com>
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'

View File

@ -3434,6 +3434,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]

View File

@ -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.

View File

@ -15,37 +15,45 @@ 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.
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
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.
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:
To build the hotplug tests:
$ make -C tools/testing/selftests hotplug
To run the tests:
To run the hotplug tests:
$ make -C tools/testing/selftests run_hotplug
- note that some tests will require root privileges.
Contributing new tests
======================

View File

@ -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 */

View File

@ -1,5 +1,5 @@
# List of programs to build
hostprogs-y := mpssd
hostprogs-$(CONFIG_X86_64) := mpssd
mpssd-objs := mpssd.o sysfs.o

View File

@ -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

View File

@ -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).

View File

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

View File

@ -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.

View File

@ -283,7 +283,7 @@ EXPORT_SYMBOL(fence_add_callback);
* @cb: [in] the callback to remove
*
* Remove a previously queued callback from the fence. This function returns
* true if the callback is succesfully removed, or false if the fence has
* true if the callback is successfully removed, or false if the fence has
* already been signaled.
*
* *WARNING*:

View File

@ -128,8 +128,8 @@ struct fence_cb {
* from irq context, so normal spinlocks can be used.
*
* A return value of false indicates the fence already passed,
* or some failure occured that made it impossible to enable
* signaling. True indicates succesful enabling.
* or some failure occurred that made it impossible to enable
* signaling. True indicates successful enabling.
*
* fence->status may be set in enable_signaling, but only when false is
* returned.

View File

@ -359,7 +359,7 @@ i2c_register_board_info(int busnum, struct i2c_board_info const *info,
* to name two of the most common.
*
* The return codes from the @master_xfer field should indicate the type of
* error code that occured during the transfer, as documented in the kernel
* error code that occurred during the transfer, as documented in the kernel
* Documentation file Documentation/i2c/fault-codes.
*/
struct i2c_algorithm {