A relatively calm cycle for the docs tree again.
- The old driver statement has been added to the kernel docs.
- We have a couple of new helper scripts. find-unused-docs.sh from Sayli
Karnic will point out kerneldoc comments that are not actually used in
the documentation. Jani Nikula's documentation-file-ref-check finds
references to non-existing files.
- A new ftrace document from Steve Rostedt.
- Vinod Koul converted the dmaengine docs to RST
Beyond that, it's mostly simple fixes.
-----BEGIN PGP SIGNATURE-----
iQIcBAABAgAGBQJaCK37AAoJEI3ONVYwIuV63nwQALeqzVwGqqTwiyRyMqgEwMQM
je/6IurEwTHtyfwtW/mztCfNid1CLTiYZg7RET3/zlHjcUI/9VlV2dbBksGFgoQo
muHGqhwTJjXYREwjK3FkzrGckRsVZKJgdzmZYgukCCY6Ir7IffwJKYaLOCZN1S/l
4nBHQpt2nITo0WhdmZjaNRKOQxMA8nN5yGpOIl0neGE6ywIUMgauCCCHhxnOPVWg
ant1HliS8WR8Tizqt9wQgLCvs5lvklsBFibZPO9LBTPG2Zy3HIO9kb+npUAh2MTl
j0Wg39zzOFvVVErqErqUIwIuQ9IrfltHrEHYYoruTvDBXBiMKIcwApF+DS+H3WSp
TnDu3Qif4llM5SZsZGvcjawXNnbck+7SYOe9cyqpylV3SWMWrEX1tbUv6zVuVk+7
fencYBvEZgkJmWbjDeO/Z4S50STxRTzIxFwZgLft7g/RiHo9HvlubjjwQTqBFjxA
fVkolN7h69MGkrD8TF19eapyujqSXaNYH0pFYo87JNOjLgYmezUHyvHd8YeZJL31
Ll0h10HqSNVzJsjFolBMgrC3CcVjsEXdBufu0yVk45sAg9ZiMYOCpwa6Rtp+tfxa
uIBf1LKzfWSa0ocKx7+sMJt0B/CXwU3AMtsbYGyDhFhR2r3cp1NWBHf5nisz9etD
2Md9RDFAMLELZurewB9Q
=H6ud
-----END PGP SIGNATURE-----
Merge tag 'docs-4.15' of git://git.lwn.net/linux
Pull documentation updates from Jonathan Corbet:
"A relatively calm cycle for the docs tree again.
- The old driver statement has been added to the kernel docs.
- We have a couple of new helper scripts. find-unused-docs.sh from
Sayli Karnic will point out kerneldoc comments that are not actually
used in the documentation. Jani Nikula's
documentation-file-ref-check finds references to non-existing files.
- A new ftrace document from Steve Rostedt.
- Vinod Koul converted the dmaengine docs to RST
Beyond that, it's mostly simple fixes.
This set reaches outside of Documentation/ a bit more than most. In
all cases, the changes are to comment docs, mostly from Randy, in
places where there didn't seem to be anybody better to take them"
* tag 'docs-4.15' of git://git.lwn.net/linux: (52 commits)
documentation: fb: update list of available compiled-in fonts
MAINTAINERS: update DMAengine documentation location
dmaengine: doc: ReSTize pxa_dma doc
dmaengine: doc: ReSTize dmatest doc
dmaengine: doc: ReSTize client API doc
dmaengine: doc: ReSTize provider doc
dmaengine: doc: Add ReST style dmaengine document
ftrace/docs: Add documentation on how to use ftrace from within the kernel
bug-hunting.rst: Fix an example and a typo in a Sphinx tag
scripts: Add a script to find unused documentation
samples: Convert timers to use timer_setup()
documentation: kernel-api: add more info on bitmap functions
Documentation: fix selftests related file refs
Documentation: fix ref to power basic-pm-debugging
Documentation: fix ref to trace stm content
Documentation: fix ref to coccinelle content
Documentation: fix ref to workqueue content
Documentation: fix ref to sphinx/kerneldoc.py
Documentation: fix locking rt-mutex doc refs
docs: dev-tools: correct Coccinelle version number
...
This commit is contained in:
Linus Torvalds
commit
7832681b36
83 changed files with 2018 additions and 1044 deletions
|
|
@ -1,5 +1,5 @@
|
||||||
# Note: This documents additional properties of any device beyond what
|
# Note: This documents additional properties of any device beyond what
|
||||||
# is documented in Documentation/sysfs-rules.txt
|
# is documented in Documentation/admin-guide/sysfs-rules.rst
|
||||||
|
|
||||||
What: /sys/devices/*/of_node
|
What: /sys/devices/*/of_node
|
||||||
Date: February 2015
|
Date: February 2015
|
||||||
|
|
|
||||||
|
|
@ -18,6 +18,6 @@ Description:
|
||||||
in the initramfs, which has already been measured as part
|
in the initramfs, which has already been measured as part
|
||||||
of the trusted boot. For more information on creating and
|
of the trusted boot. For more information on creating and
|
||||||
loading existing trusted/encrypted keys, refer to:
|
loading existing trusted/encrypted keys, refer to:
|
||||||
Documentation/keys-trusted-encrypted.txt. (A sample dracut
|
Documentation/security/keys/trusted-encrypted.rst. (A sample
|
||||||
patch, which loads the trusted/encrypted key and enables
|
dracut patch, which loads the trusted/encrypted key and enables
|
||||||
EVM, is available from http://linux-ima.sourceforge.net/#EVM.)
|
EVM, is available from http://linux-ima.sourceforge.net/#EVM.)
|
||||||
|
|
|
||||||
|
|
@ -187,7 +187,8 @@ Description: Processor frequency boosting control
|
||||||
This switch controls the boost setting for the whole system.
|
This switch controls the boost setting for the whole system.
|
||||||
Boosting allows the CPU and the firmware to run at a frequency
|
Boosting allows the CPU and the firmware to run at a frequency
|
||||||
beyound it's nominal limit.
|
beyound it's nominal limit.
|
||||||
More details can be found in Documentation/cpu-freq/boost.txt
|
More details can be found in
|
||||||
|
Documentation/admin-guide/pm/cpufreq.rst
|
||||||
|
|
||||||
|
|
||||||
What: /sys/devices/system/cpu/cpu#/crash_notes
|
What: /sys/devices/system/cpu/cpu#/crash_notes
|
||||||
|
|
@ -223,7 +224,8 @@ Description: Parameters for the Intel P-state driver
|
||||||
no_turbo: limits the driver to selecting P states below the turbo
|
no_turbo: limits the driver to selecting P states below the turbo
|
||||||
frequency range.
|
frequency range.
|
||||||
|
|
||||||
More details can be found in Documentation/cpu-freq/intel-pstate.txt
|
More details can be found in
|
||||||
|
Documentation/admin-guide/pm/intel_pstate.rst
|
||||||
|
|
||||||
What: /sys/devices/system/cpu/cpu*/cache/index*/<set_of_attributes_mentioned_below>
|
What: /sys/devices/system/cpu/cpu*/cache/index*/<set_of_attributes_mentioned_below>
|
||||||
Date: July 2014(documented, existed before August 2008)
|
Date: July 2014(documented, existed before August 2008)
|
||||||
|
|
|
||||||
|
|
@ -18,7 +18,8 @@ Description:
|
||||||
Writing one of the above strings to this file causes the system
|
Writing one of the above strings to this file causes the system
|
||||||
to transition into the corresponding state, if available.
|
to transition into the corresponding state, if available.
|
||||||
|
|
||||||
See Documentation/power/states.txt for more information.
|
See Documentation/admin-guide/pm/sleep-states.rst for more
|
||||||
|
information.
|
||||||
|
|
||||||
What: /sys/power/mem_sleep
|
What: /sys/power/mem_sleep
|
||||||
Date: November 2016
|
Date: November 2016
|
||||||
|
|
@ -35,7 +36,8 @@ Description:
|
||||||
represented by it to be used on subsequent attempts to suspend
|
represented by it to be used on subsequent attempts to suspend
|
||||||
the system.
|
the system.
|
||||||
|
|
||||||
See Documentation/power/states.txt for more information.
|
See Documentation/admin-guide/pm/sleep-states.rst for more
|
||||||
|
information.
|
||||||
|
|
||||||
What: /sys/power/disk
|
What: /sys/power/disk
|
||||||
Date: September 2006
|
Date: September 2006
|
||||||
|
|
|
||||||
|
|
@ -97,6 +97,9 @@ endif # HAVE_SPHINX
|
||||||
# The following targets are independent of HAVE_SPHINX, and the rules should
|
# The following targets are independent of HAVE_SPHINX, and the rules should
|
||||||
# work or silently pass without Sphinx.
|
# work or silently pass without Sphinx.
|
||||||
|
|
||||||
|
refcheckdocs:
|
||||||
|
$(Q)cd $(srctree);scripts/documentation-file-ref-check
|
||||||
|
|
||||||
cleandocs:
|
cleandocs:
|
||||||
$(Q)rm -rf $(BUILDDIR)
|
$(Q)rm -rf $(BUILDDIR)
|
||||||
$(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media clean
|
$(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media clean
|
||||||
|
|
@ -109,6 +112,7 @@ dochelp:
|
||||||
@echo ' epubdocs - EPUB'
|
@echo ' epubdocs - EPUB'
|
||||||
@echo ' xmldocs - XML'
|
@echo ' xmldocs - XML'
|
||||||
@echo ' linkcheckdocs - check for broken external links (will connect to external hosts)'
|
@echo ' linkcheckdocs - check for broken external links (will connect to external hosts)'
|
||||||
|
@echo ' refcheckdocs - check for references to non-existing files under Documentation'
|
||||||
@echo ' cleandocs - clean all generated files'
|
@echo ' cleandocs - clean all generated files'
|
||||||
@echo
|
@echo
|
||||||
@echo ' make SPHINXDIRS="s1 s2" [target] Generate only docs of folder s1, s2'
|
@echo ' make SPHINXDIRS="s1 s2" [target] Generate only docs of folder s1, s2'
|
||||||
|
|
@ -116,3 +120,5 @@ dochelp:
|
||||||
@echo
|
@echo
|
||||||
@echo ' make SPHINX_CONF={conf-file} [target] use *additional* sphinx-build'
|
@echo ' make SPHINX_CONF={conf-file} [target] use *additional* sphinx-build'
|
||||||
@echo ' configuration. This is e.g. useful to build with nit-picking config.'
|
@echo ' configuration. This is e.g. useful to build with nit-picking config.'
|
||||||
|
@echo
|
||||||
|
@echo ' Default location for the generated documents is Documentation/output'
|
||||||
|
|
|
||||||
|
|
@ -527,7 +527,7 @@ grace period also drove it to completion.
|
||||||
This straightforward approach had the disadvantage of needing to
|
This straightforward approach had the disadvantage of needing to
|
||||||
account for POSIX signals sent to user tasks,
|
account for POSIX signals sent to user tasks,
|
||||||
so more recent implemementations use the Linux kernel's
|
so more recent implemementations use the Linux kernel's
|
||||||
<a href="https://www.kernel.org/doc/Documentation/workqueue.txt">workqueues</a>.
|
<a href="https://www.kernel.org/doc/Documentation/core-api/workqueue.rst">workqueues</a>.
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
The requesting task still does counter snapshotting and funnel-lock
|
The requesting task still does counter snapshotting and funnel-lock
|
||||||
|
|
|
||||||
|
|
@ -350,7 +350,7 @@ If something goes wrong
|
||||||
help debugging the problem. The text above the dump is also
|
help debugging the problem. The text above the dump is also
|
||||||
important: it tells something about why the kernel dumped code (in
|
important: it tells something about why the kernel dumped code (in
|
||||||
the above example, it's due to a bad kernel pointer). More information
|
the above example, it's due to a bad kernel pointer). More information
|
||||||
on making sense of the dump is in Documentation/admin-guide/oops-tracing.rst
|
on making sense of the dump is in Documentation/admin-guide/bug-hunting.rst
|
||||||
|
|
||||||
- If you compiled the kernel with CONFIG_KALLSYMS you can send the dump
|
- If you compiled the kernel with CONFIG_KALLSYMS you can send the dump
|
||||||
as is, otherwise you will have to use the ``ksymoops`` program to make
|
as is, otherwise you will have to use the ``ksymoops`` program to make
|
||||||
|
|
|
||||||
|
|
@ -240,7 +240,7 @@ In order to report it upstream, you should identify the mailing list
|
||||||
used for the development of the affected code. This can be done by using
|
used for the development of the affected code. This can be done by using
|
||||||
the ``get_maintainer.pl`` script.
|
the ``get_maintainer.pl`` script.
|
||||||
|
|
||||||
For example, if you find a bug at the gspca's conex.c file, you can get
|
For example, if you find a bug at the gspca's sonixj.c file, you can get
|
||||||
their maintainers with::
|
their maintainers with::
|
||||||
|
|
||||||
$ ./scripts/get_maintainer.pl -f drivers/media/usb/gspca/sonixj.c
|
$ ./scripts/get_maintainer.pl -f drivers/media/usb/gspca/sonixj.c
|
||||||
|
|
@ -257,7 +257,7 @@ Please notice that it will point to:
|
||||||
Tejun and Bhaktipriya (in this specific case, none really envolved on the
|
Tejun and Bhaktipriya (in this specific case, none really envolved on the
|
||||||
development of this file);
|
development of this file);
|
||||||
- The driver maintainer (Hans Verkuil);
|
- The driver maintainer (Hans Verkuil);
|
||||||
- The subsystem maintainer (Mauro Carvalho Chehab)
|
- The subsystem maintainer (Mauro Carvalho Chehab);
|
||||||
- The driver and/or subsystem mailing list (linux-media@vger.kernel.org);
|
- The driver and/or subsystem mailing list (linux-media@vger.kernel.org);
|
||||||
- the Linux Kernel mailing list (linux-kernel@vger.kernel.org).
|
- the Linux Kernel mailing list (linux-kernel@vger.kernel.org).
|
||||||
|
|
||||||
|
|
@ -274,14 +274,14 @@ Fixing the bug
|
||||||
--------------
|
--------------
|
||||||
|
|
||||||
If you know programming, you could help us by not only reporting the bug,
|
If you know programming, you could help us by not only reporting the bug,
|
||||||
but also providing us with a solution. After all open source is about
|
but also providing us with a solution. After all, open source is about
|
||||||
sharing what you do and don't you want to be recognised for your genius?
|
sharing what you do and don't you want to be recognised for your genius?
|
||||||
|
|
||||||
If you decide to take this way, once you have worked out a fix please submit
|
If you decide to take this way, once you have worked out a fix please submit
|
||||||
it upstream.
|
it upstream.
|
||||||
|
|
||||||
Please do read
|
Please do read
|
||||||
ref:`Documentation/process/submitting-patches.rst <submittingpatches>` though
|
:ref:`Documentation/process/submitting-patches.rst <submittingpatches>` though
|
||||||
to help your code get accepted.
|
to help your code get accepted.
|
||||||
|
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -314,7 +314,7 @@
|
||||||
amijoy.map= [HW,JOY] Amiga joystick support
|
amijoy.map= [HW,JOY] Amiga joystick support
|
||||||
Map of devices attached to JOY0DAT and JOY1DAT
|
Map of devices attached to JOY0DAT and JOY1DAT
|
||||||
Format: <a>,<b>
|
Format: <a>,<b>
|
||||||
See also Documentation/input/joystick.txt
|
See also Documentation/input/joydev/joystick.rst
|
||||||
|
|
||||||
analog.map= [HW,JOY] Analog joystick and gamepad support
|
analog.map= [HW,JOY] Analog joystick and gamepad support
|
||||||
Specifies type or capabilities of an analog joystick
|
Specifies type or capabilities of an analog joystick
|
||||||
|
|
@ -439,7 +439,7 @@
|
||||||
bttv.card= [HW,V4L] bttv (bt848 + bt878 based grabber cards)
|
bttv.card= [HW,V4L] bttv (bt848 + bt878 based grabber cards)
|
||||||
bttv.radio= Most important insmod options are available as
|
bttv.radio= Most important insmod options are available as
|
||||||
kernel args too.
|
kernel args too.
|
||||||
bttv.pll= See Documentation/video4linux/bttv/Insmod-options
|
bttv.pll= See Documentation/media/v4l-drivers/bttv.rst
|
||||||
bttv.tuner=
|
bttv.tuner=
|
||||||
|
|
||||||
bulk_remove=off [PPC] This parameter disables the use of the pSeries
|
bulk_remove=off [PPC] This parameter disables the use of the pSeries
|
||||||
|
|
@ -641,8 +641,8 @@
|
||||||
For now, only VisioBraille is supported.
|
For now, only VisioBraille is supported.
|
||||||
|
|
||||||
consoleblank= [KNL] The console blank (screen saver) timeout in
|
consoleblank= [KNL] The console blank (screen saver) timeout in
|
||||||
seconds. Defaults to 10*60 = 10mins. A value of 0
|
seconds. A value of 0 disables the blank timer.
|
||||||
disables the blank timer.
|
Defaults to 0.
|
||||||
|
|
||||||
coredump_filter=
|
coredump_filter=
|
||||||
[KNL] Change the default value for
|
[KNL] Change the default value for
|
||||||
|
|
@ -724,7 +724,7 @@
|
||||||
db9.dev[2|3]= [HW,JOY] Multisystem joystick support via parallel port
|
db9.dev[2|3]= [HW,JOY] Multisystem joystick support via parallel port
|
||||||
(one device per port)
|
(one device per port)
|
||||||
Format: <port#>,<type>
|
Format: <port#>,<type>
|
||||||
See also Documentation/input/joystick-parport.txt
|
See also Documentation/input/devices/joystick-parport.rst
|
||||||
|
|
||||||
ddebug_query= [KNL,DYNAMIC_DEBUG] Enable debug messages at early boot
|
ddebug_query= [KNL,DYNAMIC_DEBUG] Enable debug messages at early boot
|
||||||
time. See
|
time. See
|
||||||
|
|
@ -1220,7 +1220,7 @@
|
||||||
[HW,JOY] Multisystem joystick and NES/SNES/PSX pad
|
[HW,JOY] Multisystem joystick and NES/SNES/PSX pad
|
||||||
support via parallel port (up to 5 devices per port)
|
support via parallel port (up to 5 devices per port)
|
||||||
Format: <port#>,<pad1>,<pad2>,<pad3>,<pad4>,<pad5>
|
Format: <port#>,<pad1>,<pad2>,<pad3>,<pad4>,<pad5>
|
||||||
See also Documentation/input/joystick-parport.txt
|
See also Documentation/input/devices/joystick-parport.rst
|
||||||
|
|
||||||
gamma= [HW,DRM]
|
gamma= [HW,DRM]
|
||||||
|
|
||||||
|
|
@ -1766,7 +1766,7 @@
|
||||||
ivrs_acpihid[00:14.5]=AMD0020:0
|
ivrs_acpihid[00:14.5]=AMD0020:0
|
||||||
|
|
||||||
js= [HW,JOY] Analog joystick
|
js= [HW,JOY] Analog joystick
|
||||||
See Documentation/input/joystick.txt.
|
See Documentation/input/joydev/joystick.rst.
|
||||||
|
|
||||||
nokaslr [KNL]
|
nokaslr [KNL]
|
||||||
When CONFIG_RANDOMIZE_BASE is set, this disables
|
When CONFIG_RANDOMIZE_BASE is set, this disables
|
||||||
|
|
@ -2248,10 +2248,10 @@
|
||||||
s2idle - Suspend-To-Idle
|
s2idle - Suspend-To-Idle
|
||||||
shallow - Power-On Suspend or equivalent (if supported)
|
shallow - Power-On Suspend or equivalent (if supported)
|
||||||
deep - Suspend-To-RAM or equivalent (if supported)
|
deep - Suspend-To-RAM or equivalent (if supported)
|
||||||
See Documentation/power/states.txt.
|
See Documentation/admin-guide/pm/sleep-states.rst.
|
||||||
|
|
||||||
meye.*= [HW] Set MotionEye Camera parameters
|
meye.*= [HW] Set MotionEye Camera parameters
|
||||||
See Documentation/video4linux/meye.txt.
|
See Documentation/media/v4l-drivers/meye.rst.
|
||||||
|
|
||||||
mfgpt_irq= [IA-32] Specify the IRQ to use for the
|
mfgpt_irq= [IA-32] Specify the IRQ to use for the
|
||||||
Multi-Function General Purpose Timers on AMD Geode
|
Multi-Function General Purpose Timers on AMD Geode
|
||||||
|
|
@ -3134,7 +3134,7 @@
|
||||||
|
|
||||||
plip= [PPT,NET] Parallel port network link
|
plip= [PPT,NET] Parallel port network link
|
||||||
Format: { parport<nr> | timid | 0 }
|
Format: { parport<nr> | timid | 0 }
|
||||||
See also Documentation/parport.txt.
|
See also Documentation/admin-guide/parport.rst.
|
||||||
|
|
||||||
pmtmr= [X86] Manual setup of pmtmr I/O Port.
|
pmtmr= [X86] Manual setup of pmtmr I/O Port.
|
||||||
Override pmtimer IOPort with a hex value.
|
Override pmtimer IOPort with a hex value.
|
||||||
|
|
@ -3885,6 +3885,12 @@
|
||||||
[KNL] Should the soft-lockup detector generate panics.
|
[KNL] Should the soft-lockup detector generate panics.
|
||||||
Format: <integer>
|
Format: <integer>
|
||||||
|
|
||||||
|
A nonzero value instructs the soft-lockup detector
|
||||||
|
to panic the machine when a soft-lockup occurs. This
|
||||||
|
is also controlled by CONFIG_BOOTPARAM_SOFTLOCKUP_PANIC
|
||||||
|
which is the respective build-time switch to that
|
||||||
|
functionality.
|
||||||
|
|
||||||
softlockup_all_cpu_backtrace=
|
softlockup_all_cpu_backtrace=
|
||||||
[KNL] Should the soft-lockup detector generate
|
[KNL] Should the soft-lockup detector generate
|
||||||
backtraces on all cpus.
|
backtraces on all cpus.
|
||||||
|
|
@ -4199,7 +4205,7 @@
|
||||||
TurboGraFX parallel port interface
|
TurboGraFX parallel port interface
|
||||||
Format:
|
Format:
|
||||||
<port#>,<js1>,<js2>,<js3>,<js4>,<js5>,<js6>,<js7>
|
<port#>,<js1>,<js2>,<js3>,<js4>,<js5>,<js6>,<js7>
|
||||||
See also Documentation/input/joystick-parport.txt
|
See also Documentation/input/devices/joystick-parport.rst
|
||||||
|
|
||||||
udbg-immortal [PPC] When debugging early kernel crashes that
|
udbg-immortal [PPC] When debugging early kernel crashes that
|
||||||
happen after console_init() and before a proper
|
happen after console_init() and before a proper
|
||||||
|
|
|
||||||
|
|
@ -94,7 +94,7 @@ step-by-step instructions for how a user can trigger the bug.
|
||||||
|
|
||||||
If the failure includes an "OOPS:", take a picture of the screen, capture
|
If the failure includes an "OOPS:", take a picture of the screen, capture
|
||||||
a netconsole trace, or type the message from your screen into the bug
|
a netconsole trace, or type the message from your screen into the bug
|
||||||
report. Please read "Documentation/admin-guide/oops-tracing.rst" before posting your
|
report. Please read "Documentation/admin-guide/bug-hunting.rst" before posting your
|
||||||
bug report. This explains what you should do with the "Oops" information
|
bug report. This explains what you should do with the "Oops" information
|
||||||
to make it useful to the recipient.
|
to make it useful to the recipient.
|
||||||
|
|
||||||
|
|
@ -120,7 +120,7 @@ summary from [1.]>" for easy identification by the developers::
|
||||||
[4.2.] Kernel .config file:
|
[4.2.] Kernel .config file:
|
||||||
[5.] Most recent kernel version which did not have the bug:
|
[5.] Most recent kernel version which did not have the bug:
|
||||||
[6.] Output of Oops.. message (if applicable) with symbolic information
|
[6.] Output of Oops.. message (if applicable) with symbolic information
|
||||||
resolved (see Documentation/admin-guide/oops-tracing.rst)
|
resolved (see Documentation/admin-guide/bug-hunting.rst)
|
||||||
[7.] A small shell script or example program which triggers the
|
[7.] A small shell script or example program which triggers the
|
||||||
problem (if possible)
|
problem (if possible)
|
||||||
[8.] Environment
|
[8.] Environment
|
||||||
|
|
|
||||||
|
|
@ -55,13 +55,9 @@ This driver provides the following features:
|
||||||
(to compile support as a module which can be loaded and unloaded)
|
(to compile support as a module which can be loaded and unloaded)
|
||||||
to the options:
|
to the options:
|
||||||
|
|
||||||
Enhanced IDE/MFM/RLL disk/cdrom/tape/floppy support
|
ATA/ATAPI/MFM/RLL support
|
||||||
Include IDE/ATAPI CDROM support
|
Include IDE/ATAPI CDROM support
|
||||||
|
|
||||||
and `no' to
|
|
||||||
|
|
||||||
Use old disk-only driver on primary interface
|
|
||||||
|
|
||||||
Depending on what type of IDE interface you have, you may need to
|
Depending on what type of IDE interface you have, you may need to
|
||||||
specify additional configuration options. See
|
specify additional configuration options. See
|
||||||
Documentation/ide/ide.txt.
|
Documentation/ide/ide.txt.
|
||||||
|
|
|
||||||
|
|
@ -2,11 +2,9 @@
|
||||||
The Linux Kernel API
|
The Linux Kernel API
|
||||||
====================
|
====================
|
||||||
|
|
||||||
Data Types
|
|
||||||
==========
|
|
||||||
|
|
||||||
Doubly Linked Lists
|
List Management Functions
|
||||||
-------------------
|
=========================
|
||||||
|
|
||||||
.. kernel-doc:: include/linux/list.h
|
.. kernel-doc:: include/linux/list.h
|
||||||
:internal:
|
:internal:
|
||||||
|
|
@ -55,12 +53,27 @@ The Linux kernel provides more basic utility functions.
|
||||||
Bitmap Operations
|
Bitmap Operations
|
||||||
-----------------
|
-----------------
|
||||||
|
|
||||||
|
.. kernel-doc:: lib/bitmap.c
|
||||||
|
:doc: bitmap introduction
|
||||||
|
|
||||||
|
.. kernel-doc:: include/linux/bitmap.h
|
||||||
|
:doc: declare bitmap
|
||||||
|
|
||||||
|
.. kernel-doc:: include/linux/bitmap.h
|
||||||
|
:doc: bitmap overview
|
||||||
|
|
||||||
|
.. kernel-doc:: include/linux/bitmap.h
|
||||||
|
:doc: bitmap bitops
|
||||||
|
|
||||||
.. kernel-doc:: lib/bitmap.c
|
.. kernel-doc:: lib/bitmap.c
|
||||||
:export:
|
:export:
|
||||||
|
|
||||||
.. kernel-doc:: lib/bitmap.c
|
.. kernel-doc:: lib/bitmap.c
|
||||||
:internal:
|
:internal:
|
||||||
|
|
||||||
|
.. kernel-doc:: include/linux/bitmap.h
|
||||||
|
:internal:
|
||||||
|
|
||||||
Command-line Parsing
|
Command-line Parsing
|
||||||
--------------------
|
--------------------
|
||||||
|
|
||||||
|
|
@ -70,20 +83,26 @@ Command-line Parsing
|
||||||
CRC Functions
|
CRC Functions
|
||||||
-------------
|
-------------
|
||||||
|
|
||||||
|
.. kernel-doc:: lib/crc4.c
|
||||||
|
:export:
|
||||||
|
|
||||||
.. kernel-doc:: lib/crc7.c
|
.. kernel-doc:: lib/crc7.c
|
||||||
:export:
|
:export:
|
||||||
|
|
||||||
|
.. kernel-doc:: lib/crc8.c
|
||||||
|
:export:
|
||||||
|
|
||||||
.. kernel-doc:: lib/crc16.c
|
.. kernel-doc:: lib/crc16.c
|
||||||
:export:
|
:export:
|
||||||
|
|
||||||
.. kernel-doc:: lib/crc-itu-t.c
|
|
||||||
:export:
|
|
||||||
|
|
||||||
.. kernel-doc:: lib/crc32.c
|
.. kernel-doc:: lib/crc32.c
|
||||||
|
|
||||||
.. kernel-doc:: lib/crc-ccitt.c
|
.. kernel-doc:: lib/crc-ccitt.c
|
||||||
:export:
|
:export:
|
||||||
|
|
||||||
|
.. kernel-doc:: lib/crc-itu-t.c
|
||||||
|
:export:
|
||||||
|
|
||||||
idr/ida Functions
|
idr/ida Functions
|
||||||
-----------------
|
-----------------
|
||||||
|
|
||||||
|
|
@ -96,6 +115,30 @@ idr/ida Functions
|
||||||
.. kernel-doc:: lib/idr.c
|
.. kernel-doc:: lib/idr.c
|
||||||
:export:
|
:export:
|
||||||
|
|
||||||
|
Math Functions in Linux
|
||||||
|
=======================
|
||||||
|
|
||||||
|
Base 2 log and power Functions
|
||||||
|
------------------------------
|
||||||
|
|
||||||
|
.. kernel-doc:: include/linux/log2.h
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
Division Functions
|
||||||
|
------------------
|
||||||
|
|
||||||
|
.. kernel-doc:: include/asm-generic/div64.h
|
||||||
|
:functions: do_div
|
||||||
|
|
||||||
|
.. kernel-doc:: include/linux/math64.h
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
.. kernel-doc:: lib/div64.c
|
||||||
|
:functions: div_s64_rem div64_u64_rem div64_u64 div64_s64
|
||||||
|
|
||||||
|
.. kernel-doc:: lib/gcd.c
|
||||||
|
:export:
|
||||||
|
|
||||||
Memory Management in Linux
|
Memory Management in Linux
|
||||||
==========================
|
==========================
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -209,7 +209,7 @@ err.log will now have the profiling information, while stdout will
|
||||||
provide some progress information as Coccinelle moves forward with
|
provide some progress information as Coccinelle moves forward with
|
||||||
work.
|
work.
|
||||||
|
|
||||||
DEBUG_FILE support is only supported when using coccinelle >= 1.2.
|
DEBUG_FILE support is only supported when using coccinelle >= 1.0.2.
|
||||||
|
|
||||||
.cocciconfig support
|
.cocciconfig support
|
||||||
--------------------
|
--------------------
|
||||||
|
|
|
||||||
|
|
@ -31,6 +31,17 @@ To build and run the tests with a single command, use::
|
||||||
|
|
||||||
Note that some tests will require root privileges.
|
Note that some tests will require root privileges.
|
||||||
|
|
||||||
|
Build and run from user specific object directory (make O=dir)::
|
||||||
|
|
||||||
|
$ make O=/tmp/kselftest kselftest
|
||||||
|
|
||||||
|
Build and run KBUILD_OUTPUT directory (make KBUILD_OUTPUT=)::
|
||||||
|
|
||||||
|
$ make KBUILD_OUTPUT=/tmp/kselftest kselftest
|
||||||
|
|
||||||
|
The above commands run the tests and print pass/fail summary to make it
|
||||||
|
easier to understand the test results. Please find the detailed individual
|
||||||
|
test results for each test in /tmp/testname file(s).
|
||||||
|
|
||||||
Running a subset of selftests
|
Running a subset of selftests
|
||||||
=============================
|
=============================
|
||||||
|
|
@ -46,10 +57,21 @@ You can specify multiple tests to build and run::
|
||||||
|
|
||||||
$ make TARGETS="size timers" kselftest
|
$ make TARGETS="size timers" kselftest
|
||||||
|
|
||||||
|
Build and run from user specific object directory (make O=dir)::
|
||||||
|
|
||||||
|
$ make O=/tmp/kselftest TARGETS="size timers" kselftest
|
||||||
|
|
||||||
|
Build and run KBUILD_OUTPUT directory (make KBUILD_OUTPUT=)::
|
||||||
|
|
||||||
|
$ make KBUILD_OUTPUT=/tmp/kselftest TARGETS="size timers" kselftest
|
||||||
|
|
||||||
|
The above commands run the tests and print pass/fail summary to make it
|
||||||
|
easier to understand the test results. Please find the detailed individual
|
||||||
|
test results for each test in /tmp/testname file(s).
|
||||||
|
|
||||||
See the top-level tools/testing/selftests/Makefile for the list of all
|
See the top-level tools/testing/selftests/Makefile for the list of all
|
||||||
possible targets.
|
possible targets.
|
||||||
|
|
||||||
|
|
||||||
Running the full range hotplug selftests
|
Running the full range hotplug selftests
|
||||||
========================================
|
========================================
|
||||||
|
|
||||||
|
|
@ -113,9 +135,17 @@ Contributing new tests (details)
|
||||||
* Use TEST_GEN_XXX if such binaries or files are generated during
|
* Use TEST_GEN_XXX if such binaries or files are generated during
|
||||||
compiling.
|
compiling.
|
||||||
|
|
||||||
TEST_PROGS, TEST_GEN_PROGS mean it is the excutable tested by
|
TEST_PROGS, TEST_GEN_PROGS mean it is the executable tested by
|
||||||
default.
|
default.
|
||||||
|
|
||||||
|
TEST_CUSTOM_PROGS should be used by tests that require custom build
|
||||||
|
rule and prevent common build rule use.
|
||||||
|
|
||||||
|
TEST_PROGS are for test shell scripts. Please ensure shell script has
|
||||||
|
its exec bit set. Otherwise, lib.mk run_tests will generate a warning.
|
||||||
|
|
||||||
|
TEST_CUSTOM_PROGS and TEST_PROGS will be run by common run_tests.
|
||||||
|
|
||||||
TEST_PROGS_EXTENDED, TEST_GEN_PROGS_EXTENDED mean it is the
|
TEST_PROGS_EXTENDED, TEST_GEN_PROGS_EXTENDED mean it is the
|
||||||
executable which is not tested by default.
|
executable which is not tested by default.
|
||||||
TEST_FILES, TEST_GEN_FILES mean it is the file which is used by
|
TEST_FILES, TEST_GEN_FILES mean it is the file which is used by
|
||||||
|
|
|
||||||
|
|
@ -1,8 +0,0 @@
|
||||||
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.
|
|
||||||
|
|
@ -1,222 +0,0 @@
|
||||||
DMA Engine API Guide
|
|
||||||
====================
|
|
||||||
|
|
||||||
Vinod Koul <vinod dot koul at intel.com>
|
|
||||||
|
|
||||||
NOTE: For DMA Engine usage in async_tx please see:
|
|
||||||
Documentation/crypto/async-tx-api.txt
|
|
||||||
|
|
||||||
|
|
||||||
Below is a guide to device driver writers on how to use the Slave-DMA API of the
|
|
||||||
DMA Engine. This is applicable only for slave DMA usage only.
|
|
||||||
|
|
||||||
The slave DMA usage consists of following steps:
|
|
||||||
1. Allocate a DMA slave channel
|
|
||||||
2. Set slave and controller specific parameters
|
|
||||||
3. Get a descriptor for transaction
|
|
||||||
4. Submit the transaction
|
|
||||||
5. Issue pending requests and wait for callback notification
|
|
||||||
|
|
||||||
1. Allocate a DMA slave channel
|
|
||||||
|
|
||||||
Channel allocation is slightly different in the slave DMA context,
|
|
||||||
client drivers typically need a channel from a particular DMA
|
|
||||||
controller only and even in some cases a specific channel is desired.
|
|
||||||
To request a channel dma_request_chan() API is used.
|
|
||||||
|
|
||||||
Interface:
|
|
||||||
struct dma_chan *dma_request_chan(struct device *dev, const char *name);
|
|
||||||
|
|
||||||
Which will find and return the 'name' DMA channel associated with the 'dev'
|
|
||||||
device. The association is done via DT, ACPI or board file based
|
|
||||||
dma_slave_map matching table.
|
|
||||||
|
|
||||||
A channel allocated via this interface is exclusive to the caller,
|
|
||||||
until dma_release_channel() is called.
|
|
||||||
|
|
||||||
2. Set slave and controller specific parameters
|
|
||||||
|
|
||||||
Next step is always to pass some specific information to the DMA
|
|
||||||
driver. Most of the generic information which a slave DMA can use
|
|
||||||
is in struct dma_slave_config. This allows the clients to specify
|
|
||||||
DMA direction, DMA addresses, bus widths, DMA burst lengths etc
|
|
||||||
for the peripheral.
|
|
||||||
|
|
||||||
If some DMA controllers have more parameters to be sent then they
|
|
||||||
should try to embed struct dma_slave_config in their controller
|
|
||||||
specific structure. That gives flexibility to client to pass more
|
|
||||||
parameters, if required.
|
|
||||||
|
|
||||||
Interface:
|
|
||||||
int dmaengine_slave_config(struct dma_chan *chan,
|
|
||||||
struct dma_slave_config *config)
|
|
||||||
|
|
||||||
Please see the dma_slave_config structure definition in dmaengine.h
|
|
||||||
for a detailed explanation of the struct members. Please note
|
|
||||||
that the 'direction' member will be going away as it duplicates the
|
|
||||||
direction given in the prepare call.
|
|
||||||
|
|
||||||
3. Get a descriptor for transaction
|
|
||||||
|
|
||||||
For slave usage the various modes of slave transfers supported by the
|
|
||||||
DMA-engine are:
|
|
||||||
|
|
||||||
slave_sg - DMA a list of scatter gather buffers from/to a peripheral
|
|
||||||
dma_cyclic - Perform a cyclic DMA operation from/to a peripheral till the
|
|
||||||
operation is explicitly stopped.
|
|
||||||
interleaved_dma - This is common to Slave as well as M2M clients. For slave
|
|
||||||
address of devices' fifo could be already known to the driver.
|
|
||||||
Various types of operations could be expressed by setting
|
|
||||||
appropriate values to the 'dma_interleaved_template' members.
|
|
||||||
|
|
||||||
A non-NULL return of this transfer API represents a "descriptor" for
|
|
||||||
the given transaction.
|
|
||||||
|
|
||||||
Interface:
|
|
||||||
struct dma_async_tx_descriptor *dmaengine_prep_slave_sg(
|
|
||||||
struct dma_chan *chan, struct scatterlist *sgl,
|
|
||||||
unsigned int sg_len, enum dma_data_direction direction,
|
|
||||||
unsigned long flags);
|
|
||||||
|
|
||||||
struct dma_async_tx_descriptor *dmaengine_prep_dma_cyclic(
|
|
||||||
struct dma_chan *chan, dma_addr_t buf_addr, size_t buf_len,
|
|
||||||
size_t period_len, enum dma_data_direction direction);
|
|
||||||
|
|
||||||
struct dma_async_tx_descriptor *dmaengine_prep_interleaved_dma(
|
|
||||||
struct dma_chan *chan, struct dma_interleaved_template *xt,
|
|
||||||
unsigned long flags);
|
|
||||||
|
|
||||||
The peripheral driver is expected to have mapped the scatterlist for
|
|
||||||
the DMA operation prior to calling dmaengine_prep_slave_sg(), and must
|
|
||||||
keep the scatterlist mapped until the DMA operation has completed.
|
|
||||||
The scatterlist must be mapped using the DMA struct device.
|
|
||||||
If a mapping needs to be synchronized later, dma_sync_*_for_*() must be
|
|
||||||
called using the DMA struct device, too.
|
|
||||||
So, normal setup should look like this:
|
|
||||||
|
|
||||||
nr_sg = dma_map_sg(chan->device->dev, sgl, sg_len);
|
|
||||||
if (nr_sg == 0)
|
|
||||||
/* error */
|
|
||||||
|
|
||||||
desc = dmaengine_prep_slave_sg(chan, sgl, nr_sg, direction, flags);
|
|
||||||
|
|
||||||
Once a descriptor has been obtained, the callback information can be
|
|
||||||
added and the descriptor must then be submitted. Some DMA engine
|
|
||||||
drivers may hold a spinlock between a successful preparation and
|
|
||||||
submission so it is important that these two operations are closely
|
|
||||||
paired.
|
|
||||||
|
|
||||||
Note:
|
|
||||||
Although the async_tx API specifies that completion callback
|
|
||||||
routines cannot submit any new operations, this is not the
|
|
||||||
case for slave/cyclic DMA.
|
|
||||||
|
|
||||||
For slave DMA, the subsequent transaction may not be available
|
|
||||||
for submission prior to callback function being invoked, so
|
|
||||||
slave DMA callbacks are permitted to prepare and submit a new
|
|
||||||
transaction.
|
|
||||||
|
|
||||||
For cyclic DMA, a callback function may wish to terminate the
|
|
||||||
DMA via dmaengine_terminate_async().
|
|
||||||
|
|
||||||
Therefore, it is important that DMA engine drivers drop any
|
|
||||||
locks before calling the callback function which may cause a
|
|
||||||
deadlock.
|
|
||||||
|
|
||||||
Note that callbacks will always be invoked from the DMA
|
|
||||||
engines tasklet, never from interrupt context.
|
|
||||||
|
|
||||||
4. Submit the transaction
|
|
||||||
|
|
||||||
Once the descriptor has been prepared and the callback information
|
|
||||||
added, it must be placed on the DMA engine drivers pending queue.
|
|
||||||
|
|
||||||
Interface:
|
|
||||||
dma_cookie_t dmaengine_submit(struct dma_async_tx_descriptor *desc)
|
|
||||||
|
|
||||||
This returns a cookie can be used to check the progress of DMA engine
|
|
||||||
activity via other DMA engine calls not covered in this document.
|
|
||||||
|
|
||||||
dmaengine_submit() will not start the DMA operation, it merely adds
|
|
||||||
it to the pending queue. For this, see step 5, dma_async_issue_pending.
|
|
||||||
|
|
||||||
5. Issue pending DMA requests and wait for callback notification
|
|
||||||
|
|
||||||
The transactions in the pending queue can be activated by calling the
|
|
||||||
issue_pending API. If channel is idle then the first transaction in
|
|
||||||
queue is started and subsequent ones queued up.
|
|
||||||
|
|
||||||
On completion of each DMA operation, the next in queue is started and
|
|
||||||
a tasklet triggered. The tasklet will then call the client driver
|
|
||||||
completion callback routine for notification, if set.
|
|
||||||
|
|
||||||
Interface:
|
|
||||||
void dma_async_issue_pending(struct dma_chan *chan);
|
|
||||||
|
|
||||||
Further APIs:
|
|
||||||
|
|
||||||
1. int dmaengine_terminate_sync(struct dma_chan *chan)
|
|
||||||
int dmaengine_terminate_async(struct dma_chan *chan)
|
|
||||||
int dmaengine_terminate_all(struct dma_chan *chan) /* DEPRECATED */
|
|
||||||
|
|
||||||
This causes all activity for the DMA channel to be stopped, and may
|
|
||||||
discard data in the DMA FIFO which hasn't been fully transferred.
|
|
||||||
No callback functions will be called for any incomplete transfers.
|
|
||||||
|
|
||||||
Two variants of this function are available.
|
|
||||||
|
|
||||||
dmaengine_terminate_async() might not wait until the DMA has been fully
|
|
||||||
stopped or until any running complete callbacks have finished. But it is
|
|
||||||
possible to call dmaengine_terminate_async() from atomic context or from
|
|
||||||
within a complete callback. dmaengine_synchronize() must be called before it
|
|
||||||
is safe to free the memory accessed by the DMA transfer or free resources
|
|
||||||
accessed from within the complete callback.
|
|
||||||
|
|
||||||
dmaengine_terminate_sync() will wait for the transfer and any running
|
|
||||||
complete callbacks to finish before it returns. But the function must not be
|
|
||||||
called from atomic context or from within a complete callback.
|
|
||||||
|
|
||||||
dmaengine_terminate_all() is deprecated and should not be used in new code.
|
|
||||||
|
|
||||||
2. int dmaengine_pause(struct dma_chan *chan)
|
|
||||||
|
|
||||||
This pauses activity on the DMA channel without data loss.
|
|
||||||
|
|
||||||
3. int dmaengine_resume(struct dma_chan *chan)
|
|
||||||
|
|
||||||
Resume a previously paused DMA channel. It is invalid to resume a
|
|
||||||
channel which is not currently paused.
|
|
||||||
|
|
||||||
4. enum dma_status dma_async_is_tx_complete(struct dma_chan *chan,
|
|
||||||
dma_cookie_t cookie, dma_cookie_t *last, dma_cookie_t *used)
|
|
||||||
|
|
||||||
This can be used to check the status of the channel. Please see
|
|
||||||
the documentation in include/linux/dmaengine.h for a more complete
|
|
||||||
description of this API.
|
|
||||||
|
|
||||||
This can be used in conjunction with dma_async_is_complete() and
|
|
||||||
the cookie returned from dmaengine_submit() to check for
|
|
||||||
completion of a specific DMA transaction.
|
|
||||||
|
|
||||||
Note:
|
|
||||||
Not all DMA engine drivers can return reliable information for
|
|
||||||
a running DMA channel. It is recommended that DMA engine users
|
|
||||||
pause or stop (via dmaengine_terminate_all()) the channel before
|
|
||||||
using this API.
|
|
||||||
|
|
||||||
5. void dmaengine_synchronize(struct dma_chan *chan)
|
|
||||||
|
|
||||||
Synchronize the termination of the DMA channel to the current context.
|
|
||||||
|
|
||||||
This function should be used after dmaengine_terminate_async() to synchronize
|
|
||||||
the termination of the DMA channel to the current context. The function will
|
|
||||||
wait for the transfer and any running complete callbacks to finish before it
|
|
||||||
returns.
|
|
||||||
|
|
||||||
If dmaengine_terminate_async() is used to stop the DMA channel this function
|
|
||||||
must be called before it is safe to free memory accessed by previously
|
|
||||||
submitted descriptors or to free any resources accessed within the complete
|
|
||||||
callback of previously submitted descriptors.
|
|
||||||
|
|
||||||
The behavior of this function is undefined if dma_async_issue_pending() has
|
|
||||||
been called between dmaengine_terminate_async() and this function.
|
|
||||||
|
|
@ -1,424 +0,0 @@
|
||||||
DMAengine controller documentation
|
|
||||||
==================================
|
|
||||||
|
|
||||||
Hardware Introduction
|
|
||||||
+++++++++++++++++++++
|
|
||||||
|
|
||||||
Most of the Slave DMA controllers have the same general principles of
|
|
||||||
operations.
|
|
||||||
|
|
||||||
They have a given number of channels to use for the DMA transfers, and
|
|
||||||
a given number of requests lines.
|
|
||||||
|
|
||||||
Requests and channels are pretty much orthogonal. Channels can be used
|
|
||||||
to serve several to any requests. To simplify, channels are the
|
|
||||||
entities that will be doing the copy, and requests what endpoints are
|
|
||||||
involved.
|
|
||||||
|
|
||||||
The request lines actually correspond to physical lines going from the
|
|
||||||
DMA-eligible devices to the controller itself. Whenever the device
|
|
||||||
will want to start a transfer, it will assert a DMA request (DRQ) by
|
|
||||||
asserting that request line.
|
|
||||||
|
|
||||||
A very simple DMA controller would only take into account a single
|
|
||||||
parameter: the transfer size. At each clock cycle, it would transfer a
|
|
||||||
byte of data from one buffer to another, until the transfer size has
|
|
||||||
been reached.
|
|
||||||
|
|
||||||
That wouldn't work well in the real world, since slave devices might
|
|
||||||
require a specific number of bits to be transferred in a single
|
|
||||||
cycle. For example, we may want to transfer as much data as the
|
|
||||||
physical bus allows to maximize performances when doing a simple
|
|
||||||
memory copy operation, but our audio device could have a narrower FIFO
|
|
||||||
that requires data to be written exactly 16 or 24 bits at a time. This
|
|
||||||
is why most if not all of the DMA controllers can adjust this, using a
|
|
||||||
parameter called the transfer width.
|
|
||||||
|
|
||||||
Moreover, some DMA controllers, whenever the RAM is used as a source
|
|
||||||
or destination, can group the reads or writes in memory into a buffer,
|
|
||||||
so instead of having a lot of small memory accesses, which is not
|
|
||||||
really efficient, you'll get several bigger transfers. This is done
|
|
||||||
using a parameter called the burst size, that defines how many single
|
|
||||||
reads/writes it's allowed to do without the controller splitting the
|
|
||||||
transfer into smaller sub-transfers.
|
|
||||||
|
|
||||||
Our theoretical DMA controller would then only be able to do transfers
|
|
||||||
that involve a single contiguous block of data. However, some of the
|
|
||||||
transfers we usually have are not, and want to copy data from
|
|
||||||
non-contiguous buffers to a contiguous buffer, which is called
|
|
||||||
scatter-gather.
|
|
||||||
|
|
||||||
DMAEngine, at least for mem2dev transfers, require support for
|
|
||||||
scatter-gather. So we're left with two cases here: either we have a
|
|
||||||
quite simple DMA controller that doesn't support it, and we'll have to
|
|
||||||
implement it in software, or we have a more advanced DMA controller,
|
|
||||||
that implements in hardware scatter-gather.
|
|
||||||
|
|
||||||
The latter are usually programmed using a collection of chunks to
|
|
||||||
transfer, and whenever the transfer is started, the controller will go
|
|
||||||
over that collection, doing whatever we programmed there.
|
|
||||||
|
|
||||||
This collection is usually either a table or a linked list. You will
|
|
||||||
then push either the address of the table and its number of elements,
|
|
||||||
or the first item of the list to one channel of the DMA controller,
|
|
||||||
and whenever a DRQ will be asserted, it will go through the collection
|
|
||||||
to know where to fetch the data from.
|
|
||||||
|
|
||||||
Either way, the format of this collection is completely dependent on
|
|
||||||
your hardware. Each DMA controller will require a different structure,
|
|
||||||
but all of them will require, for every chunk, at least the source and
|
|
||||||
destination addresses, whether it should increment these addresses or
|
|
||||||
not and the three parameters we saw earlier: the burst size, the
|
|
||||||
transfer width and the transfer size.
|
|
||||||
|
|
||||||
The one last thing is that usually, slave devices won't issue DRQ by
|
|
||||||
default, and you have to enable this in your slave device driver first
|
|
||||||
whenever you're willing to use DMA.
|
|
||||||
|
|
||||||
These were just the general memory-to-memory (also called mem2mem) or
|
|
||||||
memory-to-device (mem2dev) kind of transfers. Most devices often
|
|
||||||
support other kind of transfers or memory operations that dmaengine
|
|
||||||
support and will be detailed later in this document.
|
|
||||||
|
|
||||||
DMA Support in Linux
|
|
||||||
++++++++++++++++++++
|
|
||||||
|
|
||||||
Historically, DMA controller drivers have been implemented using the
|
|
||||||
async TX API, to offload operations such as memory copy, XOR,
|
|
||||||
cryptography, etc., basically any memory to memory operation.
|
|
||||||
|
|
||||||
Over time, the need for memory to device transfers arose, and
|
|
||||||
dmaengine was extended. Nowadays, the async TX API is written as a
|
|
||||||
layer on top of dmaengine, and acts as a client. Still, dmaengine
|
|
||||||
accommodates that API in some cases, and made some design choices to
|
|
||||||
ensure that it stayed compatible.
|
|
||||||
|
|
||||||
For more information on the Async TX API, please look the relevant
|
|
||||||
documentation file in Documentation/crypto/async-tx-api.txt.
|
|
||||||
|
|
||||||
DMAEngine Registration
|
|
||||||
++++++++++++++++++++++
|
|
||||||
|
|
||||||
struct dma_device Initialization
|
|
||||||
--------------------------------
|
|
||||||
|
|
||||||
Just like any other kernel framework, the whole DMAEngine registration
|
|
||||||
relies on the driver filling a structure and registering against the
|
|
||||||
framework. In our case, that structure is dma_device.
|
|
||||||
|
|
||||||
The first thing you need to do in your driver is to allocate this
|
|
||||||
structure. Any of the usual memory allocators will do, but you'll also
|
|
||||||
need to initialize a few fields in there:
|
|
||||||
|
|
||||||
* channels: should be initialized as a list using the
|
|
||||||
INIT_LIST_HEAD macro for example
|
|
||||||
|
|
||||||
* src_addr_widths:
|
|
||||||
- should contain a bitmask of the supported source transfer width
|
|
||||||
|
|
||||||
* dst_addr_widths:
|
|
||||||
- should contain a bitmask of the supported destination transfer
|
|
||||||
width
|
|
||||||
|
|
||||||
* directions:
|
|
||||||
- should contain a bitmask of the supported slave directions
|
|
||||||
(i.e. excluding mem2mem transfers)
|
|
||||||
|
|
||||||
* residue_granularity:
|
|
||||||
- Granularity of the transfer residue reported to dma_set_residue.
|
|
||||||
- This can be either:
|
|
||||||
+ Descriptor
|
|
||||||
-> Your device doesn't support any kind of residue
|
|
||||||
reporting. The framework will only know that a particular
|
|
||||||
transaction descriptor is done.
|
|
||||||
+ Segment
|
|
||||||
-> Your device is able to report which chunks have been
|
|
||||||
transferred
|
|
||||||
+ Burst
|
|
||||||
-> Your device is able to report which burst have been
|
|
||||||
transferred
|
|
||||||
|
|
||||||
* dev: should hold the pointer to the struct device associated
|
|
||||||
to your current driver instance.
|
|
||||||
|
|
||||||
Supported transaction types
|
|
||||||
---------------------------
|
|
||||||
|
|
||||||
The next thing you need is to set which transaction types your device
|
|
||||||
(and driver) supports.
|
|
||||||
|
|
||||||
Our dma_device structure has a field called cap_mask that holds the
|
|
||||||
various types of transaction supported, and you need to modify this
|
|
||||||
mask using the dma_cap_set function, with various flags depending on
|
|
||||||
transaction types you support as an argument.
|
|
||||||
|
|
||||||
All those capabilities are defined in the dma_transaction_type enum,
|
|
||||||
in include/linux/dmaengine.h
|
|
||||||
|
|
||||||
Currently, the types available are:
|
|
||||||
* DMA_MEMCPY
|
|
||||||
- The device is able to do memory to memory copies
|
|
||||||
|
|
||||||
* DMA_XOR
|
|
||||||
- The device is able to perform XOR operations on memory areas
|
|
||||||
- Used to accelerate XOR intensive tasks, such as RAID5
|
|
||||||
|
|
||||||
* DMA_XOR_VAL
|
|
||||||
- The device is able to perform parity check using the XOR
|
|
||||||
algorithm against a memory buffer.
|
|
||||||
|
|
||||||
* DMA_PQ
|
|
||||||
- The device is able to perform RAID6 P+Q computations, P being a
|
|
||||||
simple XOR, and Q being a Reed-Solomon algorithm.
|
|
||||||
|
|
||||||
* DMA_PQ_VAL
|
|
||||||
- The device is able to perform parity check using RAID6 P+Q
|
|
||||||
algorithm against a memory buffer.
|
|
||||||
|
|
||||||
* DMA_INTERRUPT
|
|
||||||
- The device is able to trigger a dummy transfer that will
|
|
||||||
generate periodic interrupts
|
|
||||||
- Used by the client drivers to register a callback that will be
|
|
||||||
called on a regular basis through the DMA controller interrupt
|
|
||||||
|
|
||||||
* DMA_PRIVATE
|
|
||||||
- The devices only supports slave transfers, and as such isn't
|
|
||||||
available for async transfers.
|
|
||||||
|
|
||||||
* DMA_ASYNC_TX
|
|
||||||
- Must not be set by the device, and will be set by the framework
|
|
||||||
if needed
|
|
||||||
- /* TODO: What is it about? */
|
|
||||||
|
|
||||||
* DMA_SLAVE
|
|
||||||
- The device can handle device to memory transfers, including
|
|
||||||
scatter-gather transfers.
|
|
||||||
- While in the mem2mem case we were having two distinct types to
|
|
||||||
deal with a single chunk to copy or a collection of them, here,
|
|
||||||
we just have a single transaction type that is supposed to
|
|
||||||
handle both.
|
|
||||||
- If you want to transfer a single contiguous memory buffer,
|
|
||||||
simply build a scatter list with only one item.
|
|
||||||
|
|
||||||
* DMA_CYCLIC
|
|
||||||
- The device can handle cyclic transfers.
|
|
||||||
- A cyclic transfer is a transfer where the chunk collection will
|
|
||||||
loop over itself, with the last item pointing to the first.
|
|
||||||
- It's usually used for audio transfers, where you want to operate
|
|
||||||
on a single ring buffer that you will fill with your audio data.
|
|
||||||
|
|
||||||
* DMA_INTERLEAVE
|
|
||||||
- The device supports interleaved transfer.
|
|
||||||
- These transfers can transfer data from a non-contiguous buffer
|
|
||||||
to a non-contiguous buffer, opposed to DMA_SLAVE that can
|
|
||||||
transfer data from a non-contiguous data set to a continuous
|
|
||||||
destination buffer.
|
|
||||||
- It's usually used for 2d content transfers, in which case you
|
|
||||||
want to transfer a portion of uncompressed data directly to the
|
|
||||||
display to print it
|
|
||||||
|
|
||||||
These various types will also affect how the source and destination
|
|
||||||
addresses change over time.
|
|
||||||
|
|
||||||
Addresses pointing to RAM are typically incremented (or decremented)
|
|
||||||
after each transfer. In case of a ring buffer, they may loop
|
|
||||||
(DMA_CYCLIC). Addresses pointing to a device's register (e.g. a FIFO)
|
|
||||||
are typically fixed.
|
|
||||||
|
|
||||||
Device operations
|
|
||||||
-----------------
|
|
||||||
|
|
||||||
Our dma_device structure also requires a few function pointers in
|
|
||||||
order to implement the actual logic, now that we described what
|
|
||||||
operations we were able to perform.
|
|
||||||
|
|
||||||
The functions that we have to fill in there, and hence have to
|
|
||||||
implement, obviously depend on the transaction types you reported as
|
|
||||||
supported.
|
|
||||||
|
|
||||||
* device_alloc_chan_resources
|
|
||||||
* device_free_chan_resources
|
|
||||||
- These functions will be called whenever a driver will call
|
|
||||||
dma_request_channel or dma_release_channel for the first/last
|
|
||||||
time on the channel associated to that driver.
|
|
||||||
- They are in charge of allocating/freeing all the needed
|
|
||||||
resources in order for that channel to be useful for your
|
|
||||||
driver.
|
|
||||||
- These functions can sleep.
|
|
||||||
|
|
||||||
* device_prep_dma_*
|
|
||||||
- These functions are matching the capabilities you registered
|
|
||||||
previously.
|
|
||||||
- These functions all take the buffer or the scatterlist relevant
|
|
||||||
for the transfer being prepared, and should create a hardware
|
|
||||||
descriptor or a list of hardware descriptors from it
|
|
||||||
- These functions can be called from an interrupt context
|
|
||||||
- Any allocation you might do should be using the GFP_NOWAIT
|
|
||||||
flag, in order not to potentially sleep, but without depleting
|
|
||||||
the emergency pool either.
|
|
||||||
- Drivers should try to pre-allocate any memory they might need
|
|
||||||
during the transfer setup at probe time to avoid putting to
|
|
||||||
much pressure on the nowait allocator.
|
|
||||||
|
|
||||||
- It should return a unique instance of the
|
|
||||||
dma_async_tx_descriptor structure, that further represents this
|
|
||||||
particular transfer.
|
|
||||||
|
|
||||||
- This structure can be initialized using the function
|
|
||||||
dma_async_tx_descriptor_init.
|
|
||||||
- You'll also need to set two fields in this structure:
|
|
||||||
+ flags:
|
|
||||||
TODO: Can it be modified by the driver itself, or
|
|
||||||
should it be always the flags passed in the arguments
|
|
||||||
|
|
||||||
+ tx_submit: A pointer to a function you have to implement,
|
|
||||||
that is supposed to push the current
|
|
||||||
transaction descriptor to a pending queue, waiting
|
|
||||||
for issue_pending to be called.
|
|
||||||
- In this structure the function pointer callback_result can be
|
|
||||||
initialized in order for the submitter to be notified that a
|
|
||||||
transaction has completed. In the earlier code the function pointer
|
|
||||||
callback has been used. However it does not provide any status to the
|
|
||||||
transaction and will be deprecated. The result structure defined as
|
|
||||||
dmaengine_result that is passed in to callback_result has two fields:
|
|
||||||
+ result: This provides the transfer result defined by
|
|
||||||
dmaengine_tx_result. Either success or some error
|
|
||||||
condition.
|
|
||||||
+ residue: Provides the residue bytes of the transfer for those that
|
|
||||||
support residue.
|
|
||||||
|
|
||||||
* device_issue_pending
|
|
||||||
- Takes the first transaction descriptor in the pending queue,
|
|
||||||
and starts the transfer. Whenever that transfer is done, it
|
|
||||||
should move to the next transaction in the list.
|
|
||||||
- This function can be called in an interrupt context
|
|
||||||
|
|
||||||
* device_tx_status
|
|
||||||
- Should report the bytes left to go over on the given channel
|
|
||||||
- Should only care about the transaction descriptor passed as
|
|
||||||
argument, not the currently active one on a given channel
|
|
||||||
- The tx_state argument might be NULL
|
|
||||||
- Should use dma_set_residue to report it
|
|
||||||
- In the case of a cyclic transfer, it should only take into
|
|
||||||
account the current period.
|
|
||||||
- This function can be called in an interrupt context.
|
|
||||||
|
|
||||||
* device_config
|
|
||||||
- Reconfigures the channel with the configuration given as
|
|
||||||
argument
|
|
||||||
- This command should NOT perform synchronously, or on any
|
|
||||||
currently queued transfers, but only on subsequent ones
|
|
||||||
- In this case, the function will receive a dma_slave_config
|
|
||||||
structure pointer as an argument, that will detail which
|
|
||||||
configuration to use.
|
|
||||||
- Even though that structure contains a direction field, this
|
|
||||||
field is deprecated in favor of the direction argument given to
|
|
||||||
the prep_* functions
|
|
||||||
- This call is mandatory for slave operations only. This should NOT be
|
|
||||||
set or expected to be set for memcpy operations.
|
|
||||||
If a driver support both, it should use this call for slave
|
|
||||||
operations only and not for memcpy ones.
|
|
||||||
|
|
||||||
* device_pause
|
|
||||||
- Pauses a transfer on the channel
|
|
||||||
- This command should operate synchronously on the channel,
|
|
||||||
pausing right away the work of the given channel
|
|
||||||
|
|
||||||
* device_resume
|
|
||||||
- Resumes a transfer on the channel
|
|
||||||
- This command should operate synchronously on the channel,
|
|
||||||
resuming right away the work of the given channel
|
|
||||||
|
|
||||||
* device_terminate_all
|
|
||||||
- Aborts all the pending and ongoing transfers on the channel
|
|
||||||
- For aborted transfers the complete callback should not be called
|
|
||||||
- Can be called from atomic context or from within a complete
|
|
||||||
callback of a descriptor. Must not sleep. Drivers must be able
|
|
||||||
to handle this correctly.
|
|
||||||
- Termination may be asynchronous. The driver does not have to
|
|
||||||
wait until the currently active transfer has completely stopped.
|
|
||||||
See device_synchronize.
|
|
||||||
|
|
||||||
* device_synchronize
|
|
||||||
- Must synchronize the termination of a channel to the current
|
|
||||||
context.
|
|
||||||
- Must make sure that memory for previously submitted
|
|
||||||
descriptors is no longer accessed by the DMA controller.
|
|
||||||
- Must make sure that all complete callbacks for previously
|
|
||||||
submitted descriptors have finished running and none are
|
|
||||||
scheduled to run.
|
|
||||||
- May sleep.
|
|
||||||
|
|
||||||
|
|
||||||
Misc notes (stuff that should be documented, but don't really know
|
|
||||||
where to put them)
|
|
||||||
------------------------------------------------------------------
|
|
||||||
* dma_run_dependencies
|
|
||||||
- Should be called at the end of an async TX transfer, and can be
|
|
||||||
ignored in the slave transfers case.
|
|
||||||
- Makes sure that dependent operations are run before marking it
|
|
||||||
as complete.
|
|
||||||
|
|
||||||
* dma_cookie_t
|
|
||||||
- it's a DMA transaction ID that will increment over time.
|
|
||||||
- Not really relevant any more since the introduction of virt-dma
|
|
||||||
that abstracts it away.
|
|
||||||
|
|
||||||
* DMA_CTRL_ACK
|
|
||||||
- If clear, the descriptor cannot be reused by provider until the
|
|
||||||
client acknowledges receipt, i.e. has has a chance to establish any
|
|
||||||
dependency chains
|
|
||||||
- This can be acked by invoking async_tx_ack()
|
|
||||||
- If set, does not mean descriptor can be reused
|
|
||||||
|
|
||||||
* DMA_CTRL_REUSE
|
|
||||||
- If set, the descriptor can be reused after being completed. It should
|
|
||||||
not be freed by provider if this flag is set.
|
|
||||||
- The descriptor should be prepared for reuse by invoking
|
|
||||||
dmaengine_desc_set_reuse() which will set DMA_CTRL_REUSE.
|
|
||||||
- dmaengine_desc_set_reuse() will succeed only when channel support
|
|
||||||
reusable descriptor as exhibited by capabilities
|
|
||||||
- As a consequence, if a device driver wants to skip the dma_map_sg() and
|
|
||||||
dma_unmap_sg() in between 2 transfers, because the DMA'd data wasn't used,
|
|
||||||
it can resubmit the transfer right after its completion.
|
|
||||||
- Descriptor can be freed in few ways
|
|
||||||
- Clearing DMA_CTRL_REUSE by invoking dmaengine_desc_clear_reuse()
|
|
||||||
and submitting for last txn
|
|
||||||
- Explicitly invoking dmaengine_desc_free(), this can succeed only
|
|
||||||
when DMA_CTRL_REUSE is already set
|
|
||||||
- Terminating the channel
|
|
||||||
|
|
||||||
* DMA_PREP_CMD
|
|
||||||
- If set, the client driver tells DMA controller that passed data in DMA
|
|
||||||
API is command data.
|
|
||||||
- Interpretation of command data is DMA controller specific. It can be
|
|
||||||
used for issuing commands to other peripherals/register reads/register
|
|
||||||
writes for which the descriptor should be in different format from
|
|
||||||
normal data descriptors.
|
|
||||||
|
|
||||||
General Design Notes
|
|
||||||
--------------------
|
|
||||||
|
|
||||||
Most of the DMAEngine drivers you'll see are based on a similar design
|
|
||||||
that handles the end of transfer interrupts in the handler, but defer
|
|
||||||
most work to a tasklet, including the start of a new transfer whenever
|
|
||||||
the previous transfer ended.
|
|
||||||
|
|
||||||
This is a rather inefficient design though, because the inter-transfer
|
|
||||||
latency will be not only the interrupt latency, but also the
|
|
||||||
scheduling latency of the tasklet, which will leave the channel idle
|
|
||||||
in between, which will slow down the global transfer rate.
|
|
||||||
|
|
||||||
You should avoid this kind of practice, and instead of electing a new
|
|
||||||
transfer in your tasklet, move that part to the interrupt handler in
|
|
||||||
order to have a shorter idle window (that we can't really avoid
|
|
||||||
anyway).
|
|
||||||
|
|
||||||
Glossary
|
|
||||||
--------
|
|
||||||
|
|
||||||
Burst: A number of consecutive read or write operations
|
|
||||||
that can be queued to buffers before being flushed to
|
|
||||||
memory.
|
|
||||||
Chunk: A contiguous collection of bursts
|
|
||||||
Transfer: A collection of chunks (be it contiguous or not)
|
|
||||||
|
|
@ -1,153 +0,0 @@
|
||||||
PXA/MMP - DMA Slave controller
|
|
||||||
==============================
|
|
||||||
|
|
||||||
Constraints
|
|
||||||
-----------
|
|
||||||
a) Transfers hot queuing
|
|
||||||
A driver submitting a transfer and issuing it should be granted the transfer
|
|
||||||
is queued even on a running DMA channel.
|
|
||||||
This implies that the queuing doesn't wait for the previous transfer end,
|
|
||||||
and that the descriptor chaining is not only done in the irq/tasklet code
|
|
||||||
triggered by the end of the transfer.
|
|
||||||
A transfer which is submitted and issued on a phy doesn't wait for a phy to
|
|
||||||
stop and restart, but is submitted on a "running channel". The other
|
|
||||||
drivers, especially mmp_pdma waited for the phy to stop before relaunching
|
|
||||||
a new transfer.
|
|
||||||
|
|
||||||
b) All transfers having asked for confirmation should be signaled
|
|
||||||
Any issued transfer with DMA_PREP_INTERRUPT should trigger a callback call.
|
|
||||||
This implies that even if an irq/tasklet is triggered by end of tx1, but
|
|
||||||
at the time of irq/dma tx2 is already finished, tx1->complete() and
|
|
||||||
tx2->complete() should be called.
|
|
||||||
|
|
||||||
c) Channel running state
|
|
||||||
A driver should be able to query if a channel is running or not. For the
|
|
||||||
multimedia case, such as video capture, if a transfer is submitted and then
|
|
||||||
a check of the DMA channel reports a "stopped channel", the transfer should
|
|
||||||
not be issued until the next "start of frame interrupt", hence the need to
|
|
||||||
know if a channel is in running or stopped state.
|
|
||||||
|
|
||||||
d) Bandwidth guarantee
|
|
||||||
The PXA architecture has 4 levels of DMAs priorities : high, normal, low.
|
|
||||||
The high priorities get twice as much bandwidth as the normal, which get twice
|
|
||||||
as much as the low priorities.
|
|
||||||
A driver should be able to request a priority, especially the real-time
|
|
||||||
ones such as pxa_camera with (big) throughputs.
|
|
||||||
|
|
||||||
Design
|
|
||||||
------
|
|
||||||
a) Virtual channels
|
|
||||||
Same concept as in sa11x0 driver, ie. a driver was assigned a "virtual
|
|
||||||
channel" linked to the requestor line, and the physical DMA channel is
|
|
||||||
assigned on the fly when the transfer is issued.
|
|
||||||
|
|
||||||
b) Transfer anatomy for a scatter-gather transfer
|
|
||||||
+------------+-----+---------------+----------------+-----------------+
|
|
||||||
| desc-sg[0] | ... | desc-sg[last] | status updater | finisher/linker |
|
|
||||||
+------------+-----+---------------+----------------+-----------------+
|
|
||||||
|
|
||||||
This structure is pointed by dma->sg_cpu.
|
|
||||||
The descriptors are used as follows :
|
|
||||||
- desc-sg[i]: i-th descriptor, transferring the i-th sg
|
|
||||||
element to the video buffer scatter gather
|
|
||||||
- status updater
|
|
||||||
Transfers a single u32 to a well known dma coherent memory to leave
|
|
||||||
a trace that this transfer is done. The "well known" is unique per
|
|
||||||
physical channel, meaning that a read of this value will tell which
|
|
||||||
is the last finished transfer at that point in time.
|
|
||||||
- finisher: has ddadr=DADDR_STOP, dcmd=ENDIRQEN
|
|
||||||
- linker: has ddadr= desc-sg[0] of next transfer, dcmd=0
|
|
||||||
|
|
||||||
c) Transfers hot-chaining
|
|
||||||
Suppose the running chain is :
|
|
||||||
Buffer 1 Buffer 2
|
|
||||||
+---------+----+---+ +----+----+----+---+
|
|
||||||
| d0 | .. | dN | l | | d0 | .. | dN | f |
|
|
||||||
+---------+----+-|-+ ^----+----+----+---+
|
|
||||||
| |
|
|
||||||
+----+
|
|
||||||
|
|
||||||
After a call to dmaengine_submit(b3), the chain will look like :
|
|
||||||
Buffer 1 Buffer 2 Buffer 3
|
|
||||||
+---------+----+---+ +----+----+----+---+ +----+----+----+---+
|
|
||||||
| d0 | .. | dN | l | | d0 | .. | dN | l | | d0 | .. | dN | f |
|
|
||||||
+---------+----+-|-+ ^----+----+----+-|-+ ^----+----+----+---+
|
|
||||||
| | | |
|
|
||||||
+----+ +----+
|
|
||||||
new_link
|
|
||||||
|
|
||||||
If while new_link was created the DMA channel stopped, it is _not_
|
|
||||||
restarted. Hot-chaining doesn't break the assumption that
|
|
||||||
dma_async_issue_pending() is to be used to ensure the transfer is actually started.
|
|
||||||
|
|
||||||
One exception to this rule :
|
|
||||||
- if Buffer1 and Buffer2 had all their addresses 8 bytes aligned
|
|
||||||
- and if Buffer3 has at least one address not 4 bytes aligned
|
|
||||||
- then hot-chaining cannot happen, as the channel must be stopped, the
|
|
||||||
"align bit" must be set, and the channel restarted As a consequence,
|
|
||||||
such a transfer tx_submit() will be queued on the submitted queue, and
|
|
||||||
this specific case if the DMA is already running in aligned mode.
|
|
||||||
|
|
||||||
d) Transfers completion updater
|
|
||||||
Each time a transfer is completed on a channel, an interrupt might be
|
|
||||||
generated or not, up to the client's request. But in each case, the last
|
|
||||||
descriptor of a transfer, the "status updater", will write the latest
|
|
||||||
transfer being completed into the physical channel's completion mark.
|
|
||||||
|
|
||||||
This will speed up residue calculation, for large transfers such as video
|
|
||||||
buffers which hold around 6k descriptors or more. This also allows without
|
|
||||||
any lock to find out what is the latest completed transfer in a running
|
|
||||||
DMA chain.
|
|
||||||
|
|
||||||
e) Transfers completion, irq and tasklet
|
|
||||||
When a transfer flagged as "DMA_PREP_INTERRUPT" is finished, the dma irq
|
|
||||||
is raised. Upon this interrupt, a tasklet is scheduled for the physical
|
|
||||||
channel.
|
|
||||||
The tasklet is responsible for :
|
|
||||||
- reading the physical channel last updater mark
|
|
||||||
- calling all the transfer callbacks of finished transfers, based on
|
|
||||||
that mark, and each transfer flags.
|
|
||||||
If a transfer is completed while this handling is done, a dma irq will
|
|
||||||
be raised, and the tasklet will be scheduled once again, having a new
|
|
||||||
updater mark.
|
|
||||||
|
|
||||||
f) Residue
|
|
||||||
Residue granularity will be descriptor based. The issued but not completed
|
|
||||||
transfers will be scanned for all of their descriptors against the
|
|
||||||
currently running descriptor.
|
|
||||||
|
|
||||||
g) Most complicated case of driver's tx queues
|
|
||||||
The most tricky situation is when :
|
|
||||||
- there are not "acked" transfers (tx0)
|
|
||||||
- a driver submitted an aligned tx1, not chained
|
|
||||||
- a driver submitted an aligned tx2 => tx2 is cold chained to tx1
|
|
||||||
- a driver issued tx1+tx2 => channel is running in aligned mode
|
|
||||||
- a driver submitted an aligned tx3 => tx3 is hot-chained
|
|
||||||
- a driver submitted an unaligned tx4 => tx4 is put in submitted queue,
|
|
||||||
not chained
|
|
||||||
- a driver issued tx4 => tx4 is put in issued queue, not chained
|
|
||||||
- a driver submitted an aligned tx5 => tx5 is put in submitted queue, not
|
|
||||||
chained
|
|
||||||
- a driver submitted an aligned tx6 => tx6 is put in submitted queue,
|
|
||||||
cold chained to tx5
|
|
||||||
|
|
||||||
This translates into (after tx4 is issued) :
|
|
||||||
- issued queue
|
|
||||||
+-----+ +-----+ +-----+ +-----+
|
|
||||||
| tx1 | | tx2 | | tx3 | | tx4 |
|
|
||||||
+---|-+ ^---|-+ ^-----+ +-----+
|
|
||||||
| | | |
|
|
||||||
+---+ +---+
|
|
||||||
- submitted queue
|
|
||||||
+-----+ +-----+
|
|
||||||
| tx5 | | tx6 |
|
|
||||||
+---|-+ ^-----+
|
|
||||||
| |
|
|
||||||
+---+
|
|
||||||
- completed queue : empty
|
|
||||||
- allocated queue : tx0
|
|
||||||
|
|
||||||
It should be noted that after tx3 is completed, the channel is stopped, and
|
|
||||||
restarted in "unaligned mode" to handle tx4.
|
|
||||||
|
|
||||||
Author: Robert Jarzmik <robert.jarzmik@free.fr>
|
|
||||||
|
|
@ -65,7 +65,7 @@ Without options, the kernel-doc directive includes all documentation comments
|
||||||
from the source file.
|
from the source file.
|
||||||
|
|
||||||
The kernel-doc extension is included in the kernel source tree, at
|
The kernel-doc extension is included in the kernel source tree, at
|
||||||
``Documentation/sphinx/kernel-doc.py``. Internally, it uses the
|
``Documentation/sphinx/kerneldoc.py``. Internally, it uses the
|
||||||
``scripts/kernel-doc`` script to extract the documentation comments from the
|
``scripts/kernel-doc`` script to extract the documentation comments from the
|
||||||
source.
|
source.
|
||||||
|
|
||||||
|
|
|
||||||
275
Documentation/driver-api/dmaengine/client.rst
Normal file
275
Documentation/driver-api/dmaengine/client.rst
Normal file
|
|
@ -0,0 +1,275 @@
|
||||||
|
====================
|
||||||
|
DMA Engine API Guide
|
||||||
|
====================
|
||||||
|
|
||||||
|
Vinod Koul <vinod dot koul at intel.com>
|
||||||
|
|
||||||
|
.. note:: For DMA Engine usage in async_tx please see:
|
||||||
|
``Documentation/crypto/async-tx-api.txt``
|
||||||
|
|
||||||
|
|
||||||
|
Below is a guide to device driver writers on how to use the Slave-DMA API of the
|
||||||
|
DMA Engine. This is applicable only for slave DMA usage only.
|
||||||
|
|
||||||
|
DMA usage
|
||||||
|
=========
|
||||||
|
|
||||||
|
The slave DMA usage consists of following steps:
|
||||||
|
|
||||||
|
- Allocate a DMA slave channel
|
||||||
|
|
||||||
|
- Set slave and controller specific parameters
|
||||||
|
|
||||||
|
- Get a descriptor for transaction
|
||||||
|
|
||||||
|
- Submit the transaction
|
||||||
|
|
||||||
|
- Issue pending requests and wait for callback notification
|
||||||
|
|
||||||
|
The details of these operations are:
|
||||||
|
|
||||||
|
1. Allocate a DMA slave channel
|
||||||
|
|
||||||
|
Channel allocation is slightly different in the slave DMA context,
|
||||||
|
client drivers typically need a channel from a particular DMA
|
||||||
|
controller only and even in some cases a specific channel is desired.
|
||||||
|
To request a channel dma_request_chan() API is used.
|
||||||
|
|
||||||
|
Interface:
|
||||||
|
|
||||||
|
.. code-block:: c
|
||||||
|
|
||||||
|
struct dma_chan *dma_request_chan(struct device *dev, const char *name);
|
||||||
|
|
||||||
|
Which will find and return the ``name`` DMA channel associated with the 'dev'
|
||||||
|
device. The association is done via DT, ACPI or board file based
|
||||||
|
dma_slave_map matching table.
|
||||||
|
|
||||||
|
A channel allocated via this interface is exclusive to the caller,
|
||||||
|
until dma_release_channel() is called.
|
||||||
|
|
||||||
|
2. Set slave and controller specific parameters
|
||||||
|
|
||||||
|
Next step is always to pass some specific information to the DMA
|
||||||
|
driver. Most of the generic information which a slave DMA can use
|
||||||
|
is in struct dma_slave_config. This allows the clients to specify
|
||||||
|
DMA direction, DMA addresses, bus widths, DMA burst lengths etc
|
||||||
|
for the peripheral.
|
||||||
|
|
||||||
|
If some DMA controllers have more parameters to be sent then they
|
||||||
|
should try to embed struct dma_slave_config in their controller
|
||||||
|
specific structure. That gives flexibility to client to pass more
|
||||||
|
parameters, if required.
|
||||||
|
|
||||||
|
Interface:
|
||||||
|
|
||||||
|
.. code-block:: c
|
||||||
|
|
||||||
|
int dmaengine_slave_config(struct dma_chan *chan,
|
||||||
|
struct dma_slave_config *config)
|
||||||
|
|
||||||
|
Please see the dma_slave_config structure definition in dmaengine.h
|
||||||
|
for a detailed explanation of the struct members. Please note
|
||||||
|
that the 'direction' member will be going away as it duplicates the
|
||||||
|
direction given in the prepare call.
|
||||||
|
|
||||||
|
3. Get a descriptor for transaction
|
||||||
|
|
||||||
|
For slave usage the various modes of slave transfers supported by the
|
||||||
|
DMA-engine are:
|
||||||
|
|
||||||
|
- slave_sg: DMA a list of scatter gather buffers from/to a peripheral
|
||||||
|
|
||||||
|
- dma_cyclic: Perform a cyclic DMA operation from/to a peripheral till the
|
||||||
|
operation is explicitly stopped.
|
||||||
|
|
||||||
|
- interleaved_dma: This is common to Slave as well as M2M clients. For slave
|
||||||
|
address of devices' fifo could be already known to the driver.
|
||||||
|
Various types of operations could be expressed by setting
|
||||||
|
appropriate values to the 'dma_interleaved_template' members.
|
||||||
|
|
||||||
|
A non-NULL return of this transfer API represents a "descriptor" for
|
||||||
|
the given transaction.
|
||||||
|
|
||||||
|
Interface:
|
||||||
|
|
||||||
|
.. code-block:: c
|
||||||
|
|
||||||
|
struct dma_async_tx_descriptor *dmaengine_prep_slave_sg(
|
||||||
|
struct dma_chan *chan, struct scatterlist *sgl,
|
||||||
|
unsigned int sg_len, enum dma_data_direction direction,
|
||||||
|
unsigned long flags);
|
||||||
|
|
||||||
|
struct dma_async_tx_descriptor *dmaengine_prep_dma_cyclic(
|
||||||
|
struct dma_chan *chan, dma_addr_t buf_addr, size_t buf_len,
|
||||||
|
size_t period_len, enum dma_data_direction direction);
|
||||||
|
|
||||||
|
struct dma_async_tx_descriptor *dmaengine_prep_interleaved_dma(
|
||||||
|
struct dma_chan *chan, struct dma_interleaved_template *xt,
|
||||||
|
unsigned long flags);
|
||||||
|
|
||||||
|
The peripheral driver is expected to have mapped the scatterlist for
|
||||||
|
the DMA operation prior to calling dmaengine_prep_slave_sg(), and must
|
||||||
|
keep the scatterlist mapped until the DMA operation has completed.
|
||||||
|
The scatterlist must be mapped using the DMA struct device.
|
||||||
|
If a mapping needs to be synchronized later, dma_sync_*_for_*() must be
|
||||||
|
called using the DMA struct device, too.
|
||||||
|
So, normal setup should look like this:
|
||||||
|
|
||||||
|
.. code-block:: c
|
||||||
|
|
||||||
|
nr_sg = dma_map_sg(chan->device->dev, sgl, sg_len);
|
||||||
|
if (nr_sg == 0)
|
||||||
|
/* error */
|
||||||
|
|
||||||
|
desc = dmaengine_prep_slave_sg(chan, sgl, nr_sg, direction, flags);
|
||||||
|
|
||||||
|
Once a descriptor has been obtained, the callback information can be
|
||||||
|
added and the descriptor must then be submitted. Some DMA engine
|
||||||
|
drivers may hold a spinlock between a successful preparation and
|
||||||
|
submission so it is important that these two operations are closely
|
||||||
|
paired.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
Although the async_tx API specifies that completion callback
|
||||||
|
routines cannot submit any new operations, this is not the
|
||||||
|
case for slave/cyclic DMA.
|
||||||
|
|
||||||
|
For slave DMA, the subsequent transaction may not be available
|
||||||
|
for submission prior to callback function being invoked, so
|
||||||
|
slave DMA callbacks are permitted to prepare and submit a new
|
||||||
|
transaction.
|
||||||
|
|
||||||
|
For cyclic DMA, a callback function may wish to terminate the
|
||||||
|
DMA via dmaengine_terminate_async().
|
||||||
|
|
||||||
|
Therefore, it is important that DMA engine drivers drop any
|
||||||
|
locks before calling the callback function which may cause a
|
||||||
|
deadlock.
|
||||||
|
|
||||||
|
Note that callbacks will always be invoked from the DMA
|
||||||
|
engines tasklet, never from interrupt context.
|
||||||
|
|
||||||
|
4. Submit the transaction
|
||||||
|
|
||||||
|
Once the descriptor has been prepared and the callback information
|
||||||
|
added, it must be placed on the DMA engine drivers pending queue.
|
||||||
|
|
||||||
|
Interface:
|
||||||
|
|
||||||
|
.. code-block:: c
|
||||||
|
|
||||||
|
dma_cookie_t dmaengine_submit(struct dma_async_tx_descriptor *desc)
|
||||||
|
|
||||||
|
This returns a cookie can be used to check the progress of DMA engine
|
||||||
|
activity via other DMA engine calls not covered in this document.
|
||||||
|
|
||||||
|
dmaengine_submit() will not start the DMA operation, it merely adds
|
||||||
|
it to the pending queue. For this, see step 5, dma_async_issue_pending.
|
||||||
|
|
||||||
|
5. Issue pending DMA requests and wait for callback notification
|
||||||
|
|
||||||
|
The transactions in the pending queue can be activated by calling the
|
||||||
|
issue_pending API. If channel is idle then the first transaction in
|
||||||
|
queue is started and subsequent ones queued up.
|
||||||
|
|
||||||
|
On completion of each DMA operation, the next in queue is started and
|
||||||
|
a tasklet triggered. The tasklet will then call the client driver
|
||||||
|
completion callback routine for notification, if set.
|
||||||
|
|
||||||
|
Interface:
|
||||||
|
|
||||||
|
.. code-block:: c
|
||||||
|
|
||||||
|
void dma_async_issue_pending(struct dma_chan *chan);
|
||||||
|
|
||||||
|
Further APIs:
|
||||||
|
------------
|
||||||
|
|
||||||
|
1. Terminate APIs
|
||||||
|
|
||||||
|
.. code-block:: c
|
||||||
|
|
||||||
|
int dmaengine_terminate_sync(struct dma_chan *chan)
|
||||||
|
int dmaengine_terminate_async(struct dma_chan *chan)
|
||||||
|
int dmaengine_terminate_all(struct dma_chan *chan) /* DEPRECATED */
|
||||||
|
|
||||||
|
This causes all activity for the DMA channel to be stopped, and may
|
||||||
|
discard data in the DMA FIFO which hasn't been fully transferred.
|
||||||
|
No callback functions will be called for any incomplete transfers.
|
||||||
|
|
||||||
|
Two variants of this function are available.
|
||||||
|
|
||||||
|
dmaengine_terminate_async() might not wait until the DMA has been fully
|
||||||
|
stopped or until any running complete callbacks have finished. But it is
|
||||||
|
possible to call dmaengine_terminate_async() from atomic context or from
|
||||||
|
within a complete callback. dmaengine_synchronize() must be called before it
|
||||||
|
is safe to free the memory accessed by the DMA transfer or free resources
|
||||||
|
accessed from within the complete callback.
|
||||||
|
|
||||||
|
dmaengine_terminate_sync() will wait for the transfer and any running
|
||||||
|
complete callbacks to finish before it returns. But the function must not be
|
||||||
|
called from atomic context or from within a complete callback.
|
||||||
|
|
||||||
|
dmaengine_terminate_all() is deprecated and should not be used in new code.
|
||||||
|
|
||||||
|
2. Pause API
|
||||||
|
|
||||||
|
.. code-block:: c
|
||||||
|
|
||||||
|
int dmaengine_pause(struct dma_chan *chan)
|
||||||
|
|
||||||
|
This pauses activity on the DMA channel without data loss.
|
||||||
|
|
||||||
|
3. Resume API
|
||||||
|
|
||||||
|
.. code-block:: c
|
||||||
|
|
||||||
|
int dmaengine_resume(struct dma_chan *chan)
|
||||||
|
|
||||||
|
Resume a previously paused DMA channel. It is invalid to resume a
|
||||||
|
channel which is not currently paused.
|
||||||
|
|
||||||
|
4. Check Txn complete
|
||||||
|
|
||||||
|
.. code-block:: c
|
||||||
|
|
||||||
|
enum dma_status dma_async_is_tx_complete(struct dma_chan *chan,
|
||||||
|
dma_cookie_t cookie, dma_cookie_t *last, dma_cookie_t *used)
|
||||||
|
|
||||||
|
This can be used to check the status of the channel. Please see
|
||||||
|
the documentation in include/linux/dmaengine.h for a more complete
|
||||||
|
description of this API.
|
||||||
|
|
||||||
|
This can be used in conjunction with dma_async_is_complete() and
|
||||||
|
the cookie returned from dmaengine_submit() to check for
|
||||||
|
completion of a specific DMA transaction.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
Not all DMA engine drivers can return reliable information for
|
||||||
|
a running DMA channel. It is recommended that DMA engine users
|
||||||
|
pause or stop (via dmaengine_terminate_all()) the channel before
|
||||||
|
using this API.
|
||||||
|
|
||||||
|
5. Synchronize termination API
|
||||||
|
|
||||||
|
.. code-block:: c
|
||||||
|
|
||||||
|
void dmaengine_synchronize(struct dma_chan *chan)
|
||||||
|
|
||||||
|
Synchronize the termination of the DMA channel to the current context.
|
||||||
|
|
||||||
|
This function should be used after dmaengine_terminate_async() to synchronize
|
||||||
|
the termination of the DMA channel to the current context. The function will
|
||||||
|
wait for the transfer and any running complete callbacks to finish before it
|
||||||
|
returns.
|
||||||
|
|
||||||
|
If dmaengine_terminate_async() is used to stop the DMA channel this function
|
||||||
|
must be called before it is safe to free memory accessed by previously
|
||||||
|
submitted descriptors or to free any resources accessed within the complete
|
||||||
|
callback of previously submitted descriptors.
|
||||||
|
|
||||||
|
The behavior of this function is undefined if dma_async_issue_pending() has
|
||||||
|
been called between dmaengine_terminate_async() and this function.
|
||||||
|
|
@ -1,11 +1,13 @@
|
||||||
DMA Test Guide
|
==============
|
||||||
==============
|
DMA Test Guide
|
||||||
|
==============
|
||||||
|
|
||||||
Andy Shevchenko <andriy.shevchenko@linux.intel.com>
|
Andy Shevchenko <andriy.shevchenko@linux.intel.com>
|
||||||
|
|
||||||
This small document introduces how to test DMA drivers using dmatest module.
|
This small document introduces how to test DMA drivers using dmatest module.
|
||||||
|
|
||||||
Part 1 - How to build the test module
|
Part 1 - How to build the test module
|
||||||
|
=====================================
|
||||||
|
|
||||||
The menuconfig contains an option that could be found by following path:
|
The menuconfig contains an option that could be found by following path:
|
||||||
Device Drivers -> DMA Engine support -> DMA Test client
|
Device Drivers -> DMA Engine support -> DMA Test client
|
||||||
|
|
@ -13,25 +15,31 @@ The menuconfig contains an option that could be found by following path:
|
||||||
In the configuration file the option called CONFIG_DMATEST. The dmatest could
|
In the configuration file the option called CONFIG_DMATEST. The dmatest could
|
||||||
be built as module or inside kernel. Let's consider those cases.
|
be built as module or inside kernel. Let's consider those cases.
|
||||||
|
|
||||||
Part 2 - When dmatest is built as a module...
|
Part 2 - When dmatest is built as a module
|
||||||
|
==========================================
|
||||||
|
|
||||||
Example of usage:
|
Example of usage: ::
|
||||||
% modprobe dmatest channel=dma0chan0 timeout=2000 iterations=1 run=1
|
|
||||||
|
|
||||||
...or:
|
% modprobe dmatest channel=dma0chan0 timeout=2000 iterations=1 run=1
|
||||||
% modprobe dmatest
|
|
||||||
% echo dma0chan0 > /sys/module/dmatest/parameters/channel
|
|
||||||
% echo 2000 > /sys/module/dmatest/parameters/timeout
|
|
||||||
% echo 1 > /sys/module/dmatest/parameters/iterations
|
|
||||||
% echo 1 > /sys/module/dmatest/parameters/run
|
|
||||||
|
|
||||||
...or on the kernel command line:
|
...or: ::
|
||||||
|
|
||||||
dmatest.channel=dma0chan0 dmatest.timeout=2000 dmatest.iterations=1 dmatest.run=1
|
% modprobe dmatest
|
||||||
|
% echo dma0chan0 > /sys/module/dmatest/parameters/channel
|
||||||
|
% echo 2000 > /sys/module/dmatest/parameters/timeout
|
||||||
|
% echo 1 > /sys/module/dmatest/parameters/iterations
|
||||||
|
% echo 1 > /sys/module/dmatest/parameters/run
|
||||||
|
|
||||||
Hint: available channel list could be extracted by running the following
|
...or on the kernel command line: ::
|
||||||
command:
|
|
||||||
% ls -1 /sys/class/dma/
|
dmatest.channel=dma0chan0 dmatest.timeout=2000 dmatest.iterations=1 dmatest.run=1
|
||||||
|
|
||||||
|
..hint:: available channel list could be extracted by running the following
|
||||||
|
command:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
% ls -1 /sys/class/dma/
|
||||||
|
|
||||||
Once started a message like "dmatest: Started 1 threads using dma0chan0" is
|
Once started a message like "dmatest: Started 1 threads using dma0chan0" is
|
||||||
emitted. After that only test failure messages are reported until the test
|
emitted. After that only test failure messages are reported until the test
|
||||||
|
|
@ -39,8 +47,9 @@ stops.
|
||||||
|
|
||||||
Note that running a new test will not stop any in progress test.
|
Note that running a new test will not stop any in progress test.
|
||||||
|
|
||||||
The following command returns the state of the test.
|
The following command returns the state of the test. ::
|
||||||
% cat /sys/module/dmatest/parameters/run
|
|
||||||
|
% cat /sys/module/dmatest/parameters/run
|
||||||
|
|
||||||
To wait for test completion userpace can poll 'run' until it is false, or use
|
To wait for test completion userpace can poll 'run' until it is false, or use
|
||||||
the wait parameter. Specifying 'wait=1' when loading the module causes module
|
the wait parameter. Specifying 'wait=1' when loading the module causes module
|
||||||
|
|
@ -50,15 +59,19 @@ before returning. For example, the following scripts wait for 42 tests
|
||||||
to complete before exiting. Note that if 'iterations' is set to 'infinite' then
|
to complete before exiting. Note that if 'iterations' is set to 'infinite' then
|
||||||
waiting is disabled.
|
waiting is disabled.
|
||||||
|
|
||||||
Example:
|
Example: ::
|
||||||
% modprobe dmatest run=1 iterations=42 wait=1
|
|
||||||
% modprobe -r dmatest
|
|
||||||
...or:
|
|
||||||
% modprobe dmatest run=1 iterations=42
|
|
||||||
% cat /sys/module/dmatest/parameters/wait
|
|
||||||
% modprobe -r dmatest
|
|
||||||
|
|
||||||
Part 3 - When built-in in the kernel...
|
% modprobe dmatest run=1 iterations=42 wait=1
|
||||||
|
% modprobe -r dmatest
|
||||||
|
|
||||||
|
...or: ::
|
||||||
|
|
||||||
|
% modprobe dmatest run=1 iterations=42
|
||||||
|
% cat /sys/module/dmatest/parameters/wait
|
||||||
|
% modprobe -r dmatest
|
||||||
|
|
||||||
|
Part 3 - When built-in in the kernel
|
||||||
|
====================================
|
||||||
|
|
||||||
The module parameters that is supplied to the kernel command line will be used
|
The module parameters that is supplied to the kernel command line will be used
|
||||||
for the first performed test. After user gets a control, the test could be
|
for the first performed test. After user gets a control, the test could be
|
||||||
|
|
@ -66,27 +79,32 @@ re-run with the same or different parameters. For the details see the above
|
||||||
section "Part 2 - When dmatest is built as a module..."
|
section "Part 2 - When dmatest is built as a module..."
|
||||||
|
|
||||||
In both cases the module parameters are used as the actual values for the test
|
In both cases the module parameters are used as the actual values for the test
|
||||||
case. You always could check them at run-time by running
|
case. You always could check them at run-time by running ::
|
||||||
% grep -H . /sys/module/dmatest/parameters/*
|
|
||||||
|
|
||||||
Part 4 - Gathering the test results
|
% grep -H . /sys/module/dmatest/parameters/*
|
||||||
|
|
||||||
Test results are printed to the kernel log buffer with the format:
|
Part 4 - Gathering the test results
|
||||||
|
===================================
|
||||||
|
|
||||||
"dmatest: result <channel>: <test id>: '<error msg>' with src_off=<val> dst_off=<val> len=<val> (<err code>)"
|
Test results are printed to the kernel log buffer with the format: ::
|
||||||
|
|
||||||
Example of output:
|
"dmatest: result <channel>: <test id>: '<error msg>' with src_off=<val> dst_off=<val> len=<val> (<err code>)"
|
||||||
% dmesg | tail -n 1
|
|
||||||
dmatest: result dma0chan0-copy0: #1: No errors with src_off=0x7bf dst_off=0x8ad len=0x3fea (0)
|
Example of output: ::
|
||||||
|
|
||||||
|
|
||||||
|
% dmesg | tail -n 1
|
||||||
|
dmatest: result dma0chan0-copy0: #1: No errors with src_off=0x7bf dst_off=0x8ad len=0x3fea (0)
|
||||||
|
|
||||||
The message format is unified across the different types of errors. A number in
|
The message format is unified across the different types of errors. A number in
|
||||||
the parens represents additional information, e.g. error code, error counter,
|
the parens represents additional information, e.g. error code, error counter,
|
||||||
or status. A test thread also emits a summary line at completion listing the
|
or status. A test thread also emits a summary line at completion listing the
|
||||||
number of tests executed, number that failed, and a result code.
|
number of tests executed, number that failed, and a result code.
|
||||||
|
|
||||||
Example:
|
Example: ::
|
||||||
% dmesg | tail -n 1
|
|
||||||
dmatest: dma0chan0-copy0: summary 1 test, 0 failures 1000 iops 100000 KB/s (0)
|
% dmesg | tail -n 1
|
||||||
|
dmatest: dma0chan0-copy0: summary 1 test, 0 failures 1000 iops 100000 KB/s (0)
|
||||||
|
|
||||||
The details of a data miscompare error are also emitted, but do not follow the
|
The details of a data miscompare error are also emitted, but do not follow the
|
||||||
above format.
|
above format.
|
||||||
55
Documentation/driver-api/dmaengine/index.rst
Normal file
55
Documentation/driver-api/dmaengine/index.rst
Normal file
|
|
@ -0,0 +1,55 @@
|
||||||
|
=======================
|
||||||
|
DMAEngine documentation
|
||||||
|
=======================
|
||||||
|
|
||||||
|
DMAEngine documentation provides documents for various aspects of DMAEngine
|
||||||
|
framework.
|
||||||
|
|
||||||
|
DMAEngine documentation
|
||||||
|
-----------------------
|
||||||
|
|
||||||
|
This book helps with DMAengine internal APIs and guide for DMAEngine device
|
||||||
|
driver writers.
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 1
|
||||||
|
|
||||||
|
provider
|
||||||
|
|
||||||
|
DMAEngine client documentation
|
||||||
|
------------------------------
|
||||||
|
|
||||||
|
This book is a guide to device driver writers on how to use the Slave-DMA
|
||||||
|
API of the DMAEngine. This is applicable only for slave DMA usage only.
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 1
|
||||||
|
|
||||||
|
client
|
||||||
|
|
||||||
|
DMA Test documentation
|
||||||
|
----------------------
|
||||||
|
|
||||||
|
This book introduces how to test DMA drivers using dmatest module.
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 1
|
||||||
|
|
||||||
|
dmatest
|
||||||
|
|
||||||
|
PXA DMA documentation
|
||||||
|
----------------------
|
||||||
|
|
||||||
|
This book adds some notes about PXA DMA
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 1
|
||||||
|
|
||||||
|
pxa_dma
|
||||||
|
|
||||||
|
.. only:: subproject
|
||||||
|
|
||||||
|
Indices
|
||||||
|
=======
|
||||||
|
|
||||||
|
* :ref:`genindex`
|
||||||
508
Documentation/driver-api/dmaengine/provider.rst
Normal file
508
Documentation/driver-api/dmaengine/provider.rst
Normal file
|
|
@ -0,0 +1,508 @@
|
||||||
|
==================================
|
||||||
|
DMAengine controller documentation
|
||||||
|
==================================
|
||||||
|
|
||||||
|
Hardware Introduction
|
||||||
|
=====================
|
||||||
|
|
||||||
|
Most of the Slave DMA controllers have the same general principles of
|
||||||
|
operations.
|
||||||
|
|
||||||
|
They have a given number of channels to use for the DMA transfers, and
|
||||||
|
a given number of requests lines.
|
||||||
|
|
||||||
|
Requests and channels are pretty much orthogonal. Channels can be used
|
||||||
|
to serve several to any requests. To simplify, channels are the
|
||||||
|
entities that will be doing the copy, and requests what endpoints are
|
||||||
|
involved.
|
||||||
|
|
||||||
|
The request lines actually correspond to physical lines going from the
|
||||||
|
DMA-eligible devices to the controller itself. Whenever the device
|
||||||
|
will want to start a transfer, it will assert a DMA request (DRQ) by
|
||||||
|
asserting that request line.
|
||||||
|
|
||||||
|
A very simple DMA controller would only take into account a single
|
||||||
|
parameter: the transfer size. At each clock cycle, it would transfer a
|
||||||
|
byte of data from one buffer to another, until the transfer size has
|
||||||
|
been reached.
|
||||||
|
|
||||||
|
That wouldn't work well in the real world, since slave devices might
|
||||||
|
require a specific number of bits to be transferred in a single
|
||||||
|
cycle. For example, we may want to transfer as much data as the
|
||||||
|
physical bus allows to maximize performances when doing a simple
|
||||||
|
memory copy operation, but our audio device could have a narrower FIFO
|
||||||
|
that requires data to be written exactly 16 or 24 bits at a time. This
|
||||||
|
is why most if not all of the DMA controllers can adjust this, using a
|
||||||
|
parameter called the transfer width.
|
||||||
|
|
||||||
|
Moreover, some DMA controllers, whenever the RAM is used as a source
|
||||||
|
or destination, can group the reads or writes in memory into a buffer,
|
||||||
|
so instead of having a lot of small memory accesses, which is not
|
||||||
|
really efficient, you'll get several bigger transfers. This is done
|
||||||
|
using a parameter called the burst size, that defines how many single
|
||||||
|
reads/writes it's allowed to do without the controller splitting the
|
||||||
|
transfer into smaller sub-transfers.
|
||||||
|
|
||||||
|
Our theoretical DMA controller would then only be able to do transfers
|
||||||
|
that involve a single contiguous block of data. However, some of the
|
||||||
|
transfers we usually have are not, and want to copy data from
|
||||||
|
non-contiguous buffers to a contiguous buffer, which is called
|
||||||
|
scatter-gather.
|
||||||
|
|
||||||
|
DMAEngine, at least for mem2dev transfers, require support for
|
||||||
|
scatter-gather. So we're left with two cases here: either we have a
|
||||||
|
quite simple DMA controller that doesn't support it, and we'll have to
|
||||||
|
implement it in software, or we have a more advanced DMA controller,
|
||||||
|
that implements in hardware scatter-gather.
|
||||||
|
|
||||||
|
The latter are usually programmed using a collection of chunks to
|
||||||
|
transfer, and whenever the transfer is started, the controller will go
|
||||||
|
over that collection, doing whatever we programmed there.
|
||||||
|
|
||||||
|
This collection is usually either a table or a linked list. You will
|
||||||
|
then push either the address of the table and its number of elements,
|
||||||
|
or the first item of the list to one channel of the DMA controller,
|
||||||
|
and whenever a DRQ will be asserted, it will go through the collection
|
||||||
|
to know where to fetch the data from.
|
||||||
|
|
||||||
|
Either way, the format of this collection is completely dependent on
|
||||||
|
your hardware. Each DMA controller will require a different structure,
|
||||||
|
but all of them will require, for every chunk, at least the source and
|
||||||
|
destination addresses, whether it should increment these addresses or
|
||||||
|
not and the three parameters we saw earlier: the burst size, the
|
||||||
|
transfer width and the transfer size.
|
||||||
|
|
||||||
|
The one last thing is that usually, slave devices won't issue DRQ by
|
||||||
|
default, and you have to enable this in your slave device driver first
|
||||||
|
whenever you're willing to use DMA.
|
||||||
|
|
||||||
|
These were just the general memory-to-memory (also called mem2mem) or
|
||||||
|
memory-to-device (mem2dev) kind of transfers. Most devices often
|
||||||
|
support other kind of transfers or memory operations that dmaengine
|
||||||
|
support and will be detailed later in this document.
|
||||||
|
|
||||||
|
DMA Support in Linux
|
||||||
|
====================
|
||||||
|
|
||||||
|
Historically, DMA controller drivers have been implemented using the
|
||||||
|
async TX API, to offload operations such as memory copy, XOR,
|
||||||
|
cryptography, etc., basically any memory to memory operation.
|
||||||
|
|
||||||
|
Over time, the need for memory to device transfers arose, and
|
||||||
|
dmaengine was extended. Nowadays, the async TX API is written as a
|
||||||
|
layer on top of dmaengine, and acts as a client. Still, dmaengine
|
||||||
|
accommodates that API in some cases, and made some design choices to
|
||||||
|
ensure that it stayed compatible.
|
||||||
|
|
||||||
|
For more information on the Async TX API, please look the relevant
|
||||||
|
documentation file in Documentation/crypto/async-tx-api.txt.
|
||||||
|
|
||||||
|
DMAEngine APIs
|
||||||
|
==============
|
||||||
|
|
||||||
|
``struct dma_device`` Initialization
|
||||||
|
------------------------------------
|
||||||
|
|
||||||
|
Just like any other kernel framework, the whole DMAEngine registration
|
||||||
|
relies on the driver filling a structure and registering against the
|
||||||
|
framework. In our case, that structure is dma_device.
|
||||||
|
|
||||||
|
The first thing you need to do in your driver is to allocate this
|
||||||
|
structure. Any of the usual memory allocators will do, but you'll also
|
||||||
|
need to initialize a few fields in there:
|
||||||
|
|
||||||
|
- channels: should be initialized as a list using the
|
||||||
|
INIT_LIST_HEAD macro for example
|
||||||
|
|
||||||
|
- src_addr_widths:
|
||||||
|
should contain a bitmask of the supported source transfer width
|
||||||
|
|
||||||
|
- dst_addr_widths:
|
||||||
|
should contain a bitmask of the supported destination transfer width
|
||||||
|
|
||||||
|
- directions:
|
||||||
|
should contain a bitmask of the supported slave directions
|
||||||
|
(i.e. excluding mem2mem transfers)
|
||||||
|
|
||||||
|
- residue_granularity:
|
||||||
|
|
||||||
|
- Granularity of the transfer residue reported to dma_set_residue.
|
||||||
|
This can be either:
|
||||||
|
|
||||||
|
- Descriptor
|
||||||
|
|
||||||
|
- Your device doesn't support any kind of residue
|
||||||
|
reporting. The framework will only know that a particular
|
||||||
|
transaction descriptor is done.
|
||||||
|
|
||||||
|
- Segment
|
||||||
|
|
||||||
|
- Your device is able to report which chunks have been transferred
|
||||||
|
|
||||||
|
- Burst
|
||||||
|
|
||||||
|
- Your device is able to report which burst have been transferred
|
||||||
|
|
||||||
|
- dev: should hold the pointer to the ``struct device`` associated
|
||||||
|
to your current driver instance.
|
||||||
|
|
||||||
|
Supported transaction types
|
||||||
|
---------------------------
|
||||||
|
|
||||||
|
The next thing you need is to set which transaction types your device
|
||||||
|
(and driver) supports.
|
||||||
|
|
||||||
|
Our ``dma_device structure`` has a field called cap_mask that holds the
|
||||||
|
various types of transaction supported, and you need to modify this
|
||||||
|
mask using the dma_cap_set function, with various flags depending on
|
||||||
|
transaction types you support as an argument.
|
||||||
|
|
||||||
|
All those capabilities are defined in the ``dma_transaction_type enum``,
|
||||||
|
in ``include/linux/dmaengine.h``
|
||||||
|
|
||||||
|
Currently, the types available are:
|
||||||
|
|
||||||
|
- DMA_MEMCPY
|
||||||
|
|
||||||
|
- The device is able to do memory to memory copies
|
||||||
|
|
||||||
|
- DMA_XOR
|
||||||
|
|
||||||
|
- The device is able to perform XOR operations on memory areas
|
||||||
|
|
||||||
|
- Used to accelerate XOR intensive tasks, such as RAID5
|
||||||
|
|
||||||
|
- DMA_XOR_VAL
|
||||||
|
|
||||||
|
- The device is able to perform parity check using the XOR
|
||||||
|
algorithm against a memory buffer.
|
||||||
|
|
||||||
|
- DMA_PQ
|
||||||
|
|
||||||
|
- The device is able to perform RAID6 P+Q computations, P being a
|
||||||
|
simple XOR, and Q being a Reed-Solomon algorithm.
|
||||||
|
|
||||||
|
- DMA_PQ_VAL
|
||||||
|
|
||||||
|
- The device is able to perform parity check using RAID6 P+Q
|
||||||
|
algorithm against a memory buffer.
|
||||||
|
|
||||||
|
- DMA_INTERRUPT
|
||||||
|
|
||||||
|
- The device is able to trigger a dummy transfer that will
|
||||||
|
generate periodic interrupts
|
||||||
|
|
||||||
|
- Used by the client drivers to register a callback that will be
|
||||||
|
called on a regular basis through the DMA controller interrupt
|
||||||
|
|
||||||
|
- DMA_PRIVATE
|
||||||
|
|
||||||
|
- The devices only supports slave transfers, and as such isn't
|
||||||
|
available for async transfers.
|
||||||
|
|
||||||
|
- DMA_ASYNC_TX
|
||||||
|
|
||||||
|
- Must not be set by the device, and will be set by the framework
|
||||||
|
if needed
|
||||||
|
|
||||||
|
- TODO: What is it about?
|
||||||
|
|
||||||
|
- DMA_SLAVE
|
||||||
|
|
||||||
|
- The device can handle device to memory transfers, including
|
||||||
|
scatter-gather transfers.
|
||||||
|
|
||||||
|
- While in the mem2mem case we were having two distinct types to
|
||||||
|
deal with a single chunk to copy or a collection of them, here,
|
||||||
|
we just have a single transaction type that is supposed to
|
||||||
|
handle both.
|
||||||
|
|
||||||
|
- If you want to transfer a single contiguous memory buffer,
|
||||||
|
simply build a scatter list with only one item.
|
||||||
|
|
||||||
|
- DMA_CYCLIC
|
||||||
|
|
||||||
|
- The device can handle cyclic transfers.
|
||||||
|
|
||||||
|
- A cyclic transfer is a transfer where the chunk collection will
|
||||||
|
loop over itself, with the last item pointing to the first.
|
||||||
|
|
||||||
|
- It's usually used for audio transfers, where you want to operate
|
||||||
|
on a single ring buffer that you will fill with your audio data.
|
||||||
|
|
||||||
|
- DMA_INTERLEAVE
|
||||||
|
|
||||||
|
- The device supports interleaved transfer.
|
||||||
|
|
||||||
|
- These transfers can transfer data from a non-contiguous buffer
|
||||||
|
to a non-contiguous buffer, opposed to DMA_SLAVE that can
|
||||||
|
transfer data from a non-contiguous data set to a continuous
|
||||||
|
destination buffer.
|
||||||
|
|
||||||
|
- It's usually used for 2d content transfers, in which case you
|
||||||
|
want to transfer a portion of uncompressed data directly to the
|
||||||
|
display to print it
|
||||||
|
|
||||||
|
These various types will also affect how the source and destination
|
||||||
|
addresses change over time.
|
||||||
|
|
||||||
|
Addresses pointing to RAM are typically incremented (or decremented)
|
||||||
|
after each transfer. In case of a ring buffer, they may loop
|
||||||
|
(DMA_CYCLIC). Addresses pointing to a device's register (e.g. a FIFO)
|
||||||
|
are typically fixed.
|
||||||
|
|
||||||
|
Device operations
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
Our dma_device structure also requires a few function pointers in
|
||||||
|
order to implement the actual logic, now that we described what
|
||||||
|
operations we were able to perform.
|
||||||
|
|
||||||
|
The functions that we have to fill in there, and hence have to
|
||||||
|
implement, obviously depend on the transaction types you reported as
|
||||||
|
supported.
|
||||||
|
|
||||||
|
- ``device_alloc_chan_resources``
|
||||||
|
|
||||||
|
- ``device_free_chan_resources``
|
||||||
|
|
||||||
|
- These functions will be called whenever a driver will call
|
||||||
|
``dma_request_channel`` or ``dma_release_channel`` for the first/last
|
||||||
|
time on the channel associated to that driver.
|
||||||
|
|
||||||
|
- They are in charge of allocating/freeing all the needed
|
||||||
|
resources in order for that channel to be useful for your driver.
|
||||||
|
|
||||||
|
- These functions can sleep.
|
||||||
|
|
||||||
|
- ``device_prep_dma_*``
|
||||||
|
|
||||||
|
- These functions are matching the capabilities you registered
|
||||||
|
previously.
|
||||||
|
|
||||||
|
- These functions all take the buffer or the scatterlist relevant
|
||||||
|
for the transfer being prepared, and should create a hardware
|
||||||
|
descriptor or a list of hardware descriptors from it
|
||||||
|
|
||||||
|
- These functions can be called from an interrupt context
|
||||||
|
|
||||||
|
- Any allocation you might do should be using the GFP_NOWAIT
|
||||||
|
flag, in order not to potentially sleep, but without depleting
|
||||||
|
the emergency pool either.
|
||||||
|
|
||||||
|
- Drivers should try to pre-allocate any memory they might need
|
||||||
|
during the transfer setup at probe time to avoid putting to
|
||||||
|
much pressure on the nowait allocator.
|
||||||
|
|
||||||
|
- It should return a unique instance of the
|
||||||
|
``dma_async_tx_descriptor structure``, that further represents this
|
||||||
|
particular transfer.
|
||||||
|
|
||||||
|
- This structure can be initialized using the function
|
||||||
|
``dma_async_tx_descriptor_init``.
|
||||||
|
|
||||||
|
- You'll also need to set two fields in this structure:
|
||||||
|
|
||||||
|
- flags:
|
||||||
|
TODO: Can it be modified by the driver itself, or
|
||||||
|
should it be always the flags passed in the arguments
|
||||||
|
|
||||||
|
- tx_submit: A pointer to a function you have to implement,
|
||||||
|
that is supposed to push the current transaction descriptor to a
|
||||||
|
pending queue, waiting for issue_pending to be called.
|
||||||
|
|
||||||
|
- In this structure the function pointer callback_result can be
|
||||||
|
initialized in order for the submitter to be notified that a
|
||||||
|
transaction has completed. In the earlier code the function pointer
|
||||||
|
callback has been used. However it does not provide any status to the
|
||||||
|
transaction and will be deprecated. The result structure defined as
|
||||||
|
``dmaengine_result`` that is passed in to callback_result
|
||||||
|
has two fields:
|
||||||
|
|
||||||
|
- result: This provides the transfer result defined by
|
||||||
|
``dmaengine_tx_result``. Either success or some error condition.
|
||||||
|
|
||||||
|
- residue: Provides the residue bytes of the transfer for those that
|
||||||
|
support residue.
|
||||||
|
|
||||||
|
- ``device_issue_pending``
|
||||||
|
|
||||||
|
- Takes the first transaction descriptor in the pending queue,
|
||||||
|
and starts the transfer. Whenever that transfer is done, it
|
||||||
|
should move to the next transaction in the list.
|
||||||
|
|
||||||
|
- This function can be called in an interrupt context
|
||||||
|
|
||||||
|
- ``device_tx_status``
|
||||||
|
|
||||||
|
- Should report the bytes left to go over on the given channel
|
||||||
|
|
||||||
|
- Should only care about the transaction descriptor passed as
|
||||||
|
argument, not the currently active one on a given channel
|
||||||
|
|
||||||
|
- The tx_state argument might be NULL
|
||||||
|
|
||||||
|
- Should use dma_set_residue to report it
|
||||||
|
|
||||||
|
- In the case of a cyclic transfer, it should only take into
|
||||||
|
account the current period.
|
||||||
|
|
||||||
|
- This function can be called in an interrupt context.
|
||||||
|
|
||||||
|
- device_config
|
||||||
|
|
||||||
|
- Reconfigures the channel with the configuration given as argument
|
||||||
|
|
||||||
|
- This command should NOT perform synchronously, or on any
|
||||||
|
currently queued transfers, but only on subsequent ones
|
||||||
|
|
||||||
|
- In this case, the function will receive a ``dma_slave_config``
|
||||||
|
structure pointer as an argument, that will detail which
|
||||||
|
configuration to use.
|
||||||
|
|
||||||
|
- Even though that structure contains a direction field, this
|
||||||
|
field is deprecated in favor of the direction argument given to
|
||||||
|
the prep_* functions
|
||||||
|
|
||||||
|
- This call is mandatory for slave operations only. This should NOT be
|
||||||
|
set or expected to be set for memcpy operations.
|
||||||
|
If a driver support both, it should use this call for slave
|
||||||
|
operations only and not for memcpy ones.
|
||||||
|
|
||||||
|
- device_pause
|
||||||
|
|
||||||
|
- Pauses a transfer on the channel
|
||||||
|
|
||||||
|
- This command should operate synchronously on the channel,
|
||||||
|
pausing right away the work of the given channel
|
||||||
|
|
||||||
|
- device_resume
|
||||||
|
|
||||||
|
- Resumes a transfer on the channel
|
||||||
|
|
||||||
|
- This command should operate synchronously on the channel,
|
||||||
|
resuming right away the work of the given channel
|
||||||
|
|
||||||
|
- device_terminate_all
|
||||||
|
|
||||||
|
- Aborts all the pending and ongoing transfers on the channel
|
||||||
|
|
||||||
|
- For aborted transfers the complete callback should not be called
|
||||||
|
|
||||||
|
- Can be called from atomic context or from within a complete
|
||||||
|
callback of a descriptor. Must not sleep. Drivers must be able
|
||||||
|
to handle this correctly.
|
||||||
|
|
||||||
|
- Termination may be asynchronous. The driver does not have to
|
||||||
|
wait until the currently active transfer has completely stopped.
|
||||||
|
See device_synchronize.
|
||||||
|
|
||||||
|
- device_synchronize
|
||||||
|
|
||||||
|
- Must synchronize the termination of a channel to the current
|
||||||
|
context.
|
||||||
|
|
||||||
|
- Must make sure that memory for previously submitted
|
||||||
|
descriptors is no longer accessed by the DMA controller.
|
||||||
|
|
||||||
|
- Must make sure that all complete callbacks for previously
|
||||||
|
submitted descriptors have finished running and none are
|
||||||
|
scheduled to run.
|
||||||
|
|
||||||
|
- May sleep.
|
||||||
|
|
||||||
|
|
||||||
|
Misc notes
|
||||||
|
==========
|
||||||
|
|
||||||
|
(stuff that should be documented, but don't really know
|
||||||
|
where to put them)
|
||||||
|
|
||||||
|
``dma_run_dependencies``
|
||||||
|
|
||||||
|
- Should be called at the end of an async TX transfer, and can be
|
||||||
|
ignored in the slave transfers case.
|
||||||
|
|
||||||
|
- Makes sure that dependent operations are run before marking it
|
||||||
|
as complete.
|
||||||
|
|
||||||
|
dma_cookie_t
|
||||||
|
|
||||||
|
- it's a DMA transaction ID that will increment over time.
|
||||||
|
|
||||||
|
- Not really relevant any more since the introduction of ``virt-dma``
|
||||||
|
that abstracts it away.
|
||||||
|
|
||||||
|
DMA_CTRL_ACK
|
||||||
|
|
||||||
|
- If clear, the descriptor cannot be reused by provider until the
|
||||||
|
client acknowledges receipt, i.e. has has a chance to establish any
|
||||||
|
dependency chains
|
||||||
|
|
||||||
|
- This can be acked by invoking async_tx_ack()
|
||||||
|
|
||||||
|
- If set, does not mean descriptor can be reused
|
||||||
|
|
||||||
|
DMA_CTRL_REUSE
|
||||||
|
|
||||||
|
- If set, the descriptor can be reused after being completed. It should
|
||||||
|
not be freed by provider if this flag is set.
|
||||||
|
|
||||||
|
- The descriptor should be prepared for reuse by invoking
|
||||||
|
``dmaengine_desc_set_reuse()`` which will set DMA_CTRL_REUSE.
|
||||||
|
|
||||||
|
- ``dmaengine_desc_set_reuse()`` will succeed only when channel support
|
||||||
|
reusable descriptor as exhibited by capabilities
|
||||||
|
|
||||||
|
- As a consequence, if a device driver wants to skip the
|
||||||
|
``dma_map_sg()`` and ``dma_unmap_sg()`` in between 2 transfers,
|
||||||
|
because the DMA'd data wasn't used, it can resubmit the transfer right after
|
||||||
|
its completion.
|
||||||
|
|
||||||
|
- Descriptor can be freed in few ways
|
||||||
|
|
||||||
|
- Clearing DMA_CTRL_REUSE by invoking
|
||||||
|
``dmaengine_desc_clear_reuse()`` and submitting for last txn
|
||||||
|
|
||||||
|
- Explicitly invoking ``dmaengine_desc_free()``, this can succeed only
|
||||||
|
when DMA_CTRL_REUSE is already set
|
||||||
|
|
||||||
|
- Terminating the channel
|
||||||
|
|
||||||
|
- DMA_PREP_CMD
|
||||||
|
|
||||||
|
- If set, the client driver tells DMA controller that passed data in DMA
|
||||||
|
API is command data.
|
||||||
|
|
||||||
|
- Interpretation of command data is DMA controller specific. It can be
|
||||||
|
used for issuing commands to other peripherals/register reads/register
|
||||||
|
writes for which the descriptor should be in different format from
|
||||||
|
normal data descriptors.
|
||||||
|
|
||||||
|
General Design Notes
|
||||||
|
====================
|
||||||
|
|
||||||
|
Most of the DMAEngine drivers you'll see are based on a similar design
|
||||||
|
that handles the end of transfer interrupts in the handler, but defer
|
||||||
|
most work to a tasklet, including the start of a new transfer whenever
|
||||||
|
the previous transfer ended.
|
||||||
|
|
||||||
|
This is a rather inefficient design though, because the inter-transfer
|
||||||
|
latency will be not only the interrupt latency, but also the
|
||||||
|
scheduling latency of the tasklet, which will leave the channel idle
|
||||||
|
in between, which will slow down the global transfer rate.
|
||||||
|
|
||||||
|
You should avoid this kind of practice, and instead of electing a new
|
||||||
|
transfer in your tasklet, move that part to the interrupt handler in
|
||||||
|
order to have a shorter idle window (that we can't really avoid
|
||||||
|
anyway).
|
||||||
|
|
||||||
|
Glossary
|
||||||
|
========
|
||||||
|
|
||||||
|
- Burst: A number of consecutive read or write operations that
|
||||||
|
can be queued to buffers before being flushed to memory.
|
||||||
|
|
||||||
|
- Chunk: A contiguous collection of bursts
|
||||||
|
|
||||||
|
- Transfer: A collection of chunks (be it contiguous or not)
|
||||||
190
Documentation/driver-api/dmaengine/pxa_dma.rst
Normal file
190
Documentation/driver-api/dmaengine/pxa_dma.rst
Normal file
|
|
@ -0,0 +1,190 @@
|
||||||
|
==============================
|
||||||
|
PXA/MMP - DMA Slave controller
|
||||||
|
==============================
|
||||||
|
|
||||||
|
Constraints
|
||||||
|
===========
|
||||||
|
|
||||||
|
a) Transfers hot queuing
|
||||||
|
A driver submitting a transfer and issuing it should be granted the transfer
|
||||||
|
is queued even on a running DMA channel.
|
||||||
|
This implies that the queuing doesn't wait for the previous transfer end,
|
||||||
|
and that the descriptor chaining is not only done in the irq/tasklet code
|
||||||
|
triggered by the end of the transfer.
|
||||||
|
A transfer which is submitted and issued on a phy doesn't wait for a phy to
|
||||||
|
stop and restart, but is submitted on a "running channel". The other
|
||||||
|
drivers, especially mmp_pdma waited for the phy to stop before relaunching
|
||||||
|
a new transfer.
|
||||||
|
|
||||||
|
b) All transfers having asked for confirmation should be signaled
|
||||||
|
Any issued transfer with DMA_PREP_INTERRUPT should trigger a callback call.
|
||||||
|
This implies that even if an irq/tasklet is triggered by end of tx1, but
|
||||||
|
at the time of irq/dma tx2 is already finished, tx1->complete() and
|
||||||
|
tx2->complete() should be called.
|
||||||
|
|
||||||
|
c) Channel running state
|
||||||
|
A driver should be able to query if a channel is running or not. For the
|
||||||
|
multimedia case, such as video capture, if a transfer is submitted and then
|
||||||
|
a check of the DMA channel reports a "stopped channel", the transfer should
|
||||||
|
not be issued until the next "start of frame interrupt", hence the need to
|
||||||
|
know if a channel is in running or stopped state.
|
||||||
|
|
||||||
|
d) Bandwidth guarantee
|
||||||
|
The PXA architecture has 4 levels of DMAs priorities : high, normal, low.
|
||||||
|
The high priorities get twice as much bandwidth as the normal, which get twice
|
||||||
|
as much as the low priorities.
|
||||||
|
A driver should be able to request a priority, especially the real-time
|
||||||
|
ones such as pxa_camera with (big) throughputs.
|
||||||
|
|
||||||
|
Design
|
||||||
|
======
|
||||||
|
a) Virtual channels
|
||||||
|
Same concept as in sa11x0 driver, ie. a driver was assigned a "virtual
|
||||||
|
channel" linked to the requestor line, and the physical DMA channel is
|
||||||
|
assigned on the fly when the transfer is issued.
|
||||||
|
|
||||||
|
b) Transfer anatomy for a scatter-gather transfer
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
+------------+-----+---------------+----------------+-----------------+
|
||||||
|
| desc-sg[0] | ... | desc-sg[last] | status updater | finisher/linker |
|
||||||
|
+------------+-----+---------------+----------------+-----------------+
|
||||||
|
|
||||||
|
This structure is pointed by dma->sg_cpu.
|
||||||
|
The descriptors are used as follows :
|
||||||
|
|
||||||
|
- desc-sg[i]: i-th descriptor, transferring the i-th sg
|
||||||
|
element to the video buffer scatter gather
|
||||||
|
|
||||||
|
- status updater
|
||||||
|
Transfers a single u32 to a well known dma coherent memory to leave
|
||||||
|
a trace that this transfer is done. The "well known" is unique per
|
||||||
|
physical channel, meaning that a read of this value will tell which
|
||||||
|
is the last finished transfer at that point in time.
|
||||||
|
|
||||||
|
- finisher: has ddadr=DADDR_STOP, dcmd=ENDIRQEN
|
||||||
|
|
||||||
|
- linker: has ddadr= desc-sg[0] of next transfer, dcmd=0
|
||||||
|
|
||||||
|
c) Transfers hot-chaining
|
||||||
|
Suppose the running chain is:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
Buffer 1 Buffer 2
|
||||||
|
+---------+----+---+ +----+----+----+---+
|
||||||
|
| d0 | .. | dN | l | | d0 | .. | dN | f |
|
||||||
|
+---------+----+-|-+ ^----+----+----+---+
|
||||||
|
| |
|
||||||
|
+----+
|
||||||
|
|
||||||
|
After a call to dmaengine_submit(b3), the chain will look like:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
Buffer 1 Buffer 2 Buffer 3
|
||||||
|
+---------+----+---+ +----+----+----+---+ +----+----+----+---+
|
||||||
|
| d0 | .. | dN | l | | d0 | .. | dN | l | | d0 | .. | dN | f |
|
||||||
|
+---------+----+-|-+ ^----+----+----+-|-+ ^----+----+----+---+
|
||||||
|
| | | |
|
||||||
|
+----+ +----+
|
||||||
|
new_link
|
||||||
|
|
||||||
|
If while new_link was created the DMA channel stopped, it is _not_
|
||||||
|
restarted. Hot-chaining doesn't break the assumption that
|
||||||
|
dma_async_issue_pending() is to be used to ensure the transfer is actually started.
|
||||||
|
|
||||||
|
One exception to this rule :
|
||||||
|
|
||||||
|
- if Buffer1 and Buffer2 had all their addresses 8 bytes aligned
|
||||||
|
|
||||||
|
- and if Buffer3 has at least one address not 4 bytes aligned
|
||||||
|
|
||||||
|
- then hot-chaining cannot happen, as the channel must be stopped, the
|
||||||
|
"align bit" must be set, and the channel restarted As a consequence,
|
||||||
|
such a transfer tx_submit() will be queued on the submitted queue, and
|
||||||
|
this specific case if the DMA is already running in aligned mode.
|
||||||
|
|
||||||
|
d) Transfers completion updater
|
||||||
|
Each time a transfer is completed on a channel, an interrupt might be
|
||||||
|
generated or not, up to the client's request. But in each case, the last
|
||||||
|
descriptor of a transfer, the "status updater", will write the latest
|
||||||
|
transfer being completed into the physical channel's completion mark.
|
||||||
|
|
||||||
|
This will speed up residue calculation, for large transfers such as video
|
||||||
|
buffers which hold around 6k descriptors or more. This also allows without
|
||||||
|
any lock to find out what is the latest completed transfer in a running
|
||||||
|
DMA chain.
|
||||||
|
|
||||||
|
e) Transfers completion, irq and tasklet
|
||||||
|
When a transfer flagged as "DMA_PREP_INTERRUPT" is finished, the dma irq
|
||||||
|
is raised. Upon this interrupt, a tasklet is scheduled for the physical
|
||||||
|
channel.
|
||||||
|
|
||||||
|
The tasklet is responsible for :
|
||||||
|
|
||||||
|
- reading the physical channel last updater mark
|
||||||
|
|
||||||
|
- calling all the transfer callbacks of finished transfers, based on
|
||||||
|
that mark, and each transfer flags.
|
||||||
|
|
||||||
|
If a transfer is completed while this handling is done, a dma irq will
|
||||||
|
be raised, and the tasklet will be scheduled once again, having a new
|
||||||
|
updater mark.
|
||||||
|
|
||||||
|
f) Residue
|
||||||
|
Residue granularity will be descriptor based. The issued but not completed
|
||||||
|
transfers will be scanned for all of their descriptors against the
|
||||||
|
currently running descriptor.
|
||||||
|
|
||||||
|
g) Most complicated case of driver's tx queues
|
||||||
|
The most tricky situation is when :
|
||||||
|
|
||||||
|
- there are not "acked" transfers (tx0)
|
||||||
|
|
||||||
|
- a driver submitted an aligned tx1, not chained
|
||||||
|
|
||||||
|
- a driver submitted an aligned tx2 => tx2 is cold chained to tx1
|
||||||
|
|
||||||
|
- a driver issued tx1+tx2 => channel is running in aligned mode
|
||||||
|
|
||||||
|
- a driver submitted an aligned tx3 => tx3 is hot-chained
|
||||||
|
|
||||||
|
- a driver submitted an unaligned tx4 => tx4 is put in submitted queue,
|
||||||
|
not chained
|
||||||
|
|
||||||
|
- a driver issued tx4 => tx4 is put in issued queue, not chained
|
||||||
|
|
||||||
|
- a driver submitted an aligned tx5 => tx5 is put in submitted queue, not
|
||||||
|
chained
|
||||||
|
|
||||||
|
- a driver submitted an aligned tx6 => tx6 is put in submitted queue,
|
||||||
|
cold chained to tx5
|
||||||
|
|
||||||
|
This translates into (after tx4 is issued) :
|
||||||
|
|
||||||
|
- issued queue
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
+-----+ +-----+ +-----+ +-----+
|
||||||
|
| tx1 | | tx2 | | tx3 | | tx4 |
|
||||||
|
+---|-+ ^---|-+ ^-----+ +-----+
|
||||||
|
| | | |
|
||||||
|
+---+ +---+
|
||||||
|
- submitted queue
|
||||||
|
+-----+ +-----+
|
||||||
|
| tx5 | | tx6 |
|
||||||
|
+---|-+ ^-----+
|
||||||
|
| |
|
||||||
|
+---+
|
||||||
|
|
||||||
|
- completed queue : empty
|
||||||
|
|
||||||
|
- allocated queue : tx0
|
||||||
|
|
||||||
|
It should be noted that after tx3 is completed, the channel is stopped, and
|
||||||
|
restarted in "unaligned mode" to handle tx4.
|
||||||
|
|
||||||
|
Author: Robert Jarzmik <robert.jarzmik@free.fr>
|
||||||
|
|
@ -46,6 +46,7 @@ available subsections can be seen below.
|
||||||
pinctl
|
pinctl
|
||||||
gpio
|
gpio
|
||||||
misc_devices
|
misc_devices
|
||||||
|
dmaengine/index
|
||||||
|
|
||||||
.. only:: subproject and html
|
.. only:: subproject and html
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -690,9 +690,7 @@ The USB devices are now exported via debugfs:
|
||||||
This file is handy for status viewing tools in user mode, which can scan
|
This file is handy for status viewing tools in user mode, which can scan
|
||||||
the text format and ignore most of it. More detailed device status
|
the text format and ignore most of it. More detailed device status
|
||||||
(including class and vendor status) is available from device-specific
|
(including class and vendor status) is available from device-specific
|
||||||
files. For information about the current format of this file, see the
|
files. For information about the current format of this file, see below.
|
||||||
``Documentation/usb/proc_usb_info.txt`` file in your Linux kernel
|
|
||||||
sources.
|
|
||||||
|
|
||||||
This file, in combination with the poll() system call, can also be used
|
This file, in combination with the poll() system call, can also be used
|
||||||
to detect when devices are added or removed::
|
to detect when devices are added or removed::
|
||||||
|
|
|
||||||
|
|
@ -77,8 +77,8 @@ C. Boot options
|
||||||
1. fbcon=font:<name>
|
1. fbcon=font:<name>
|
||||||
|
|
||||||
Select the initial font to use. The value 'name' can be any of the
|
Select the initial font to use. The value 'name' can be any of the
|
||||||
compiled-in fonts: VGA8x16, 7x14, 10x18, VGA8x8, MINI4x6, RomanLarge,
|
compiled-in fonts: 10x18, 6x10, 7x14, Acorn8x8, MINI4x6,
|
||||||
SUN8x16, SUN12x22, ProFont6x11, Acorn8x8, PEARL8x8.
|
PEARL8x8, ProFont6x11, SUN12x22, SUN8x16, VGA8x16, VGA8x8.
|
||||||
|
|
||||||
Note, not all drivers can handle font with widths not divisible by 8,
|
Note, not all drivers can handle font with widths not divisible by 8,
|
||||||
such as vga16fb.
|
such as vga16fb.
|
||||||
|
|
|
||||||
|
|
@ -34,6 +34,6 @@
|
||||||
| tile: | TODO |
|
| tile: | TODO |
|
||||||
| um: | TODO |
|
| um: | TODO |
|
||||||
| unicore32: | TODO |
|
| unicore32: | TODO |
|
||||||
| x86: | ok |
|
| x86: | ok | 64-bit only
|
||||||
| xtensa: | TODO |
|
| xtensa: | TODO |
|
||||||
-----------------------
|
-----------------------
|
||||||
|
|
|
||||||
|
|
@ -62,7 +62,7 @@ disabled, fcntl(fd, F_NOTIFY, ...) will return -EINVAL.
|
||||||
|
|
||||||
Example
|
Example
|
||||||
-------
|
-------
|
||||||
See Documentation/filesystems/dnotify_test.c for an example.
|
See tools/testing/selftests/filesystems/dnotify_test.c for an example.
|
||||||
|
|
||||||
NOTE
|
NOTE
|
||||||
----
|
----
|
||||||
|
|
|
||||||
|
|
@ -94,10 +94,10 @@ Note: More extensive information for getting started with ext4 can be
|
||||||
* ability to pack bitmaps and inode tables into larger virtual groups via the
|
* ability to pack bitmaps and inode tables into larger virtual groups via the
|
||||||
flex_bg feature
|
flex_bg feature
|
||||||
* large file support
|
* large file support
|
||||||
* Inode allocation using large virtual block groups via flex_bg
|
* inode allocation using large virtual block groups via flex_bg
|
||||||
* delayed allocation
|
* delayed allocation
|
||||||
* large block (up to pagesize) support
|
* large block (up to pagesize) support
|
||||||
* efficient new ordered mode in JBD2 and ext4(avoid using buffer head to force
|
* efficient new ordered mode in JBD2 and ext4 (avoid using buffer head to force
|
||||||
the ordering)
|
the ordering)
|
||||||
|
|
||||||
[1] Filesystems with a block size of 1k may see a limit imposed by the
|
[1] Filesystems with a block size of 1k may see a limit imposed by the
|
||||||
|
|
@ -105,7 +105,7 @@ directory hash tree having a maximum depth of two.
|
||||||
|
|
||||||
2.2 Candidate features for future inclusion
|
2.2 Candidate features for future inclusion
|
||||||
|
|
||||||
* Online defrag (patches available but not well tested)
|
* online defrag (patches available but not well tested)
|
||||||
* reduced mke2fs time via lazy itable initialization in conjunction with
|
* reduced mke2fs time via lazy itable initialization in conjunction with
|
||||||
the uninit_bg feature (capability to do this is available in e2fsprogs
|
the uninit_bg feature (capability to do this is available in e2fsprogs
|
||||||
but a kernel thread to do lazy zeroing of unused inode table blocks
|
but a kernel thread to do lazy zeroing of unused inode table blocks
|
||||||
|
|
@ -602,7 +602,7 @@ Table of Ext4 specific ioctls
|
||||||
bitmaps and inode table, the userspace tool thus
|
bitmaps and inode table, the userspace tool thus
|
||||||
just passes the new number of blocks.
|
just passes the new number of blocks.
|
||||||
|
|
||||||
EXT4_IOC_SWAP_BOOT Swap i_blocks and associated attributes
|
EXT4_IOC_SWAP_BOOT Swap i_blocks and associated attributes
|
||||||
(like i_blocks, i_size, i_flags, ...) from
|
(like i_blocks, i_size, i_flags, ...) from
|
||||||
the specified inode with inode
|
the specified inode with inode
|
||||||
EXT4_BOOT_LOADER_INO (#5). This is typically
|
EXT4_BOOT_LOADER_INO (#5). This is typically
|
||||||
|
|
|
||||||
|
|
@ -12,7 +12,7 @@ To support these disparate requirements, the Linux USB system provides
|
||||||
HID events to two separate interfaces:
|
HID events to two separate interfaces:
|
||||||
* the input subsystem, which converts HID events into normal input
|
* the input subsystem, which converts HID events into normal input
|
||||||
device interfaces (such as keyboard, mouse and joystick) and a
|
device interfaces (such as keyboard, mouse and joystick) and a
|
||||||
normalised event interface - see Documentation/input/input.txt
|
normalised event interface - see Documentation/input/input.rst
|
||||||
* the hiddev interface, which provides fairly raw HID events
|
* the hiddev interface, which provides fairly raw HID events
|
||||||
|
|
||||||
The data flow for a HID event produced by a device is something like
|
The data flow for a HID event produced by a device is something like
|
||||||
|
|
|
||||||
|
|
@ -230,4 +230,5 @@ Historic Edits
|
||||||
2005-03-19 - Dominic Cerquetti <binary1230@yahoo.com>
|
2005-03-19 - Dominic Cerquetti <binary1230@yahoo.com>
|
||||||
- added stuff for dance pads, new d-pad->axes mappings
|
- added stuff for dance pads, new d-pad->axes mappings
|
||||||
|
|
||||||
Later changes may be viewed with 'git log Documentation/input/xpad.txt'
|
Later changes may be viewed with
|
||||||
|
'git log --follow Documentation/input/devices/xpad.rst'
|
||||||
|
|
|
||||||
|
|
@ -184,7 +184,7 @@ is done when dirty_ratio is reached.
|
||||||
DO_CPU:
|
DO_CPU:
|
||||||
|
|
||||||
Enable CPU frequency scaling when in laptop mode. (Requires CPUFreq to be setup.
|
Enable CPU frequency scaling when in laptop mode. (Requires CPUFreq to be setup.
|
||||||
See Documentation/cpu-freq/user-guide.txt for more info. Disabled by default.)
|
See Documentation/admin-guide/pm/cpufreq.rst for more info. Disabled by default.)
|
||||||
|
|
||||||
CPU_MAXFREQ:
|
CPU_MAXFREQ:
|
||||||
|
|
||||||
|
|
@ -287,7 +287,7 @@ MINIMUM_BATTERY_MINUTES=10
|
||||||
|
|
||||||
# Should the maximum CPU frequency be adjusted down while on battery?
|
# Should the maximum CPU frequency be adjusted down while on battery?
|
||||||
# Requires CPUFreq to be setup.
|
# Requires CPUFreq to be setup.
|
||||||
# See Documentation/cpu-freq/user-guide.txt for more info
|
# See Documentation/admin-guide/pm/cpufreq.rst for more info
|
||||||
#DO_CPU=0
|
#DO_CPU=0
|
||||||
|
|
||||||
# When on battery what is the maximum CPU speed that the system should
|
# When on battery what is the maximum CPU speed that the system should
|
||||||
|
|
@ -378,7 +378,7 @@ BATT_HD=${BATT_HD:-'4'}
|
||||||
DIRTY_RATIO=${DIRTY_RATIO:-'40'}
|
DIRTY_RATIO=${DIRTY_RATIO:-'40'}
|
||||||
|
|
||||||
# cpu frequency scaling
|
# cpu frequency scaling
|
||||||
# See Documentation/cpu-freq/user-guide.txt for more info
|
# See Documentation/admin-guide/pm/cpufreq.rst for more info
|
||||||
DO_CPU=${CPU_MANAGE:-'0'}
|
DO_CPU=${CPU_MANAGE:-'0'}
|
||||||
CPU_MAXFREQ=${CPU_MAXFREQ:-'slowest'}
|
CPU_MAXFREQ=${CPU_MAXFREQ:-'slowest'}
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -8,7 +8,7 @@ RT-mutex implementation design
|
||||||
|
|
||||||
This document tries to describe the design of the rtmutex.c implementation.
|
This document tries to describe the design of the rtmutex.c implementation.
|
||||||
It doesn't describe the reasons why rtmutex.c exists. For that please see
|
It doesn't describe the reasons why rtmutex.c exists. For that please see
|
||||||
Documentation/rt-mutex.txt. Although this document does explain problems
|
Documentation/locking/rt-mutex.txt. Although this document does explain problems
|
||||||
that happen without this code, but that is in the concept to understand
|
that happen without this code, but that is in the concept to understand
|
||||||
what the code actually is doing.
|
what the code actually is doing.
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -18,7 +18,7 @@ General information
|
||||||
|
|
||||||
This class of cards has a bt878a as the PCI interface, and require the bttv driver
|
This class of cards has a bt878a as the PCI interface, and require the bttv driver
|
||||||
for accessing the i2c bus and the gpio pins of the bt8xx chipset.
|
for accessing the i2c bus and the gpio pins of the bt8xx chipset.
|
||||||
Please see Documentation/dvb/cards.txt => o Cards based on the Conexant Bt8xx PCI bridge:
|
Please see Documentation/media/dvb-drivers/cards.rst => o Cards based on the Conexant Bt8xx PCI bridge:
|
||||||
|
|
||||||
Compiling kernel please enable:
|
Compiling kernel please enable:
|
||||||
|
|
||||||
|
|
@ -45,7 +45,7 @@ Loading Modules
|
||||||
Regular case: If the bttv driver detects a bt8xx-based DVB card, all frontend and backend modules will be loaded automatically.
|
Regular case: If the bttv driver detects a bt8xx-based DVB card, all frontend and backend modules will be loaded automatically.
|
||||||
Exceptions are:
|
Exceptions are:
|
||||||
- Old TwinHan DST cards or clones with or without CA slot and not containing an Eeprom.
|
- Old TwinHan DST cards or clones with or without CA slot and not containing an Eeprom.
|
||||||
People running udev please see Documentation/dvb/udev.txt.
|
People running udev please see Documentation/media/dvb-drivers/udev.rst.
|
||||||
|
|
||||||
In the following cases overriding the PCI type detection for dvb-bt8xx might be necessary:
|
In the following cases overriding the PCI type detection for dvb-bt8xx might be necessary:
|
||||||
|
|
||||||
|
|
@ -72,7 +72,7 @@ Useful parameters for verbosity level and debugging the dst module:
|
||||||
The autodetected values are determined by the cards' "response string".
|
The autodetected values are determined by the cards' "response string".
|
||||||
In your logs see f. ex.: dst_get_device_id: Recognize [DSTMCI].
|
In your logs see f. ex.: dst_get_device_id: Recognize [DSTMCI].
|
||||||
For bug reports please send in a complete log with verbose=4 activated.
|
For bug reports please send in a complete log with verbose=4 activated.
|
||||||
Please also see Documentation/dvb/ci.txt.
|
Please also see Documentation/media/dvb-drivers/ci.rst.
|
||||||
|
|
||||||
Running multiple cards
|
Running multiple cards
|
||||||
~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
@ -100,7 +100,7 @@ Examples of card ID's:
|
||||||
|
|
||||||
$ modprobe bttv card=113 card=135
|
$ modprobe bttv card=113 card=135
|
||||||
|
|
||||||
For a full list of card ID's please see Documentation/video4linux/CARDLIST.bttv.
|
For a full list of card ID's please see Documentation/media/v4l-drivers/bttv-cardlist.rst.
|
||||||
In case of further problems please subscribe and send questions to the mailing list: linux-dvb@linuxtv.org.
|
In case of further problems please subscribe and send questions to the mailing list: linux-dvb@linuxtv.org.
|
||||||
|
|
||||||
Probing the cards with broken PCI subsystem ID
|
Probing the cards with broken PCI subsystem ID
|
||||||
|
|
|
||||||
|
|
@ -431,7 +431,7 @@ MPEG stream.
|
||||||
*Historical context*: This format specification originates from a
|
*Historical context*: This format specification originates from a
|
||||||
custom, embedded, sliced VBI data format used by the ``ivtv`` driver.
|
custom, embedded, sliced VBI data format used by the ``ivtv`` driver.
|
||||||
This format has already been informally specified in the kernel sources
|
This format has already been informally specified in the kernel sources
|
||||||
in the file ``Documentation/video4linux/cx2341x/README.vbi`` . The
|
in the file ``Documentation/media/v4l-drivers/cx2341x.rst`` . The
|
||||||
maximum size of the payload and other aspects of this format are driven
|
maximum size of the payload and other aspects of this format are driven
|
||||||
by the CX23415 MPEG decoder's capabilities and limitations with respect
|
by the CX23415 MPEG decoder's capabilities and limitations with respect
|
||||||
to extracting, decoding, and displaying sliced VBI data embedded within
|
to extracting, decoding, and displaying sliced VBI data embedded within
|
||||||
|
|
|
||||||
|
|
@ -284,7 +284,7 @@ enum v4l2_mpeg_stream_vbi_fmt -
|
||||||
* - ``V4L2_MPEG_STREAM_VBI_FMT_IVTV``
|
* - ``V4L2_MPEG_STREAM_VBI_FMT_IVTV``
|
||||||
- VBI in private packets, IVTV format (documented in the kernel
|
- VBI in private packets, IVTV format (documented in the kernel
|
||||||
sources in the file
|
sources in the file
|
||||||
``Documentation/video4linux/cx2341x/README.vbi``)
|
``Documentation/media/v4l-drivers/cx2341x.rst``)
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -52,7 +52,7 @@ please make a proposal on the linux-media mailing list.
|
||||||
`http://www.ivtvdriver.org/ <http://www.ivtvdriver.org/>`__
|
`http://www.ivtvdriver.org/ <http://www.ivtvdriver.org/>`__
|
||||||
|
|
||||||
The format is documented in the kernel sources in the file
|
The format is documented in the kernel sources in the file
|
||||||
``Documentation/video4linux/cx2341x/README.hm12``
|
``Documentation/media/v4l-drivers/cx2341x.rst``
|
||||||
* .. _V4L2-PIX-FMT-CPIA1:
|
* .. _V4L2-PIX-FMT-CPIA1:
|
||||||
|
|
||||||
- ``V4L2_PIX_FMT_CPIA1``
|
- ``V4L2_PIX_FMT_CPIA1``
|
||||||
|
|
|
||||||
|
|
@ -307,7 +307,7 @@ console and let some terminal application log the messages. /me uses
|
||||||
screen. See Documentation/admin-guide/serial-console.rst for details on setting
|
screen. See Documentation/admin-guide/serial-console.rst for details on setting
|
||||||
up a serial console.
|
up a serial console.
|
||||||
|
|
||||||
Read Documentation/admin-guide/oops-tracing.rst to learn how to get any useful
|
Read Documentation/admin-guide/bug-hunting.rst to learn how to get any useful
|
||||||
information out of a register+stack dump printed by the kernel on
|
information out of a register+stack dump printed by the kernel on
|
||||||
protection faults (so-called "kernel oops").
|
protection faults (so-called "kernel oops").
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -7,7 +7,7 @@ The MAX2175 driver implements the following driver-specific controls:
|
||||||
-------------------------------
|
-------------------------------
|
||||||
Enable/Disable I2S output of the tuner. This is a private control
|
Enable/Disable I2S output of the tuner. This is a private control
|
||||||
that can be accessed only using the subdev interface.
|
that can be accessed only using the subdev interface.
|
||||||
Refer to Documentation/media/kapi/v4l2-controls for more details.
|
Refer to Documentation/media/kapi/v4l2-controls.rst for more details.
|
||||||
|
|
||||||
.. flat-table::
|
.. flat-table::
|
||||||
:header-rows: 0
|
:header-rows: 0
|
||||||
|
|
|
||||||
|
|
@ -332,8 +332,8 @@ References
|
||||||
[5] "MBIM (Mobile Broadband Interface Model) Registry"
|
[5] "MBIM (Mobile Broadband Interface Model) Registry"
|
||||||
- http://compliance.usb.org/mbim/
|
- http://compliance.usb.org/mbim/
|
||||||
|
|
||||||
[6] "/dev/bus/usb filesystem output"
|
[6] "/sys/kernel/debug/usb/devices output format"
|
||||||
- Documentation/usb/proc_usb_info.txt
|
- Documentation/driver-api/usb/usb.rst
|
||||||
|
|
||||||
[7] "/sys/bus/usb/devices/.../descriptors"
|
[7] "/sys/bus/usb/devices/.../descriptors"
|
||||||
- Documentation/ABI/stable/sysfs-bus-usb
|
- Documentation/ABI/stable/sysfs-bus-usb
|
||||||
|
|
|
||||||
|
|
@ -47,7 +47,7 @@ The requirements for GSO are more complicated, because when segmenting an
|
||||||
(section 'E') for more details.
|
(section 'E') for more details.
|
||||||
|
|
||||||
A driver declares its offload capabilities in netdev->hw_features; see
|
A driver declares its offload capabilities in netdev->hw_features; see
|
||||||
Documentation/networking/netdev-features for more. Note that a device
|
Documentation/networking/netdev-features.txt for more. Note that a device
|
||||||
which only advertises NETIF_F_IP[V6]_CSUM must still obey the csum_start
|
which only advertises NETIF_F_IP[V6]_CSUM must still obey the csum_start
|
||||||
and csum_offset given in the SKB; if it tries to deduce these itself in
|
and csum_offset given in the SKB; if it tries to deduce these itself in
|
||||||
hardware (as some NICs do) the driver should check that the values in the
|
hardware (as some NICs do) the driver should check that the values in the
|
||||||
|
|
|
||||||
|
|
@ -1055,7 +1055,7 @@ TX_RING part only TP_STATUS_AVAILABLE is set, then the tp_sec and tp_{n,u}sec
|
||||||
members do not contain a valid value. For TX_RINGs, by default no timestamp
|
members do not contain a valid value. For TX_RINGs, by default no timestamp
|
||||||
is generated!
|
is generated!
|
||||||
|
|
||||||
See include/linux/net_tstamp.h and Documentation/networking/timestamping
|
See include/linux/net_tstamp.h and Documentation/networking/timestamping.txt
|
||||||
for more information on hardware timestamps.
|
for more information on hardware timestamps.
|
||||||
|
|
||||||
-------------------------------------------------------------------------------
|
-------------------------------------------------------------------------------
|
||||||
|
|
|
||||||
|
|
@ -119,4 +119,4 @@ properties of futexes, and all four combinations are possible: futex,
|
||||||
robust-futex, PI-futex, robust+PI-futex.
|
robust-futex, PI-futex, robust+PI-futex.
|
||||||
|
|
||||||
More details about priority inheritance can be found in
|
More details about priority inheritance can be found in
|
||||||
Documentation/rt-mutex.txt.
|
Documentation/locking/rt-mutex.txt.
|
||||||
|
|
|
||||||
|
|
@ -24,7 +24,8 @@ platform.
|
||||||
|
|
||||||
If one of the strings listed in /sys/power/state is written to it, the system
|
If one of the strings listed in /sys/power/state is written to it, the system
|
||||||
will attempt to transition into the corresponding sleep state. Refer to
|
will attempt to transition into the corresponding sleep state. Refer to
|
||||||
Documentation/power/states.txt for a description of each of those states.
|
Documentation/admin-guide/pm/sleep-states.rst for a description of each of
|
||||||
|
those states.
|
||||||
|
|
||||||
/sys/power/disk controls the operating mode of hibernation (Suspend-to-Disk).
|
/sys/power/disk controls the operating mode of hibernation (Suspend-to-Disk).
|
||||||
Specifically, it tells the kernel what to do after creating a hibernation image.
|
Specifically, it tells the kernel what to do after creating a hibernation image.
|
||||||
|
|
@ -42,7 +43,7 @@ The currently selected option is printed in square brackets.
|
||||||
The 'platform' option is only available if the platform provides a special
|
The 'platform' option is only available if the platform provides a special
|
||||||
mechanism to put the system to sleep after creating a hibernation image (ACPI
|
mechanism to put the system to sleep after creating a hibernation image (ACPI
|
||||||
does that, for example). The 'suspend' option is available if Suspend-to-RAM
|
does that, for example). The 'suspend' option is available if Suspend-to-RAM
|
||||||
is supported. Refer to Documentation/power/basic_pm_debugging.txt for the
|
is supported. Refer to Documentation/power/basic-pm-debugging.txt for the
|
||||||
description of the 'test_resume' option.
|
description of the 'test_resume' option.
|
||||||
|
|
||||||
To select an option, write the string representing it to /sys/power/disk.
|
To select an option, write the string representing it to /sys/power/disk.
|
||||||
|
|
|
||||||
|
|
@ -8,7 +8,7 @@ management. Based on previous work by Patrick Mochel <mochel@transmeta.com>
|
||||||
|
|
||||||
This document only covers the aspects of power management specific to PCI
|
This document only covers the aspects of power management specific to PCI
|
||||||
devices. For general description of the kernel's interfaces related to device
|
devices. For general description of the kernel's interfaces related to device
|
||||||
power management refer to Documentation/power/admin-guide/devices.rst and
|
power management refer to Documentation/driver-api/pm/devices.rst and
|
||||||
Documentation/power/runtime_pm.txt.
|
Documentation/power/runtime_pm.txt.
|
||||||
|
|
||||||
---------------------------------------------------------------------------
|
---------------------------------------------------------------------------
|
||||||
|
|
@ -417,7 +417,7 @@ pm->runtime_idle() callback.
|
||||||
2.4. System-Wide Power Transitions
|
2.4. System-Wide Power Transitions
|
||||||
----------------------------------
|
----------------------------------
|
||||||
There are a few different types of system-wide power transitions, described in
|
There are a few different types of system-wide power transitions, described in
|
||||||
Documentation/power/admin-guide/devices.rst. Each of them requires devices to be handled
|
Documentation/driver-api/pm/devices.rst. Each of them requires devices to be handled
|
||||||
in a specific way and the PM core executes subsystem-level power management
|
in a specific way and the PM core executes subsystem-level power management
|
||||||
callbacks for this purpose. They are executed in phases such that each phase
|
callbacks for this purpose. They are executed in phases such that each phase
|
||||||
involves executing the same subsystem-level callback for every device belonging
|
involves executing the same subsystem-level callback for every device belonging
|
||||||
|
|
@ -623,7 +623,7 @@ System restore requires a hibernation image to be loaded into memory and the
|
||||||
pre-hibernation memory contents to be restored before the pre-hibernation system
|
pre-hibernation memory contents to be restored before the pre-hibernation system
|
||||||
activity can be resumed.
|
activity can be resumed.
|
||||||
|
|
||||||
As described in Documentation/power/admin-guide/devices.rst, the hibernation image is loaded
|
As described in Documentation/driver-api/pm/devices.rst, the hibernation image is loaded
|
||||||
into memory by a fresh instance of the kernel, called the boot kernel, which in
|
into memory by a fresh instance of the kernel, called the boot kernel, which in
|
||||||
turn is loaded and run by a boot loader in the usual way. After the boot kernel
|
turn is loaded and run by a boot loader in the usual way. After the boot kernel
|
||||||
has loaded the image, it needs to replace its own code and data with the code
|
has loaded the image, it needs to replace its own code and data with the code
|
||||||
|
|
@ -677,7 +677,7 @@ controlling the runtime power management of their devices.
|
||||||
|
|
||||||
At the time of this writing there are two ways to define power management
|
At the time of this writing there are two ways to define power management
|
||||||
callbacks for a PCI device driver, the recommended one, based on using a
|
callbacks for a PCI device driver, the recommended one, based on using a
|
||||||
dev_pm_ops structure described in Documentation/power/admin-guide/devices.rst, and the
|
dev_pm_ops structure described in Documentation/driver-api/pm/devices.rst, and the
|
||||||
"legacy" one, in which the .suspend(), .suspend_late(), .resume_early(), and
|
"legacy" one, in which the .suspend(), .suspend_late(), .resume_early(), and
|
||||||
.resume() callbacks from struct pci_driver are used. The legacy approach,
|
.resume() callbacks from struct pci_driver are used. The legacy approach,
|
||||||
however, doesn't allow one to define runtime power management callbacks and is
|
however, doesn't allow one to define runtime power management callbacks and is
|
||||||
|
|
@ -1046,5 +1046,5 @@ PCI Local Bus Specification, Rev. 3.0
|
||||||
PCI Bus Power Management Interface Specification, Rev. 1.2
|
PCI Bus Power Management Interface Specification, Rev. 1.2
|
||||||
Advanced Configuration and Power Interface (ACPI) Specification, Rev. 3.0b
|
Advanced Configuration and Power Interface (ACPI) Specification, Rev. 3.0b
|
||||||
PCI Express Base Specification, Rev. 2.0
|
PCI Express Base Specification, Rev. 2.0
|
||||||
Documentation/power/admin-guide/devices.rst
|
Documentation/driver-api/pm/devices.rst
|
||||||
Documentation/power/runtime_pm.txt
|
Documentation/power/runtime_pm.txt
|
||||||
|
|
|
||||||
|
|
@ -680,7 +680,7 @@ left in runtime suspend. If that happens, the PM core will not execute any
|
||||||
system suspend and resume callbacks for all of those devices, except for the
|
system suspend and resume callbacks for all of those devices, except for the
|
||||||
complete callback, which is then entirely responsible for handling the device
|
complete callback, which is then entirely responsible for handling the device
|
||||||
as appropriate. This only applies to system suspend transitions that are not
|
as appropriate. This only applies to system suspend transitions that are not
|
||||||
related to hibernation (see Documentation/power/admin-guide/devices.rst for more
|
related to hibernation (see Documentation/driver-api/pm/devices.rst for more
|
||||||
information).
|
information).
|
||||||
|
|
||||||
The PM core does its best to reduce the probability of race conditions between
|
The PM core does its best to reduce the probability of race conditions between
|
||||||
|
|
|
||||||
|
|
@ -178,7 +178,7 @@ matter is (1) kernel developers tend to be busy, (2) there is no shortage
|
||||||
of people with grand plans and little code (or even prospect of code) to
|
of people with grand plans and little code (or even prospect of code) to
|
||||||
back them up, and (3) nobody is obligated to review or comment on ideas
|
back them up, and (3) nobody is obligated to review or comment on ideas
|
||||||
posted by others. Beyond that, high-level designs often hide problems
|
posted by others. Beyond that, high-level designs often hide problems
|
||||||
which are only reviewed when somebody actually tries to implement those
|
which are only revealed when somebody actually tries to implement those
|
||||||
designs; for that reason, kernel developers would rather see the code.
|
designs; for that reason, kernel developers would rather see the code.
|
||||||
|
|
||||||
If a request-for-comments posting yields little in the way of comments, do
|
If a request-for-comments posting yields little in the way of comments, do
|
||||||
|
|
|
||||||
|
|
@ -307,7 +307,7 @@ variety of potential coding problems; it can also propose fixes for those
|
||||||
problems. Quite a few "semantic patches" for the kernel have been packaged
|
problems. Quite a few "semantic patches" for the kernel have been packaged
|
||||||
under the scripts/coccinelle directory; running "make coccicheck" will run
|
under the scripts/coccinelle directory; running "make coccicheck" will run
|
||||||
through those semantic patches and report on any problems found. See
|
through those semantic patches and report on any problems found. See
|
||||||
Documentation/coccinelle.txt for more information.
|
Documentation/dev-tools/coccinelle.rst for more information.
|
||||||
|
|
||||||
Other kinds of portability errors are best found by compiling your code for
|
Other kinds of portability errors are best found by compiling your code for
|
||||||
other architectures. If you do not happen to have an S/390 system or a
|
other architectures. If you do not happen to have an S/390 system or a
|
||||||
|
|
|
||||||
|
|
@ -26,6 +26,7 @@ Below are the essential guides that every developer should read.
|
||||||
coding-style
|
coding-style
|
||||||
email-clients
|
email-clients
|
||||||
kernel-enforcement-statement
|
kernel-enforcement-statement
|
||||||
|
kernel-driver-statement
|
||||||
|
|
||||||
Other guides to the community that are of interest to most developers are:
|
Other guides to the community that are of interest to most developers are:
|
||||||
|
|
||||||
|
|
|
||||||
199
Documentation/process/kernel-driver-statement.rst
Normal file
199
Documentation/process/kernel-driver-statement.rst
Normal file
|
|
@ -0,0 +1,199 @@
|
||||||
|
Kernel Driver Statement
|
||||||
|
-----------------------
|
||||||
|
|
||||||
|
Position Statement on Linux Kernel Modules
|
||||||
|
==========================================
|
||||||
|
|
||||||
|
|
||||||
|
We, the undersigned Linux kernel developers, consider any closed-source
|
||||||
|
Linux kernel module or driver to be harmful and undesirable. We have
|
||||||
|
repeatedly found them to be detrimental to Linux users, businesses, and
|
||||||
|
the greater Linux ecosystem. Such modules negate the openness,
|
||||||
|
stability, flexibility, and maintainability of the Linux development
|
||||||
|
model and shut their users off from the expertise of the Linux
|
||||||
|
community. Vendors that provide closed-source kernel modules force their
|
||||||
|
customers to give up key Linux advantages or choose new vendors.
|
||||||
|
Therefore, in order to take full advantage of the cost savings and
|
||||||
|
shared support benefits open source has to offer, we urge vendors to
|
||||||
|
adopt a policy of supporting their customers on Linux with open-source
|
||||||
|
kernel code.
|
||||||
|
|
||||||
|
We speak only for ourselves, and not for any company we might work for
|
||||||
|
today, have in the past, or will in the future.
|
||||||
|
|
||||||
|
- Dave Airlie
|
||||||
|
- Nick Andrew
|
||||||
|
- Jens Axboe
|
||||||
|
- Ralf Baechle
|
||||||
|
- Felipe Balbi
|
||||||
|
- Ohad Ben-Cohen
|
||||||
|
- Muli Ben-Yehuda
|
||||||
|
- Jiri Benc
|
||||||
|
- Arnd Bergmann
|
||||||
|
- Thomas Bogendoerfer
|
||||||
|
- Vitaly Bordug
|
||||||
|
- James Bottomley
|
||||||
|
- Josh Boyer
|
||||||
|
- Neil Brown
|
||||||
|
- Mark Brown
|
||||||
|
- David Brownell
|
||||||
|
- Michael Buesch
|
||||||
|
- Franck Bui-Huu
|
||||||
|
- Adrian Bunk
|
||||||
|
- François Cami
|
||||||
|
- Ralph Campbell
|
||||||
|
- Luiz Fernando N. Capitulino
|
||||||
|
- Mauro Carvalho Chehab
|
||||||
|
- Denis Cheng
|
||||||
|
- Jonathan Corbet
|
||||||
|
- Glauber Costa
|
||||||
|
- Alan Cox
|
||||||
|
- Magnus Damm
|
||||||
|
- Ahmed S. Darwish
|
||||||
|
- Robert P. J. Day
|
||||||
|
- Hans de Goede
|
||||||
|
- Arnaldo Carvalho de Melo
|
||||||
|
- Helge Deller
|
||||||
|
- Jean Delvare
|
||||||
|
- Mathieu Desnoyers
|
||||||
|
- Sven-Thorsten Dietrich
|
||||||
|
- Alexey Dobriyan
|
||||||
|
- Daniel Drake
|
||||||
|
- Alex Dubov
|
||||||
|
- Randy Dunlap
|
||||||
|
- Michael Ellerman
|
||||||
|
- Pekka Enberg
|
||||||
|
- Jan Engelhardt
|
||||||
|
- Mark Fasheh
|
||||||
|
- J. Bruce Fields
|
||||||
|
- Larry Finger
|
||||||
|
- Jeremy Fitzhardinge
|
||||||
|
- Mike Frysinger
|
||||||
|
- Kumar Gala
|
||||||
|
- Robin Getz
|
||||||
|
- Liam Girdwood
|
||||||
|
- Jan-Benedict Glaw
|
||||||
|
- Thomas Gleixner
|
||||||
|
- Brice Goglin
|
||||||
|
- Cyrill Gorcunov
|
||||||
|
- Andy Gospodarek
|
||||||
|
- Thomas Graf
|
||||||
|
- Krzysztof Halasa
|
||||||
|
- Harvey Harrison
|
||||||
|
- Stephen Hemminger
|
||||||
|
- Michael Hennerich
|
||||||
|
- Tejun Heo
|
||||||
|
- Benjamin Herrenschmidt
|
||||||
|
- Kristian Høgsberg
|
||||||
|
- Henrique de Moraes Holschuh
|
||||||
|
- Marcel Holtmann
|
||||||
|
- Mike Isely
|
||||||
|
- Takashi Iwai
|
||||||
|
- Olof Johansson
|
||||||
|
- Dave Jones
|
||||||
|
- Jesper Juhl
|
||||||
|
- Matthias Kaehlcke
|
||||||
|
- Kenji Kaneshige
|
||||||
|
- Jan Kara
|
||||||
|
- Jeremy Kerr
|
||||||
|
- Russell King
|
||||||
|
- Olaf Kirch
|
||||||
|
- Roel Kluin
|
||||||
|
- Hans-Jürgen Koch
|
||||||
|
- Auke Kok
|
||||||
|
- Peter Korsgaard
|
||||||
|
- Jiri Kosina
|
||||||
|
- Mariusz Kozlowski
|
||||||
|
- Greg Kroah-Hartman
|
||||||
|
- Michael Krufky
|
||||||
|
- Aneesh Kumar
|
||||||
|
- Clemens Ladisch
|
||||||
|
- Christoph Lameter
|
||||||
|
- Gunnar Larisch
|
||||||
|
- Anders Larsen
|
||||||
|
- Grant Likely
|
||||||
|
- John W. Linville
|
||||||
|
- Yinghai Lu
|
||||||
|
- Tony Luck
|
||||||
|
- Pavel Machek
|
||||||
|
- Matt Mackall
|
||||||
|
- Paul Mackerras
|
||||||
|
- Roland McGrath
|
||||||
|
- Patrick McHardy
|
||||||
|
- Kyle McMartin
|
||||||
|
- Paul Menage
|
||||||
|
- Thierry Merle
|
||||||
|
- Eric Miao
|
||||||
|
- Akinobu Mita
|
||||||
|
- Ingo Molnar
|
||||||
|
- James Morris
|
||||||
|
- Andrew Morton
|
||||||
|
- Paul Mundt
|
||||||
|
- Oleg Nesterov
|
||||||
|
- Luca Olivetti
|
||||||
|
- S.Çağlar Onur
|
||||||
|
- Pierre Ossman
|
||||||
|
- Keith Owens
|
||||||
|
- Venkatesh Pallipadi
|
||||||
|
- Nick Piggin
|
||||||
|
- Nicolas Pitre
|
||||||
|
- Evgeniy Polyakov
|
||||||
|
- Richard Purdie
|
||||||
|
- Mike Rapoport
|
||||||
|
- Sam Ravnborg
|
||||||
|
- Gerrit Renker
|
||||||
|
- Stefan Richter
|
||||||
|
- David Rientjes
|
||||||
|
- Luis R. Rodriguez
|
||||||
|
- Stefan Roese
|
||||||
|
- Francois Romieu
|
||||||
|
- Rami Rosen
|
||||||
|
- Stephen Rothwell
|
||||||
|
- Maciej W. Rozycki
|
||||||
|
- Mark Salyzyn
|
||||||
|
- Yoshinori Sato
|
||||||
|
- Deepak Saxena
|
||||||
|
- Holger Schurig
|
||||||
|
- Amit Shah
|
||||||
|
- Yoshihiro Shimoda
|
||||||
|
- Sergei Shtylyov
|
||||||
|
- Kay Sievers
|
||||||
|
- Sebastian Siewior
|
||||||
|
- Rik Snel
|
||||||
|
- Jes Sorensen
|
||||||
|
- Alexey Starikovskiy
|
||||||
|
- Alan Stern
|
||||||
|
- Timur Tabi
|
||||||
|
- Hirokazu Takata
|
||||||
|
- Eliezer Tamir
|
||||||
|
- Eugene Teo
|
||||||
|
- Doug Thompson
|
||||||
|
- FUJITA Tomonori
|
||||||
|
- Dmitry Torokhov
|
||||||
|
- Marcelo Tosatti
|
||||||
|
- Steven Toth
|
||||||
|
- Theodore Tso
|
||||||
|
- Matthias Urlichs
|
||||||
|
- Geert Uytterhoeven
|
||||||
|
- Arjan van de Ven
|
||||||
|
- Ivo van Doorn
|
||||||
|
- Rik van Riel
|
||||||
|
- Wim Van Sebroeck
|
||||||
|
- Hans Verkuil
|
||||||
|
- Horst H. von Brand
|
||||||
|
- Dmitri Vorobiev
|
||||||
|
- Anton Vorontsov
|
||||||
|
- Daniel Walker
|
||||||
|
- Johannes Weiner
|
||||||
|
- Harald Welte
|
||||||
|
- Matthew Wilcox
|
||||||
|
- Dan J. Williams
|
||||||
|
- Darrick J. Wong
|
||||||
|
- David Woodhouse
|
||||||
|
- Chris Wright
|
||||||
|
- Bryan Wu
|
||||||
|
- Rafael J. Wysocki
|
||||||
|
- Herbert Xu
|
||||||
|
- Vlad Yasevich
|
||||||
|
- Peter Zijlstra
|
||||||
|
- Bartlomiej Zolnierkiewicz
|
||||||
|
|
@ -117,7 +117,7 @@ PM support:
|
||||||
anything. For the driver testing instructions see
|
anything. For the driver testing instructions see
|
||||||
Documentation/power/drivers-testing.txt and for a relatively
|
Documentation/power/drivers-testing.txt and for a relatively
|
||||||
complete overview of the power management issues related to
|
complete overview of the power management issues related to
|
||||||
drivers see Documentation/power/admin-guide/devices.rst .
|
drivers see Documentation/driver-api/pm/devices.rst.
|
||||||
|
|
||||||
Control:
|
Control:
|
||||||
In general if there is active maintenance of a driver by
|
In general if there is active maintenance of a driver by
|
||||||
|
|
|
||||||
|
|
@ -621,14 +621,14 @@ 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 (only needed if the person
|
- A ``from`` line specifying the patch author, followed by an empty
|
||||||
sending the patch is not the author).
|
line (only needed if the person sending the patch is not the author).
|
||||||
|
|
||||||
- An empty line.
|
|
||||||
|
|
||||||
- The body of the explanation, line wrapped at 75 columns, which will
|
- The body of the explanation, line wrapped at 75 columns, which will
|
||||||
be copied to the permanent changelog to describe this patch.
|
be copied to the permanent changelog to describe this patch.
|
||||||
|
|
||||||
|
- An empty line.
|
||||||
|
|
||||||
- The ``Signed-off-by:`` lines, described above, which will
|
- The ``Signed-off-by:`` lines, described above, which will
|
||||||
also go in the changelog.
|
also go in the changelog.
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -5,7 +5,7 @@ Linux Security Module Development
|
||||||
Based on https://lkml.org/lkml/2007/10/26/215,
|
Based on https://lkml.org/lkml/2007/10/26/215,
|
||||||
a new LSM is accepted into the kernel when its intent (a description of
|
a new LSM is accepted into the kernel when its intent (a description of
|
||||||
what it tries to protect against and in what cases one would expect to
|
what it tries to protect against and in what cases one would expect to
|
||||||
use it) has been appropriately documented in ``Documentation/security/LSM``.
|
use it) has been appropriately documented in ``Documentation/security/LSM.rst``.
|
||||||
This allows an LSM's code to be easily compared to its goals, and so
|
This allows an LSM's code to be easily compared to its goals, and so
|
||||||
that end users and distros can make a more informed decision about which
|
that end users and distros can make a more informed decision about which
|
||||||
LSMs suit their requirements.
|
LSMs suit their requirements.
|
||||||
|
|
|
||||||
|
|
@ -196,7 +196,7 @@ The Linux kernel supports the following types of credentials:
|
||||||
When a process accesses a key, if not already present, it will normally be
|
When a process accesses a key, if not already present, it will normally be
|
||||||
cached on one of these keyrings for future accesses to find.
|
cached on one of these keyrings for future accesses to find.
|
||||||
|
|
||||||
For more information on using keys, see Documentation/security/keys.txt.
|
For more information on using keys, see ``Documentation/security/keys/*``.
|
||||||
|
|
||||||
5. LSM
|
5. LSM
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -3,7 +3,7 @@ Key Request Service
|
||||||
===================
|
===================
|
||||||
|
|
||||||
The key request service is part of the key retention service (refer to
|
The key request service is part of the key retention service (refer to
|
||||||
Documentation/security/core.rst). This document explains more fully how
|
Documentation/security/keys/core.rst). This document explains more fully how
|
||||||
the requesting algorithm works.
|
the requesting algorithm works.
|
||||||
|
|
||||||
The process starts by either the kernel requesting a service by calling
|
The process starts by either the kernel requesting a service by calling
|
||||||
|
|
|
||||||
|
|
@ -11,7 +11,7 @@ General
|
||||||
|
|
||||||
First of all, you need to enable GAMEPORT support on Linux kernel for
|
First of all, you need to enable GAMEPORT support on Linux kernel for
|
||||||
using a joystick with the ALSA driver. For the details of gameport
|
using a joystick with the ALSA driver. For the details of gameport
|
||||||
support, refer to Documentation/input/joystick.txt.
|
support, refer to Documentation/input/joydev/joystick.rst.
|
||||||
|
|
||||||
The joystick support of ALSA drivers is different between ISA and PCI
|
The joystick support of ALSA drivers is different between ISA and PCI
|
||||||
cards. In the case of ISA (PnP) cards, it's usually handled by the
|
cards. In the case of ISA (PnP) cards, it's usually handled by the
|
||||||
|
|
|
||||||
|
|
@ -192,7 +192,7 @@ preset model instead of PCI (and codec-) SSID look-up.
|
||||||
What ``model`` option values are available depends on the codec chip.
|
What ``model`` option values are available depends on the codec chip.
|
||||||
Check your codec chip from the codec proc file (see "Codec Proc-File"
|
Check your codec chip from the codec proc file (see "Codec Proc-File"
|
||||||
section below). It will show the vendor/product name of your codec
|
section below). It will show the vendor/product name of your codec
|
||||||
chip. Then, see Documentation/sound/HD-Audio-Models.rst file,
|
chip. Then, see Documentation/sound/hd-audio/models.rst file,
|
||||||
the section of HD-audio driver. You can find a list of codecs
|
the section of HD-audio driver. You can find a list of codecs
|
||||||
and ``model`` options belonging to each codec. For example, for Realtek
|
and ``model`` options belonging to each codec. For example, for Realtek
|
||||||
ALC262 codec chip, pass ``model=ultra`` for devices that are compatible
|
ALC262 codec chip, pass ``model=ultra`` for devices that are compatible
|
||||||
|
|
|
||||||
|
|
@ -2498,7 +2498,7 @@ Mic boost
|
||||||
Mic-boost switch is set as “Mic Boost” or “Mic Boost (6dB)”.
|
Mic-boost switch is set as “Mic Boost” or “Mic Boost (6dB)”.
|
||||||
|
|
||||||
More precise information can be found in
|
More precise information can be found in
|
||||||
``Documentation/sound/alsa/ControlNames.txt``.
|
``Documentation/sound/designs/control-names.rst``.
|
||||||
|
|
||||||
Access Flags
|
Access Flags
|
||||||
------------
|
------------
|
||||||
|
|
|
||||||
|
|
@ -60,7 +60,7 @@ debug/ <empty>
|
||||||
dev/ device specific information (eg dev/cdrom/info)
|
dev/ device specific information (eg dev/cdrom/info)
|
||||||
fs/ specific filesystems
|
fs/ specific filesystems
|
||||||
filehandle, inode, dentry and quota tuning
|
filehandle, inode, dentry and quota tuning
|
||||||
binfmt_misc <Documentation/binfmt_misc.txt>
|
binfmt_misc <Documentation/admin-guide/binfmt-misc.rst>
|
||||||
kernel/ global kernel info / tuning
|
kernel/ global kernel info / tuning
|
||||||
miscellaneous stuff
|
miscellaneous stuff
|
||||||
net/ networking stuff, for documentation look in:
|
net/ networking stuff, for documentation look in:
|
||||||
|
|
|
||||||
|
|
@ -277,7 +277,7 @@ in a mount namespace.
|
||||||
----------------------------------------------------------
|
----------------------------------------------------------
|
||||||
|
|
||||||
Documentation for the files in /proc/sys/fs/binfmt_misc is
|
Documentation for the files in /proc/sys/fs/binfmt_misc is
|
||||||
in Documentation/binfmt_misc.txt.
|
in Documentation/admin-guide/binfmt-misc.rst.
|
||||||
|
|
||||||
|
|
||||||
3. /proc/sys/fs/mqueue - POSIX message queues filesystem
|
3. /proc/sys/fs/mqueue - POSIX message queues filesystem
|
||||||
|
|
|
||||||
|
|
@ -4,10 +4,10 @@ High resolution timers and dynamic ticks design notes
|
||||||
Further information can be found in the paper of the OLS 2006 talk "hrtimers
|
Further information can be found in the paper of the OLS 2006 talk "hrtimers
|
||||||
and beyond". The paper is part of the OLS 2006 Proceedings Volume 1, which can
|
and beyond". The paper is part of the OLS 2006 Proceedings Volume 1, which can
|
||||||
be found on the OLS website:
|
be found on the OLS website:
|
||||||
http://www.linuxsymposium.org/2006/linuxsymposium_procv1.pdf
|
https://www.kernel.org/doc/ols/2006/ols2006v1-pages-333-346.pdf
|
||||||
|
|
||||||
The slides to this talk are available from:
|
The slides to this talk are available from:
|
||||||
http://tglx.de/projects/hrtimers/ols2006-hrtimers.pdf
|
http://www.cs.columbia.edu/~nahum/w6998/papers/ols2006-hrtimers-slides.pdf
|
||||||
|
|
||||||
The slides contain five figures (pages 2, 15, 18, 20, 22), which illustrate the
|
The slides contain five figures (pages 2, 15, 18, 20, 22), which illustrate the
|
||||||
changes in the time(r) related Linux subsystems. Figure #1 (p. 2) shows the
|
changes in the time(r) related Linux subsystems. Figure #1 (p. 2) shows the
|
||||||
|
|
|
||||||
293
Documentation/trace/ftrace-uses.rst
Normal file
293
Documentation/trace/ftrace-uses.rst
Normal file
|
|
@ -0,0 +1,293 @@
|
||||||
|
=================================
|
||||||
|
Using ftrace to hook to functions
|
||||||
|
=================================
|
||||||
|
|
||||||
|
.. Copyright 2017 VMware Inc.
|
||||||
|
.. Author: Steven Rostedt <srostedt@goodmis.org>
|
||||||
|
.. License: The GNU Free Documentation License, Version 1.2
|
||||||
|
.. (dual licensed under the GPL v2)
|
||||||
|
|
||||||
|
Written for: 4.14
|
||||||
|
|
||||||
|
Introduction
|
||||||
|
============
|
||||||
|
|
||||||
|
The ftrace infrastructure was originially created to attach callbacks to the
|
||||||
|
beginning of functions in order to record and trace the flow of the kernel.
|
||||||
|
But callbacks to the start of a function can have other use cases. Either
|
||||||
|
for live kernel patching, or for security monitoring. This document describes
|
||||||
|
how to use ftrace to implement your own function callbacks.
|
||||||
|
|
||||||
|
|
||||||
|
The ftrace context
|
||||||
|
==================
|
||||||
|
|
||||||
|
WARNING: The ability to add a callback to almost any function within the
|
||||||
|
kernel comes with risks. A callback can be called from any context
|
||||||
|
(normal, softirq, irq, and NMI). Callbacks can also be called just before
|
||||||
|
going to idle, during CPU bring up and takedown, or going to user space.
|
||||||
|
This requires extra care to what can be done inside a callback. A callback
|
||||||
|
can be called outside the protective scope of RCU.
|
||||||
|
|
||||||
|
The ftrace infrastructure has some protections agains recursions and RCU
|
||||||
|
but one must still be very careful how they use the callbacks.
|
||||||
|
|
||||||
|
|
||||||
|
The ftrace_ops structure
|
||||||
|
========================
|
||||||
|
|
||||||
|
To register a function callback, a ftrace_ops is required. This structure
|
||||||
|
is used to tell ftrace what function should be called as the callback
|
||||||
|
as well as what protections the callback will perform and not require
|
||||||
|
ftrace to handle.
|
||||||
|
|
||||||
|
There is only one field that is needed to be set when registering
|
||||||
|
an ftrace_ops with ftrace::
|
||||||
|
|
||||||
|
.. code-block: c
|
||||||
|
|
||||||
|
struct ftrace_ops ops = {
|
||||||
|
.func = my_callback_func,
|
||||||
|
.flags = MY_FTRACE_FLAGS
|
||||||
|
.private = any_private_data_structure,
|
||||||
|
};
|
||||||
|
|
||||||
|
Both .flags and .private are optional. Only .func is required.
|
||||||
|
|
||||||
|
To enable tracing call::
|
||||||
|
|
||||||
|
.. c:function:: register_ftrace_function(&ops);
|
||||||
|
|
||||||
|
To disable tracing call::
|
||||||
|
|
||||||
|
.. c:function:: unregister_ftrace_function(&ops);
|
||||||
|
|
||||||
|
The above is defined by including the header::
|
||||||
|
|
||||||
|
.. c:function:: #include <linux/ftrace.h>
|
||||||
|
|
||||||
|
The registered callback will start being called some time after the
|
||||||
|
register_ftrace_function() is called and before it returns. The exact time
|
||||||
|
that callbacks start being called is dependent upon architecture and scheduling
|
||||||
|
of services. The callback itself will have to handle any synchronization if it
|
||||||
|
must begin at an exact moment.
|
||||||
|
|
||||||
|
The unregister_ftrace_function() will guarantee that the callback is
|
||||||
|
no longer being called by functions after the unregister_ftrace_function()
|
||||||
|
returns. Note that to perform this guarantee, the unregister_ftrace_function()
|
||||||
|
may take some time to finish.
|
||||||
|
|
||||||
|
|
||||||
|
The callback function
|
||||||
|
=====================
|
||||||
|
|
||||||
|
The prototype of the callback function is as follows (as of v4.14)::
|
||||||
|
|
||||||
|
.. code-block: c
|
||||||
|
|
||||||
|
void callback_func(unsigned long ip, unsigned long parent_ip,
|
||||||
|
struct ftrace_ops *op, struct pt_regs *regs);
|
||||||
|
|
||||||
|
@ip
|
||||||
|
This is the instruction pointer of the function that is being traced.
|
||||||
|
(where the fentry or mcount is within the function)
|
||||||
|
|
||||||
|
@parent_ip
|
||||||
|
This is the instruction pointer of the function that called the
|
||||||
|
the function being traced (where the call of the function occurred).
|
||||||
|
|
||||||
|
@op
|
||||||
|
This is a pointer to ftrace_ops that was used to register the callback.
|
||||||
|
This can be used to pass data to the callback via the private pointer.
|
||||||
|
|
||||||
|
@regs
|
||||||
|
If the FTRACE_OPS_FL_SAVE_REGS or FTRACE_OPS_FL_SAVE_REGS_IF_SUPPORTED
|
||||||
|
flags are set in the ftrace_ops structure, then this will be pointing
|
||||||
|
to the pt_regs structure like it would be if an breakpoint was placed
|
||||||
|
at the start of the function where ftrace was tracing. Otherwise it
|
||||||
|
either contains garbage, or NULL.
|
||||||
|
|
||||||
|
|
||||||
|
The ftrace FLAGS
|
||||||
|
================
|
||||||
|
|
||||||
|
The ftrace_ops flags are all defined and documented in include/linux/ftrace.h.
|
||||||
|
Some of the flags are used for internal infrastructure of ftrace, but the
|
||||||
|
ones that users should be aware of are the following:
|
||||||
|
|
||||||
|
FTRACE_OPS_FL_SAVE_REGS
|
||||||
|
If the callback requires reading or modifying the pt_regs
|
||||||
|
passed to the callback, then it must set this flag. Registering
|
||||||
|
a ftrace_ops with this flag set on an architecture that does not
|
||||||
|
support passing of pt_regs to the callback will fail.
|
||||||
|
|
||||||
|
FTRACE_OPS_FL_SAVE_REGS_IF_SUPPORTED
|
||||||
|
Similar to SAVE_REGS but the registering of a
|
||||||
|
ftrace_ops on an architecture that does not support passing of regs
|
||||||
|
will not fail with this flag set. But the callback must check if
|
||||||
|
regs is NULL or not to determine if the architecture supports it.
|
||||||
|
|
||||||
|
FTRACE_OPS_FL_RECURSION_SAFE
|
||||||
|
By default, a wrapper is added around the callback to
|
||||||
|
make sure that recursion of the function does not occur. That is,
|
||||||
|
if a function that is called as a result of the callback's execution
|
||||||
|
is also traced, ftrace will prevent the callback from being called
|
||||||
|
again. But this wrapper adds some overhead, and if the callback is
|
||||||
|
safe from recursion, it can set this flag to disable the ftrace
|
||||||
|
protection.
|
||||||
|
|
||||||
|
Note, if this flag is set, and recursion does occur, it could cause
|
||||||
|
the system to crash, and possibly reboot via a triple fault.
|
||||||
|
|
||||||
|
It is OK if another callback traces a function that is called by a
|
||||||
|
callback that is marked recursion safe. Recursion safe callbacks
|
||||||
|
must never trace any function that are called by the callback
|
||||||
|
itself or any nested functions that those functions call.
|
||||||
|
|
||||||
|
If this flag is set, it is possible that the callback will also
|
||||||
|
be called with preemption enabled (when CONFIG_PREEMPT is set),
|
||||||
|
but this is not guaranteed.
|
||||||
|
|
||||||
|
FTRACE_OPS_FL_IPMODIFY
|
||||||
|
Requires FTRACE_OPS_FL_SAVE_REGS set. If the callback is to "hijack"
|
||||||
|
the traced function (have another function called instead of the
|
||||||
|
traced function), it requires setting this flag. This is what live
|
||||||
|
kernel patches uses. Without this flag the pt_regs->ip can not be
|
||||||
|
modified.
|
||||||
|
|
||||||
|
Note, only one ftrace_ops with FTRACE_OPS_FL_IPMODIFY set may be
|
||||||
|
registered to any given function at a time.
|
||||||
|
|
||||||
|
FTRACE_OPS_FL_RCU
|
||||||
|
If this is set, then the callback will only be called by functions
|
||||||
|
where RCU is "watching". This is required if the callback function
|
||||||
|
performs any rcu_read_lock() operation.
|
||||||
|
|
||||||
|
RCU stops watching when the system goes idle, the time when a CPU
|
||||||
|
is taken down and comes back online, and when entering from kernel
|
||||||
|
to user space and back to kernel space. During these transitions,
|
||||||
|
a callback may be executed and RCU synchronization will not protect
|
||||||
|
it.
|
||||||
|
|
||||||
|
|
||||||
|
Filtering which functions to trace
|
||||||
|
==================================
|
||||||
|
|
||||||
|
If a callback is only to be called from specific functions, a filter must be
|
||||||
|
set up. The filters are added by name, or ip if it is known.
|
||||||
|
|
||||||
|
.. code-block: c
|
||||||
|
|
||||||
|
int ftrace_set_filter(struct ftrace_ops *ops, unsigned char *buf,
|
||||||
|
int len, int reset);
|
||||||
|
|
||||||
|
@ops
|
||||||
|
The ops to set the filter with
|
||||||
|
|
||||||
|
@buf
|
||||||
|
The string that holds the function filter text.
|
||||||
|
@len
|
||||||
|
The length of the string.
|
||||||
|
|
||||||
|
@reset
|
||||||
|
Non-zero to reset all filters before applying this filter.
|
||||||
|
|
||||||
|
Filters denote which functions should be enabled when tracing is enabled.
|
||||||
|
If @buf is NULL and reset is set, all functions will be enabled for tracing.
|
||||||
|
|
||||||
|
The @buf can also be a glob expression to enable all functions that
|
||||||
|
match a specific pattern.
|
||||||
|
|
||||||
|
See Filter Commands in :file:`Documentation/trace/ftrace.txt`.
|
||||||
|
|
||||||
|
To just trace the schedule function::
|
||||||
|
|
||||||
|
.. code-block: c
|
||||||
|
|
||||||
|
ret = ftrace_set_filter(&ops, "schedule", strlen("schedule"), 0);
|
||||||
|
|
||||||
|
To add more functions, call the ftrace_set_filter() more than once with the
|
||||||
|
@reset parameter set to zero. To remove the current filter set and replace it
|
||||||
|
with new functions defined by @buf, have @reset be non-zero.
|
||||||
|
|
||||||
|
To remove all the filtered functions and trace all functions::
|
||||||
|
|
||||||
|
.. code-block: c
|
||||||
|
|
||||||
|
ret = ftrace_set_filter(&ops, NULL, 0, 1);
|
||||||
|
|
||||||
|
|
||||||
|
Sometimes more than one function has the same name. To trace just a specific
|
||||||
|
function in this case, ftrace_set_filter_ip() can be used.
|
||||||
|
|
||||||
|
.. code-block: c
|
||||||
|
|
||||||
|
ret = ftrace_set_filter_ip(&ops, ip, 0, 0);
|
||||||
|
|
||||||
|
Although the ip must be the address where the call to fentry or mcount is
|
||||||
|
located in the function. This function is used by perf and kprobes that
|
||||||
|
gets the ip address from the user (usually using debug info from the kernel).
|
||||||
|
|
||||||
|
If a glob is used to set the filter, functions can be added to a "notrace"
|
||||||
|
list that will prevent those functions from calling the callback.
|
||||||
|
The "notrace" list takes precedence over the "filter" list. If the
|
||||||
|
two lists are non-empty and contain the same functions, the callback will not
|
||||||
|
be called by any function.
|
||||||
|
|
||||||
|
An empty "notrace" list means to allow all functions defined by the filter
|
||||||
|
to be traced.
|
||||||
|
|
||||||
|
.. code-block: c
|
||||||
|
|
||||||
|
int ftrace_set_notrace(struct ftrace_ops *ops, unsigned char *buf,
|
||||||
|
int len, int reset);
|
||||||
|
|
||||||
|
This takes the same parameters as ftrace_set_filter() but will add the
|
||||||
|
functions it finds to not be traced. This is a separate list from the
|
||||||
|
filter list, and this function does not modify the filter list.
|
||||||
|
|
||||||
|
A non-zero @reset will clear the "notrace" list before adding functions
|
||||||
|
that match @buf to it.
|
||||||
|
|
||||||
|
Clearing the "notrace" list is the same as clearing the filter list
|
||||||
|
|
||||||
|
.. code-block: c
|
||||||
|
|
||||||
|
ret = ftrace_set_notrace(&ops, NULL, 0, 1);
|
||||||
|
|
||||||
|
The filter and notrace lists may be changed at any time. If only a set of
|
||||||
|
functions should call the callback, it is best to set the filters before
|
||||||
|
registering the callback. But the changes may also happen after the callback
|
||||||
|
has been registered.
|
||||||
|
|
||||||
|
If a filter is in place, and the @reset is non-zero, and @buf contains a
|
||||||
|
matching glob to functions, the switch will happen during the time of
|
||||||
|
the ftrace_set_filter() call. At no time will all functions call the callback.
|
||||||
|
|
||||||
|
.. code-block: c
|
||||||
|
|
||||||
|
ftrace_set_filter(&ops, "schedule", strlen("schedule"), 1);
|
||||||
|
|
||||||
|
register_ftrace_function(&ops);
|
||||||
|
|
||||||
|
msleep(10);
|
||||||
|
|
||||||
|
ftrace_set_filter(&ops, "try_to_wake_up", strlen("try_to_wake_up"), 1);
|
||||||
|
|
||||||
|
is not the same as:
|
||||||
|
|
||||||
|
.. code-block: c
|
||||||
|
|
||||||
|
ftrace_set_filter(&ops, "schedule", strlen("schedule"), 1);
|
||||||
|
|
||||||
|
register_ftrace_function(&ops);
|
||||||
|
|
||||||
|
msleep(10);
|
||||||
|
|
||||||
|
ftrace_set_filter(&ops, NULL, 0, 1);
|
||||||
|
|
||||||
|
ftrace_set_filter(&ops, "try_to_wake_up", strlen("try_to_wake_up"), 0);
|
||||||
|
|
||||||
|
As the latter will have a short time where all functions will call
|
||||||
|
the callback, between the time of the reset, and the time of the
|
||||||
|
new setting of the filter.
|
||||||
|
|
@ -37,7 +37,7 @@ description is at Documentation/ABI/testing/sysfs-bus-intel_th-devices-gth.
|
||||||
|
|
||||||
STH registers an stm class device, through which it provides interface
|
STH registers an stm class device, through which it provides interface
|
||||||
to userspace and kernelspace software trace sources. See
|
to userspace and kernelspace software trace sources. See
|
||||||
Documentation/tracing/stm.txt for more information on that.
|
Documentation/trace/stm.txt for more information on that.
|
||||||
|
|
||||||
MSU can be configured to collect trace data into a system memory
|
MSU can be configured to collect trace data into a system memory
|
||||||
buffer, which can later on be read from its device nodes via read() or
|
buffer, which can later on be read from its device nodes via read() or
|
||||||
|
|
|
||||||
|
|
@ -773,7 +773,7 @@ host:
|
||||||
# cat /dev/usb/lp0
|
# cat /dev/usb/lp0
|
||||||
|
|
||||||
More advanced testing can be done with the prn_example
|
More advanced testing can be done with the prn_example
|
||||||
described in Documentation/usb/gadget-printer.txt.
|
described in Documentation/usb/gadget_printer.txt.
|
||||||
|
|
||||||
|
|
||||||
20. UAC1 function (virtual ALSA card, using u_audio API)
|
20. UAC1 function (virtual ALSA card, using u_audio API)
|
||||||
|
|
|
||||||
|
|
@ -15,7 +15,7 @@ Last reviewed: 05/20/2016
|
||||||
|
|
||||||
Watchdog functionality is enabled like any other common watchdog driver. That
|
Watchdog functionality is enabled like any other common watchdog driver. That
|
||||||
is, an application needs to be started that kicks off the watchdog timer. A
|
is, an application needs to be started that kicks off the watchdog timer. A
|
||||||
basic application exists in the Documentation/watchdog/src directory called
|
basic application exists in tools/testing/selftests/watchdog/ named
|
||||||
watchdog-test.c. Simply compile the C file and kick it off. If the system
|
watchdog-test.c. Simply compile the C file and kick it off. If the system
|
||||||
gets into a bad state and hangs, the HPE ProLiant iLO timer register will
|
gets into a bad state and hangs, the HPE ProLiant iLO timer register will
|
||||||
not be updated in a timely fashion and a hardware system reset (also known as
|
not be updated in a timely fashion and a hardware system reset (also known as
|
||||||
|
|
|
||||||
|
|
@ -25,7 +25,7 @@ Last reviewed: 10/05/2007
|
||||||
|
|
||||||
If you want to write a program to be compatible with the PC Watchdog
|
If you want to write a program to be compatible with the PC Watchdog
|
||||||
driver, simply use of modify the watchdog test program:
|
driver, simply use of modify the watchdog test program:
|
||||||
Documentation/watchdog/src/watchdog-test.c
|
tools/testing/selftests/watchdog/watchdog-test.c
|
||||||
|
|
||||||
|
|
||||||
Other IOCTL functions include:
|
Other IOCTL functions include:
|
||||||
|
|
|
||||||
|
|
@ -4234,7 +4234,7 @@ S: Maintained
|
||||||
F: drivers/dma/
|
F: drivers/dma/
|
||||||
F: include/linux/dmaengine.h
|
F: include/linux/dmaengine.h
|
||||||
F: Documentation/devicetree/bindings/dma/
|
F: Documentation/devicetree/bindings/dma/
|
||||||
F: Documentation/dmaengine/
|
F: Documentation/driver-api/dmaengine/
|
||||||
T: git git://git.infradead.org/users/vkoul/slave-dma.git
|
T: git git://git.infradead.org/users/vkoul/slave-dma.git
|
||||||
|
|
||||||
DMA MAPPING HELPERS
|
DMA MAPPING HELPERS
|
||||||
|
|
|
||||||
3
Makefile
3
Makefile
|
|
@ -1459,7 +1459,8 @@ $(help-board-dirs): help-%:
|
||||||
|
|
||||||
# Documentation targets
|
# Documentation targets
|
||||||
# ---------------------------------------------------------------------------
|
# ---------------------------------------------------------------------------
|
||||||
DOC_TARGETS := xmldocs latexdocs pdfdocs htmldocs epubdocs cleandocs linkcheckdocs
|
DOC_TARGETS := xmldocs latexdocs pdfdocs htmldocs epubdocs cleandocs \
|
||||||
|
linkcheckdocs dochelp refcheckdocs
|
||||||
PHONY += $(DOC_TARGETS)
|
PHONY += $(DOC_TARGETS)
|
||||||
$(DOC_TARGETS): scripts_basic FORCE
|
$(DOC_TARGETS): scripts_basic FORCE
|
||||||
$(Q)$(MAKE) $(build)=Documentation $@
|
$(Q)$(MAKE) $(build)=Documentation $@
|
||||||
|
|
|
||||||
|
|
@ -26,6 +26,20 @@
|
||||||
|
|
||||||
#if BITS_PER_LONG == 64
|
#if BITS_PER_LONG == 64
|
||||||
|
|
||||||
|
/**
|
||||||
|
* do_div - returns 2 values: calculate remainder and update new dividend
|
||||||
|
* @n: pointer to uint64_t dividend (will be updated)
|
||||||
|
* @base: uint32_t divisor
|
||||||
|
*
|
||||||
|
* Summary:
|
||||||
|
* ``uint32_t remainder = *n % base;``
|
||||||
|
* ``*n = *n / base;``
|
||||||
|
*
|
||||||
|
* Return: (uint32_t)remainder
|
||||||
|
*
|
||||||
|
* NOTE: macro parameter @n is evaluated multiple times,
|
||||||
|
* beware of side effects!
|
||||||
|
*/
|
||||||
# define do_div(n,base) ({ \
|
# define do_div(n,base) ({ \
|
||||||
uint32_t __base = (base); \
|
uint32_t __base = (base); \
|
||||||
uint32_t __rem; \
|
uint32_t __rem; \
|
||||||
|
|
|
||||||
|
|
@ -22,65 +22,74 @@
|
||||||
* See lib/bitmap.c for more details.
|
* See lib/bitmap.c for more details.
|
||||||
*/
|
*/
|
||||||
|
|
||||||
/*
|
/**
|
||||||
|
* DOC: bitmap overview
|
||||||
|
*
|
||||||
* The available bitmap operations and their rough meaning in the
|
* The available bitmap operations and their rough meaning in the
|
||||||
* case that the bitmap is a single unsigned long are thus:
|
* case that the bitmap is a single unsigned long are thus:
|
||||||
*
|
*
|
||||||
* Note that nbits should be always a compile time evaluable constant.
|
* Note that nbits should be always a compile time evaluable constant.
|
||||||
* Otherwise many inlines will generate horrible code.
|
* Otherwise many inlines will generate horrible code.
|
||||||
*
|
*
|
||||||
* bitmap_zero(dst, nbits) *dst = 0UL
|
* ::
|
||||||
* bitmap_fill(dst, nbits) *dst = ~0UL
|
*
|
||||||
* bitmap_copy(dst, src, nbits) *dst = *src
|
* bitmap_zero(dst, nbits) *dst = 0UL
|
||||||
* bitmap_and(dst, src1, src2, nbits) *dst = *src1 & *src2
|
* bitmap_fill(dst, nbits) *dst = ~0UL
|
||||||
* bitmap_or(dst, src1, src2, nbits) *dst = *src1 | *src2
|
* bitmap_copy(dst, src, nbits) *dst = *src
|
||||||
* bitmap_xor(dst, src1, src2, nbits) *dst = *src1 ^ *src2
|
* bitmap_and(dst, src1, src2, nbits) *dst = *src1 & *src2
|
||||||
* bitmap_andnot(dst, src1, src2, nbits) *dst = *src1 & ~(*src2)
|
* bitmap_or(dst, src1, src2, nbits) *dst = *src1 | *src2
|
||||||
* bitmap_complement(dst, src, nbits) *dst = ~(*src)
|
* bitmap_xor(dst, src1, src2, nbits) *dst = *src1 ^ *src2
|
||||||
* bitmap_equal(src1, src2, nbits) Are *src1 and *src2 equal?
|
* bitmap_andnot(dst, src1, src2, nbits) *dst = *src1 & ~(*src2)
|
||||||
* bitmap_intersects(src1, src2, nbits) Do *src1 and *src2 overlap?
|
* bitmap_complement(dst, src, nbits) *dst = ~(*src)
|
||||||
* bitmap_subset(src1, src2, nbits) Is *src1 a subset of *src2?
|
* bitmap_equal(src1, src2, nbits) Are *src1 and *src2 equal?
|
||||||
* bitmap_empty(src, nbits) Are all bits zero in *src?
|
* bitmap_intersects(src1, src2, nbits) Do *src1 and *src2 overlap?
|
||||||
* bitmap_full(src, nbits) Are all bits set in *src?
|
* bitmap_subset(src1, src2, nbits) Is *src1 a subset of *src2?
|
||||||
* bitmap_weight(src, nbits) Hamming Weight: number set bits
|
* bitmap_empty(src, nbits) Are all bits zero in *src?
|
||||||
* bitmap_set(dst, pos, nbits) Set specified bit area
|
* bitmap_full(src, nbits) Are all bits set in *src?
|
||||||
* bitmap_clear(dst, pos, nbits) Clear specified bit area
|
* bitmap_weight(src, nbits) Hamming Weight: number set bits
|
||||||
* bitmap_find_next_zero_area(buf, len, pos, n, mask) Find bit free area
|
* bitmap_set(dst, pos, nbits) Set specified bit area
|
||||||
* bitmap_find_next_zero_area_off(buf, len, pos, n, mask) as above
|
* bitmap_clear(dst, pos, nbits) Clear specified bit area
|
||||||
* bitmap_shift_right(dst, src, n, nbits) *dst = *src >> n
|
* bitmap_find_next_zero_area(buf, len, pos, n, mask) Find bit free area
|
||||||
* bitmap_shift_left(dst, src, n, nbits) *dst = *src << n
|
* bitmap_find_next_zero_area_off(buf, len, pos, n, mask) as above
|
||||||
* bitmap_remap(dst, src, old, new, nbits) *dst = map(old, new)(src)
|
* bitmap_shift_right(dst, src, n, nbits) *dst = *src >> n
|
||||||
* bitmap_bitremap(oldbit, old, new, nbits) newbit = map(old, new)(oldbit)
|
* bitmap_shift_left(dst, src, n, nbits) *dst = *src << n
|
||||||
* bitmap_onto(dst, orig, relmap, nbits) *dst = orig relative to relmap
|
* bitmap_remap(dst, src, old, new, nbits) *dst = map(old, new)(src)
|
||||||
* bitmap_fold(dst, orig, sz, nbits) dst bits = orig bits mod sz
|
* bitmap_bitremap(oldbit, old, new, nbits) newbit = map(old, new)(oldbit)
|
||||||
* bitmap_parse(buf, buflen, dst, nbits) Parse bitmap dst from kernel buf
|
* bitmap_onto(dst, orig, relmap, nbits) *dst = orig relative to relmap
|
||||||
* bitmap_parse_user(ubuf, ulen, dst, nbits) Parse bitmap dst from user buf
|
* bitmap_fold(dst, orig, sz, nbits) dst bits = orig bits mod sz
|
||||||
* bitmap_parselist(buf, dst, nbits) Parse bitmap dst from kernel buf
|
* bitmap_parse(buf, buflen, dst, nbits) Parse bitmap dst from kernel buf
|
||||||
* bitmap_parselist_user(buf, dst, nbits) Parse bitmap dst from user buf
|
* bitmap_parse_user(ubuf, ulen, dst, nbits) Parse bitmap dst from user buf
|
||||||
* bitmap_find_free_region(bitmap, bits, order) Find and allocate bit region
|
* bitmap_parselist(buf, dst, nbits) Parse bitmap dst from kernel buf
|
||||||
* bitmap_release_region(bitmap, pos, order) Free specified bit region
|
* bitmap_parselist_user(buf, dst, nbits) Parse bitmap dst from user buf
|
||||||
* bitmap_allocate_region(bitmap, pos, order) Allocate specified bit region
|
* bitmap_find_free_region(bitmap, bits, order) Find and allocate bit region
|
||||||
* bitmap_from_u32array(dst, nbits, buf, nwords) *dst = *buf (nwords 32b words)
|
* bitmap_release_region(bitmap, pos, order) Free specified bit region
|
||||||
* bitmap_to_u32array(buf, nwords, src, nbits) *buf = *dst (nwords 32b words)
|
* bitmap_allocate_region(bitmap, pos, order) Allocate specified bit region
|
||||||
*/
|
* bitmap_from_u32array(dst, nbits, buf, nwords) *dst = *buf (nwords 32b words)
|
||||||
|
* bitmap_to_u32array(buf, nwords, src, nbits) *buf = *dst (nwords 32b words)
|
||||||
/*
|
|
||||||
* Also the following operations in asm/bitops.h apply to bitmaps.
|
|
||||||
*
|
*
|
||||||
* set_bit(bit, addr) *addr |= bit
|
|
||||||
* clear_bit(bit, addr) *addr &= ~bit
|
|
||||||
* change_bit(bit, addr) *addr ^= bit
|
|
||||||
* test_bit(bit, addr) Is bit set in *addr?
|
|
||||||
* test_and_set_bit(bit, addr) Set bit and return old value
|
|
||||||
* test_and_clear_bit(bit, addr) Clear bit and return old value
|
|
||||||
* test_and_change_bit(bit, addr) Change bit and return old value
|
|
||||||
* find_first_zero_bit(addr, nbits) Position first zero bit in *addr
|
|
||||||
* find_first_bit(addr, nbits) Position first set bit in *addr
|
|
||||||
* find_next_zero_bit(addr, nbits, bit) Position next zero bit in *addr >= bit
|
|
||||||
* find_next_bit(addr, nbits, bit) Position next set bit in *addr >= bit
|
|
||||||
*/
|
*/
|
||||||
|
|
||||||
/*
|
/**
|
||||||
|
* DOC: bitmap bitops
|
||||||
|
*
|
||||||
|
* Also the following operations in asm/bitops.h apply to bitmaps.::
|
||||||
|
*
|
||||||
|
* set_bit(bit, addr) *addr |= bit
|
||||||
|
* clear_bit(bit, addr) *addr &= ~bit
|
||||||
|
* change_bit(bit, addr) *addr ^= bit
|
||||||
|
* test_bit(bit, addr) Is bit set in *addr?
|
||||||
|
* test_and_set_bit(bit, addr) Set bit and return old value
|
||||||
|
* test_and_clear_bit(bit, addr) Clear bit and return old value
|
||||||
|
* test_and_change_bit(bit, addr) Change bit and return old value
|
||||||
|
* find_first_zero_bit(addr, nbits) Position first zero bit in *addr
|
||||||
|
* find_first_bit(addr, nbits) Position first set bit in *addr
|
||||||
|
* find_next_zero_bit(addr, nbits, bit) Position next zero bit in *addr >= bit
|
||||||
|
* find_next_bit(addr, nbits, bit) Position next set bit in *addr >= bit
|
||||||
|
*
|
||||||
|
*/
|
||||||
|
|
||||||
|
/**
|
||||||
|
* DOC: declare bitmap
|
||||||
* The DECLARE_BITMAP(name,bits) macro, in linux/types.h, can be used
|
* The DECLARE_BITMAP(name,bits) macro, in linux/types.h, can be used
|
||||||
* to declare an array named 'name' of just enough unsigned longs to
|
* to declare an array named 'name' of just enough unsigned longs to
|
||||||
* contain all bit positions from 0 to 'bits' - 1.
|
* contain all bit positions from 0 to 'bits' - 1.
|
||||||
|
|
@ -361,8 +370,9 @@ static inline int bitmap_parse(const char *buf, unsigned int buflen,
|
||||||
return __bitmap_parse(buf, buflen, 0, maskp, nmaskbits);
|
return __bitmap_parse(buf, buflen, 0, maskp, nmaskbits);
|
||||||
}
|
}
|
||||||
|
|
||||||
/*
|
/**
|
||||||
* BITMAP_FROM_U64() - Represent u64 value in the format suitable for bitmap.
|
* BITMAP_FROM_U64() - Represent u64 value in the format suitable for bitmap.
|
||||||
|
* @n: u64 value
|
||||||
*
|
*
|
||||||
* Linux bitmaps are internally arrays of unsigned longs, i.e. 32-bit
|
* Linux bitmaps are internally arrays of unsigned longs, i.e. 32-bit
|
||||||
* integers in 32-bit environment, and 64-bit integers in 64-bit one.
|
* integers in 32-bit environment, and 64-bit integers in 64-bit one.
|
||||||
|
|
@ -393,14 +403,14 @@ static inline int bitmap_parse(const char *buf, unsigned int buflen,
|
||||||
((unsigned long) ((u64)(n) >> 32))
|
((unsigned long) ((u64)(n) >> 32))
|
||||||
#endif
|
#endif
|
||||||
|
|
||||||
/*
|
/**
|
||||||
* bitmap_from_u64 - Check and swap words within u64.
|
* bitmap_from_u64 - Check and swap words within u64.
|
||||||
* @mask: source bitmap
|
* @mask: source bitmap
|
||||||
* @dst: destination bitmap
|
* @dst: destination bitmap
|
||||||
*
|
*
|
||||||
* In 32-bit Big Endian kernel, when using (u32 *)(&val)[*]
|
* In 32-bit Big Endian kernel, when using ``(u32 *)(&val)[*]``
|
||||||
* to read u64 mask, we will get the wrong word.
|
* to read u64 mask, we will get the wrong word.
|
||||||
* That is "(u32 *)(&val)[0]" gets the upper 32 bits,
|
* That is ``(u32 *)(&val)[0]`` gets the upper 32 bits,
|
||||||
* but we expect the lower 32-bits of u64.
|
* but we expect the lower 32-bits of u64.
|
||||||
*/
|
*/
|
||||||
static inline void bitmap_from_u64(unsigned long *dst, u64 mask)
|
static inline void bitmap_from_u64(unsigned long *dst, u64 mask)
|
||||||
|
|
|
||||||
|
|
@ -37,19 +37,23 @@ int __ilog2_u64(u64 n)
|
||||||
}
|
}
|
||||||
#endif
|
#endif
|
||||||
|
|
||||||
/*
|
/**
|
||||||
* Determine whether some value is a power of two, where zero is
|
* is_power_of_2() - check if a value is a power of two
|
||||||
|
* @n: the value to check
|
||||||
|
*
|
||||||
|
* Determine whether some value is a power of two, where zero is
|
||||||
* *not* considered a power of two.
|
* *not* considered a power of two.
|
||||||
|
* Return: true if @n is a power of 2, otherwise false.
|
||||||
*/
|
*/
|
||||||
|
|
||||||
static inline __attribute__((const))
|
static inline __attribute__((const))
|
||||||
bool is_power_of_2(unsigned long n)
|
bool is_power_of_2(unsigned long n)
|
||||||
{
|
{
|
||||||
return (n != 0 && ((n & (n - 1)) == 0));
|
return (n != 0 && ((n & (n - 1)) == 0));
|
||||||
}
|
}
|
||||||
|
|
||||||
/*
|
/**
|
||||||
* round up to nearest power of two
|
* __roundup_pow_of_two() - round up to nearest power of two
|
||||||
|
* @n: value to round up
|
||||||
*/
|
*/
|
||||||
static inline __attribute__((const))
|
static inline __attribute__((const))
|
||||||
unsigned long __roundup_pow_of_two(unsigned long n)
|
unsigned long __roundup_pow_of_two(unsigned long n)
|
||||||
|
|
@ -57,8 +61,9 @@ unsigned long __roundup_pow_of_two(unsigned long n)
|
||||||
return 1UL << fls_long(n - 1);
|
return 1UL << fls_long(n - 1);
|
||||||
}
|
}
|
||||||
|
|
||||||
/*
|
/**
|
||||||
* round down to nearest power of two
|
* __rounddown_pow_of_two() - round down to nearest power of two
|
||||||
|
* @n: value to round down
|
||||||
*/
|
*/
|
||||||
static inline __attribute__((const))
|
static inline __attribute__((const))
|
||||||
unsigned long __rounddown_pow_of_two(unsigned long n)
|
unsigned long __rounddown_pow_of_two(unsigned long n)
|
||||||
|
|
@ -67,12 +72,12 @@ unsigned long __rounddown_pow_of_two(unsigned long n)
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* ilog2 - log of base 2 of 32-bit or a 64-bit unsigned value
|
* ilog2 - log base 2 of 32-bit or a 64-bit unsigned value
|
||||||
* @n - parameter
|
* @n: parameter
|
||||||
*
|
*
|
||||||
* constant-capable log of base 2 calculation
|
* constant-capable log of base 2 calculation
|
||||||
* - this can be used to initialise global variables from constant data, hence
|
* - this can be used to initialise global variables from constant data, hence
|
||||||
* the massive ternary operator construction
|
* the massive ternary operator construction
|
||||||
*
|
*
|
||||||
* selects the appropriately-sized optimised version depending on sizeof(n)
|
* selects the appropriately-sized optimised version depending on sizeof(n)
|
||||||
*/
|
*/
|
||||||
|
|
@ -150,7 +155,7 @@ unsigned long __rounddown_pow_of_two(unsigned long n)
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* roundup_pow_of_two - round the given value up to nearest power of two
|
* roundup_pow_of_two - round the given value up to nearest power of two
|
||||||
* @n - parameter
|
* @n: parameter
|
||||||
*
|
*
|
||||||
* round the given value up to the nearest power of two
|
* round the given value up to the nearest power of two
|
||||||
* - the result is undefined when n == 0
|
* - the result is undefined when n == 0
|
||||||
|
|
@ -167,7 +172,7 @@ unsigned long __rounddown_pow_of_two(unsigned long n)
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* rounddown_pow_of_two - round the given value down to nearest power of two
|
* rounddown_pow_of_two - round the given value down to nearest power of two
|
||||||
* @n - parameter
|
* @n: parameter
|
||||||
*
|
*
|
||||||
* round the given value down to the nearest power of two
|
* round the given value down to the nearest power of two
|
||||||
* - the result is undefined when n == 0
|
* - the result is undefined when n == 0
|
||||||
|
|
@ -180,6 +185,12 @@ unsigned long __rounddown_pow_of_two(unsigned long n)
|
||||||
__rounddown_pow_of_two(n) \
|
__rounddown_pow_of_two(n) \
|
||||||
)
|
)
|
||||||
|
|
||||||
|
static inline __attribute_const__
|
||||||
|
int __order_base_2(unsigned long n)
|
||||||
|
{
|
||||||
|
return n > 1 ? ilog2(n - 1) + 1 : 0;
|
||||||
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* order_base_2 - calculate the (rounded up) base 2 order of the argument
|
* order_base_2 - calculate the (rounded up) base 2 order of the argument
|
||||||
* @n: parameter
|
* @n: parameter
|
||||||
|
|
@ -193,13 +204,6 @@ unsigned long __rounddown_pow_of_two(unsigned long n)
|
||||||
* ob2(5) = 3
|
* ob2(5) = 3
|
||||||
* ... and so on.
|
* ... and so on.
|
||||||
*/
|
*/
|
||||||
|
|
||||||
static inline __attribute_const__
|
|
||||||
int __order_base_2(unsigned long n)
|
|
||||||
{
|
|
||||||
return n > 1 ? ilog2(n - 1) + 1 : 0;
|
|
||||||
}
|
|
||||||
|
|
||||||
#define order_base_2(n) \
|
#define order_base_2(n) \
|
||||||
( \
|
( \
|
||||||
__builtin_constant_p(n) ? ( \
|
__builtin_constant_p(n) ? ( \
|
||||||
|
|
|
||||||
|
|
@ -12,6 +12,11 @@
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* div_u64_rem - unsigned 64bit divide with 32bit divisor with remainder
|
* div_u64_rem - unsigned 64bit divide with 32bit divisor with remainder
|
||||||
|
* @dividend: unsigned 64bit dividend
|
||||||
|
* @divisor: unsigned 32bit divisor
|
||||||
|
* @remainder: pointer to unsigned 32bit remainder
|
||||||
|
*
|
||||||
|
* Return: sets ``*remainder``, then returns dividend / divisor
|
||||||
*
|
*
|
||||||
* This is commonly provided by 32bit archs to provide an optimized 64bit
|
* This is commonly provided by 32bit archs to provide an optimized 64bit
|
||||||
* divide.
|
* divide.
|
||||||
|
|
@ -24,6 +29,11 @@ static inline u64 div_u64_rem(u64 dividend, u32 divisor, u32 *remainder)
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* div_s64_rem - signed 64bit divide with 32bit divisor with remainder
|
* div_s64_rem - signed 64bit divide with 32bit divisor with remainder
|
||||||
|
* @dividend: signed 64bit dividend
|
||||||
|
* @divisor: signed 32bit divisor
|
||||||
|
* @remainder: pointer to signed 32bit remainder
|
||||||
|
*
|
||||||
|
* Return: sets ``*remainder``, then returns dividend / divisor
|
||||||
*/
|
*/
|
||||||
static inline s64 div_s64_rem(s64 dividend, s32 divisor, s32 *remainder)
|
static inline s64 div_s64_rem(s64 dividend, s32 divisor, s32 *remainder)
|
||||||
{
|
{
|
||||||
|
|
@ -33,6 +43,11 @@ static inline s64 div_s64_rem(s64 dividend, s32 divisor, s32 *remainder)
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* div64_u64_rem - unsigned 64bit divide with 64bit divisor and remainder
|
* div64_u64_rem - unsigned 64bit divide with 64bit divisor and remainder
|
||||||
|
* @dividend: unsigned 64bit dividend
|
||||||
|
* @divisor: unsigned 64bit divisor
|
||||||
|
* @remainder: pointer to unsigned 64bit remainder
|
||||||
|
*
|
||||||
|
* Return: sets ``*remainder``, then returns dividend / divisor
|
||||||
*/
|
*/
|
||||||
static inline u64 div64_u64_rem(u64 dividend, u64 divisor, u64 *remainder)
|
static inline u64 div64_u64_rem(u64 dividend, u64 divisor, u64 *remainder)
|
||||||
{
|
{
|
||||||
|
|
@ -42,6 +57,10 @@ static inline u64 div64_u64_rem(u64 dividend, u64 divisor, u64 *remainder)
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* div64_u64 - unsigned 64bit divide with 64bit divisor
|
* div64_u64 - unsigned 64bit divide with 64bit divisor
|
||||||
|
* @dividend: unsigned 64bit dividend
|
||||||
|
* @divisor: unsigned 64bit divisor
|
||||||
|
*
|
||||||
|
* Return: dividend / divisor
|
||||||
*/
|
*/
|
||||||
static inline u64 div64_u64(u64 dividend, u64 divisor)
|
static inline u64 div64_u64(u64 dividend, u64 divisor)
|
||||||
{
|
{
|
||||||
|
|
@ -50,6 +69,10 @@ static inline u64 div64_u64(u64 dividend, u64 divisor)
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* div64_s64 - signed 64bit divide with 64bit divisor
|
* div64_s64 - signed 64bit divide with 64bit divisor
|
||||||
|
* @dividend: signed 64bit dividend
|
||||||
|
* @divisor: signed 64bit divisor
|
||||||
|
*
|
||||||
|
* Return: dividend / divisor
|
||||||
*/
|
*/
|
||||||
static inline s64 div64_s64(s64 dividend, s64 divisor)
|
static inline s64 div64_s64(s64 dividend, s64 divisor)
|
||||||
{
|
{
|
||||||
|
|
@ -89,6 +112,8 @@ extern s64 div64_s64(s64 dividend, s64 divisor);
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* div_u64 - unsigned 64bit divide with 32bit divisor
|
* div_u64 - unsigned 64bit divide with 32bit divisor
|
||||||
|
* @dividend: unsigned 64bit dividend
|
||||||
|
* @divisor: unsigned 32bit divisor
|
||||||
*
|
*
|
||||||
* This is the most common 64bit divide and should be used if possible,
|
* This is the most common 64bit divide and should be used if possible,
|
||||||
* as many 32bit archs can optimize this variant better than a full 64bit
|
* as many 32bit archs can optimize this variant better than a full 64bit
|
||||||
|
|
@ -104,6 +129,8 @@ static inline u64 div_u64(u64 dividend, u32 divisor)
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* div_s64 - signed 64bit divide with 32bit divisor
|
* div_s64 - signed 64bit divide with 32bit divisor
|
||||||
|
* @dividend: signed 64bit dividend
|
||||||
|
* @divisor: signed 32bit divisor
|
||||||
*/
|
*/
|
||||||
#ifndef div_s64
|
#ifndef div_s64
|
||||||
static inline s64 div_s64(s64 dividend, s32 divisor)
|
static inline s64 div_s64(s64 dividend, s32 divisor)
|
||||||
|
|
|
||||||
|
|
@ -18,7 +18,9 @@
|
||||||
|
|
||||||
#include <asm/page.h>
|
#include <asm/page.h>
|
||||||
|
|
||||||
/*
|
/**
|
||||||
|
* DOC: bitmap introduction
|
||||||
|
*
|
||||||
* bitmaps provide an array of bits, implemented using an an
|
* bitmaps provide an array of bits, implemented using an an
|
||||||
* array of unsigned longs. The number of valid bits in a
|
* array of unsigned longs. The number of valid bits in a
|
||||||
* given bitmap does _not_ need to be an exact multiple of
|
* given bitmap does _not_ need to be an exact multiple of
|
||||||
|
|
|
||||||
|
|
@ -225,7 +225,7 @@ static u32 __attribute_const__ gf2_multiply(u32 x, u32 y, u32 modulus)
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* crc32_generic_shift - Append len 0 bytes to crc, in logarithmic time
|
* crc32_generic_shift - Append @len 0 bytes to crc, in logarithmic time
|
||||||
* @crc: The original little-endian CRC (i.e. lsbit is x^31 coefficient)
|
* @crc: The original little-endian CRC (i.e. lsbit is x^31 coefficient)
|
||||||
* @len: The number of bytes. @crc is multiplied by x^(8*@len)
|
* @len: The number of bytes. @crc is multiplied by x^(8*@len)
|
||||||
* @polynomial: The modulus used to reduce the result to 32 bits.
|
* @polynomial: The modulus used to reduce the result to 32 bits.
|
||||||
|
|
|
||||||
|
|
@ -15,7 +15,7 @@ static const uint8_t crc4_tab[] = {
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* crc4 - calculate the 4-bit crc of a value.
|
* crc4 - calculate the 4-bit crc of a value.
|
||||||
* @crc: starting crc4
|
* @c: starting crc4
|
||||||
* @x: value to checksum
|
* @x: value to checksum
|
||||||
* @bits: number of bits in @x to checksum
|
* @bits: number of bits in @x to checksum
|
||||||
*
|
*
|
||||||
|
|
|
||||||
22
lib/crc8.c
22
lib/crc8.c
|
|
@ -20,11 +20,11 @@
|
||||||
#include <linux/crc8.h>
|
#include <linux/crc8.h>
|
||||||
#include <linux/printk.h>
|
#include <linux/printk.h>
|
||||||
|
|
||||||
/*
|
/**
|
||||||
* crc8_populate_msb - fill crc table for given polynomial in reverse bit order.
|
* crc8_populate_msb - fill crc table for given polynomial in reverse bit order.
|
||||||
*
|
*
|
||||||
* table: table to be filled.
|
* @table: table to be filled.
|
||||||
* polynomial: polynomial for which table is to be filled.
|
* @polynomial: polynomial for which table is to be filled.
|
||||||
*/
|
*/
|
||||||
void crc8_populate_msb(u8 table[CRC8_TABLE_SIZE], u8 polynomial)
|
void crc8_populate_msb(u8 table[CRC8_TABLE_SIZE], u8 polynomial)
|
||||||
{
|
{
|
||||||
|
|
@ -42,11 +42,11 @@ void crc8_populate_msb(u8 table[CRC8_TABLE_SIZE], u8 polynomial)
|
||||||
}
|
}
|
||||||
EXPORT_SYMBOL(crc8_populate_msb);
|
EXPORT_SYMBOL(crc8_populate_msb);
|
||||||
|
|
||||||
/*
|
/**
|
||||||
* crc8_populate_lsb - fill crc table for given polynomial in regular bit order.
|
* crc8_populate_lsb - fill crc table for given polynomial in regular bit order.
|
||||||
*
|
*
|
||||||
* table: table to be filled.
|
* @table: table to be filled.
|
||||||
* polynomial: polynomial for which table is to be filled.
|
* @polynomial: polynomial for which table is to be filled.
|
||||||
*/
|
*/
|
||||||
void crc8_populate_lsb(u8 table[CRC8_TABLE_SIZE], u8 polynomial)
|
void crc8_populate_lsb(u8 table[CRC8_TABLE_SIZE], u8 polynomial)
|
||||||
{
|
{
|
||||||
|
|
@ -63,13 +63,13 @@ void crc8_populate_lsb(u8 table[CRC8_TABLE_SIZE], u8 polynomial)
|
||||||
}
|
}
|
||||||
EXPORT_SYMBOL(crc8_populate_lsb);
|
EXPORT_SYMBOL(crc8_populate_lsb);
|
||||||
|
|
||||||
/*
|
/**
|
||||||
* crc8 - calculate a crc8 over the given input data.
|
* crc8 - calculate a crc8 over the given input data.
|
||||||
*
|
*
|
||||||
* table: crc table used for calculation.
|
* @table: crc table used for calculation.
|
||||||
* pdata: pointer to data buffer.
|
* @pdata: pointer to data buffer.
|
||||||
* nbytes: number of bytes in data buffer.
|
* @nbytes: number of bytes in data buffer.
|
||||||
* crc: previous returned crc8 value.
|
* @crc: previous returned crc8 value.
|
||||||
*/
|
*/
|
||||||
u8 crc8(const u8 table[CRC8_TABLE_SIZE], u8 *pdata, size_t nbytes, u8 crc)
|
u8 crc8(const u8 table[CRC8_TABLE_SIZE], u8 *pdata, size_t nbytes, u8 crc)
|
||||||
{
|
{
|
||||||
|
|
|
||||||
|
|
@ -61,6 +61,12 @@ uint32_t __attribute__((weak)) __div64_32(uint64_t *n, uint32_t base)
|
||||||
EXPORT_SYMBOL(__div64_32);
|
EXPORT_SYMBOL(__div64_32);
|
||||||
#endif
|
#endif
|
||||||
|
|
||||||
|
/**
|
||||||
|
* div_s64_rem - signed 64bit divide with 64bit divisor and remainder
|
||||||
|
* @dividend: 64bit dividend
|
||||||
|
* @divisor: 64bit divisor
|
||||||
|
* @remainder: 64bit remainder
|
||||||
|
*/
|
||||||
#ifndef div_s64_rem
|
#ifndef div_s64_rem
|
||||||
s64 div_s64_rem(s64 dividend, s32 divisor, s32 *remainder)
|
s64 div_s64_rem(s64 dividend, s32 divisor, s32 *remainder)
|
||||||
{
|
{
|
||||||
|
|
|
||||||
|
|
@ -13,6 +13,12 @@
|
||||||
#if !defined(CONFIG_CPU_NO_EFFICIENT_FFS) && !defined(CPU_NO_EFFICIENT_FFS)
|
#if !defined(CONFIG_CPU_NO_EFFICIENT_FFS) && !defined(CPU_NO_EFFICIENT_FFS)
|
||||||
|
|
||||||
/* If __ffs is available, the even/odd algorithm benchmarks slower. */
|
/* If __ffs is available, the even/odd algorithm benchmarks slower. */
|
||||||
|
|
||||||
|
/**
|
||||||
|
* gcd - calculate and return the greatest common divisor of 2 unsigned longs
|
||||||
|
* @a: first value
|
||||||
|
* @b: second value
|
||||||
|
*/
|
||||||
unsigned long gcd(unsigned long a, unsigned long b)
|
unsigned long gcd(unsigned long a, unsigned long b)
|
||||||
{
|
{
|
||||||
unsigned long r = a | b;
|
unsigned long r = a | b;
|
||||||
|
|
|
||||||
|
|
@ -125,12 +125,12 @@ static int cn_test_want_notify(void)
|
||||||
#endif
|
#endif
|
||||||
|
|
||||||
static u32 cn_test_timer_counter;
|
static u32 cn_test_timer_counter;
|
||||||
static void cn_test_timer_func(unsigned long __data)
|
static void cn_test_timer_func(struct timer_list *unused)
|
||||||
{
|
{
|
||||||
struct cn_msg *m;
|
struct cn_msg *m;
|
||||||
char data[32];
|
char data[32];
|
||||||
|
|
||||||
pr_debug("%s: timer fired with data %lu\n", __func__, __data);
|
pr_debug("%s: timer fired\n", __func__);
|
||||||
|
|
||||||
m = kzalloc(sizeof(*m) + sizeof(data), GFP_ATOMIC);
|
m = kzalloc(sizeof(*m) + sizeof(data), GFP_ATOMIC);
|
||||||
if (m) {
|
if (m) {
|
||||||
|
|
@ -168,7 +168,7 @@ static int cn_test_init(void)
|
||||||
goto err_out;
|
goto err_out;
|
||||||
}
|
}
|
||||||
|
|
||||||
setup_timer(&cn_test_timer, cn_test_timer_func, 0);
|
timer_setup(&cn_test_timer, cn_test_timer_func, 0);
|
||||||
mod_timer(&cn_test_timer, jiffies + msecs_to_jiffies(1000));
|
mod_timer(&cn_test_timer, jiffies + msecs_to_jiffies(1000));
|
||||||
|
|
||||||
pr_info("initialized with id={%u.%u}\n",
|
pr_info("initialized with id={%u.%u}\n",
|
||||||
|
|
|
||||||
15
scripts/documentation-file-ref-check
Executable file
15
scripts/documentation-file-ref-check
Executable file
|
|
@ -0,0 +1,15 @@
|
||||||
|
#!/bin/sh
|
||||||
|
# Treewide grep for references to files under Documentation, and report
|
||||||
|
# non-existing files in stderr.
|
||||||
|
|
||||||
|
for f in $(git ls-files); do
|
||||||
|
for ref in $(grep -ho "Documentation/[A-Za-z0-9_.,~/*+-]*" "$f"); do
|
||||||
|
# presume trailing . and , are not part of the name
|
||||||
|
ref=${ref%%[.,]}
|
||||||
|
|
||||||
|
# use ls to handle wildcards
|
||||||
|
if ! ls $ref >/dev/null 2>&1; then
|
||||||
|
echo "$f: $ref" >&2
|
||||||
|
fi
|
||||||
|
done
|
||||||
|
done
|
||||||
62
scripts/find-unused-docs.sh
Executable file
62
scripts/find-unused-docs.sh
Executable file
|
|
@ -0,0 +1,62 @@
|
||||||
|
#!/bin/bash
|
||||||
|
# (c) 2017, Jonathan Corbet <corbet@lwn.net>
|
||||||
|
# sayli karnik <karniksayli1995@gmail.com>
|
||||||
|
#
|
||||||
|
# This script detects files with kernel-doc comments for exported functions
|
||||||
|
# that are not included in documentation.
|
||||||
|
#
|
||||||
|
# usage: Run 'scripts/find-unused-docs.sh directory' from top level of kernel
|
||||||
|
# tree.
|
||||||
|
#
|
||||||
|
# example: $scripts/find-unused-docs.sh drivers/scsi
|
||||||
|
#
|
||||||
|
# Licensed under the terms of the GNU GPL License
|
||||||
|
|
||||||
|
if ! [ -d "Documentation" ]; then
|
||||||
|
echo "Run from top level of kernel tree"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
if [ "$#" -ne 1 ]; then
|
||||||
|
echo "Usage: scripts/find-unused-docs.sh directory"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
if ! [ -d "$1" ]; then
|
||||||
|
echo "Directory $1 doesn't exist"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
cd "$( dirname "${BASH_SOURCE[0]}" )"
|
||||||
|
cd ..
|
||||||
|
|
||||||
|
cd Documentation/
|
||||||
|
|
||||||
|
echo "The following files contain kerneldoc comments for exported functions \
|
||||||
|
that are not used in the formatted documentation"
|
||||||
|
|
||||||
|
# FILES INCLUDED
|
||||||
|
|
||||||
|
files_included=($(grep -rHR ".. kernel-doc" --include \*.rst | cut -d " " -f 3))
|
||||||
|
|
||||||
|
declare -A FILES_INCLUDED
|
||||||
|
|
||||||
|
for each in "${files_included[@]}"; do
|
||||||
|
FILES_INCLUDED[$each]="$each"
|
||||||
|
done
|
||||||
|
|
||||||
|
cd ..
|
||||||
|
|
||||||
|
# FILES NOT INCLUDED
|
||||||
|
|
||||||
|
for file in `find $1 -name '*.c'`; do
|
||||||
|
|
||||||
|
if [[ ${FILES_INCLUDED[$file]+_} ]]; then
|
||||||
|
continue;
|
||||||
|
fi
|
||||||
|
str=$(scripts/kernel-doc -text -export "$file" 2>/dev/null)
|
||||||
|
if [[ -n "$str" ]]; then
|
||||||
|
echo "$file"
|
||||||
|
fi
|
||||||
|
done
|
||||||
|
|
||||||
|
|
@ -2168,7 +2168,7 @@ sub dump_struct($$) {
|
||||||
my $nested;
|
my $nested;
|
||||||
|
|
||||||
if ($x =~ /(struct|union)\s+(\w+)\s*{(.*)}/) {
|
if ($x =~ /(struct|union)\s+(\w+)\s*{(.*)}/) {
|
||||||
#my $decl_type = $1;
|
my $decl_type = $1;
|
||||||
$declaration_name = $2;
|
$declaration_name = $2;
|
||||||
my $members = $3;
|
my $members = $3;
|
||||||
|
|
||||||
|
|
@ -2194,7 +2194,7 @@ sub dump_struct($$) {
|
||||||
$members =~ s/DECLARE_HASHTABLE\s*\(([^,)]+), ([^,)]+)\)/unsigned long $1\[1 << (($2) - 1)\]/gos;
|
$members =~ s/DECLARE_HASHTABLE\s*\(([^,)]+), ([^,)]+)\)/unsigned long $1\[1 << (($2) - 1)\]/gos;
|
||||||
|
|
||||||
create_parameterlist($members, ';', $file);
|
create_parameterlist($members, ';', $file);
|
||||||
check_sections($file, $declaration_name, "struct", $sectcheck, $struct_actual, $nested);
|
check_sections($file, $declaration_name, $decl_type, $sectcheck, $struct_actual, $nested);
|
||||||
|
|
||||||
output_declaration($declaration_name,
|
output_declaration($declaration_name,
|
||||||
'struct',
|
'struct',
|
||||||
|
|
@ -2226,6 +2226,8 @@ sub dump_enum($$) {
|
||||||
if ($x =~ /enum\s+(\w+)\s*{(.*)}/) {
|
if ($x =~ /enum\s+(\w+)\s*{(.*)}/) {
|
||||||
$declaration_name = $1;
|
$declaration_name = $1;
|
||||||
my $members = $2;
|
my $members = $2;
|
||||||
|
my %_members;
|
||||||
|
|
||||||
$members =~ s/\s+$//;
|
$members =~ s/\s+$//;
|
||||||
|
|
||||||
foreach my $arg (split ',', $members) {
|
foreach my $arg (split ',', $members) {
|
||||||
|
|
@ -2236,9 +2238,16 @@ sub dump_enum($$) {
|
||||||
print STDERR "${file}:$.: warning: Enum value '$arg' ".
|
print STDERR "${file}:$.: warning: Enum value '$arg' ".
|
||||||
"not described in enum '$declaration_name'\n";
|
"not described in enum '$declaration_name'\n";
|
||||||
}
|
}
|
||||||
|
$_members{$arg} = 1;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
while (my ($k, $v) = each %parameterdescs) {
|
||||||
|
if (!exists($_members{$k})) {
|
||||||
|
print STDERR "${file}:$.: warning: Excess enum value " .
|
||||||
|
"'$k' description in '$declaration_name'\n";
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
output_declaration($declaration_name,
|
output_declaration($declaration_name,
|
||||||
'enum',
|
'enum',
|
||||||
{'enum' => $declaration_name,
|
{'enum' => $declaration_name,
|
||||||
|
|
@ -2506,7 +2515,7 @@ sub check_sections($$$$$$) {
|
||||||
} else {
|
} else {
|
||||||
if ($nested !~ m/\Q$sects[$sx]\E/) {
|
if ($nested !~ m/\Q$sects[$sx]\E/) {
|
||||||
print STDERR "${file}:$.: warning: " .
|
print STDERR "${file}:$.: warning: " .
|
||||||
"Excess struct/union/enum/typedef member " .
|
"Excess $decl_type member " .
|
||||||
"'$sects[$sx]' " .
|
"'$sects[$sx]' " .
|
||||||
"description in '$decl_name'\n";
|
"description in '$decl_name'\n";
|
||||||
++$warnings;
|
++$warnings;
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue