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
Коммит
7832681b36
|
|
@ -1,5 +1,5 @@
|
|||
# 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
|
||||
Date: February 2015
|
||||
|
|
|
|||
|
|
@ -18,6 +18,6 @@ Description:
|
|||
in the initramfs, which has already been measured as part
|
||||
of the trusted boot. For more information on creating and
|
||||
loading existing trusted/encrypted keys, refer to:
|
||||
Documentation/keys-trusted-encrypted.txt. (A sample dracut
|
||||
patch, which loads the trusted/encrypted key and enables
|
||||
Documentation/security/keys/trusted-encrypted.rst. (A sample
|
||||
dracut patch, which loads the trusted/encrypted key and enables
|
||||
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.
|
||||
Boosting allows the CPU and the firmware to run at a frequency
|
||||
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
|
||||
|
|
@ -223,7 +224,8 @@ Description: Parameters for the Intel P-state driver
|
|||
no_turbo: limits the driver to selecting P states below the turbo
|
||||
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>
|
||||
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
|
||||
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
|
||||
Date: November 2016
|
||||
|
|
@ -35,7 +36,8 @@ Description:
|
|||
represented by it to be used on subsequent attempts to suspend
|
||||
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
|
||||
Date: September 2006
|
||||
|
|
|
|||
|
|
@ -97,6 +97,9 @@ endif # HAVE_SPHINX
|
|||
# The following targets are independent of HAVE_SPHINX, and the rules should
|
||||
# work or silently pass without Sphinx.
|
||||
|
||||
refcheckdocs:
|
||||
$(Q)cd $(srctree);scripts/documentation-file-ref-check
|
||||
|
||||
cleandocs:
|
||||
$(Q)rm -rf $(BUILDDIR)
|
||||
$(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media clean
|
||||
|
|
@ -109,6 +112,7 @@ dochelp:
|
|||
@echo ' epubdocs - EPUB'
|
||||
@echo ' xmldocs - XML'
|
||||
@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
|
||||
@echo ' make SPHINXDIRS="s1 s2" [target] Generate only docs of folder s1, s2'
|
||||
|
|
@ -116,3 +120,5 @@ dochelp:
|
|||
@echo
|
||||
@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
|
||||
@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
|
||||
account for POSIX signals sent to user tasks,
|
||||
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>
|
||||
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
|
||||
important: it tells something about why the kernel dumped code (in
|
||||
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
|
||||
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
|
||||
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::
|
||||
|
||||
$ ./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
|
||||
development of this file);
|
||||
- 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 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,
|
||||
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?
|
||||
|
||||
If you decide to take this way, once you have worked out a fix please submit
|
||||
it upstream.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -314,7 +314,7 @@
|
|||
amijoy.map= [HW,JOY] Amiga joystick support
|
||||
Map of devices attached to JOY0DAT and JOY1DAT
|
||||
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
|
||||
Specifies type or capabilities of an analog joystick
|
||||
|
|
@ -439,7 +439,7 @@
|
|||
bttv.card= [HW,V4L] bttv (bt848 + bt878 based grabber cards)
|
||||
bttv.radio= Most important insmod options are available as
|
||||
kernel args too.
|
||||
bttv.pll= See Documentation/video4linux/bttv/Insmod-options
|
||||
bttv.pll= See Documentation/media/v4l-drivers/bttv.rst
|
||||
bttv.tuner=
|
||||
|
||||
bulk_remove=off [PPC] This parameter disables the use of the pSeries
|
||||
|
|
@ -641,8 +641,8 @@
|
|||
For now, only VisioBraille is supported.
|
||||
|
||||
consoleblank= [KNL] The console blank (screen saver) timeout in
|
||||
seconds. Defaults to 10*60 = 10mins. A value of 0
|
||||
disables the blank timer.
|
||||
seconds. A value of 0 disables the blank timer.
|
||||
Defaults to 0.
|
||||
|
||||
coredump_filter=
|
||||
[KNL] Change the default value for
|
||||
|
|
@ -724,7 +724,7 @@
|
|||
db9.dev[2|3]= [HW,JOY] Multisystem joystick support via parallel port
|
||||
(one device per port)
|
||||
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
|
||||
time. See
|
||||
|
|
@ -1220,7 +1220,7 @@
|
|||
[HW,JOY] Multisystem joystick and NES/SNES/PSX pad
|
||||
support via parallel port (up to 5 devices per port)
|
||||
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]
|
||||
|
||||
|
|
@ -1766,7 +1766,7 @@
|
|||
ivrs_acpihid[00:14.5]=AMD0020:0
|
||||
|
||||
js= [HW,JOY] Analog joystick
|
||||
See Documentation/input/joystick.txt.
|
||||
See Documentation/input/joydev/joystick.rst.
|
||||
|
||||
nokaslr [KNL]
|
||||
When CONFIG_RANDOMIZE_BASE is set, this disables
|
||||
|
|
@ -2248,10 +2248,10 @@
|
|||
s2idle - Suspend-To-Idle
|
||||
shallow - Power-On Suspend 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
|
||||
See Documentation/video4linux/meye.txt.
|
||||
See Documentation/media/v4l-drivers/meye.rst.
|
||||
|
||||
mfgpt_irq= [IA-32] Specify the IRQ to use for the
|
||||
Multi-Function General Purpose Timers on AMD Geode
|
||||
|
|
@ -3134,7 +3134,7 @@
|
|||
|
||||
plip= [PPT,NET] Parallel port network link
|
||||
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.
|
||||
Override pmtimer IOPort with a hex value.
|
||||
|
|
@ -3885,6 +3885,12 @@
|
|||
[KNL] Should the soft-lockup detector generate panics.
|
||||
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=
|
||||
[KNL] Should the soft-lockup detector generate
|
||||
backtraces on all cpus.
|
||||
|
|
@ -4199,7 +4205,7 @@
|
|||
TurboGraFX parallel port interface
|
||||
Format:
|
||||
<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
|
||||
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
|
||||
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
|
||||
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:
|
||||
[5.] Most recent kernel version which did not have the bug:
|
||||
[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
|
||||
problem (if possible)
|
||||
[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 the options:
|
||||
|
||||
Enhanced IDE/MFM/RLL disk/cdrom/tape/floppy support
|
||||
ATA/ATAPI/MFM/RLL 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
|
||||
specify additional configuration options. See
|
||||
Documentation/ide/ide.txt.
|
||||
|
|
|
|||
|
|
@ -2,11 +2,9 @@
|
|||
The Linux Kernel API
|
||||
====================
|
||||
|
||||
Data Types
|
||||
==========
|
||||
|
||||
Doubly Linked Lists
|
||||
-------------------
|
||||
List Management Functions
|
||||
=========================
|
||||
|
||||
.. kernel-doc:: include/linux/list.h
|
||||
:internal:
|
||||
|
|
@ -55,12 +53,27 @@ The Linux kernel provides more basic utility functions.
|
|||
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
|
||||
:export:
|
||||
|
||||
.. kernel-doc:: lib/bitmap.c
|
||||
:internal:
|
||||
|
||||
.. kernel-doc:: include/linux/bitmap.h
|
||||
:internal:
|
||||
|
||||
Command-line Parsing
|
||||
--------------------
|
||||
|
||||
|
|
@ -70,20 +83,26 @@ Command-line Parsing
|
|||
CRC Functions
|
||||
-------------
|
||||
|
||||
.. kernel-doc:: lib/crc4.c
|
||||
:export:
|
||||
|
||||
.. kernel-doc:: lib/crc7.c
|
||||
:export:
|
||||
|
||||
.. kernel-doc:: lib/crc8.c
|
||||
:export:
|
||||
|
||||
.. kernel-doc:: lib/crc16.c
|
||||
:export:
|
||||
|
||||
.. kernel-doc:: lib/crc-itu-t.c
|
||||
:export:
|
||||
|
||||
.. kernel-doc:: lib/crc32.c
|
||||
|
||||
.. kernel-doc:: lib/crc-ccitt.c
|
||||
:export:
|
||||
|
||||
.. kernel-doc:: lib/crc-itu-t.c
|
||||
:export:
|
||||
|
||||
idr/ida Functions
|
||||
-----------------
|
||||
|
||||
|
|
@ -96,6 +115,30 @@ idr/ida Functions
|
|||
.. kernel-doc:: lib/idr.c
|
||||
: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
|
||||
==========================
|
||||
|
||||
|
|
|
|||
|
|
@ -209,7 +209,7 @@ err.log will now have the profiling information, while stdout will
|
|||
provide some progress information as Coccinelle moves forward with
|
||||
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
|
||||
--------------------
|
||||
|
|
|
|||
|
|
@ -31,6 +31,17 @@ To build and run the tests with a single command, use::
|
|||
|
||||
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
|
||||
=============================
|
||||
|
|
@ -46,10 +57,21 @@ You can specify multiple tests to build and run::
|
|||
|
||||
$ 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
|
||||
possible targets.
|
||||
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
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
|
||||
executable which is not tested by default.
|
||||
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.
|
||||
|
||||
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
|
||||
source.
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
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:
|
||||
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
|
||||
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:
|
||||
% modprobe dmatest channel=dma0chan0 timeout=2000 iterations=1 run=1
|
||||
Example of usage: ::
|
||||
|
||||
...or:
|
||||
% 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
|
||||
% modprobe dmatest channel=dma0chan0 timeout=2000 iterations=1 run=1
|
||||
|
||||
...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
|
||||
command:
|
||||
% ls -1 /sys/class/dma/
|
||||
...or on the kernel command line: ::
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
The following command returns the state of the test.
|
||||
% cat /sys/module/dmatest/parameters/run
|
||||
The following command returns the state of the test. ::
|
||||
|
||||
% cat /sys/module/dmatest/parameters/run
|
||||
|
||||
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
|
||||
|
|
@ -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
|
||||
waiting is disabled.
|
||||
|
||||
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
|
||||
Example: ::
|
||||
|
||||
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
|
||||
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..."
|
||||
|
||||
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
|
||||
% grep -H . /sys/module/dmatest/parameters/*
|
||||
case. You always could check them at run-time by running ::
|
||||
|
||||
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:
|
||||
% dmesg | tail -n 1
|
||||
dmatest: result dma0chan0-copy0: #1: No errors with src_off=0x7bf dst_off=0x8ad len=0x3fea (0)
|
||||
"dmatest: result <channel>: <test id>: '<error msg>' with src_off=<val> dst_off=<val> len=<val> (<err code>)"
|
||||
|
||||
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 parens represents additional information, e.g. error code, error counter,
|
||||
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.
|
||||
|
||||
Example:
|
||||
% dmesg | tail -n 1
|
||||
dmatest: dma0chan0-copy0: summary 1 test, 0 failures 1000 iops 100000 KB/s (0)
|
||||
Example: ::
|
||||
|
||||
% 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
|
||||
above format.
|
||||
|
|
@ -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`
|
||||
|
|
@ -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)
|
||||
|
|
@ -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
|
||||
gpio
|
||||
misc_devices
|
||||
dmaengine/index
|
||||
|
||||
.. 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
|
||||
the text format and ignore most of it. More detailed device status
|
||||
(including class and vendor status) is available from device-specific
|
||||
files. For information about the current format of this file, see the
|
||||
``Documentation/usb/proc_usb_info.txt`` file in your Linux kernel
|
||||
sources.
|
||||
files. For information about the current format of this file, see below.
|
||||
|
||||
This file, in combination with the poll() system call, can also be used
|
||||
to detect when devices are added or removed::
|
||||
|
|
|
|||
|
|
@ -77,8 +77,8 @@ C. Boot options
|
|||
1. fbcon=font:<name>
|
||||
|
||||
Select the initial font to use. The value 'name' can be any of the
|
||||
compiled-in fonts: VGA8x16, 7x14, 10x18, VGA8x8, MINI4x6, RomanLarge,
|
||||
SUN8x16, SUN12x22, ProFont6x11, Acorn8x8, PEARL8x8.
|
||||
compiled-in fonts: 10x18, 6x10, 7x14, Acorn8x8, MINI4x6,
|
||||
PEARL8x8, ProFont6x11, SUN12x22, SUN8x16, VGA8x16, VGA8x8.
|
||||
|
||||
Note, not all drivers can handle font with widths not divisible by 8,
|
||||
such as vga16fb.
|
||||
|
|
|
|||
|
|
@ -34,6 +34,6 @@
|
|||
| tile: | TODO |
|
||||
| um: | TODO |
|
||||
| unicore32: | TODO |
|
||||
| x86: | ok |
|
||||
| x86: | ok | 64-bit only
|
||||
| xtensa: | TODO |
|
||||
-----------------------
|
||||
|
|
|
|||
|
|
@ -62,7 +62,7 @@ disabled, fcntl(fd, F_NOTIFY, ...) will return -EINVAL.
|
|||
|
||||
Example
|
||||
-------
|
||||
See Documentation/filesystems/dnotify_test.c for an example.
|
||||
See tools/testing/selftests/filesystems/dnotify_test.c for an example.
|
||||
|
||||
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
|
||||
flex_bg feature
|
||||
* 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
|
||||
* 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)
|
||||
|
||||
[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
|
||||
|
||||
* 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
|
||||
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
|
||||
|
|
@ -602,7 +602,7 @@ Table of Ext4 specific ioctls
|
|||
bitmaps and inode table, the userspace tool thus
|
||||
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
|
||||
the specified inode with inode
|
||||
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:
|
||||
* the input subsystem, which converts HID events into normal input
|
||||
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 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>
|
||||
- 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:
|
||||
|
||||
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:
|
||||
|
||||
|
|
@ -287,7 +287,7 @@ MINIMUM_BATTERY_MINUTES=10
|
|||
|
||||
# Should the maximum CPU frequency be adjusted down while on battery?
|
||||
# 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
|
||||
|
||||
# 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'}
|
||||
|
||||
# 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'}
|
||||
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.
|
||||
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
|
||||
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
|
||||
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:
|
||||
|
||||
|
|
@ -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.
|
||||
Exceptions are:
|
||||
- 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:
|
||||
|
||||
|
|
@ -72,7 +72,7 @@ Useful parameters for verbosity level and debugging the dst module:
|
|||
The autodetected values are determined by the cards' "response string".
|
||||
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.
|
||||
Please also see Documentation/dvb/ci.txt.
|
||||
Please also see Documentation/media/dvb-drivers/ci.rst.
|
||||
|
||||
Running multiple cards
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
|
@ -100,7 +100,7 @@ Examples of card ID's:
|
|||
|
||||
$ 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.
|
||||
|
||||
Probing the cards with broken PCI subsystem ID
|
||||
|
|
|
|||
|
|
@ -431,7 +431,7 @@ MPEG stream.
|
|||
*Historical context*: This format specification originates from a
|
||||
custom, embedded, sliced VBI data format used by the ``ivtv`` driver.
|
||||
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
|
||||
by the CX23415 MPEG decoder's capabilities and limitations with respect
|
||||
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``
|
||||
- VBI in private packets, IVTV format (documented in the kernel
|
||||
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/>`__
|
||||
|
||||
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``
|
||||
|
|
|
|||
|
|
@ -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
|
||||
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
|
||||
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
|
||||
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::
|
||||
:header-rows: 0
|
||||
|
|
|
|||
|
|
@ -332,8 +332,8 @@ References
|
|||
[5] "MBIM (Mobile Broadband Interface Model) Registry"
|
||||
- http://compliance.usb.org/mbim/
|
||||
|
||||
[6] "/dev/bus/usb filesystem output"
|
||||
- Documentation/usb/proc_usb_info.txt
|
||||
[6] "/sys/kernel/debug/usb/devices output format"
|
||||
- Documentation/driver-api/usb/usb.rst
|
||||
|
||||
[7] "/sys/bus/usb/devices/.../descriptors"
|
||||
- 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.
|
||||
|
||||
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
|
||||
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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
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.
|
||||
|
||||
-------------------------------------------------------------------------------
|
||||
|
|
|
|||
|
|
@ -119,4 +119,4 @@ properties of futexes, and all four combinations are possible: futex,
|
|||
robust-futex, PI-futex, robust+PI-futex.
|
||||
|
||||
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
|
||||
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).
|
||||
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
|
||||
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
|
||||
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.
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
---------------------------------------------------------------------------
|
||||
|
|
@ -417,7 +417,7 @@ pm->runtime_idle() callback.
|
|||
2.4. System-Wide Power Transitions
|
||||
----------------------------------
|
||||
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
|
||||
callbacks for this purpose. They are executed in phases such that each phase
|
||||
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
|
||||
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
|
||||
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
|
||||
|
|
@ -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
|
||||
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
|
||||
.resume() callbacks from struct pci_driver are used. The legacy approach,
|
||||
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
|
||||
Advanced Configuration and Power Interface (ACPI) Specification, Rev. 3.0b
|
||||
PCI Express Base Specification, Rev. 2.0
|
||||
Documentation/power/admin-guide/devices.rst
|
||||
Documentation/driver-api/pm/devices.rst
|
||||
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
|
||||
complete callback, which is then entirely responsible for handling the device
|
||||
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).
|
||||
|
||||
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
|
||||
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
|
||||
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.
|
||||
|
||||
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
|
||||
under the scripts/coccinelle directory; running "make coccicheck" will run
|
||||
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 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
|
||||
email-clients
|
||||
kernel-enforcement-statement
|
||||
kernel-driver-statement
|
||||
|
||||
Other guides to the community that are of interest to most developers are:
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
Documentation/power/drivers-testing.txt and for a relatively
|
||||
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:
|
||||
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:
|
||||
|
||||
- A ``from`` line specifying the patch author (only needed if the person
|
||||
sending the patch is not the author).
|
||||
|
||||
- An empty line.
|
||||
- A ``from`` line specifying the patch author, followed by an empty
|
||||
line (only needed if the person sending the patch is not the author).
|
||||
|
||||
- The body of the explanation, line wrapped at 75 columns, which will
|
||||
be copied to the permanent changelog to describe this patch.
|
||||
|
||||
- An empty line.
|
||||
|
||||
- The ``Signed-off-by:`` lines, described above, which will
|
||||
also go in the changelog.
|
||||
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ Linux Security Module Development
|
|||
Based on https://lkml.org/lkml/2007/10/26/215,
|
||||
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
|
||||
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
|
||||
that end users and distros can make a more informed decision about which
|
||||
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
|
||||
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
|
||||
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ Key Request Service
|
|||
===================
|
||||
|
||||
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 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
|
||||
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
|
||||
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.
|
||||
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
|
||||
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
|
||||
and ``model`` options belonging to each codec. For example, for Realtek
|
||||
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)”.
|
||||
|
||||
More precise information can be found in
|
||||
``Documentation/sound/alsa/ControlNames.txt``.
|
||||
``Documentation/sound/designs/control-names.rst``.
|
||||
|
||||
Access Flags
|
||||
------------
|
||||
|
|
|
|||
|
|
@ -60,7 +60,7 @@ debug/ <empty>
|
|||
dev/ device specific information (eg dev/cdrom/info)
|
||||
fs/ specific filesystems
|
||||
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
|
||||
miscellaneous stuff
|
||||
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
|
||||
in Documentation/binfmt_misc.txt.
|
||||
in Documentation/admin-guide/binfmt-misc.rst.
|
||||
|
||||
|
||||
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
|
||||
and beyond". The paper is part of the OLS 2006 Proceedings Volume 1, which can
|
||||
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:
|
||||
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
|
||||
changes in the time(r) related Linux subsystems. Figure #1 (p. 2) shows the
|
||||
|
|
|
|||
|
|
@ -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
|
||||
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
|
||||
buffer, which can later on be read from its device nodes via read() or
|
||||
|
|
|
|||
|
|
@ -773,7 +773,7 @@ host:
|
|||
# cat /dev/usb/lp0
|
||||
|
||||
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)
|
||||
|
|
|
|||
|
|
@ -15,7 +15,7 @@ Last reviewed: 05/20/2016
|
|||
|
||||
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
|
||||
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
|
||||
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
|
||||
|
|
|
|||
|
|
@ -25,7 +25,7 @@ Last reviewed: 10/05/2007
|
|||
|
||||
If you want to write a program to be compatible with the PC Watchdog
|
||||
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:
|
||||
|
|
|
|||
|
|
@ -4234,7 +4234,7 @@ S: Maintained
|
|||
F: drivers/dma/
|
||||
F: include/linux/dmaengine.h
|
||||
F: Documentation/devicetree/bindings/dma/
|
||||
F: Documentation/dmaengine/
|
||||
F: Documentation/driver-api/dmaengine/
|
||||
T: git git://git.infradead.org/users/vkoul/slave-dma.git
|
||||
|
||||
DMA MAPPING HELPERS
|
||||
|
|
|
|||
3
Makefile
3
Makefile
|
|
@ -1459,7 +1459,8 @@ $(help-board-dirs): help-%:
|
|||
|
||||
# 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)
|
||||
$(DOC_TARGETS): scripts_basic FORCE
|
||||
$(Q)$(MAKE) $(build)=Documentation $@
|
||||
|
|
|
|||
|
|
@ -26,6 +26,20 @@
|
|||
|
||||
#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) ({ \
|
||||
uint32_t __base = (base); \
|
||||
uint32_t __rem; \
|
||||
|
|
|
|||
|
|
@ -22,65 +22,74 @@
|
|||
* See lib/bitmap.c for more details.
|
||||
*/
|
||||
|
||||
/*
|
||||
/**
|
||||
* DOC: bitmap overview
|
||||
*
|
||||
* The available bitmap operations and their rough meaning in the
|
||||
* case that the bitmap is a single unsigned long are thus:
|
||||
*
|
||||
* Note that nbits should be always a compile time evaluable constant.
|
||||
* 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_and(dst, src1, src2, nbits) *dst = *src1 & *src2
|
||||
* bitmap_or(dst, src1, src2, nbits) *dst = *src1 | *src2
|
||||
* bitmap_xor(dst, src1, src2, nbits) *dst = *src1 ^ *src2
|
||||
* bitmap_andnot(dst, src1, src2, nbits) *dst = *src1 & ~(*src2)
|
||||
* bitmap_complement(dst, src, nbits) *dst = ~(*src)
|
||||
* bitmap_equal(src1, src2, nbits) Are *src1 and *src2 equal?
|
||||
* bitmap_intersects(src1, src2, nbits) Do *src1 and *src2 overlap?
|
||||
* bitmap_subset(src1, src2, nbits) Is *src1 a subset of *src2?
|
||||
* bitmap_empty(src, nbits) Are all bits zero in *src?
|
||||
* bitmap_full(src, nbits) Are all bits set in *src?
|
||||
* bitmap_weight(src, nbits) Hamming Weight: number set bits
|
||||
* bitmap_set(dst, pos, nbits) Set specified bit area
|
||||
* bitmap_clear(dst, pos, nbits) Clear specified bit area
|
||||
* bitmap_find_next_zero_area(buf, len, pos, n, mask) Find bit free area
|
||||
* bitmap_find_next_zero_area_off(buf, len, pos, n, mask) as above
|
||||
* bitmap_shift_right(dst, src, n, nbits) *dst = *src >> n
|
||||
* bitmap_shift_left(dst, src, n, nbits) *dst = *src << n
|
||||
* bitmap_remap(dst, src, old, new, nbits) *dst = map(old, new)(src)
|
||||
* bitmap_bitremap(oldbit, old, new, nbits) newbit = map(old, new)(oldbit)
|
||||
* bitmap_onto(dst, orig, relmap, nbits) *dst = orig relative to relmap
|
||||
* bitmap_fold(dst, orig, sz, nbits) dst bits = orig bits mod sz
|
||||
* bitmap_parse(buf, buflen, dst, nbits) Parse bitmap dst from kernel buf
|
||||
* bitmap_parse_user(ubuf, ulen, dst, nbits) Parse bitmap dst from user buf
|
||||
* bitmap_parselist(buf, dst, nbits) Parse bitmap dst from kernel buf
|
||||
* bitmap_parselist_user(buf, dst, nbits) Parse bitmap dst from user buf
|
||||
* bitmap_find_free_region(bitmap, bits, order) Find and allocate bit region
|
||||
* bitmap_release_region(bitmap, pos, order) Free specified bit region
|
||||
* 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.
|
||||
* ::
|
||||
*
|
||||
* bitmap_zero(dst, nbits) *dst = 0UL
|
||||
* bitmap_fill(dst, nbits) *dst = ~0UL
|
||||
* bitmap_copy(dst, src, nbits) *dst = *src
|
||||
* bitmap_and(dst, src1, src2, nbits) *dst = *src1 & *src2
|
||||
* bitmap_or(dst, src1, src2, nbits) *dst = *src1 | *src2
|
||||
* bitmap_xor(dst, src1, src2, nbits) *dst = *src1 ^ *src2
|
||||
* bitmap_andnot(dst, src1, src2, nbits) *dst = *src1 & ~(*src2)
|
||||
* bitmap_complement(dst, src, nbits) *dst = ~(*src)
|
||||
* bitmap_equal(src1, src2, nbits) Are *src1 and *src2 equal?
|
||||
* bitmap_intersects(src1, src2, nbits) Do *src1 and *src2 overlap?
|
||||
* bitmap_subset(src1, src2, nbits) Is *src1 a subset of *src2?
|
||||
* bitmap_empty(src, nbits) Are all bits zero in *src?
|
||||
* bitmap_full(src, nbits) Are all bits set in *src?
|
||||
* bitmap_weight(src, nbits) Hamming Weight: number set bits
|
||||
* bitmap_set(dst, pos, nbits) Set specified bit area
|
||||
* bitmap_clear(dst, pos, nbits) Clear specified bit area
|
||||
* bitmap_find_next_zero_area(buf, len, pos, n, mask) Find bit free area
|
||||
* bitmap_find_next_zero_area_off(buf, len, pos, n, mask) as above
|
||||
* bitmap_shift_right(dst, src, n, nbits) *dst = *src >> n
|
||||
* bitmap_shift_left(dst, src, n, nbits) *dst = *src << n
|
||||
* bitmap_remap(dst, src, old, new, nbits) *dst = map(old, new)(src)
|
||||
* bitmap_bitremap(oldbit, old, new, nbits) newbit = map(old, new)(oldbit)
|
||||
* bitmap_onto(dst, orig, relmap, nbits) *dst = orig relative to relmap
|
||||
* bitmap_fold(dst, orig, sz, nbits) dst bits = orig bits mod sz
|
||||
* bitmap_parse(buf, buflen, dst, nbits) Parse bitmap dst from kernel buf
|
||||
* bitmap_parse_user(ubuf, ulen, dst, nbits) Parse bitmap dst from user buf
|
||||
* bitmap_parselist(buf, dst, nbits) Parse bitmap dst from kernel buf
|
||||
* bitmap_parselist_user(buf, dst, nbits) Parse bitmap dst from user buf
|
||||
* bitmap_find_free_region(bitmap, bits, order) Find and allocate bit region
|
||||
* bitmap_release_region(bitmap, pos, order) Free specified bit region
|
||||
* 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)
|
||||
*
|
||||
* 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
|
||||
* to declare an array named 'name' of just enough unsigned longs to
|
||||
* 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);
|
||||
}
|
||||
|
||||
/*
|
||||
/**
|
||||
* 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
|
||||
* 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))
|
||||
#endif
|
||||
|
||||
/*
|
||||
/**
|
||||
* bitmap_from_u64 - Check and swap words within u64.
|
||||
* @mask: source 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.
|
||||
* 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.
|
||||
*/
|
||||
static inline void bitmap_from_u64(unsigned long *dst, u64 mask)
|
||||
|
|
|
|||
|
|
@ -37,19 +37,23 @@ int __ilog2_u64(u64 n)
|
|||
}
|
||||
#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.
|
||||
* Return: true if @n is a power of 2, otherwise false.
|
||||
*/
|
||||
|
||||
static inline __attribute__((const))
|
||||
bool is_power_of_2(unsigned long n)
|
||||
{
|
||||
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))
|
||||
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);
|
||||
}
|
||||
|
||||
/*
|
||||
* 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))
|
||||
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
|
||||
* @n - parameter
|
||||
* ilog2 - log base 2 of 32-bit or a 64-bit unsigned value
|
||||
* @n: parameter
|
||||
*
|
||||
* constant-capable log of base 2 calculation
|
||||
* - 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)
|
||||
*/
|
||||
|
|
@ -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
|
||||
* @n - parameter
|
||||
* @n: parameter
|
||||
*
|
||||
* round the given value up to the nearest power of two
|
||||
* - 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
|
||||
* @n - parameter
|
||||
* @n: parameter
|
||||
*
|
||||
* round the given value down to the nearest power of two
|
||||
* - 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) \
|
||||
)
|
||||
|
||||
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
|
||||
* @n: parameter
|
||||
|
|
@ -193,13 +204,6 @@ unsigned long __rounddown_pow_of_two(unsigned long n)
|
|||
* ob2(5) = 3
|
||||
* ... 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) \
|
||||
( \
|
||||
__builtin_constant_p(n) ? ( \
|
||||
|
|
|
|||
|
|
@ -12,6 +12,11 @@
|
|||
|
||||
/**
|
||||
* 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
|
||||
* 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
|
||||
* @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)
|
||||
{
|
||||
|
|
@ -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
|
||||
* @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)
|
||||
{
|
||||
|
|
@ -42,6 +57,10 @@ static inline u64 div64_u64_rem(u64 dividend, u64 divisor, u64 *remainder)
|
|||
|
||||
/**
|
||||
* 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)
|
||||
{
|
||||
|
|
@ -50,6 +69,10 @@ static inline u64 div64_u64(u64 dividend, u64 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)
|
||||
{
|
||||
|
|
@ -89,6 +112,8 @@ extern s64 div64_s64(s64 dividend, s64 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,
|
||||
* 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
|
||||
* @dividend: signed 64bit dividend
|
||||
* @divisor: signed 32bit divisor
|
||||
*/
|
||||
#ifndef div_s64
|
||||
static inline s64 div_s64(s64 dividend, s32 divisor)
|
||||
|
|
|
|||
|
|
@ -18,7 +18,9 @@
|
|||
|
||||
#include <asm/page.h>
|
||||
|
||||
/*
|
||||
/**
|
||||
* DOC: bitmap introduction
|
||||
*
|
||||
* bitmaps provide an array of bits, implemented using an an
|
||||
* array of unsigned longs. The number of valid bits in a
|
||||
* 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)
|
||||
* @len: The number of bytes. @crc is multiplied by x^(8*@len)
|
||||
* @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.
|
||||
* @crc: starting crc4
|
||||
* @c: starting crc4
|
||||
* @x: value 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/printk.h>
|
||||
|
||||
/*
|
||||
/**
|
||||
* crc8_populate_msb - fill crc table for given polynomial in reverse bit order.
|
||||
*
|
||||
* table: table to be filled.
|
||||
* polynomial: polynomial for which table is to be filled.
|
||||
* @table: table to be filled.
|
||||
* @polynomial: polynomial for which table is to be filled.
|
||||
*/
|
||||
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);
|
||||
|
||||
/*
|
||||
/**
|
||||
* crc8_populate_lsb - fill crc table for given polynomial in regular bit order.
|
||||
*
|
||||
* table: table to be filled.
|
||||
* polynomial: polynomial for which table is to be filled.
|
||||
* @table: table to be filled.
|
||||
* @polynomial: polynomial for which table is to be filled.
|
||||
*/
|
||||
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);
|
||||
|
||||
/*
|
||||
/**
|
||||
* crc8 - calculate a crc8 over the given input data.
|
||||
*
|
||||
* table: crc table used for calculation.
|
||||
* pdata: pointer to data buffer.
|
||||
* nbytes: number of bytes in data buffer.
|
||||
* crc: previous returned crc8 value.
|
||||
* @table: crc table used for calculation.
|
||||
* @pdata: pointer to data buffer.
|
||||
* @nbytes: number of bytes in data buffer.
|
||||
* @crc: previous returned crc8 value.
|
||||
*/
|
||||
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);
|
||||
#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
|
||||
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 __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 r = a | b;
|
||||
|
|
|
|||
|
|
@ -125,12 +125,12 @@ static int cn_test_want_notify(void)
|
|||
#endif
|
||||
|
||||
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;
|
||||
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);
|
||||
if (m) {
|
||||
|
|
@ -168,7 +168,7 @@ static int cn_test_init(void)
|
|||
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));
|
||||
|
||||
pr_info("initialized with id={%u.%u}\n",
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -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;
|
||||
|
||||
if ($x =~ /(struct|union)\s+(\w+)\s*{(.*)}/) {
|
||||
#my $decl_type = $1;
|
||||
my $decl_type = $1;
|
||||
$declaration_name = $2;
|
||||
my $members = $3;
|
||||
|
||||
|
|
@ -2194,7 +2194,7 @@ sub dump_struct($$) {
|
|||
$members =~ s/DECLARE_HASHTABLE\s*\(([^,)]+), ([^,)]+)\)/unsigned long $1\[1 << (($2) - 1)\]/gos;
|
||||
|
||||
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,
|
||||
'struct',
|
||||
|
|
@ -2226,6 +2226,8 @@ sub dump_enum($$) {
|
|||
if ($x =~ /enum\s+(\w+)\s*{(.*)}/) {
|
||||
$declaration_name = $1;
|
||||
my $members = $2;
|
||||
my %_members;
|
||||
|
||||
$members =~ s/\s+$//;
|
||||
|
||||
foreach my $arg (split ',', $members) {
|
||||
|
|
@ -2236,9 +2238,16 @@ sub dump_enum($$) {
|
|||
print STDERR "${file}:$.: warning: Enum value '$arg' ".
|
||||
"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,
|
||||
'enum',
|
||||
{'enum' => $declaration_name,
|
||||
|
|
@ -2506,7 +2515,7 @@ sub check_sections($$$$$$) {
|
|||
} else {
|
||||
if ($nested !~ m/\Q$sects[$sx]\E/) {
|
||||
print STDERR "${file}:$.: warning: " .
|
||||
"Excess struct/union/enum/typedef member " .
|
||||
"Excess $decl_type member " .
|
||||
"'$sects[$sx]' " .
|
||||
"description in '$decl_name'\n";
|
||||
++$warnings;
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче