Commit 73b4f63a authored by Linus Torvalds's avatar Linus Torvalds

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

Pull documentation updates from Jonathan Corbet:
 "Highlights this time around include:

   - A thrashing of SubmittingPatches to bring it out of the "send
     everything to Linus" era of kernel development.

   - A new document on completions from Nicholas McGuire

   - Lots of typo fixes, formatting improvements, corrections, build
     fixes, and more"

* tag 'docs-for-linus' of git://git.lwn.net/linux-2.6: (35 commits)
  Documentation: Fix the wrong command `echo -1 > set_ftrace_pid` for cleaning the filter.
  can-doc: Fixed a wrong filepath in can.txt
  Documentation: Fix trivial typo in comment.
  kgdb,docs: Fix typo and minor style issues
  Documentation: add description for FTRACE probe status
  doc: brief user documentation for completion
  Documentation/misc-devices/mei: Fix indentation of embedded code.
  Documentation/misc-devices/mei: Fix indentation of enumeration.
  Documentation/misc-devices/mei: Fix spacing around parentheses.
  Documentation/misc-devices/mei: Fix formatting of headings.
  Documentation: devicetree: Fix double words in Doumentation/devicetree
  Documentation: mm: Fix typo in vm.txt
  lockstat: Add documentation on contention and contenting points
  Documentation: fix blackfin gptimers-example build errors
  Fixes column alignment in table of contents entry 1.9 in Documentation/filesystems/proc.txt
  CodingStyle: enable emacs display of trailing whitespace
  DocBook: Do not exceed argument list limit
  gpio: board.txt: Fix the gpio name example
  Documentation/SubmittingPatches: unify whitespace/tabs for the DCO
  MAINTAINERS: Add the docs-next git tree to the maintainer entry
  ...
