mirror of
https://github.com/Fishwaldo/Star64_linux.git
synced 2025-03-17 20:54:10 +00:00
Documentation changes for 3.20
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. -----BEGIN PGP SIGNATURE----- Version: GnuPG v1 iQIcBAABAgAGBQJU2QvPAAoJEI3ONVYwIuV6UdAP/iFa3yK0jTMFJV49K2PhVPiW 9AxlcDT3mKCmGrCxS2ST84Kyvxi+bn5k6pQbOhXqPTLRzlWj7o+9zG76yCvhI1/0 mSUc/DoEZSlxQCAi4RH6lNFBtyopwOF1Fy2hqP8Wj7fOu2OxJ+DbTFJ7Cjy2Ybnq REFT+28mD3GwBYv1r6mirbXsxBGUWK4avqUl9TPkC1AgVoksZ/aLrDffdmixL6Ul cNBGGn3/mQhDCd6QgrHfdSe3BmL/vpiO5nr7BnSGe/hg65tUgi5d5s9tyP1eRkYo d+3Ityz24ISCW6kAGH9udNzdtw2QA7vxdVIcz01RgxHQcYdcTyE7ZH28+A+aEtxm ANkOO5PvaQJrCdPATOuVvwTPmK+xjdW7TmmPiJZ3QpVuPkFlUDP+amOgOajBDQ2l UDHE2GfrUcjUG4FSUGXLVKXVAXuqLG8DG1rMSEf1utb80jxcuhK2kIrhjfRi4gle gL3PKd7SfhMowm3QbaMxdiy0RpNK+IlJpiFsDFWUJwQCJvCtxlwL/RalfGxitjqs RxJo+uPxFLrmsnM8fdw5a/82R0T/nclvnzniq5PoZROOJ6VzKvwn3oS9d63bliPI JQTfNpbfYq8sRlrPlp+XETrrcbmmYyxgqvurLobNXb74cdJHEzHjqf9OG++NKtQQ Jre067cSnkSrHAHtxNns =r07E -----END PGP SIGNATURE----- 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 ...
This commit is contained in:
commit
73b4f63aeb
35 changed files with 658 additions and 382 deletions
|
@ -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
|
||||||
-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/
|
||||||
- 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
|
||||||
- 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/
|
||||||
- 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/
|
||||||
- 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
|
||||||
- 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
|
||||||
- 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/
|
||||||
- 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
|
||||||
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.
|
||||||
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:
|
||||||
(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)
|
||||||
|
|
||||||
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 @@
|
||||||
<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 @@
|
||||||
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 @@
|
||||||
<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 @@
|
||||||
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 @@
|
||||||
<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 @@
|
||||||
<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 @@
|
||||||
</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 @@
|
||||||
<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 @@
|
||||||
</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 @@
|
||||||
<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 > /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem>
|
<listitem><para><constant>echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem>
|
||||||
</itemizedlist>
|
</itemizedlist>
|
||||||
|
@ -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 > /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem>
|
<listitem><para><constant>echo kbd > /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem>
|
||||||
</itemizedlist>
|
</itemizedlist>
|
||||||
|
@ -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 > /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem>
|
<listitem><para><constant>echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem>
|
||||||
</itemizedlist></para>
|
</itemizedlist></para>
|
||||||
|
@ -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 @@
|
||||||
<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
|
||||||
<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
|
||||||
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>
|
||||||
|
@ -779,21 +776,25 @@ Task Addr Pid Parent [*] cpu State Thread Command
|
||||||
their <asm/kgdb.h> file. These are:
|
their <asm/kgdb.h> file. These are:
|
||||||
<itemizedlist>
|
<itemizedlist>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
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>
|
||||||
<para>
|
</listitem>
|
||||||
BUFMAX: The size in bytes of the buffer GDB will read into.
|
<listitem>
|
||||||
This must be larger than NUMREGBYTES.
|
<para>
|
||||||
</para>
|
BUFMAX: The size in bytes of the buffer GDB will read into.
|
||||||
<para>
|
This must be larger than NUMREGBYTES.
|
||||||
CACHE_FLUSH_IS_SAFE: Set to 1 if it is always safe to call
|
</para>
|
||||||
flush_cache_range or flush_icache_range. On some architectures,
|
</listitem>
|
||||||
these functions may not be safe to call on SMP since we keep other
|
<listitem>
|
||||||
CPUs in a holding pattern.
|
<para>
|
||||||
</para>
|
CACHE_FLUSH_IS_SAFE: Set to 1 if it is always safe to call
|
||||||
</listitem>
|
flush_cache_range or flush_icache_range. On some architectures,
|
||||||
|
these functions may not be safe to call on SMP since we keep other
|
||||||
|
CPUs in a holding pattern.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
</itemizedlist>
|
</itemizedlist>
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
|
@ -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
|
||||||
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.
|
||||||
|
|
||||||
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",
|
||||||
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.
|
||||||
|
|
||||||
|
|
||||||
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.
|
||||||
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:
|
||||||
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
|
||||||
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,
|
||||||
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 the recipients for your patch.
|
||||||
|
----------------------------------------
|
||||||
|
|
||||||
5) Select e-mail destination.
|
You should always copy the appropriate subsystem maintainer(s) on any patch
|
||||||
|
to code that they maintain; look through the MAINTAINERS file and the
|
||||||
|
source code revision history to see who those maintainers are. The
|
||||||
|
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.
|
||||||
|
|
||||||
Look through the MAINTAINERS file and the source code, and determine
|
You should also normally choose at least one mailing list to receive a copy
|
||||||
if your change applies to a specific subsystem of the kernel, with
|
of your patch set. linux-kernel@vger.kernel.org functions as a list of
|
||||||
an assigned maintainer. If so, e-mail that person. The script
|
last resort, but the volume on that list has caused a number of developers
|
||||||
scripts/get_maintainer.pl can be very useful at this step.
|
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
|
||||||
If no maintainer is listed, or the maintainer does not respond, send
|
spam unrelated lists, though.
|
||||||
your patch to the primary Linux kernel developer's mailing list,
|
|
||||||
linux-kernel@vger.kernel.org. Most kernel developers monitor this
|
|
||||||
e-mail list, and can comment on your changes.
|
|
||||||
|
|
||||||
|
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
|
||||||
sending him e-mail.
|
Linus directly, so typically you should do your best to -avoid-
|
||||||
|
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.
|
|
||||||
|
|
||||||
|
Patches that fix a severe bug in a released kernel should be directed
|
||||||
|
toward the stable maintainers by putting a line like this:
|
||||||
|
|
||||||
|
Cc: stable@vger.kernel.org
|
||||||
|
|
||||||
6) Select your CC (e-mail carbon copy) list.
|
into your patch.
|
||||||
|
|
||||||
Unless you have a reason NOT to do so, CC linux-kernel@vger.kernel.org.
|
Note, however, that some subsystem maintainers want to come to their own
|
||||||
|
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.
|
||||||
|
|
||||||
Other kernel developers besides Linus need to be aware of your change,
|
If changes affect userland-kernel interfaces, please send the MAN-PAGES
|
||||||
so that they may comment on it and offer code review and suggestions.
|
maintainer (as listed in the MAINTAINERS file) a man-pages patch, or at
|
||||||
linux-kernel is the primary Linux kernel developer mailing list.
|
least a notification of the change, so that some information makes its way
|
||||||
Other mailing lists are available for specific subsystems, such as
|
into the manual pages. User-space API changes should also be copied to
|
||||||
USB, framebuffer devices, the VFS, the SCSI subsystem, etc. See the
|
linux-api@vger.kernel.org.
|
||||||
MAINTAINERS file for a mailing list that relates specifically to
|
|
||||||
your change.
|
|
||||||
|
|
||||||
Majordomo lists of VGER.KERNEL.ORG at:
|
|
||||||
<http://vger.kernel.org/vger-lists.html>
|
|
||||||
|
|
||||||
If changes affect userland-kernel interfaces, please send
|
|
||||||
the MAN-PAGES maintainer (as listed in the MAINTAINERS file)
|
|
||||||
a man-pages patch, or at least a notification of the change,
|
|
||||||
so that some information makes its way into the manual pages.
|
|
||||||
|
|
||||||
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:
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
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.
|
||||||
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.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
|
||||||
|
9) Don't get discouraged - or impatient.
|
||||||
|
----------------------------------------
|
||||||
|
|
||||||
9) Name your kernel version.
|
After you have submitted your change, be patient and wait. Reviewers are
|
||||||
|
busy people and may not get to your patch right away.
|
||||||
|
|
||||||
It is important to note, either in the subject line or in the patch
|
Once upon a time, patches used to disappear into the void without comment,
|
||||||
description, the kernel version to which this patch applies.
|
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
|
||||||
If the patch does not apply cleanly to the latest kernel version,
|
that you have sent your patches to the right place. Wait for a minimum of
|
||||||
Linus will not apply it.
|
one week before resubmitting or pinging reviewers - possibly longer during
|
||||||
|
busy times like merge windows.
|
||||||
|
|
||||||
|
|
||||||
|
10) Include PATCH in the subject
|
||||||
10) Don't get discouraged. Re-submit.
|
--------------------------------
|
||||||
|
|
||||||
After you have submitted your change, be patient and wait. If Linus
|
|
||||||
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.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
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
|
||||||
|
@ -387,11 +437,11 @@ can certify the below:
|
||||||
person who certified (a), (b) or (c) and I have not modified
|
person who certified (a), (b) or (c) and I have not modified
|
||||||
it.
|
it.
|
||||||
|
|
||||||
(d) I understand and agree that this project and the contribution
|
(d) I understand and agree that this project and the contribution
|
||||||
are public and that a record of the contribution (including all
|
are public and that a record of the contribution (including all
|
||||||
personal information I submit with it, including my sign-off) is
|
personal information I submit with it, including my sign-off) is
|
||||||
maintained indefinitely and may be redistributed consistent with
|
maintained indefinitely and may be redistributed consistent with
|
||||||
this project or the open source license(s) involved.
|
this project or the open source license(s) involved.
|
||||||
|
|
||||||
then you just add a line saying
|
then you just add a line saying
|
||||||
|
|
||||||
|
@ -401,7 +451,7 @@ using your real name (sorry, no pseudonyms or anonymous contributions.)
|
||||||
|
|
||||||
Some people also put extra tags at the end. They'll just be ignored for
|
Some people also put extra tags at the end. They'll just be ignored for
|
||||||
now, but you can do this to mark internal company procedures or just
|
now, but you can do this to mark internal company procedures or just
|
||||||
point out some special detail about the sign-off.
|
point out some special detail about the sign-off.
|
||||||
|
|
||||||
If you are a subsystem or branch maintainer, sometimes you need to slightly
|
If you are a subsystem or branch maintainer, sometimes you need to slightly
|
||||||
modify patches you receive in order to merge them, because the code is not
|
modify patches you receive in order to merge them, because the code is not
|
||||||
|
@ -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 :
|
||||||
[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.
|
||||||
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.
|
||||||
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
|
||||||
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:
|
||||||
|
|
||||||
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
|
||||||
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.
|
||||||
|
|
||||||
|
Some maintainers (including Linus) want to see pull requests from signed
|
||||||
|
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.
|
||||||
|
|
||||||
Please use "git diff -M --stat --summary" to generate the diffstat:
|
The first step toward creating such tags is to make a GNUPG key and get it
|
||||||
the -M enables rename detection, and the summary enables a summary of
|
signed by one or more core kernel developers. This step can be hard for
|
||||||
new/deleted or renamed files.
|
new developers, but there is no way around it. Attending conferences can
|
||||||
|
be a good way to find developers who can sign your key.
|
||||||
|
|
||||||
With rename detection, the statistics are rather different [...]
|
Once you have prepared a patch series in git that you wish to have somebody
|
||||||
because git will notice that a fair number of the changes are renames.
|
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.
|
||||||
|
|
||||||
-----------------------------------
|
If the tree the maintainer will be pulling from is not the repository you
|
||||||
SECTION 2 - HINTS, TIPS, AND TRICKS
|
are working from, don't forget to push the signed tag explicitly to the
|
||||||
-----------------------------------
|
public tree.
|
||||||
|
|
||||||
This section lists many of the common "rules" associated with code
|
When generating your pull request, use the signed tag as the target. A
|
||||||
submitted to the kernel. There are always exceptions... but you must
|
command like this will do the trick:
|
||||||
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',
|
|
||||||
and 'extern __inline__'.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
4) Don't over-design.
|
|
||||||
|
|
||||||
Don't try to anticipate nebulous future cases which may or may not
|
|
||||||
be useful: "Make it as simple as you can, and no simpler."
|
|
||||||
|
|
||||||
|
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 @@
|
||||||
- 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
|
||||||
- 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
|
||||||
|
|
|
@ -1,3 +1,5 @@
|
||||||
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:
|
||||||
"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:
|
||||||
|
|
||||||
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
|
||||||
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.
|
||||||
|
|
||||||
|
|
|
@ -1,6 +1,6 @@
|
||||||
* 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:
|
||||||
- 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:
|
||||||
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:
|
||||||
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 @@
|
||||||
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:
|
||||||
|
|
||||||
|
|
||||||
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
|
||||||
-----------------
|
-----------------
|
||||||
|
|
||||||
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
|
||||||
};
|
};
|
||||||
---- 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.
|
||||||
|
|
||||||
|
|
8
Documentation/dmaengine/00-INDEX
Normal file
8
Documentation/dmaengine/00-INDEX
Normal file
|
@ -0,0 +1,8 @@
|
||||||
|
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.
|
|
@ -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
|
||||||
|
|
|
@ -28,7 +28,7 @@ Table of Contents
|
||||||
1.6 Parallel port info in /proc/parport
|
1.6 Parallel port info in /proc/parport
|
||||||
1.7 TTY info in /proc/tty
|
1.7 TTY info in /proc/tty
|
||||||
1.8 Miscellaneous kernel statistics in /proc/stat
|
1.8 Miscellaneous kernel statistics in /proc/stat
|
||||||
1.9 Ext4 file system parameters
|
1.9 Ext4 file system parameters
|
||||||
|
|
||||||
2 Modifying System Parameters
|
2 Modifying System Parameters
|
||||||
|
|
||||||
|
|
|
@ -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:
|
||||||
<&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
|
||||||
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.
|
||||||
|
|
||||||
|
|
16
Documentation/locking/00-INDEX
Normal file
16
Documentation/locking/00-INDEX
Normal file
|
@ -0,0 +1,16 @@
|
||||||
|
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
|
||||||
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
|
||||||
|
|
|
@ -1,9 +1,10 @@
|
||||||
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.
|
||||||
|
|
||||||
|
|
||||||
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.
|
||||||
|
|
||||||
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:
|
||||||
|
|
||||||
|
@ -69,11 +72,11 @@ static struct mei_cl_device_id contact_mei_cl_tbl[] = {
|
||||||
MODULE_DEVICE_TABLE(mei_cl, contact_mei_cl_tbl);
|
MODULE_DEVICE_TABLE(mei_cl, contact_mei_cl_tbl);
|
||||||
|
|
||||||
static struct mei_cl_driver contact_driver = {
|
static struct mei_cl_driver contact_driver = {
|
||||||
.id_table = contact_mei_tbl,
|
.id_table = contact_mei_tbl,
|
||||||
.name = CONTACT_DRIVER_NAME,
|
.name = CONTACT_DRIVER_NAME,
|
||||||
|
|
||||||
.probe = contact_probe,
|
.probe = contact_probe,
|
||||||
.remove = contact_remove,
|
.remove = contact_remove,
|
||||||
};
|
};
|
||||||
|
|
||||||
static int contact_init(void)
|
static int contact_init(void)
|
||||||
|
@ -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
|
||||||
|
|
|
@ -1,8 +1,8 @@
|
||||||
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
|
||||||
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.
|
||||||
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:
|
||||||
[...]
|
[...]
|
||||||
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,58 +125,61 @@ 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
|
||||||
|
=====================
|
||||||
|
|
||||||
Applications running locally on the platform communicate with Intel AMT Release
|
1) Intel Local Management Service (Intel LMS)
|
||||||
2.0 and later releases in the same way that network applications do via SOAP
|
|
||||||
over HTTP (deprecated starting with Release 6.0) or with WS-Management over
|
|
||||||
SOAP over HTTP. This means that some Intel AMT features can be accessed from a
|
|
||||||
local application using the same network interface as a remote application
|
|
||||||
communicating with Intel AMT over the network.
|
|
||||||
|
|
||||||
When a local application sends a message addressed to the local Intel AMT host
|
Applications running locally on the platform communicate with Intel AMT Release
|
||||||
name, the Intel LMS, which listens for traffic directed to the host name,
|
2.0 and later releases in the same way that network applications do via SOAP
|
||||||
intercepts the message and routes it to the Intel MEI.
|
over HTTP (deprecated starting with Release 6.0) or with WS-Management over
|
||||||
For more information:
|
SOAP over HTTP. This means that some Intel AMT features can be accessed from a
|
||||||
http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide
|
local application using the same network interface as a remote application
|
||||||
Under "About Intel AMT" => "Local Access"
|
communicating with Intel AMT over the network.
|
||||||
|
|
||||||
For downloading Intel LMS:
|
When a local application sends a message addressed to the local Intel AMT host
|
||||||
http://software.intel.com/en-us/articles/download-the-latest-intel-amt-open-source-drivers/
|
name, the Intel LMS, which listens for traffic directed to the host name,
|
||||||
|
intercepts the message and routes it to the Intel MEI.
|
||||||
|
For more information:
|
||||||
|
http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide
|
||||||
|
Under "About Intel AMT" => "Local Access"
|
||||||
|
|
||||||
The Intel LMS opens a connection using the Intel MEI driver to the Intel LMS
|
For downloading Intel LMS:
|
||||||
firmware feature using a defined UUID and then communicates with the feature
|
http://software.intel.com/en-us/articles/download-the-latest-intel-amt-open-source-drivers/
|
||||||
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
|
|
||||||
single application.
|
|
||||||
|
|
||||||
See the protocol specification in the Intel AMT Software Development Kit(SDK)
|
The Intel LMS opens a connection using the Intel MEI driver to the Intel LMS
|
||||||
http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide
|
firmware feature using a defined UUID and then communicates with the feature
|
||||||
Under "SDK Resources" => "Intel(R) vPro(TM) Gateway(MPS)"
|
using a protocol called Intel AMT Port Forwarding Protocol (Intel APF protocol).
|
||||||
=> "Information for Intel(R) vPro(TM) Gateway Developers"
|
The protocol is used to maintain multiple sessions with Intel AMT from a
|
||||||
=> "Description of the Intel AMT Port Forwarding (APF)Protocol"
|
single application.
|
||||||
|
|
||||||
2) Intel AMT Remote configuration using a Local Agent
|
See the protocol specification in the Intel AMT Software Development Kit (SDK)
|
||||||
A Local Agent enables IT personnel to configure Intel AMT out-of-the-box
|
http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide
|
||||||
without requiring installing additional data to enable setup. The remote
|
Under "SDK Resources" => "Intel(R) vPro(TM) Gateway (MPS)"
|
||||||
configuration process may involve an ISV-developed remote configuration
|
=> "Information for Intel(R) vPro(TM) Gateway Developers"
|
||||||
agent that runs on the host.
|
=> "Description of the Intel AMT Port Forwarding (APF) Protocol"
|
||||||
For more information:
|
|
||||||
http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide
|
|
||||||
Under "Setup and Configuration of Intel AMT" =>
|
|
||||||
"SDK Tools Supporting Setup and Configuration" =>
|
|
||||||
"Using the Local Agent Sample"
|
|
||||||
|
|
||||||
An open source Intel AMT configuration utility, implementing a local agent
|
2) Intel AMT Remote configuration using a Local Agent
|
||||||
that accesses the Intel MEI driver, can be found here:
|
|
||||||
http://software.intel.com/en-us/articles/download-the-latest-intel-amt-open-source-drivers/
|
A Local Agent enables IT personnel to configure Intel AMT out-of-the-box
|
||||||
|
without requiring installing additional data to enable setup. The remote
|
||||||
|
configuration process may involve an ISV-developed remote configuration
|
||||||
|
agent that runs on the host.
|
||||||
|
For more information:
|
||||||
|
http://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide
|
||||||
|
Under "Setup and Configuration of Intel AMT" =>
|
||||||
|
"SDK Tools Supporting Setup and Configuration" =>
|
||||||
|
"Using the Local Agent Sample"
|
||||||
|
|
||||||
|
An open source Intel AMT configuration utility, implementing a local agent
|
||||||
|
that accesses the Intel MEI driver, can be found here:
|
||||||
|
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.
|
||||||
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
|
||||||
|
|
|
@ -1,7 +1,5 @@
|
||||||
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
|
||||||
- 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
|
||||||
- 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
|
||||||
- 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:
|
||||||
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
|
||||||
------------------------
|
------------------------
|
||||||
|
|
236
Documentation/scheduler/completion.txt
Normal file
236
Documentation/scheduler/completion.txt
Normal file
|
@ -0,0 +1,236 @@
|
||||||
|
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.
|
||||||
|
|
||||||
- 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
|
||||||
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/
|
||||||
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>
|
||||||
|
|
Loading…
Add table
Reference in a new issue