parents bfe9183f 52e68924
...@@ -29,8 +29,6 @@ DMA-ISA-LPC.txt ...@@ -29,8 +29,6 @@ DMA-ISA-LPC.txt
- How to do DMA with ISA (and LPC) devices. - How to do DMA with ISA (and LPC) devices.
DMA-attributes.txt DMA-attributes.txt
- listing of the various possible attributes a DMA region can have - listing of the various possible attributes a DMA region can have
dmatest.txt
- how to compile, configure and use the dmatest system.
DocBook/ DocBook/
- directory with DocBook templates etc. for kernel documentation. - directory with DocBook templates etc. for kernel documentation.
EDID/ EDID/
...@@ -163,8 +161,6 @@ digsig.txt ...@@ -163,8 +161,6 @@ digsig.txt
-info on the Digital Signature Verification API -info on the Digital Signature Verification API
dma-buf-sharing.txt dma-buf-sharing.txt
- the DMA Buffer Sharing API Guide - the DMA Buffer Sharing API Guide
dmaengine.txt
-the DMA Engine API Guide
dontdiff dontdiff
- file containing a list of files that should never be diff'ed. - file containing a list of files that should never be diff'ed.
driver-model/ driver-model/
...@@ -209,6 +205,8 @@ hid/ ...@@ -209,6 +205,8 @@ hid/
- directory with information on human interface devices - directory with information on human interface devices
highuid.txt highuid.txt
- notes on the change from 16 bit to 32 bit user/group IDs. - notes on the change from 16 bit to 32 bit user/group IDs.
hsi.txt
- HSI subsystem overview.
hwspinlock.txt hwspinlock.txt
- hardware spinlock provides hardware assistance for synchronization - hardware spinlock provides hardware assistance for synchronization
timers/ timers/
...@@ -277,6 +275,8 @@ kprobes.txt ...@@ -277,6 +275,8 @@ kprobes.txt
- documents the kernel probes debugging feature. - documents the kernel probes debugging feature.
kref.txt kref.txt
- docs on adding reference counters (krefs) to kernel objects. - docs on adding reference counters (krefs) to kernel objects.
kselftest.txt
- small unittests for (some) individual codepaths in the kernel.
laptops/ laptops/
- directory with laptop related info and laptop driver documentation. - directory with laptop related info and laptop driver documentation.
ldm.txt ldm.txt
...@@ -285,22 +285,22 @@ leds/ ...@@ -285,22 +285,22 @@ leds/
- directory with info about LED handling under Linux. - directory with info about LED handling under Linux.
local_ops.txt local_ops.txt
- semantics and behavior of local atomic operations. - semantics and behavior of local atomic operations.
lockdep-design.txt
- documentation on the runtime locking correctness validator.
locking/ locking/
- directory with info about kernel locking primitives - directory with info about kernel locking primitives
lockstat.txt
- info on collecting statistics on locks (and contention).
lockup-watchdogs.txt lockup-watchdogs.txt
- info on soft and hard lockup detectors (aka nmi_watchdog). - info on soft and hard lockup detectors (aka nmi_watchdog).
logo.gif logo.gif
- full colour GIF image of Linux logo (penguin - Tux). - full colour GIF image of Linux logo (penguin - Tux).
logo.txt logo.txt
- info on creator of above logo & site to get additional images from. - info on creator of above logo & site to get additional images from.
lzo.txt
- kernel LZO decompressor input formats
m68k/ m68k/
- directory with info about Linux on Motorola 68k architecture. - directory with info about Linux on Motorola 68k architecture.
magic-number.txt magic-number.txt
- list of magic numbers used to mark/protect kernel data structures. - list of magic numbers used to mark/protect kernel data structures.
mailbox.txt
- How to write drivers for the common mailbox framework (IPC).
md.txt md.txt
- info on boot arguments for the multiple devices driver. - info on boot arguments for the multiple devices driver.
media-framework.txt media-framework.txt
...@@ -327,8 +327,6 @@ mtd/ ...@@ -327,8 +327,6 @@ mtd/
- directory with info about memory technology devices (flash) - directory with info about memory technology devices (flash)
mono.txt mono.txt
- how to execute Mono-based .NET binaries with the help of BINFMT_MISC. - how to execute Mono-based .NET binaries with the help of BINFMT_MISC.
mutex-design.txt
- info on the generic mutex subsystem.
namespaces/ namespaces/
- directory with various information about namespaces - directory with various information about namespaces
netlabel/ netlabel/
...@@ -395,10 +393,6 @@ robust-futexes.txt ...@@ -395,10 +393,6 @@ robust-futexes.txt
- a description of what robust futexes are. - a description of what robust futexes are.
rpmsg.txt rpmsg.txt
- info on the Remote Processor Messaging (rpmsg) Framework - info on the Remote Processor Messaging (rpmsg) Framework
rt-mutex-design.txt
- description of the RealTime mutex implementation design.
rt-mutex.txt
- desc. of RT-mutex subsystem with PI (Priority Inheritance) support.
rtc.txt rtc.txt
- notes on how to use the Real Time Clock (aka CMOS clock) driver. - notes on how to use the Real Time Clock (aka CMOS clock) driver.
s390/ s390/
...@@ -425,8 +419,6 @@ sparse.txt ...@@ -425,8 +419,6 @@ sparse.txt
- info on how to obtain and use the sparse tool for typechecking. - info on how to obtain and use the sparse tool for typechecking.
spi/ spi/
- overview of Linux kernel Serial Peripheral Interface (SPI) support. - overview of Linux kernel Serial Peripheral Interface (SPI) support.
spinlocks.txt
- info on using spinlocks to provide exclusive access in kernel.
stable_api_nonsense.txt stable_api_nonsense.txt
- info on why the kernel does not have a stable in-kernel api or abi. - info on why the kernel does not have a stable in-kernel api or abi.
stable_kernel_rules.txt stable_kernel_rules.txt
...@@ -483,10 +475,10 @@ wimax/ ...@@ -483,10 +475,10 @@ wimax/
- directory with info about Intel Wireless Wimax Connections - directory with info about Intel Wireless Wimax Connections
workqueue.txt workqueue.txt
- information on the Concurrency Managed Workqueue implementation - information on the Concurrency Managed Workqueue implementation
ww-mutex-design.txt
- Intro to Mutex wait/would deadlock handling.s
x86/x86_64/ x86/x86_64/
- directory with info on Linux support for AMD x86-64 (Hammer) machines. - directory with info on Linux support for AMD x86-64 (Hammer) machines.
xillybus.txt
- Overview and basic ui of xillybus driver
xtensa/ xtensa/
- directory with documents relating to arch/xtensa port/implementation - directory with documents relating to arch/xtensa port/implementation
xz.txt xz.txt
......
...@@ -21,8 +21,8 @@ running a Linux kernel. Also, not all tools are necessary on all ...@@ -21,8 +21,8 @@ running a Linux kernel. Also, not all tools are necessary on all
systems; obviously, if you don't have any ISDN hardware, for example, systems; obviously, if you don't have any ISDN hardware, for example,
you probably needn't concern yourself with isdn4k-utils. you probably needn't concern yourself with isdn4k-utils.
o Gnu C 3.2 # gcc --version o GNU C 3.2 # gcc --version
o Gnu make 3.80 # make --version o GNU make 3.80 # make --version
o binutils 2.12 # ld -v o binutils 2.12 # ld -v
o util-linux 2.10o # fdformat --version o util-linux 2.10o # fdformat --version
o module-init-tools 0.9.10 # depmod -V o module-init-tools 0.9.10 # depmod -V
...@@ -57,7 +57,7 @@ computer. ...@@ -57,7 +57,7 @@ computer.
Make Make
---- ----
You will need Gnu make 3.80 or later to build the kernel. You will need GNU make 3.80 or later to build the kernel.
Binutils Binutils
-------- --------
......
...@@ -527,6 +527,7 @@ values. To do the latter, you can stick the following in your .emacs file: ...@@ -527,6 +527,7 @@ values. To do the latter, you can stick the following in your .emacs file:
(string-match (expand-file-name "~/src/linux-trees") (string-match (expand-file-name "~/src/linux-trees")
filename)) filename))
(setq indent-tabs-mode t) (setq indent-tabs-mode t)
(setq show-trailing-whitespace t)
(c-set-style "linux-tabs-only"))))) (c-set-style "linux-tabs-only")))))
This will make emacs go better with the kernel coding style for C This will make emacs go better with the kernel coding style for C
......
...@@ -56,7 +56,7 @@ htmldocs: $(HTML) ...@@ -56,7 +56,7 @@ htmldocs: $(HTML)
MAN := $(patsubst %.xml, %.9, $(BOOKS)) MAN := $(patsubst %.xml, %.9, $(BOOKS))
mandocs: $(MAN) mandocs: $(MAN)
$(if $(wildcard $(obj)/man/*.9),gzip -f $(obj)/man/*.9) find $(obj)/man -name '*.9' | xargs gzip -f
installmandocs: mandocs installmandocs: mandocs
mkdir -p /usr/local/man/man9/ mkdir -p /usr/local/man/man9/
......
...@@ -111,7 +111,7 @@ ...@@ -111,7 +111,7 @@
<para> <para>
This specification is intended for consumers of the kernel crypto This specification is intended for consumers of the kernel crypto
API as well as for developers implementing ciphers. This API API as well as for developers implementing ciphers. This API
specification, however, does not discusses all API calls available specification, however, does not discuss all API calls available
to data transformation implementations (i.e. implementations of to data transformation implementations (i.e. implementations of
ciphers and other transformations (such as CRC or even compression ciphers and other transformations (such as CRC or even compression
algorithms) that can register with the kernel crypto API). algorithms) that can register with the kernel crypto API).
......
...@@ -75,7 +75,7 @@ ...@@ -75,7 +75,7 @@
a development machine and the other is the target machine. The a development machine and the other is the target machine. The
kernel to be debugged runs on the target machine. The development kernel to be debugged runs on the target machine. The development
machine runs an instance of gdb against the vmlinux file which machine runs an instance of gdb against the vmlinux file which
contains the symbols (not boot image such as bzImage, zImage, contains the symbols (not a boot image such as bzImage, zImage,
uImage...). In gdb the developer specifies the connection uImage...). In gdb the developer specifies the connection
parameters and connects to kgdb. The type of connection a parameters and connects to kgdb. The type of connection a
developer makes with gdb depends on the availability of kgdb I/O developer makes with gdb depends on the availability of kgdb I/O
...@@ -95,7 +95,7 @@ ...@@ -95,7 +95,7 @@
<title>Kernel config options for kgdb</title> <title>Kernel config options for kgdb</title>
<para> <para>
To enable <symbol>CONFIG_KGDB</symbol> you should look under To enable <symbol>CONFIG_KGDB</symbol> you should look under
"Kernel debugging" and select "KGDB: kernel debugger". "Kernel hacking" / "Kernel debugging" and select "KGDB: kernel debugger".
</para> </para>
<para> <para>
While it is not a hard requirement that you have symbols in your While it is not a hard requirement that you have symbols in your
...@@ -105,7 +105,7 @@ ...@@ -105,7 +105,7 @@
kernel with debug info" in the config menu. kernel with debug info" in the config menu.
</para> </para>
<para> <para>
It is advised, but not required that you turn on the It is advised, but not required, that you turn on the
<symbol>CONFIG_FRAME_POINTER</symbol> kernel option which is called "Compile the <symbol>CONFIG_FRAME_POINTER</symbol> kernel option which is called "Compile the
kernel with frame pointers" in the config menu. This option kernel with frame pointers" in the config menu. This option
inserts code to into the compiled executable which saves the frame inserts code to into the compiled executable which saves the frame
...@@ -181,7 +181,7 @@ ...@@ -181,7 +181,7 @@
<para>This section describes the various runtime kernel <para>This section describes the various runtime kernel
parameters that affect the configuration of the kernel debugger. parameters that affect the configuration of the kernel debugger.
The following chapter covers using kdb and kgdb as well as The following chapter covers using kdb and kgdb as well as
provides some examples of the configuration parameters.</para> providing some examples of the configuration parameters.</para>
<sect1 id="kgdboc"> <sect1 id="kgdboc">
<title>Kernel parameter: kgdboc</title> <title>Kernel parameter: kgdboc</title>
<para>The kgdboc driver was originally an abbreviation meant to <para>The kgdboc driver was originally an abbreviation meant to
...@@ -219,8 +219,8 @@ ...@@ -219,8 +219,8 @@
<listitem><para>kbd = Keyboard</para></listitem> <listitem><para>kbd = Keyboard</para></listitem>
</itemizedlist> </itemizedlist>
</para> </para>
<para>You can configure kgdboc to use the keyboard, and or a serial <para>You can configure kgdboc to use the keyboard, and/or a serial
device depending on if you are using kdb and or kgdb, in one of the device depending on if you are using kdb and/or kgdb, in one of the
following scenarios. The order listed above must be observed if following scenarios. The order listed above must be observed if
you use any of the optional configurations together. Using kms + you use any of the optional configurations together. Using kms +
only gdb is generally not a useful combination.</para> only gdb is generally not a useful combination.</para>
...@@ -261,11 +261,8 @@ ...@@ -261,11 +261,8 @@
</sect3> </sect3>
<sect3 id="kgdbocArgs3"> <sect3 id="kgdbocArgs3">
<title>More examples</title> <title>More examples</title>
<para>You can configure kgdboc to use the keyboard, and or a serial <para>You can configure kgdboc to use the keyboard, and/or a serial device
device depending on if you are using kdb and or kgdb, in one of the depending on if you are using kdb and/or kgdb, in one of the
following scenarios.</para>
<para>You can configure kgdboc to use the keyboard, and or a serial device
depending on if you are using kdb and or kgdb, in one of the
following scenarios. following scenarios.
<orderedlist> <orderedlist>
<listitem><para>kdb and kgdb over only a serial port</para> <listitem><para>kdb and kgdb over only a serial port</para>
...@@ -315,7 +312,7 @@ ...@@ -315,7 +312,7 @@
<para> <para>
The Kernel command line option <constant>kgdbwait</constant> makes The Kernel command line option <constant>kgdbwait</constant> makes
kgdb wait for a debugger connection during booting of a kernel. You kgdb wait for a debugger connection during booting of a kernel. You
can only use this option you compiled a kgdb I/O driver into the can only use this option if you compiled a kgdb I/O driver into the
kernel and you specified the I/O driver configuration as a kernel kernel and you specified the I/O driver configuration as a kernel
command line option. The kgdbwait parameter should always follow the command line option. The kgdbwait parameter should always follow the
configuration parameter for the kgdb I/O driver in the kernel configuration parameter for the kgdb I/O driver in the kernel
...@@ -354,7 +351,7 @@ ...@@ -354,7 +351,7 @@
</listitem> </listitem>
</orderedlist> </orderedlist>
<para>IMPORTANT NOTE: You cannot use kgdboc + kgdbcon on a tty that is an <para>IMPORTANT NOTE: You cannot use kgdboc + kgdbcon on a tty that is an
active system console. An example incorrect usage is <constant>console=ttyS0,115200 kgdboc=ttyS0 kgdbcon</constant> active system console. An example of incorrect usage is <constant>console=ttyS0,115200 kgdboc=ttyS0 kgdbcon</constant>
</para> </para>
<para>It is possible to use this option with kgdboc on a tty that is not a system console. <para>It is possible to use this option with kgdboc on a tty that is not a system console.
</para> </para>
...@@ -386,12 +383,12 @@ ...@@ -386,12 +383,12 @@
<title>Quick start for kdb on a serial port</title> <title>Quick start for kdb on a serial port</title>
<para>This is a quick example of how to use kdb.</para> <para>This is a quick example of how to use kdb.</para>
<para><orderedlist> <para><orderedlist>
<listitem><para>Boot kernel with arguments: <listitem><para>Configure kgdboc at boot using kernel parameters:
<itemizedlist> <itemizedlist>
<listitem><para><constant>console=ttyS0,115200 kgdboc=ttyS0,115200</constant></para></listitem> <listitem><para><constant>console=ttyS0,115200 kgdboc=ttyS0,115200</constant></para></listitem>
</itemizedlist></para> </itemizedlist></para>
<para>OR</para> <para>OR</para>
<para>Configure kgdboc after the kernel booted; assuming you are using a serial port console: <para>Configure kgdboc after the kernel has booted; assuming you are using a serial port console:
<itemizedlist> <itemizedlist>
<listitem><para><constant>echo ttyS0 &gt; /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem> <listitem><para><constant>echo ttyS0 &gt; /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem>
</itemizedlist> </itemizedlist>
...@@ -442,12 +439,12 @@ ...@@ -442,12 +439,12 @@
<title>Quick start for kdb using a keyboard connected console</title> <title>Quick start for kdb using a keyboard connected console</title>
<para>This is a quick example of how to use kdb with a keyboard.</para> <para>This is a quick example of how to use kdb with a keyboard.</para>
<para><orderedlist> <para><orderedlist>
<listitem><para>Boot kernel with arguments: <listitem><para>Configure kgdboc at boot using kernel parameters:
<itemizedlist> <itemizedlist>
<listitem><para><constant>kgdboc=kbd</constant></para></listitem> <listitem><para><constant>kgdboc=kbd</constant></para></listitem>
</itemizedlist></para> </itemizedlist></para>
<para>OR</para> <para>OR</para>
<para>Configure kgdboc after the kernel booted: <para>Configure kgdboc after the kernel has booted:
<itemizedlist> <itemizedlist>
<listitem><para><constant>echo kbd &gt; /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem> <listitem><para><constant>echo kbd &gt; /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem>
</itemizedlist> </itemizedlist>
...@@ -501,12 +498,12 @@ ...@@ -501,12 +498,12 @@
<title>Connecting with gdb to a serial port</title> <title>Connecting with gdb to a serial port</title>
<orderedlist> <orderedlist>
<listitem><para>Configure kgdboc</para> <listitem><para>Configure kgdboc</para>
<para>Boot kernel with arguments: <para>Configure kgdboc at boot using kernel parameters:
<itemizedlist> <itemizedlist>
<listitem><para><constant>kgdboc=ttyS0,115200</constant></para></listitem> <listitem><para><constant>kgdboc=ttyS0,115200</constant></para></listitem>
</itemizedlist></para> </itemizedlist></para>
<para>OR</para> <para>OR</para>
<para>Configure kgdboc after the kernel booted: <para>Configure kgdboc after the kernel has booted:
<itemizedlist> <itemizedlist>
<listitem><para><constant>echo ttyS0 &gt; /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem> <listitem><para><constant>echo ttyS0 &gt; /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem>
</itemizedlist></para> </itemizedlist></para>
...@@ -536,7 +533,7 @@ ...@@ -536,7 +533,7 @@
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para>Connect from from gdb</para> <para>Connect from gdb</para>
<para> <para>
Example (using a directly connected port): Example (using a directly connected port):
</para> </para>
...@@ -584,7 +581,7 @@ ...@@ -584,7 +581,7 @@
<para> <para>
There are two ways to switch from kgdb to kdb: you can use gdb to There are two ways to switch from kgdb to kdb: you can use gdb to
issue a maintenance packet, or you can blindly type the command $3#33. issue a maintenance packet, or you can blindly type the command $3#33.
Whenever kernel debugger stops in kgdb mode it will print the Whenever the kernel debugger stops in kgdb mode it will print the
message <constant>KGDB or $3#33 for KDB</constant>. It is important message <constant>KGDB or $3#33 for KDB</constant>. It is important
to note that you have to type the sequence correctly in one pass. to note that you have to type the sequence correctly in one pass.
You cannot type a backspace or delete because kgdb will interpret You cannot type a backspace or delete because kgdb will interpret
...@@ -704,7 +701,7 @@ Task Addr Pid Parent [*] cpu State Thread Command ...@@ -704,7 +701,7 @@ Task Addr Pid Parent [*] cpu State Thread Command
<listitem><para>Registration and unregistration of architecture specific trap hooks</para></listitem> <listitem><para>Registration and unregistration of architecture specific trap hooks</para></listitem>
<listitem><para>Any special exception handling and cleanup</para></listitem> <listitem><para>Any special exception handling and cleanup</para></listitem>
<listitem><para>NMI exception handling and cleanup</para></listitem> <listitem><para>NMI exception handling and cleanup</para></listitem>
<listitem><para>(optional)HW breakpoints</para></listitem> <listitem><para>(optional) HW breakpoints</para></listitem>
</itemizedlist> </itemizedlist>
</para> </para>
</listitem> </listitem>
...@@ -760,7 +757,7 @@ Task Addr Pid Parent [*] cpu State Thread Command ...@@ -760,7 +757,7 @@ Task Addr Pid Parent [*] cpu State Thread Command
a kgdb I/O driver for characters when it needs input. The I/O a kgdb I/O driver for characters when it needs input. The I/O
driver is expected to return immediately if there is no data driver is expected to return immediately if there is no data
available. Doing so allows for the future possibility to touch available. Doing so allows for the future possibility to touch
watch dog hardware in such a way as to have a target system not watchdog hardware in such a way as to have a target system not
reset when these are enabled. reset when these are enabled.
</para> </para>
</listitem> </listitem>
...@@ -783,10 +780,14 @@ Task Addr Pid Parent [*] cpu State Thread Command ...@@ -783,10 +780,14 @@ Task Addr Pid Parent [*] cpu State Thread Command
NUMREGBYTES: The size in bytes of all of the registers, so NUMREGBYTES: The size in bytes of all of the registers, so
that we can ensure they will all fit into a packet. that we can ensure they will all fit into a packet.
</para> </para>
</listitem>
<listitem>
<para> <para>
BUFMAX: The size in bytes of the buffer GDB will read into. BUFMAX: The size in bytes of the buffer GDB will read into.
This must be larger than NUMREGBYTES. This must be larger than NUMREGBYTES.
</para> </para>
</listitem>
<listitem>
<para> <para>
CACHE_FLUSH_IS_SAFE: Set to 1 if it is always safe to call CACHE_FLUSH_IS_SAFE: Set to 1 if it is always safe to call
flush_cache_range or flush_icache_range. On some architectures, flush_cache_range or flush_icache_range. On some architectures,
...@@ -812,8 +813,8 @@ Task Addr Pid Parent [*] cpu State Thread Command ...@@ -812,8 +813,8 @@ Task Addr Pid Parent [*] cpu State Thread Command
<para> <para>
The kgdboc driver is actually a very thin driver that relies on the The kgdboc driver is actually a very thin driver that relies on the
underlying low level to the hardware driver having "polling hooks" underlying low level to the hardware driver having "polling hooks"
which the to which the tty driver is attached. In the initial to which the tty driver is attached. In the initial
implementation of kgdboc it the serial_core was changed to expose a implementation of kgdboc the serial_core was changed to expose a
low level UART hook for doing polled mode reading and writing of a low level UART hook for doing polled mode reading and writing of a
single character while in an atomic context. When kgdb makes an I/O single character while in an atomic context. When kgdb makes an I/O
request to the debugger, kgdboc invokes a callback in the serial request to the debugger, kgdboc invokes a callback in the serial
......
...@@ -10,27 +10,49 @@ kernel, the process can sometimes be daunting if you're not familiar ...@@ -10,27 +10,49 @@ kernel, the process can sometimes be daunting if you're not familiar
with "the system." This text is a collection of suggestions which with "the system." This text is a collection of suggestions which
can greatly increase the chances of your change being accepted. can greatly increase the chances of your change being accepted.
Read Documentation/SubmitChecklist for a list of items to check This document contains a large number of suggestions in a relatively terse
before submitting code. If you are submitting a driver, also read format. For detailed information on how the kernel development process
Documentation/SubmittingDrivers. works, see Documentation/development-process. Also, read
Documentation/SubmitChecklist for a list of items to check before
submitting code. If you are submitting a driver, also read
Documentation/SubmittingDrivers; for device tree binding patches, read
Documentation/devicetree/bindings/submitting-patches.txt.
Many of these steps describe the default behavior of the git version Many of these steps describe the default behavior of the git version
control system; if you use git to prepare your patches, you'll find much control system; if you use git to prepare your patches, you'll find much
of the mechanical work done for you, though you'll still need to prepare of the mechanical work done for you, though you'll still need to prepare
and document a sensible set of patches. and document a sensible set of patches. In general, use of git will make
your life as a kernel developer easier.
-------------------------------------------- --------------------------------------------
SECTION 1 - CREATING AND SENDING YOUR CHANGE SECTION 1 - CREATING AND SENDING YOUR CHANGE
-------------------------------------------- --------------------------------------------
0) Obtain a current source tree
-------------------------------
If you do not have a repository with the current kernel source handy, use
git to obtain one. You'll want to start with the mainline repository,
which can be grabbed with:
git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
Note, however, that you may not want to develop against the mainline tree
directly. Most subsystem maintainers run their own trees and want to see
patches prepared against those trees. See the "T:" entry for the subsystem
in the MAINTAINERS file to find that tree, or simply ask the maintainer if
the tree is not listed there.
It is still possible to download kernel releases via tarballs (as described
in the next section), but that is the hard way to do kernel development.
1) "diff -up" 1) "diff -up"
------------ ------------
Use "diff -up" or "diff -uprN" to create patches. git generates patches If you must generate your patches by hand, use "diff -up" or "diff -uprN"
in this form by default; if you're using git, you can skip this section to create patches. Git generates patches in this form by default; if
entirely. you're using git, you can skip this section entirely.
All changes to the Linux kernel occur in the form of patches, as All changes to the Linux kernel occur in the form of patches, as
generated by diff(1). When creating your patch, make sure to create it generated by diff(1). When creating your patch, make sure to create it
...@@ -42,7 +64,7 @@ not in any lower subdirectory. ...@@ -42,7 +64,7 @@ not in any lower subdirectory.
To create a patch for a single file, it is often sufficient to do: To create a patch for a single file, it is often sufficient to do:
SRCTREE= linux-2.6 SRCTREE= linux
MYFILE= drivers/net/mydriver.c MYFILE= drivers/net/mydriver.c
cd $SRCTREE cd $SRCTREE
...@@ -55,17 +77,16 @@ To create a patch for multiple files, you should unpack a "vanilla", ...@@ -55,17 +77,16 @@ To create a patch for multiple files, you should unpack a "vanilla",
or unmodified kernel source tree, and generate a diff against your or unmodified kernel source tree, and generate a diff against your
own source tree. For example: own source tree. For example:
MYSRC= /devel/linux-2.6 MYSRC= /devel/linux
tar xvfz linux-2.6.12.tar.gz tar xvfz linux-3.19.tar.gz
mv linux-2.6.12 linux-2.6.12-vanilla mv linux-3.19 linux-3.19-vanilla
diff -uprN -X linux-2.6.12-vanilla/Documentation/dontdiff \ diff -uprN -X linux-3.19-vanilla/Documentation/dontdiff \
linux-2.6.12-vanilla $MYSRC > /tmp/patch linux-3.19-vanilla $MYSRC > /tmp/patch
"dontdiff" is a list of files which are generated by the kernel during "dontdiff" is a list of files which are generated by the kernel during
the build process, and should be ignored in any diff(1)-generated the build process, and should be ignored in any diff(1)-generated
patch. The "dontdiff" file is included in the kernel tree in patch.
2.6.12 and later.
Make sure your patch does not include any extra files which do not Make sure your patch does not include any extra files which do not
belong in a patch submission. Make sure to review your patch -after- belong in a patch submission. Make sure to review your patch -after-
...@@ -83,6 +104,7 @@ is another popular alternative. ...@@ -83,6 +104,7 @@ is another popular alternative.
2) Describe your changes. 2) Describe your changes.
-------------------------
Describe your problem. Whether your patch is a one-line bug fix or Describe your problem. Whether your patch is a one-line bug fix or
5000 lines of a new feature, there must be an underlying problem that 5000 lines of a new feature, there must be an underlying problem that
...@@ -124,10 +146,10 @@ See #3, next. ...@@ -124,10 +146,10 @@ See #3, next.
When you submit or resubmit a patch or patch series, include the When you submit or resubmit a patch or patch series, include the
complete patch description and justification for it. Don't just complete patch description and justification for it. Don't just
say that this is version N of the patch (series). Don't expect the say that this is version N of the patch (series). Don't expect the
patch merger to refer back to earlier patch versions or referenced subsystem maintainer to refer back to earlier patch versions or referenced
URLs to find the patch description and put that into the patch. URLs to find the patch description and put that into the patch.
I.e., the patch (series) and its description should be self-contained. I.e., the patch (series) and its description should be self-contained.
This benefits both the patch merger(s) and reviewers. Some reviewers This benefits both the maintainers and reviewers. Some reviewers
probably didn't even receive earlier versions of the patch. probably didn't even receive earlier versions of the patch.
Describe your changes in imperative mood, e.g. "make xyzzy do frotz" Describe your changes in imperative mood, e.g. "make xyzzy do frotz"
...@@ -156,10 +178,15 @@ Example: ...@@ -156,10 +178,15 @@ Example:
platform_set_drvdata(), but left the variable "dev" unused, platform_set_drvdata(), but left the variable "dev" unused,
delete it. delete it.
You should also be sure to use at least the first twelve characters of the
SHA-1 ID. The kernel repository holds a *lot* of objects, making
collisions with shorter IDs a real possibility. Bear in mind that, even if
there is no collision with your six-character ID now, that condition may
change five years from now.
If your patch fixes a bug in a specific commit, e.g. you found an issue using If your patch fixes a bug in a specific commit, e.g. you found an issue using
git-bisect, please use the 'Fixes:' tag with the first 12 characters of the git-bisect, please use the 'Fixes:' tag with the first 12 characters of the
SHA-1 ID, and the one line summary. SHA-1 ID, and the one line summary. For example:
Example:
Fixes: e21d2170f366 ("video: remove unnecessary platform_set_drvdata()") Fixes: e21d2170f366 ("video: remove unnecessary platform_set_drvdata()")
...@@ -172,8 +199,9 @@ outputting the above style in the git log or git show commands ...@@ -172,8 +199,9 @@ outputting the above style in the git log or git show commands
fixes = Fixes: %h (\"%s\") fixes = Fixes: %h (\"%s\")
3) Separate your changes. 3) Separate your changes.
-------------------------
Separate _logical changes_ into a single patch file. Separate each _logical change_ into a separate patch.
For example, if your changes include both bug fixes and performance For example, if your changes include both bug fixes and performance
enhancements for a single driver, separate those changes into two enhancements for a single driver, separate those changes into two
...@@ -184,90 +212,116 @@ On the other hand, if you make a single change to numerous files, ...@@ -184,90 +212,116 @@ On the other hand, if you make a single change to numerous files,
group those changes into a single patch. Thus a single logical change group those changes into a single patch. Thus a single logical change
is contained within a single patch. is contained within a single patch.
The point to remember is that each patch should make an easily understood
change that can be verified by reviewers. Each patch should be justifiable
on its own merits.
If one patch depends on another patch in order for a change to be If one patch depends on another patch in order for a change to be
complete, that is OK. Simply note "this patch depends on patch X" complete, that is OK. Simply note "this patch depends on patch X"
in your patch description. in your patch description.
When dividing your change into a series of patches, take special care to
ensure that the kernel builds and runs properly after each patch in the
series. Developers using "git bisect" to track down a problem can end up
splitting your patch series at any point; they will not thank you if you
introduce bugs in the middle.
If you cannot condense your patch set into a smaller set of patches, If you cannot condense your patch set into a smaller set of patches,
then only post say 15 or so at a time and wait for review and integration. then only post say 15 or so at a time and wait for review and integration.
4) Style check your changes. 4) Style-check your changes.
----------------------------
Check your patch for basic style violations, details of which can be Check your patch for basic style violations, details of which can be
found in Documentation/CodingStyle. Failure to do so simply wastes found in Documentation/CodingStyle. Failure to do so simply wastes
the reviewers time and will get your patch rejected, probably the reviewers time and will get your patch rejected, probably
without even being read. without even being read.
At a minimum you should check your patches with the patch style One significant exception is when moving code from one file to
checker prior to submission (scripts/checkpatch.pl). You should another -- in this case you should not modify the moved code at all in
be able to justify all violations that remain in your patch. the same patch which moves it. This clearly delineates the act of
moving the code and your changes. This greatly aids review of the
actual differences and allows tools to better track the history of
the code itself.
Check your patches with the patch style checker prior to submission
(scripts/checkpatch.pl). Note, though, that the style checker should be
viewed as a guide, not as a replacement for human judgment. If your code
looks better with a violation then its probably best left alone.
The checker reports at three levels:
- ERROR: things that are very likely to be wrong
- WARNING: things requiring careful review
- CHECK: things requiring thought
You should be able to justify all violations that remain in your
patch.
5) Select e-mail destination. 5) Select the recipients for your patch.
----------------------------------------
Look through the MAINTAINERS file and the source code, and determine You should always copy the appropriate subsystem maintainer(s) on any patch
if your change applies to a specific subsystem of the kernel, with to code that they maintain; look through the MAINTAINERS file and the
an assigned maintainer. If so, e-mail that person. The script source code revision history to see who those maintainers are. The
scripts/get_maintainer.pl can be very useful at this step. script scripts/get_maintainer.pl can be very useful at this step. If you
cannot find a maintainer for the subsystem your are working on, Andrew
Morton (akpm@linux-foundation.org) serves as a maintainer of last resort.
If no maintainer is listed, or the maintainer does not respond, send You should also normally choose at least one mailing list to receive a copy
your patch to the primary Linux kernel developer's mailing list, of your patch set. linux-kernel@vger.kernel.org functions as a list of
linux-kernel@vger.kernel.org. Most kernel developers monitor this last resort, but the volume on that list has caused a number of developers
e-mail list, and can comment on your changes. to tune it out. Look in the MAINTAINERS file for a subsystem-specific
list; your patch will probably get more attention there. Please do not
spam unrelated lists, though.
Many kernel-related lists are hosted on vger.kernel.org; you can find a
list of them at http://vger.kernel.org/vger-lists.html. There are
kernel-related lists hosted elsewhere as well, though.
Do not send more than 15 patches at once to the vger mailing lists!!! Do not send more than 15 patches at once to the vger mailing lists!!!
Linus Torvalds is the final arbiter of all changes accepted into the Linus Torvalds is the final arbiter of all changes accepted into the
Linux kernel. His e-mail address is <torvalds@linux-foundation.org>. Linux kernel. His e-mail address is <torvalds@linux-foundation.org>.
He gets a lot of e-mail, so typically you should do your best to -avoid- He gets a lot of e-mail, and, at this point, very few patches go through
Linus directly, so typically you should do your best to -avoid-
sending him e-mail. sending him e-mail.
Patches which are bug fixes, are "obvious" changes, or similarly If you have a patch that fixes an exploitable security bug, send that patch
require little discussion should be sent or CC'd to Linus. Patches to security@kernel.org. For severe bugs, a short embargo may be considered
which require discussion or do not have a clear advantage should to allow distrbutors to get the patch out to users; in such cases,
usually be sent first to linux-kernel. Only after the patch is obviously, the patch should not be sent to any public lists.
discussed should the patch then be submitted to Linus.
6) Select your CC (e-mail carbon copy) list. Patches that fix a severe bug in a released kernel should be directed
toward the stable maintainers by putting a line like this:
Unless you have a reason NOT to do so, CC linux-kernel@vger.kernel.org. Cc: stable@vger.kernel.org
Other kernel developers besides Linus need to be aware of your change, into your patch.
so that they may comment on it and offer code review and suggestions.
linux-kernel is the primary Linux kernel developer mailing list.
Other mailing lists are available for specific subsystems, such as
USB, framebuffer devices, the VFS, the SCSI subsystem, etc. See the
MAINTAINERS file for a mailing list that relates specifically to
your change.
Majordomo lists of VGER.KERNEL.ORG at: Note, however, that some subsystem maintainers want to come to their own
<http://vger.kernel.org/vger-lists.html> conclusions on which patches should go to the stable trees. The networking
maintainer, in particular, would rather not see individual developers
adding lines like the above to their patches.
If changes affect userland-kernel interfaces, please send If changes affect userland-kernel interfaces, please send the MAN-PAGES
the MAN-PAGES maintainer (as listed in the MAINTAINERS file) maintainer (as listed in the MAINTAINERS file) a man-pages patch, or at
a man-pages patch, or at least a notification of the change, least a notification of the change, so that some information makes its way
so that some information makes its way into the manual pages. into the manual pages. User-space API changes should also be copied to
linux-api@vger.kernel.org.
Even if the maintainer did not respond in step #5, make sure to ALWAYS
copy the maintainer when you change their code.
For small patches you may want to CC the Trivial Patch Monkey For small patches you may want to CC the Trivial Patch Monkey
trivial@kernel.org which collects "trivial" patches. Have a look trivial@kernel.org which collects "trivial" patches. Have a look
into the MAINTAINERS file for its current manager. into the MAINTAINERS file for its current manager.
Trivial patches must qualify for one of the following rules: Trivial patches must qualify for one of the following rules:
Spelling fixes in documentation Spelling fixes in documentation
Spelling fixes which could break grep(1) Spelling fixes for errors which could break grep(1)
Warning fixes (cluttering with useless warnings is bad) Warning fixes (cluttering with useless warnings is bad)
Compilation fixes (only if they are actually correct) Compilation fixes (only if they are actually correct)
Runtime fixes (only if they actually fix things) Runtime fixes (only if they actually fix things)
Removing use of deprecated functions/macros (eg. check_region) Removing use of deprecated functions/macros
Contact detail and documentation fixes Contact detail and documentation fixes
Non-portable code replaced by portable code (even in arch-specific, Non-portable code replaced by portable code (even in arch-specific,
since people copy, as long as it's trivial) since people copy, as long as it's trivial)
...@@ -276,7 +330,8 @@ Trivial patches must qualify for one of the following rules: ...@@ -276,7 +330,8 @@ Trivial patches must qualify for one of the following rules:
7) No MIME, no links, no compression, no attachments. Just plain text. 6) No MIME, no links, no compression, no attachments. Just plain text.
-----------------------------------------------------------------------
Linus and other kernel developers need to be able to read and comment Linus and other kernel developers need to be able to read and comment
on the changes you are submitting. It is important for a kernel on the changes you are submitting. It is important for a kernel
...@@ -299,54 +354,48 @@ you to re-send them using MIME. ...@@ -299,54 +354,48 @@ you to re-send them using MIME.
See Documentation/email-clients.txt for hints about configuring See Documentation/email-clients.txt for hints about configuring
your e-mail client so that it sends your patches untouched. your e-mail client so that it sends your patches untouched.
8) E-mail size. 7) E-mail size.
---------------
When sending patches to Linus, always follow step #7.
Large changes are not appropriate for mailing lists, and some Large changes are not appropriate for mailing lists, and some
maintainers. If your patch, uncompressed, exceeds 300 kB in size, maintainers. If your patch, uncompressed, exceeds 300 kB in size,
it is preferred that you store your patch on an Internet-accessible it is preferred that you store your patch on an Internet-accessible
server, and provide instead a URL (link) pointing to your patch. server, and provide instead a URL (link) pointing to your patch. But note
that if your patch exceeds 300 kB, it almost certainly needs to be broken up
anyway.
8) Respond to review comments.
------------------------------
Your patch will almost certainly get comments from reviewers on ways in
which the patch can be improved. You must respond to those comments;
ignoring reviewers is a good way to get ignored in return. Review comments
or questions that do not lead to a code change should almost certainly
bring about a comment or changelog entry so that the next reviewer better
understands what is going on.
9) Name your kernel version. Be sure to tell the reviewers what changes you are making and to thank them
for their time. Code review is a tiring and time-consuming process, and
reviewers sometimes get grumpy. Even in that case, though, respond
politely and address the problems they have pointed out.
It is important to note, either in the subject line or in the patch
description, the kernel version to which this patch applies.
If the patch does not apply cleanly to the latest kernel version, 9) Don't get discouraged - or impatient.
Linus will not apply it. ----------------------------------------
After you have submitted your change, be patient and wait. Reviewers are
busy people and may not get to your patch right away.
Once upon a time, patches used to disappear into the void without comment,
but the development process works more smoothly than that now. You should
receive comments within a week or so; if that does not happen, make sure
that you have sent your patches to the right place. Wait for a minimum of
one week before resubmitting or pinging reviewers - possibly longer during
busy times like merge windows.
10) Don't get discouraged. Re-submit.
After you have submitted your change, be patient and wait. If Linus 10) Include PATCH in the subject
likes your change and applies it, it will appear in the next version --------------------------------
of the kernel that he releases.
However, if your change doesn't appear in the next version of the
kernel, there could be any number of reasons. It's YOUR job to
narrow down those reasons, correct what was wrong, and submit your
updated change.
It is quite common for Linus to "drop" your patch without comment.
That's the nature of the system. If he drops your patch, it could be
due to
* Your patch did not apply cleanly to the latest kernel version.
* Your patch was not sufficiently discussed on linux-kernel.
* A style issue (see section 2).
* An e-mail formatting issue (re-read this section).
* A technical problem with your change.
* He gets tons of e-mail, and yours got lost in the shuffle.
* You are being annoying.
When in doubt, solicit comments on linux-kernel mailing list.
11) Include PATCH in the subject
Due to high e-mail traffic to Linus, and to linux-kernel, it is common Due to high e-mail traffic to Linus, and to linux-kernel, it is common
convention to prefix your subject line with [PATCH]. This lets Linus convention to prefix your subject line with [PATCH]. This lets Linus
...@@ -355,7 +404,8 @@ e-mail discussions. ...@@ -355,7 +404,8 @@ e-mail discussions.
12) Sign your work 11) Sign your work
------------------
To improve tracking of who did what, especially with patches that can To improve tracking of who did what, especially with patches that can
percolate to their final resting place in the kernel through several percolate to their final resting place in the kernel through several
...@@ -429,15 +479,15 @@ which appears in the changelog. ...@@ -429,15 +479,15 @@ which appears in the changelog.
Special note to back-porters: It seems to be a common and useful practice Special note to back-porters: It seems to be a common and useful practice
to insert an indication of the origin of a patch at the top of the commit to insert an indication of the origin of a patch at the top of the commit
message (just after the subject line) to facilitate tracking. For instance, message (just after the subject line) to facilitate tracking. For instance,
here's what we see in 2.6-stable : here's what we see in a 3.x-stable release:
Date: Tue May 13 19:10:30 2008 +0000 Date: Tue Oct 7 07:26:38 2014 -0400
SCSI: libiscsi regression in 2.6.25: fix nop timer handling libata: Un-break ATA blacklist
commit 4cf1043593db6a337f10e006c23c69e5fc93e722 upstream commit 1c40279960bcd7d52dbdf1d466b20d24b99176c8 upstream.
And here's what appears in 2.4 : And here's what might appear in an older kernel once a patch is backported:
Date: Tue May 13 22:12:27 2008 +0200 Date: Tue May 13 22:12:27 2008 +0200
...@@ -446,18 +496,19 @@ And here's what appears in 2.4 : ...@@ -446,18 +496,19 @@ And here's what appears in 2.4 :
[backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a] [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a]
Whatever the format, this information provides a valuable help to people Whatever the format, this information provides a valuable help to people
tracking your trees, and to people trying to trouble-shoot bugs in your tracking your trees, and to people trying to troubleshoot bugs in your
tree. tree.
13) When to use Acked-by: and Cc: 12) When to use Acked-by: and Cc:
---------------------------------
The Signed-off-by: tag indicates that the signer was involved in the The Signed-off-by: tag indicates that the signer was involved in the
development of the patch, or that he/she was in the patch's delivery path. development of the patch, or that he/she was in the patch's delivery path.
If a person was not directly involved in the preparation or handling of a If a person was not directly involved in the preparation or handling of a
patch but wishes to signify and record their approval of it then they can patch but wishes to signify and record their approval of it then they can
arrange to have an Acked-by: line added to the patch's changelog. ask to have an Acked-by: line added to the patch's changelog.
Acked-by: is often used by the maintainer of the affected code when that Acked-by: is often used by the maintainer of the affected code when that
maintainer neither contributed to nor forwarded the patch. maintainer neither contributed to nor forwarded the patch.
...@@ -465,7 +516,8 @@ maintainer neither contributed to nor forwarded the patch. ...@@ -465,7 +516,8 @@ maintainer neither contributed to nor forwarded the patch.
Acked-by: is not as formal as Signed-off-by:. It is a record that the acker Acked-by: is not as formal as Signed-off-by:. It is a record that the acker
has at least reviewed the patch and has indicated acceptance. Hence patch has at least reviewed the patch and has indicated acceptance. Hence patch
mergers will sometimes manually convert an acker's "yep, looks good to me" mergers will sometimes manually convert an acker's "yep, looks good to me"
into an Acked-by:. into an Acked-by: (but note that it is usually better to ask for an
explicit ack).
Acked-by: does not necessarily indicate acknowledgement of the entire patch. Acked-by: does not necessarily indicate acknowledgement of the entire patch.
For example, if a patch affects multiple subsystems and has an Acked-by: from For example, if a patch affects multiple subsystems and has an Acked-by: from
...@@ -477,11 +529,13 @@ list archives. ...@@ -477,11 +529,13 @@ list archives.
If a person has had the opportunity to comment on a patch, but has not If a person has had the opportunity to comment on a patch, but has not
provided such comments, you may optionally add a "Cc:" tag to the patch. provided such comments, you may optionally add a "Cc:" tag to the patch.
This is the only tag which might be added without an explicit action by the This is the only tag which might be added without an explicit action by the
person it names. This tag documents that potentially interested parties person it names - but it should indicate that this person was copied on the
have been included in the discussion patch. This tag documents that potentially interested parties
have been included in the discussion.
14) Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes: 13) Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes:
--------------------------------------------------------------------------
The Reported-by tag gives credit to people who find bugs and report them and it The Reported-by tag gives credit to people who find bugs and report them and it
hopefully inspires them to help us again in the future. Please note that if hopefully inspires them to help us again in the future. Please note that if
...@@ -541,7 +595,13 @@ which stable kernel versions should receive your fix. This is the preferred ...@@ -541,7 +595,13 @@ which stable kernel versions should receive your fix. This is the preferred
method for indicating a bug fixed by the patch. See #2 above for more details. method for indicating a bug fixed by the patch. See #2 above for more details.
15) The canonical patch format 14) The canonical patch format
------------------------------
This section describes how the patch itself should be formatted. Note
that, if you have your patches stored in a git repository, proper patch
formatting can be had with "git format-patch". The tools cannot create
the necessary text, though, so read the instructions below anyway.
The canonical patch subject line is: The canonical patch subject line is:
...@@ -549,7 +609,8 @@ The canonical patch subject line is: ...@@ -549,7 +609,8 @@ The canonical patch subject line is:
The canonical patch message body contains the following: The canonical patch message body contains the following:
- A "from" line specifying the patch author. - A "from" line specifying the patch author (only needed if the person
sending the patch is not the author).
- An empty line. - An empty line.
...@@ -656,128 +717,63 @@ See more details on the proper patch format in the following ...@@ -656,128 +717,63 @@ See more details on the proper patch format in the following
references. references.
16) Sending "git pull" requests (from Linus emails) 15) Sending "git pull" requests
-------------------------------
Please write the git repo address and branch name alone on the same line If you have a series of patches, it may be most convenient to have the
so that I can't even by mistake pull from the wrong branch, and so maintainer pull them directly into the subsystem repository with a
that a triple-click just selects the whole thing. "git pull" operation. Note, however, that pulling patches from a developer
requires a higher degree of trust than taking patches from a mailing list.
As a result, many subsystem maintainers are reluctant to take pull
requests, especially from new, unknown developers. If in doubt you can use
the pull request as the cover letter for a normal posting of the patch
series, giving the maintainer the option of using either.
So the proper format is something along the lines of: A pull request should have [GIT] or [PULL] in the subject line. The
request itself should include the repository name and the branch of
interest on a single line; it should look something like:
"Please pull from Please pull from
git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus
to get these changes:" to get these changes:"
so that I don't have to hunt-and-peck for the address and inevitably A pull request should also include an overall message saying what will be
get it wrong (actually, I've only gotten it wrong a few times, and included in the request, a "git shortlog" listing of the patches
checking against the diffstat tells me when I get it wrong, but I'm themselves, and a diffstat showing the overall effect of the patch series.
just a lot more comfortable when I don't have to "look for" the right The easiest way to get all this information together is, of course, to let
thing to pull, and double-check that I have the right branch-name). git do it for you with the "git request-pull" command.
Please use "git diff -M --stat --summary" to generate the diffstat:
the -M enables rename detection, and the summary enables a summary of
new/deleted or renamed files.
With rename detection, the statistics are rather different [...]
because git will notice that a fair number of the changes are renames.
-----------------------------------
SECTION 2 - HINTS, TIPS, AND TRICKS
-----------------------------------
This section lists many of the common "rules" associated with code
submitted to the kernel. There are always exceptions... but you must
have a really good reason for doing so. You could probably call this
section Linus Computer Science 101.
1) Read Documentation/CodingStyle
Nuff said. If your code deviates too much from this, it is likely
to be rejected without further review, and without comment.
One significant exception is when moving code from one file to
another -- in this case you should not modify the moved code at all in
the same patch which moves it. This clearly delineates the act of
moving the code and your changes. This greatly aids review of the
actual differences and allows tools to better track the history of
the code itself.
Check your patches with the patch style checker prior to submission
(scripts/checkpatch.pl). The style checker should be viewed as
a guide not as the final word. If your code looks better with
a violation then its probably best left alone.
The checker reports at three levels:
- ERROR: things that are very likely to be wrong
- WARNING: things requiring careful review
- CHECK: things requiring thought
You should be able to justify all violations that remain in your
patch.
2) #ifdefs are ugly
Code cluttered with ifdefs is difficult to read and maintain. Don't do
it. Instead, put your ifdefs in a header, and conditionally define
'static inline' functions, or macros, which are used in the code.
Let the compiler optimize away the "no-op" case.
Simple example, of poor code:
dev = alloc_etherdev (sizeof(struct funky_private));
if (!dev)
return -ENODEV;
#ifdef CONFIG_NET_FUNKINESS
init_funky_net(dev);
#endif
Cleaned-up example:
(in header)
#ifndef CONFIG_NET_FUNKINESS
static inline void init_funky_net (struct net_device *d) {}
#endif
(in the code itself)
dev = alloc_etherdev (sizeof(struct funky_private));
if (!dev)
return -ENODEV;
init_funky_net(dev);
3) 'static inline' is better than a macro
Static inline functions are greatly preferred over macros.
They provide type safety, have no length limitations, no formatting
limitations, and under gcc they are as cheap as macros.
Macros should only be used for cases where a static inline is clearly
suboptimal [there are a few, isolated cases of this in fast paths],
or where it is impossible to use a static inline function [such as
string-izing].
'static inline' is preferred over 'static __inline__', 'extern inline', Some maintainers (including Linus) want to see pull requests from signed
and 'extern __inline__'. commits; that increases their confidence that the request actually came
from you. Linus, in particular, will not pull from public hosting sites
like GitHub in the absence of a signed tag.
The first step toward creating such tags is to make a GNUPG key and get it
signed by one or more core kernel developers. This step can be hard for
new developers, but there is no way around it. Attending conferences can
be a good way to find developers who can sign your key.
Once you have prepared a patch series in git that you wish to have somebody
pull, create a signed tag with "git tag -s". This will create a new tag
identifying the last commit in the series and containing a signature
created with your private key. You will also have the opportunity to add a
changelog-style message to the tag; this is an ideal place to describe the
effects of the pull request as a whole.
4) Don't over-design. If the tree the maintainer will be pulling from is not the repository you
are working from, don't forget to push the signed tag explicitly to the
public tree.
Don't try to anticipate nebulous future cases which may or may not When generating your pull request, use the signed tag as the target. A
be useful: "Make it as simple as you can, and no simpler." command like this will do the trick:
git request-pull master git://my.public.tree/linux.git my-signed-tag
---------------------- ----------------------
SECTION 3 - REFERENCES SECTION 2 - REFERENCES
---------------------- ----------------------
Andrew Morton, "The perfect patch" (tpp). Andrew Morton, "The perfect patch" (tpp).
......
...@@ -2,11 +2,15 @@ ...@@ -2,11 +2,15 @@
- this file - this file
Booting Booting
- requirements for booting - requirements for booting
CCN.txt
- Cache Coherent Network ring-bus and perf PMU driver.
Interrupts Interrupts
- ARM Interrupt subsystem documentation - ARM Interrupt subsystem documentation
IXP4xx IXP4xx
- Intel IXP4xx Network processor. - Intel IXP4xx Network processor.
msm Makefile
- Build sourcefiles as part of the Documentation-build for arm
msm/
- MSM specific documentation - MSM specific documentation
Netwinder Netwinder
- Netwinder specific documentation - Netwinder specific documentation
...@@ -18,11 +22,9 @@ README ...@@ -18,11 +22,9 @@ README
- General ARM documentation - General ARM documentation
SA1100/ SA1100/
- SA1100 documentation - SA1100 documentation
Samsung-S3C24XX Samsung-S3C24XX/
- S3C24XX ARM Linux Overview - S3C24XX ARM Linux Overview
Sharp-LH SPEAr/
- Linux on Sharp LH79524 and LH7A40X System On a Chip (SOC)
SPEAr
- ST SPEAr platform Linux Overview - ST SPEAr platform Linux Overview
VFP/ VFP/
- Release notes for Linux Kernel Vector Floating Point support code - Release notes for Linux Kernel Vector Floating Point support code
......
ifneq ($(CONFIG_BLACKFIN),) ifneq ($(CONFIG_BLACKFIN),)
ifneq ($(CONFIG_BFIN_GPTIMERS,)
obj-m := gptimers-example.o obj-m := gptimers-example.o
endif endif
endif
...@@ -8,7 +8,7 @@ Properties: ...@@ -8,7 +8,7 @@ Properties:
"qcom,kpss-timer" - krait subsystem "qcom,kpss-timer" - krait subsystem
"qcom,scss-timer" - scorpion subsystem "qcom,scss-timer" - scorpion subsystem
- interrupts : Interrupts for the the debug timer, the first general purpose - interrupts : Interrupts for the debug timer, the first general purpose
timer, and optionally a second general purpose timer in that timer, and optionally a second general purpose timer in that
order. order.
......
...@@ -9,7 +9,7 @@ Properties: ...@@ -9,7 +9,7 @@ Properties:
Compatibility with many Cavium evaluation boards. Compatibility with many Cavium evaluation boards.
- reg: The base address of the the CF chip select banks. Depending on - reg: The base address of the CF chip select banks. Depending on
the device configuration, there may be one or two banks. the device configuration, there may be one or two banks.
- cavium,bus-width: The width of the connection to the CF devices. Valid - cavium,bus-width: The width of the connection to the CF devices. Valid
......
...@@ -12,7 +12,7 @@ configuration register for writes. These configuration register may be used to ...@@ -12,7 +12,7 @@ configuration register for writes. These configuration register may be used to
enable (and disable in some cases) SoC pin drivers, select peripheral clock enable (and disable in some cases) SoC pin drivers, select peripheral clock
sources (internal or pin), etc. In some cases, a configuration register is sources (internal or pin), etc. In some cases, a configuration register is
write once or the individual bits are write once. In addition to device config, write once or the individual bits are write once. In addition to device config,
the DSCR block may provide registers which which are used to reset peripherals, the DSCR block may provide registers which are used to reset peripherals,
provide device ID information, provide ethernet MAC addresses, as well as other provide device ID information, provide ethernet MAC addresses, as well as other
miscellaneous functions. miscellaneous functions.
......
* Renesas R-Car DMA Controller Device Tree bindings * Renesas R-Car DMA Controller Device Tree bindings
Renesas R-Car Generation 2 SoCs have have multiple multi-channel DMA Renesas R-Car Generation 2 SoCs have multiple multi-channel DMA
controller instances named DMAC capable of serving multiple clients. Channels controller instances named DMAC capable of serving multiple clients. Channels
can be dedicated to specific clients or shared between a large number of can be dedicated to specific clients or shared between a large number of
clients. clients.
......
...@@ -39,7 +39,7 @@ Optional Properties: ...@@ -39,7 +39,7 @@ Optional Properties:
- lines-initial-states: Bitmask that specifies the initial state of each - lines-initial-states: Bitmask that specifies the initial state of each
line. When a bit is set to zero, the corresponding line will be initialized to line. When a bit is set to zero, the corresponding line will be initialized to
the input (pulled-up) state. When the bit is set to one, the line will be the input (pulled-up) state. When the bit is set to one, the line will be
initialized the the low-level output state. If the property is not specified initialized the low-level output state. If the property is not specified
all lines will be initialized to the input state. all lines will be initialized to the input state.
The I/O expander can detect input state changes, and thus optionally act as The I/O expander can detect input state changes, and thus optionally act as
......
...@@ -59,7 +59,7 @@ Optional properties: ...@@ -59,7 +59,7 @@ Optional properties:
Each child node represents one channel and has the following Each child node represents one channel and has the following
properties: properties:
Required properties: Required properties:
* reg: Pair of pins the the channel is connected to. * reg: Pair of pins the channel is connected to.
0: VP/VN 0: VP/VN
1: VAUXP[0]/VAUXN[0] 1: VAUXP[0]/VAUXN[0]
2: VAUXP[1]/VAUXN[1] 2: VAUXP[1]/VAUXN[1]
......
...@@ -9,7 +9,7 @@ Required properties: ...@@ -9,7 +9,7 @@ Required properties:
Optional properties: Optional properties:
- bank-width : Width (in bytes) of the device. If not present, the width - bank-width : Width (in bytes) of the device. If not present, the width
defaults to 1 byte defaults to 1 byte
- nand-skip-bbtscan: Indicates the the BBT scanning should be skipped - nand-skip-bbtscan: Indicates the BBT scanning should be skipped
- timings: array of 6 bytes for NAND timings. The meanings of these bytes - timings: array of 6 bytes for NAND timings. The meanings of these bytes
are: are:
byte 0 TCLR : CLE to RE delay in number of AHB clock cycles, only 4 bits byte 0 TCLR : CLE to RE delay in number of AHB clock cycles, only 4 bits
......
...@@ -3,7 +3,7 @@ ...@@ -3,7 +3,7 @@
Required properties: Required properties:
- compatible: should be one of "brcm,systemport-v1.00" or "brcm,systemport" - compatible: should be one of "brcm,systemport-v1.00" or "brcm,systemport"
- reg: address and length of the register set for the device. - reg: address and length of the register set for the device.
- interrupts: interrupts for the device, first cell must be for the the rx - interrupts: interrupts for the device, first cell must be for the rx
interrupts, and the second cell should be for the transmit queues. An interrupts, and the second cell should be for the transmit queues. An
optional third interrupt cell for Wake-on-LAN can be specified optional third interrupt cell for Wake-on-LAN can be specified
- local-mac-address: Ethernet MAC address (48 bits) of this adapter - local-mac-address: Ethernet MAC address (48 bits) of this adapter
......
...@@ -37,7 +37,7 @@ Required properties: ...@@ -37,7 +37,7 @@ Required properties:
You specify supplies using the standard regulator bindings by including You specify supplies using the standard regulator bindings by including
a phandle the the relevant regulator. All specified supplies must be able a phandle the relevant regulator. All specified supplies must be able
to report their voltage. The IO Voltage Domain for any non-specified to report their voltage. The IO Voltage Domain for any non-specified
supplies will be not be touched. supplies will be not be touched.
......
...@@ -10,7 +10,7 @@ How overlays work ...@@ -10,7 +10,7 @@ How overlays work
----------------- -----------------
A Device Tree's overlay purpose is to modify the kernel's live tree, and A Device Tree's overlay purpose is to modify the kernel's live tree, and
have the modification affecting the state of the the kernel in a way that have the modification affecting the state of the kernel in a way that
is reflecting the changes. is reflecting the changes.
Since the kernel mainly deals with devices, any new device node that result Since the kernel mainly deals with devices, any new device node that result
in an active device should have it created while if the device node is either in an active device should have it created while if the device node is either
...@@ -80,7 +80,7 @@ result in foo+bar.dts ...@@ -80,7 +80,7 @@ result in foo+bar.dts
}; };
---- foo+bar.dts ------------------------------------------------------------- ---- foo+bar.dts -------------------------------------------------------------
As a result of the the overlay, a new device node (bar) has been created As a result of the overlay, a new device node (bar) has been created
so a bar platform device will be registered and if a matching device driver so a bar platform device will be registered and if a matching device driver
is loaded the device will be created as expected. is loaded the device will be created as expected.
......
00-INDEX
- this file.
client.txt
-the DMA Engine API Guide.
dmatest.txt
- how to compile, configure and use the dmatest system.
provider.txt
- the DMA controller API.
\ No newline at end of file
...@@ -45,7 +45,7 @@ them are inherently bus-specific. Drivers typically declare an array ...@@ -45,7 +45,7 @@ them are inherently bus-specific. Drivers typically declare an array
of device IDs of devices they support that reside in a bus-specific of device IDs of devices they support that reside in a bus-specific
driver structure. driver structure.
The purpose of the match callback is provide the bus an opportunity to The purpose of the match callback is to give the bus an opportunity to
determine if a particular driver supports a particular device by determine if a particular driver supports a particular device by
comparing the device IDs the driver supports with the device ID of a comparing the device IDs the driver supports with the device ID of a
particular device, without sacrificing bus-specific functionality or particular device, without sacrificing bus-specific functionality or
......
...@@ -194,16 +194,16 @@ which is in the string esc will be represented in octal form in the output. ...@@ -194,16 +194,16 @@ which is in the string esc will be represented in octal form in the output.
There are also a pair of functions for printing filenames: There are also a pair of functions for printing filenames:
int seq_path(struct seq_file *m, struct path *path, char *esc); int seq_path(struct seq_file *m, const struct path *path,
int seq_path_root(struct seq_file *m, struct path *path, const char *esc);
struct path *root, char *esc) int seq_path_root(struct seq_file *m, const struct path *path,
const struct path *root, const char *esc)
Here, path indicates the file of interest, and esc is a set of characters Here, path indicates the file of interest, and esc is a set of characters
which should be escaped in the output. A call to seq_path() will output which should be escaped in the output. A call to seq_path() will output
the path relative to the current process's filesystem root. If a different the path relative to the current process's filesystem root. If a different
root is desired, it can be used with seq_path_root(). Note that, if it root is desired, it can be used with seq_path_root(). If it turns out that
turns out that path cannot be reached from root, the value of root will be path cannot be reached from root, seq_path_root() returns SEQ_SKIP.
changed in seq_file_root() to a root which *does* work.
A function producing complicated output may want to check A function producing complicated output may want to check
bool seq_has_overflowed(struct seq_file *m); bool seq_has_overflowed(struct seq_file *m);
......
...@@ -31,7 +31,7 @@ through gpiod_get(). For example: ...@@ -31,7 +31,7 @@ through gpiod_get(). For example:
<&gpio 16 GPIO_ACTIVE_HIGH>, /* green */ <&gpio 16 GPIO_ACTIVE_HIGH>, /* green */
<&gpio 17 GPIO_ACTIVE_HIGH>; /* blue */ <&gpio 17 GPIO_ACTIVE_HIGH>; /* blue */
power-gpio = <&gpio 1 GPIO_ACTIVE_LOW>; power-gpios = <&gpio 1 GPIO_ACTIVE_LOW>;
}; };
This property will make GPIOs 15, 16 and 17 available to the driver under the This property will make GPIOs 15, 16 and 17 available to the driver under the
......
...@@ -702,7 +702,8 @@ a virtual address that is no longer valid (module init sections, module ...@@ -702,7 +702,8 @@ a virtual address that is no longer valid (module init sections, module
virtual addresses that correspond to modules that've been unloaded), virtual addresses that correspond to modules that've been unloaded),
such probes are marked with [GONE]. If the probe is temporarily disabled, such probes are marked with [GONE]. If the probe is temporarily disabled,
such probes are marked with [DISABLED]. If the probe is optimized, it is such probes are marked with [DISABLED]. If the probe is optimized, it is
marked with [OPTIMIZED]. marked with [OPTIMIZED]. If the probe is ftrace-based, it is marked with
[FTRACE].
/sys/kernel/debug/kprobes/enabled: Turn kprobes ON/OFF forcibly. /sys/kernel/debug/kprobes/enabled: Turn kprobes ON/OFF forcibly.
......
00-INDEX
- this file.
lockdep-design.txt
- documentation on the runtime locking correctness validator.
lockstat.txt
- info on collecting statistics on locks (and contention).
mutex-design.txt
- info on the generic mutex subsystem.
rt-mutex-design.txt
- description of the RealTime mutex implementation design.
rt-mutex.txt
- desc. of RT-mutex subsystem with PI (Priority Inheritance) support.
spinlocks.txt
- info on using spinlocks to provide exclusive access in kernel.
ww-mutex-design.txt
- Intro to Mutex wait/would deadlock handling.s
...@@ -121,6 +121,11 @@ show the header with column descriptions. Lines 05-18 and 20-31 show the actual ...@@ -121,6 +121,11 @@ show the header with column descriptions. Lines 05-18 and 20-31 show the actual
statistics. These statistics come in two parts; the actual stats separated by a statistics. These statistics come in two parts; the actual stats separated by a
short separator (line 08, 13) from the contention points. short separator (line 08, 13) from the contention points.
Lines 09-12 show the first 4 recorded contention points (the code
which tries to get the lock) and lines 14-17 show the first 4 recorded
contended points (the lock holder). It is possible that the max
con-bounces point is missing in the statistics.
The first lock (05-18) is a read/write lock, and shows two lines above the The first lock (05-18) is a read/write lock, and shows two lines above the
short separator. The contention points don't match the column descriptors, short separator. The contention points don't match the column descriptors,
they have two: contentions and [<IP>] symbol. The second set of contention they have two: contentions and [<IP>] symbol. The second set of contention
......
Intel(R) Management Engine (ME) Client bus API Intel(R) Management Engine (ME) Client bus API
=============================================== ==============================================
Rationale Rationale
========= =========
MEI misc character device is useful for dedicated applications to send and receive MEI misc character device is useful for dedicated applications to send and receive
data to the many FW appliance found in Intel's ME from the user space. data to the many FW appliance found in Intel's ME from the user space.
However for some of the ME functionalities it make sense to leverage existing software However for some of the ME functionalities it make sense to leverage existing software
...@@ -17,7 +18,8 @@ the existing code. ...@@ -17,7 +18,8 @@ the existing code.
MEI CL bus API MEI CL bus API
=========== ==============
A driver implementation for an MEI Client is very similar to existing bus A driver implementation for an MEI Client is very similar to existing bus
based device drivers. The driver registers itself as an MEI CL bus driver through based device drivers. The driver registers itself as an MEI CL bus driver through
the mei_cl_driver structure: the mei_cl_driver structure:
...@@ -55,6 +57,7 @@ received buffers. ...@@ -55,6 +57,7 @@ received buffers.
Example Example
======= =======
As a theoretical example let's pretend the ME comes with a "contact" NFC IP. As a theoretical example let's pretend the ME comes with a "contact" NFC IP.
The driver init and exit routines for this device would look like: The driver init and exit routines for this device would look like:
...@@ -109,7 +112,7 @@ int contact_probe(struct mei_cl_device *dev, struct mei_cl_device_id *id) ...@@ -109,7 +112,7 @@ int contact_probe(struct mei_cl_device *dev, struct mei_cl_device_id *id)
mei_cl_register_event_cb(dev, contact_event_cb, contact); mei_cl_register_event_cb(dev, contact_event_cb, contact);
return 0; return 0;
} }
In the probe routine the driver first enable the MEI device and then registers In the probe routine the driver first enable the MEI device and then registers
an ME bus event handler which is as close as it can get to registering a an ME bus event handler which is as close as it can get to registering a
......
Intel(R) Management Engine Interface (Intel(R) MEI) Intel(R) Management Engine Interface (Intel(R) MEI)
======================= ===================================================
Introduction Introduction
======================= ============
The Intel Management Engine (Intel ME) is an isolated and protected computing The Intel Management Engine (Intel ME) is an isolated and protected computing
resource (Co-processor) residing inside certain Intel chipsets. The Intel ME resource (Co-processor) residing inside certain Intel chipsets. The Intel ME
...@@ -19,7 +19,7 @@ each client has its own protocol. The protocol is message-based with a ...@@ -19,7 +19,7 @@ each client has its own protocol. The protocol is message-based with a
header and payload up to 512 bytes. header and payload up to 512 bytes.
Prominent usage of the Intel ME Interface is to communicate with Intel(R) Prominent usage of the Intel ME Interface is to communicate with Intel(R)
Active Management Technology (Intel AMT)implemented in firmware running on Active Management Technology (Intel AMT) implemented in firmware running on
the Intel ME. the Intel ME.
Intel AMT provides the ability to manage a host remotely out-of-band (OOB) Intel AMT provides the ability to manage a host remotely out-of-band (OOB)
...@@ -44,8 +44,9 @@ HTTP/S that are received from a remote management console application. ...@@ -44,8 +44,9 @@ HTTP/S that are received from a remote management console application.
For more information about Intel AMT: For more information about Intel AMT:
http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide
Intel MEI Driver Intel MEI Driver
======================= ================
The driver exposes a misc device called /dev/mei. The driver exposes a misc device called /dev/mei.
...@@ -91,8 +92,10 @@ A code snippet for an application communicating with Intel AMTHI client: ...@@ -91,8 +92,10 @@ A code snippet for an application communicating with Intel AMTHI client:
[...] [...]
close(fd); close(fd);
IOCTL:
====== IOCTL
=====
The Intel MEI Driver supports the following IOCTL command: The Intel MEI Driver supports the following IOCTL command:
IOCTL_MEI_CONNECT_CLIENT Connect to firmware Feature (client). IOCTL_MEI_CONNECT_CLIENT Connect to firmware Feature (client).
...@@ -122,10 +125,11 @@ The Intel MEI Driver supports the following IOCTL command: ...@@ -122,10 +125,11 @@ The Intel MEI Driver supports the following IOCTL command:
data that can be sent or received. (e.g. if MTU=2K, can send data that can be sent or received. (e.g. if MTU=2K, can send
requests up to bytes 2k and received responses up to 2k bytes). requests up to bytes 2k and received responses up to 2k bytes).
Intel ME Applications:
==============
1) Intel Local Management Service (Intel LMS) Intel ME Applications
=====================
1) Intel Local Management Service (Intel LMS)
Applications running locally on the platform communicate with Intel AMT Release Applications running locally on the platform communicate with Intel AMT Release
2.0 and later releases in the same way that network applications do via SOAP 2.0 and later releases in the same way that network applications do via SOAP
...@@ -146,17 +150,18 @@ Intel ME Applications: ...@@ -146,17 +150,18 @@ Intel ME Applications:
The Intel LMS opens a connection using the Intel MEI driver to the Intel LMS The Intel LMS opens a connection using the Intel MEI driver to the Intel LMS
firmware feature using a defined UUID and then communicates with the feature firmware feature using a defined UUID and then communicates with the feature
using a protocol called Intel AMT Port Forwarding Protocol(Intel APF protocol). using a protocol called Intel AMT Port Forwarding Protocol (Intel APF protocol).
The protocol is used to maintain multiple sessions with Intel AMT from a The protocol is used to maintain multiple sessions with Intel AMT from a
single application. single application.
See the protocol specification in the Intel AMT Software Development Kit(SDK) See the protocol specification in the Intel AMT Software Development Kit (SDK)
http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide
Under "SDK Resources" => "Intel(R) vPro(TM) Gateway(MPS)" Under "SDK Resources" => "Intel(R) vPro(TM) Gateway (MPS)"
=> "Information for Intel(R) vPro(TM) Gateway Developers" => "Information for Intel(R) vPro(TM) Gateway Developers"
=> "Description of the Intel AMT Port Forwarding (APF)Protocol" => "Description of the Intel AMT Port Forwarding (APF) Protocol"
2) Intel AMT Remote configuration using a Local Agent 2) Intel AMT Remote configuration using a Local Agent
A Local Agent enables IT personnel to configure Intel AMT out-of-the-box A Local Agent enables IT personnel to configure Intel AMT out-of-the-box
without requiring installing additional data to enable setup. The remote without requiring installing additional data to enable setup. The remote
configuration process may involve an ISV-developed remote configuration configuration process may involve an ISV-developed remote configuration
...@@ -172,8 +177,9 @@ Intel ME Applications: ...@@ -172,8 +177,9 @@ Intel ME Applications:
http://software.intel.com/en-us/articles/download-the-latest-intel-amt-open-source-drivers/ http://software.intel.com/en-us/articles/download-the-latest-intel-amt-open-source-drivers/
Intel AMT OS Health Watchdog: Intel AMT OS Health Watchdog
============================= ============================
The Intel AMT Watchdog is an OS Health (Hang/Crash) watchdog. The Intel AMT Watchdog is an OS Health (Hang/Crash) watchdog.
Whenever the OS hangs or crashes, Intel AMT will send an event Whenever the OS hangs or crashes, Intel AMT will send an event
to any subscriber to this event. This mechanism means that to any subscriber to this event. This mechanism means that
...@@ -192,8 +198,10 @@ watchdog is 120 seconds. ...@@ -192,8 +198,10 @@ watchdog is 120 seconds.
If the Intel AMT Watchdog feature does not exist (i.e. the connection failed), If the Intel AMT Watchdog feature does not exist (i.e. the connection failed),
the Intel MEI driver will disable the sending of heartbeats. the Intel MEI driver will disable the sending of heartbeats.
Supported Chipsets:
Supported Chipsets
================== ==================
7 Series Chipset Family 7 Series Chipset Family
6 Series Chipset Family 6 Series Chipset Family
5 Series Chipset Family 5 Series Chipset Family
......
00-INDEX 00-INDEX
- this file - this file
3c505.txt
- information on the 3Com EtherLink Plus (3c505) driver.
3c509.txt 3c509.txt
- information on the 3Com Etherlink III Series Ethernet cards. - information on the 3Com Etherlink III Series Ethernet cards.
6pack.txt 6pack.txt
...@@ -24,6 +22,8 @@ README.sb1000 ...@@ -24,6 +22,8 @@ README.sb1000
- info on General Instrument/NextLevel SURFboard1000 cable modem. - info on General Instrument/NextLevel SURFboard1000 cable modem.
alias.txt alias.txt
- info on using alias network devices. - info on using alias network devices.
altera_tse.txt
- Altera Triple-Speed Ethernet controller.
arcnet-hardware.txt arcnet-hardware.txt
- tons of info on ARCnet, hubs, jumper settings for ARCnet cards, etc. - tons of info on ARCnet, hubs, jumper settings for ARCnet cards, etc.
arcnet.txt arcnet.txt
...@@ -42,6 +42,8 @@ bridge.txt ...@@ -42,6 +42,8 @@ bridge.txt
- where to get user space programs for ethernet bridging with Linux. - where to get user space programs for ethernet bridging with Linux.
can.txt can.txt
- documentation on CAN protocol family. - documentation on CAN protocol family.
cdc_mbim.txt
- 3G/LTE USB modem (Mobile Broadband Interface Model)
cops.txt cops.txt
- info on the COPS LocalTalk Linux driver - info on the COPS LocalTalk Linux driver
cs89x0.txt cs89x0.txt
...@@ -54,6 +56,8 @@ cxgb.txt ...@@ -54,6 +56,8 @@ cxgb.txt
- Release Notes for the Chelsio N210 Linux device driver. - Release Notes for the Chelsio N210 Linux device driver.
dccp.txt dccp.txt
- the Datagram Congestion Control Protocol (DCCP) (RFC 4340..42). - the Datagram Congestion Control Protocol (DCCP) (RFC 4340..42).
dctcp.txt
- DataCenter TCP congestion control
de4x5.txt de4x5.txt
- the Digital EtherWORKS DE4?? and DE5?? PCI Ethernet driver - the Digital EtherWORKS DE4?? and DE5?? PCI Ethernet driver
decnet.txt decnet.txt
......
...@@ -234,7 +234,7 @@ solution for a couple of reasons: ...@@ -234,7 +234,7 @@ solution for a couple of reasons:
mechanisms. Inside this filter definition the (interested) type of mechanisms. Inside this filter definition the (interested) type of
errors may be selected. The reception of error messages is disabled errors may be selected. The reception of error messages is disabled
by default. The format of the CAN error message frame is briefly by default. The format of the CAN error message frame is briefly
described in the Linux header file "include/linux/can/error.h". described in the Linux header file "include/uapi/linux/can/error.h".
4. How to use SocketCAN 4. How to use SocketCAN
------------------------ ------------------------
......
completions - wait for completion handling
==========================================
This document was originally written based on 3.18.0 (linux-next)
Introduction:
-------------
If you have one or more threads of execution that must wait for some process
to have reached a point or a specific state, completions can provide a race
free solution to this problem. Semantically they are somewhat like a
pthread_barriers and have similar use-cases.
Completions are a code synchronization mechanism that is preferable to any
misuse of locks. Any time you think of using yield() or some quirky
msleep(1); loop to allow something else to proceed, you probably want to
look into using one of the wait_for_completion*() calls instead. The
advantage of using completions is clear intent of the code but also more
efficient code as both threads can continue until the result is actually
needed.
Completions are built on top of the generic event infrastructure in Linux,
with the event reduced to a simple flag appropriately called "done" in
struct completion, that tells the waiting threads of execution if they
can continue safely.
As completions are scheduling related the code is found in
kernel/sched/completion.c - for details on completion design and
implementation see completions-design.txt
Usage:
------
There are three parts to the using completions, the initialization of the
struct completion, the waiting part through a call to one of the variants of
wait_for_completion() and the signaling side through a call to complete(),
or complete_all(). Further there are some helper functions for checking the
state of completions.
To use completions one needs to include <linux/completion.h> and
create a variable of type struct completion. The structure used for
handling of completions is:
struct completion {
unsigned int done;
wait_queue_head_t wait;
};
providing the wait queue to place tasks on for waiting and the flag for
indicating the state of affairs.
Completions should be named to convey the intent of the waiter. A good
example is:
wait_for_completion(&early_console_added);
complete(&early_console_added);
Good naming (as always) helps code readability.
Initializing completions:
-------------------------
Initialization of dynamically allocated completions, often embedded in
other structures, is done with:
void init_completion(&done);
Initialization is accomplished by initializing the wait queue and setting
the default state to "not available", that is, "done" is set to 0.
The re-initialization function, reinit_completion(), simply resets the
done element to "not available", thus again to 0, without touching the
wait queue. Calling init_completion() on the same completions object is
most likely a bug as it re-initializes the queue to an empty queue and
enqueued tasks could get "lost" - use reinit_completion() in that case.
For static declaration and initialization, macros are available. These are:
static DECLARE_COMPLETION(setup_done)
used for static declarations in file scope. Within functions the static
initialization should always use:
DECLARE_COMPLETION_ONSTACK(setup_done)
suitable for automatic/local variables on the stack and will make lockdep
happy. Note also that one needs to making *sure* the completion passt to
work threads remains in-scope, and no references remain to on-stack data
when the initiating function returns.
Waiting for completions:
------------------------
For a thread of execution to wait for some concurrent work to finish, it
calls wait_for_completion() on the initialized completion structure.
A typical usage scenario is:
structure completion setup_done;
init_completion(&setup_done);
initialze_work(...,&setup_done,...)
/* run non-dependent code */ /* do setup */
wait_for_completion(&seupt_done); complete(setup_done)
This is not implying any temporal order of wait_for_completion() and the
call to complete() - if the call to complete() happened before the call
to wait_for_completion() then the waiting side simply will continue
immediately as all dependencies are satisfied.
Note that wait_for_completion() is calling spin_lock_irq/spin_unlock_irq
so it can only be called safely when you know that interrupts are enabled.
Calling it from hard-irq context will result in hard to detect spurious
enabling of interrupts.
wait_for_completion():
void wait_for_completion(struct completion *done):
The default behavior is to wait without a timeout and mark the task as
uninterruptible. wait_for_completion() and its variants are only safe
in soft-interrupt or process context but not in hard-irq context.
As all variants of wait_for_completion() can (obviously) block for a long
time, you probably don't want to call this with held locks - see also
try_wait_for_completion() below.
Variants available:
-------------------
The below variants all return status and this status should be checked in
most(/all) cases - in cases where the status is deliberately not checked you
probably want to make a note explaining this (e.g. see
arch/arm/kernel/smp.c:__cpu_up()).
A common problem that occurs is to have unclean assignment of return types,
so care should be taken with assigning return-values to variables of proper
type. Checking for the specific meaning of return values also has been found
to be quite inaccurate e.g. constructs like
if(!wait_for_completion_interruptible_timeout(...)) would execute the same
code path for successful completion and for the interrupted case - which is
probably not what you want.
int wait_for_completion_interruptible(struct completion *done)
marking the task TASK_INTERRUPTIBLE. If a signal was received while waiting.
It will return -ERESTARTSYS and 0 otherwise.
unsigned long wait_for_completion_timeout(struct completion *done,
unsigned long timeout)
The task is marked as TASK_UNINTERRUPTIBLE and will wait at most timeout
(in jiffies). If timeout occurs it return 0 else the remaining time in
jiffies (but at least 1). Timeouts are preferably passed by msecs_to_jiffies()
or usecs_to_jiffies(). If the returned timeout value is deliberately ignored
a comment should probably explain why (e.g. see drivers/mfd/wm8350-core.c
wm8350_read_auxadc())
long wait_for_completion_interruptible_timeout(
struct completion *done, unsigned long timeout)
passing a timeout in jiffies and marking the task as TASK_INTERRUPTIBLE. If a
signal was received it will return -ERESTARTSYS, 0 if completion timed-out and
the remaining time in jiffies if completion occurred.
Further variants include _killable which passes TASK_KILLABLE as the
designated tasks state and will return a -ERESTARTSYS if interrupted or
else 0 if completions was achieved as well as a _timeout variant.
long wait_for_completion_killable(struct completion *done)
long wait_for_completion_killable_timeout(struct completion *done,
unsigned long timeout)
The _io variants wait_for_completion_io behave the same as the non-_io
variants, except for accounting waiting time as waiting on IO, which has
an impact on how scheduling is calculated.
void wait_for_completion_io(struct completion *done)
unsigned long wait_for_completion_io_timeout(struct completion *done
unsigned long timeout)
Signaling completions:
----------------------
A thread of execution that wants to signal that the conditions for
continuation have been achieved calls complete() to signal exactly one
of the waiters that it can continue.
void complete(struct completion *done)
or calls complete_all to signal all current and future waiters.
void complete_all(struct completion *done)
The signaling will work as expected even if completions are signaled before
a thread starts waiting. This is achieved by the waiter "consuming"
(decrementing) the done element of struct completion. Waiting threads
wakeup order is the same in which they were enqueued (FIFO order).
If complete() is called multiple times then this will allow for that number
of waiters to continue - each call to complete() will simply increment the
done element. Calling complete_all() multiple times is a bug though. Both
complete() and complete_all() can be called in hard-irq context safely.
There only can be one thread calling complete() or complete_all() on a
particular struct completions at any time - serialized through the wait
queue spinlock. Any such concurrent calls to complete() or complete_all()
probably are a design bug.
Signaling completion from hard-irq context is fine as it will appropriately
lock with spin_lock_irqsave/spin_unlock_irqrestore.
try_wait_for_completion()/completion_done():
--------------------------------------------
The try_wait_for_completion will not put the thread on the wait queue but
rather returns false if it would need to enqueue (block) the thread, else it
consumes any posted completions and returns true.
bool try_wait_for_completion(struct completion *done)
Finally to check state of a completions without changing it in any way is
provided by completion_done() returning false if there are any posted
completion that was not yet consumed by waiters implying that there are
waiters and true otherwise;
bool completion_done(struct completion *done)
Both try_wait_for_completion() and completion_done() are safe to be called in
hard-irq context.
...@@ -728,7 +728,7 @@ The default value is 60. ...@@ -728,7 +728,7 @@ The default value is 60.
- user_reserve_kbytes - user_reserve_kbytes
When overcommit_memory is set to 2, "never overommit" mode, reserve When overcommit_memory is set to 2, "never overcommit" mode, reserve
min(3% of current process size, user_reserve_kbytes) of free memory. min(3% of current process size, user_reserve_kbytes) of free memory.
This is intended to prevent a user from starting a single memory hogging This is intended to prevent a user from starting a single memory hogging
process, such that they cannot recover (kill the hog). process, such that they cannot recover (kill the hog).
......
...@@ -1740,7 +1740,7 @@ no pid ...@@ -1740,7 +1740,7 @@ no pid
yum-updatesd-3111 [003] 1637.254683: lock_hrtimer_base <-hrtimer_try_to_cancel yum-updatesd-3111 [003] 1637.254683: lock_hrtimer_base <-hrtimer_try_to_cancel
yum-updatesd-3111 [003] 1637.254685: fget_light <-do_sys_poll yum-updatesd-3111 [003] 1637.254685: fget_light <-do_sys_poll
yum-updatesd-3111 [003] 1637.254686: pipe_poll <-do_sys_poll yum-updatesd-3111 [003] 1637.254686: pipe_poll <-do_sys_poll
# echo -1 > set_ftrace_pid # echo > set_ftrace_pid
# cat trace |head # cat trace |head
# tracer: function # tracer: function
# #
......
...@@ -3226,6 +3226,7 @@ F: Documentation/ ...@@ -3226,6 +3226,7 @@ F: Documentation/
X: Documentation/ABI/ X: Documentation/ABI/
X: Documentation/devicetree/ X: Documentation/devicetree/
X: Documentation/[a-z][a-z]_[A-Z][A-Z]/ X: Documentation/[a-z][a-z]_[A-Z][A-Z]/
T: git git://git.lwn.net/linux-2.6.git docs-next
DOUBLETALK DRIVER DOUBLETALK DRIVER
M: "James R. Van Zandt" <jrv@vanzandt.mv.com> M: "James R. Van Zandt" <jrv@vanzandt.mv.com>
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment