* [PATCH 01/31] bcache.txt: standardize document format
2017-05-19 1:22 [PATCH 00/31] Standardize doc formats - part 1 Mauro Carvalho Chehab
@ 2017-05-19 1:22 ` Mauro Carvalho Chehab
2017-05-19 1:22 ` [PATCH 02/31] bt8xxgpio.txt: " Mauro Carvalho Chehab
` (29 subsequent siblings)
30 siblings, 0 replies; 37+ messages in thread
From: Mauro Carvalho Chehab @ 2017-05-19 1:22 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, David Woodhouse, Brian Norris, Boris Brezillon,
Marek Vasut, Richard Weinberger, Cyrille Pitchen, linux-mtd
Each text file under Documentation follows a different
format. Some doesn't even have titles!
Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- Add a title for the document;
- Use a list for the listed URLs;
- mark literal blocks;
- adjust whitespaces;
- Don't capitalize section titles.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/bcache.txt | 200 ++++++++++++++++++++++++++---------------------
1 file changed, 112 insertions(+), 88 deletions(-)
diff --git a/Documentation/bcache.txt b/Documentation/bcache.txt
index a9259b562d5c..c0ce64d75bbf 100644
--- a/Documentation/bcache.txt
+++ b/Documentation/bcache.txt
@@ -1,10 +1,15 @@
+============================
+A block layer cache (bcache)
+============================
+
Say you've got a big slow raid 6, and an ssd or three. Wouldn't it be
nice if you could use them as cache... Hence bcache.
Wiki and git repositories are at:
- http://bcache.evilpiepirate.org
- http://evilpiepirate.org/git/linux-bcache.git
- http://evilpiepirate.org/git/bcache-tools.git
+
+ - http://bcache.evilpiepirate.org
+ - http://evilpiepirate.org/git/linux-bcache.git
+ - http://evilpiepirate.org/git/bcache-tools.git
It's designed around the performance characteristics of SSDs - it only allocates
in erase block sized buckets, and it uses a hybrid btree/log to track cached
@@ -37,17 +42,19 @@ to be flushed.
Getting started:
You'll need make-bcache from the bcache-tools repository. Both the cache device
-and backing device must be formatted before use.
+and backing device must be formatted before use::
+
make-bcache -B /dev/sdb
make-bcache -C /dev/sdc
make-bcache has the ability to format multiple devices at the same time - if
you format your backing devices and cache device at the same time, you won't
-have to manually attach:
+have to manually attach::
+
make-bcache -B /dev/sda /dev/sdb -C /dev/sdc
bcache-tools now ships udev rules, and bcache devices are known to the kernel
-immediately. Without udev, you can manually register devices like this:
+immediately. Without udev, you can manually register devices like this::
echo /dev/sdb > /sys/fs/bcache/register
echo /dev/sdc > /sys/fs/bcache/register
@@ -60,16 +67,16 @@ slow devices as bcache backing devices without a cache, and you can choose to ad
a caching device later.
See 'ATTACHING' section below.
-The devices show up as:
+The devices show up as::
/dev/bcache<N>
-As well as (with udev):
+As well as (with udev)::
/dev/bcache/by-uuid/<uuid>
/dev/bcache/by-label/<label>
-To get started:
+To get started::
mkfs.ext4 /dev/bcache0
mount /dev/bcache0 /mnt
@@ -81,13 +88,13 @@ Cache devices are managed as sets; multiple caches per set isn't supported yet
but will allow for mirroring of metadata and dirty data in the future. Your new
cache set shows up as /sys/fs/bcache/<UUID>
-ATTACHING
+Attaching
---------
After your cache device and backing device are registered, the backing device
must be attached to your cache set to enable caching. Attaching a backing
device to a cache set is done thusly, with the UUID of the cache set in
-/sys/fs/bcache:
+/sys/fs/bcache::
echo <CSET-UUID> > /sys/block/bcache0/bcache/attach
@@ -97,7 +104,7 @@ your bcache devices. If a backing device has data in a cache somewhere, the
important if you have writeback caching turned on.
If you're booting up and your cache device is gone and never coming back, you
-can force run the backing device:
+can force run the backing device::
echo 1 > /sys/block/sdb/bcache/running
@@ -110,7 +117,7 @@ but all the cached data will be invalidated. If there was dirty data in the
cache, don't expect the filesystem to be recoverable - you will have massive
filesystem corruption, though ext4's fsck does work miracles.
-ERROR HANDLING
+Error Handling
--------------
Bcache tries to transparently handle IO errors to/from the cache device without
@@ -134,25 +141,27 @@ the backing devices to passthrough mode.
read some of the dirty data, though.
-HOWTO/COOKBOOK
+Howto/cookbook
--------------
A) Starting a bcache with a missing caching device
If registering the backing device doesn't help, it's already there, you just need
-to force it to run without the cache:
+to force it to run without the cache::
+
host:~# echo /dev/sdb1 > /sys/fs/bcache/register
[ 119.844831] bcache: register_bcache() error opening /dev/sdb1: device already registered
Next, you try to register your caching device if it's present. However
if it's absent, or registration fails for some reason, you can still
-start your bcache without its cache, like so:
+start your bcache without its cache, like so::
+
host:/sys/block/sdb/sdb1/bcache# echo 1 > running
Note that this may cause data loss if you were running in writeback mode.
-B) Bcache does not find its cache
+B) Bcache does not find its cache::
host:/sys/block/md5/bcache# echo 0226553a-37cf-41d5-b3ce-8b1e944543a8 > attach
[ 1933.455082] bcache: bch_cached_dev_attach() Couldn't find uuid for md5 in set
@@ -160,7 +169,8 @@ B) Bcache does not find its cache
[ 1933.478179] : cache set not found
In this case, the caching device was simply not registered at boot
-or disappeared and came back, and needs to be (re-)registered:
+or disappeared and came back, and needs to be (re-)registered::
+
host:/sys/block/md5/bcache# echo /dev/sdh2 > /sys/fs/bcache/register
@@ -180,7 +190,8 @@ device is still available at an 8KiB offset. So either via a loopdev
of the backing device created with --offset 8K, or any value defined by
--data-offset when you originally formatted bcache with `make-bcache`.
-For example:
+For example::
+
losetup -o 8192 /dev/loop0 /dev/your_bcache_backing_dev
This should present your unmodified backing device data in /dev/loop0
@@ -191,33 +202,38 @@ cache device without loosing data.
E) Wiping a cache device
-host:~# wipefs -a /dev/sdh2
-16 bytes were erased at offset 0x1018 (bcache)
-they were: c6 85 73 f6 4e 1a 45 ca 82 65 f5 7f 48 ba 6d 81
-
-After you boot back with bcache enabled, you recreate the cache and attach it:
-host:~# make-bcache -C /dev/sdh2
-UUID: 7be7e175-8f4c-4f99-94b2-9c904d227045
-Set UUID: 5bc072a8-ab17-446d-9744-e247949913c1
-version: 0
-nbuckets: 106874
-block_size: 1
-bucket_size: 1024
-nr_in_set: 1
-nr_this_dev: 0
-first_bucket: 1
-[ 650.511912] bcache: run_cache_set() invalidating existing data
-[ 650.549228] bcache: register_cache() registered cache device sdh2
-
-start backing device with missing cache:
-host:/sys/block/md5/bcache# echo 1 > running
-
-attach new cache:
-host:/sys/block/md5/bcache# echo 5bc072a8-ab17-446d-9744-e247949913c1 > attach
-[ 865.276616] bcache: bch_cached_dev_attach() Caching md5 as bcache0 on set 5bc072a8-ab17-446d-9744-e247949913c1
-
-
-F) Remove or replace a caching device
+::
+
+ host:~# wipefs -a /dev/sdh2
+ 16 bytes were erased at offset 0x1018 (bcache)
+ they were: c6 85 73 f6 4e 1a 45 ca 82 65 f5 7f 48 ba 6d 81
+
+After you boot back with bcache enabled, you recreate the cache and attach it::
+
+ host:~# make-bcache -C /dev/sdh2
+ UUID: 7be7e175-8f4c-4f99-94b2-9c904d227045
+ Set UUID: 5bc072a8-ab17-446d-9744-e247949913c1
+ version: 0
+ nbuckets: 106874
+ block_size: 1
+ bucket_size: 1024
+ nr_in_set: 1
+ nr_this_dev: 0
+ first_bucket: 1
+ [ 650.511912] bcache: run_cache_set() invalidating existing data
+ [ 650.549228] bcache: register_cache() registered cache device sdh2
+
+start backing device with missing cache::
+
+ host:/sys/block/md5/bcache# echo 1 > running
+
+attach new cache::
+
+ host:/sys/block/md5/bcache# echo 5bc072a8-ab17-446d-9744-e247949913c1 > attach
+ [ 865.276616] bcache: bch_cached_dev_attach() Caching md5 as bcache0 on set 5bc072a8-ab17-446d-9744-e247949913c1
+
+
+F) Remove or replace a caching device::
host:/sys/block/sda/sda7/bcache# echo 1 > detach
[ 695.872542] bcache: cached_dev_detach_finish() Caching disabled for sda7
@@ -226,13 +242,15 @@ F) Remove or replace a caching device
wipefs: error: /dev/nvme0n1p4: probing initialization failed: Device or resource busy
Ooops, it's disabled, but not unregistered, so it's still protected
-We need to go and unregister it:
+We need to go and unregister it::
+
host:/sys/fs/bcache/b7ba27a1-2398-4649-8ae3-0959f57ba128# ls -l cache0
lrwxrwxrwx 1 root root 0 Feb 25 18:33 cache0 -> ../../../devices/pci0000:00/0000:00:1d.0/0000:70:00.0/nvme/nvme0/nvme0n1/nvme0n1p4/bcache/
host:/sys/fs/bcache/b7ba27a1-2398-4649-8ae3-0959f57ba128# echo 1 > stop
kernel: [ 917.041908] bcache: cache_set_free() Cache set b7ba27a1-2398-4649-8ae3-0959f57ba128 unregistered
-Now we can wipe it:
+Now we can wipe it::
+
host:~# wipefs -a /dev/nvme0n1p4
/dev/nvme0n1p4: 16 bytes were erased at offset 0x00001018 (bcache): c6 85 73 f6 4e 1a 45 ca 82 65 f5 7f 48 ba 6d 81
@@ -252,40 +270,44 @@ if there are any active backing or caching devices left on it:
1) Is it present in /dev/bcache* ? (there are times where it won't be)
-If so, it's easy:
+ If so, it's easy::
+
host:/sys/block/bcache0/bcache# echo 1 > stop
-2) But if your backing device is gone, this won't work:
+2) But if your backing device is gone, this won't work::
+
host:/sys/block/bcache0# cd bcache
bash: cd: bcache: No such file or directory
-In this case, you may have to unregister the dmcrypt block device that
-references this bcache to free it up:
+ In this case, you may have to unregister the dmcrypt block device that
+ references this bcache to free it up::
+
host:~# dmsetup remove oldds1
bcache: bcache_device_free() bcache0 stopped
bcache: cache_set_free() Cache set 5bc072a8-ab17-446d-9744-e247949913c1 unregistered
-This causes the backing bcache to be removed from /sys/fs/bcache and
-then it can be reused. This would be true of any block device stacking
-where bcache is a lower device.
+ This causes the backing bcache to be removed from /sys/fs/bcache and
+ then it can be reused. This would be true of any block device stacking
+ where bcache is a lower device.
-3) In other cases, you can also look in /sys/fs/bcache/:
+3) In other cases, you can also look in /sys/fs/bcache/::
-host:/sys/fs/bcache# ls -l */{cache?,bdev?}
-lrwxrwxrwx 1 root root 0 Mar 5 09:39 0226553a-37cf-41d5-b3ce-8b1e944543a8/bdev1 -> ../../../devices/virtual/block/dm-1/bcache/
-lrwxrwxrwx 1 root root 0 Mar 5 09:39 0226553a-37cf-41d5-b3ce-8b1e944543a8/cache0 -> ../../../devices/virtual/block/dm-4/bcache/
-lrwxrwxrwx 1 root root 0 Mar 5 09:39 5bc072a8-ab17-446d-9744-e247949913c1/cache0 -> ../../../devices/pci0000:00/0000:00:01.0/0000:01:00.0/ata10/host9/target9:0:0/9:0:0:0/block/sdl/sdl2/bcache/
+ host:/sys/fs/bcache# ls -l */{cache?,bdev?}
+ lrwxrwxrwx 1 root root 0 Mar 5 09:39 0226553a-37cf-41d5-b3ce-8b1e944543a8/bdev1 -> ../../../devices/virtual/block/dm-1/bcache/
+ lrwxrwxrwx 1 root root 0 Mar 5 09:39 0226553a-37cf-41d5-b3ce-8b1e944543a8/cache0 -> ../../../devices/virtual/block/dm-4/bcache/
+ lrwxrwxrwx 1 root root 0 Mar 5 09:39 5bc072a8-ab17-446d-9744-e247949913c1/cache0 -> ../../../devices/pci0000:00/0000:00:01.0/0000:01:00.0/ata10/host9/target9:0:0/9:0:0:0/block/sdl/sdl2/bcache/
+
+ The device names will show which UUID is relevant, cd in that directory
+ and stop the cache::
-The device names will show which UUID is relevant, cd in that directory
-and stop the cache:
host:/sys/fs/bcache/5bc072a8-ab17-446d-9744-e247949913c1# echo 1 > stop
-This will free up bcache references and let you reuse the partition for
-other purposes.
+ This will free up bcache references and let you reuse the partition for
+ other purposes.
-TROUBLESHOOTING PERFORMANCE
+Troubleshooting performance
---------------------------
Bcache has a bunch of config options and tunables. The defaults are intended to
@@ -301,11 +323,13 @@ want for getting the best possible numbers when benchmarking.
raid stripe size to get the disk multiples that you would like.
For example: If you have a 64k stripe size, then the following offset
- would provide alignment for many common RAID5 data spindle counts:
+ would provide alignment for many common RAID5 data spindle counts::
+
64k * 2*2*2*3*3*5*7 bytes = 161280k
That space is wasted, but for only 157.5MB you can grow your RAID 5
- volume to the following data-spindle counts without re-aligning:
+ volume to the following data-spindle counts without re-aligning::
+
3,4,5,6,7,8,9,10,12,14,15,18,20,21 ...
- Bad write performance
@@ -313,9 +337,9 @@ want for getting the best possible numbers when benchmarking.
If write performance is not what you expected, you probably wanted to be
running in writeback mode, which isn't the default (not due to a lack of
maturity, but simply because in writeback mode you'll lose data if something
- happens to your SSD)
+ happens to your SSD)::
- # echo writeback > /sys/block/bcache0/bcache/cache_mode
+ # echo writeback > /sys/block/bcache0/bcache/cache_mode
- Bad performance, or traffic not going to the SSD that you'd expect
@@ -325,13 +349,13 @@ want for getting the best possible numbers when benchmarking.
accessed data out of your cache.
But if you want to benchmark reads from cache, and you start out with fio
- writing an 8 gigabyte test file - so you want to disable that.
+ writing an 8 gigabyte test file - so you want to disable that::
- # echo 0 > /sys/block/bcache0/bcache/sequential_cutoff
+ # echo 0 > /sys/block/bcache0/bcache/sequential_cutoff
- To set it back to the default (4 mb), do
+ To set it back to the default (4 mb), do::
- # echo 4M > /sys/block/bcache0/bcache/sequential_cutoff
+ # echo 4M > /sys/block/bcache0/bcache/sequential_cutoff
- Traffic's still going to the spindle/still getting cache misses
@@ -344,10 +368,10 @@ want for getting the best possible numbers when benchmarking.
throttles traffic if the latency exceeds a threshold (it does this by
cranking down the sequential bypass).
- You can disable this if you need to by setting the thresholds to 0:
+ You can disable this if you need to by setting the thresholds to 0::
- # echo 0 > /sys/fs/bcache/<cache set>/congested_read_threshold_us
- # echo 0 > /sys/fs/bcache/<cache set>/congested_write_threshold_us
+ # echo 0 > /sys/fs/bcache/<cache set>/congested_read_threshold_us
+ # echo 0 > /sys/fs/bcache/<cache set>/congested_write_threshold_us
The default is 2000 us (2 milliseconds) for reads, and 20000 for writes.
@@ -369,7 +393,7 @@ want for getting the best possible numbers when benchmarking.
a fix for the issue there).
-SYSFS - BACKING DEVICE
+Sysfs - backing device
----------------------
Available at /sys/block/<bdev>/bcache, /sys/block/bcache*/bcache and
@@ -454,7 +478,8 @@ writeback_running
still be added to the cache until it is mostly full; only meant for
benchmarking. Defaults to on.
-SYSFS - BACKING DEVICE STATS:
+Sysfs - backing device stats
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
There are directories with these numbers for a running total, as well as
versions that decay over the past day, hour and 5 minutes; they're also
@@ -463,14 +488,11 @@ aggregated in the cache set directory as well.
bypassed
Amount of IO (both reads and writes) that has bypassed the cache
-cache_hits
-cache_misses
-cache_hit_ratio
+cache_hits, cache_misses, cache_hit_ratio
Hits and misses are counted per individual IO as bcache sees them; a
partial hit is counted as a miss.
-cache_bypass_hits
-cache_bypass_misses
+cache_bypass_hits, cache_bypass_misses
Hits and misses for IO that is intended to skip the cache are still counted,
but broken out here.
@@ -482,7 +504,8 @@ cache_miss_collisions
cache_readaheads
Count of times readahead occurred.
-SYSFS - CACHE SET:
+Sysfs - cache set
+~~~~~~~~~~~~~~~~~
Available at /sys/fs/bcache/<cset-uuid>
@@ -520,8 +543,7 @@ flash_vol_create
Echoing a size to this file (in human readable units, k/M/G) creates a thinly
provisioned volume backed by the cache set.
-io_error_halflife
-io_error_limit
+io_error_halflife, io_error_limit
These determines how many errors we accept before disabling the cache.
Each error is decayed by the half life (in # ios). If the decaying count
reaches io_error_limit dirty data is written out and the cache is disabled.
@@ -545,7 +567,8 @@ unregister
Detaches all backing devices and closes the cache devices; if dirty data is
present it will disable writeback caching and wait for it to be flushed.
-SYSFS - CACHE SET INTERNAL:
+Sysfs - cache set internal
+~~~~~~~~~~~~~~~~~~~~~~~~~~
This directory also exposes timings for a number of internal operations, with
separate files for average duration, average frequency, last occurrence and max
@@ -574,7 +597,8 @@ cache_read_races
trigger_gc
Writing to this file forces garbage collection to run.
-SYSFS - CACHE DEVICE:
+Sysfs - Cache device
+~~~~~~~~~~~~~~~~~~~~
Available at /sys/block/<cdev>/bcache
--
2.9.4
^ permalink raw reply related [flat|nested] 37+ messages in thread* [PATCH 02/31] bt8xxgpio.txt: standardize document format
2017-05-19 1:22 [PATCH 00/31] Standardize doc formats - part 1 Mauro Carvalho Chehab
2017-05-19 1:22 ` [PATCH 01/31] bcache.txt: standardize document format Mauro Carvalho Chehab
@ 2017-05-19 1:22 ` Mauro Carvalho Chehab
2017-05-19 1:22 ` [PATCH 03/31] btmrvl.txt: " Mauro Carvalho Chehab
` (28 subsequent siblings)
30 siblings, 0 replies; 37+ messages in thread
From: Mauro Carvalho Chehab @ 2017-05-19 1:22 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, David Woodhouse, Brian Norris, Boris Brezillon,
Marek Vasut, Richard Weinberger, Cyrille Pitchen, linux-mtd
Each text file under Documentation follows a different
format. Some doesn't even have titles!
Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- Adjust titles to match the convention;
- use a literal block for ascii artwork.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/bt8xxgpio.txt | 19 +++++++------------
1 file changed, 7 insertions(+), 12 deletions(-)
diff --git a/Documentation/bt8xxgpio.txt b/Documentation/bt8xxgpio.txt
index d8297e4ebd26..a845feb074de 100644
--- a/Documentation/bt8xxgpio.txt
+++ b/Documentation/bt8xxgpio.txt
@@ -1,12 +1,8 @@
-===============================================================
-== BT8XXGPIO driver ==
-== ==
-== A driver for a selfmade cheap BT8xx based PCI GPIO-card ==
-== ==
-== For advanced documentation, see ==
-== http://www.bu3sch.de/btgpio.php ==
-===============================================================
+===================================================================
+A driver for a selfmade cheap BT8xx based PCI GPIO-card (bt8xxgpio)
+===================================================================
+For advanced documentation, see http://www.bu3sch.de/btgpio.php
A generic digital 24-port PCI GPIO card can be built out of an ordinary
Brooktree bt848, bt849, bt878 or bt879 based analog TV tuner card. The
@@ -17,9 +13,8 @@ The bt8xx chip does have 24 digital GPIO ports.
These ports are accessible via 24 pins on the SMD chip package.
-==============================================
-== How to physically access the GPIO pins ==
-==============================================
+How to physically access the GPIO pins
+======================================
The are several ways to access these pins. One might unsolder the whole chip
and put it on a custom PCI board, or one might only unsolder each individual
@@ -27,7 +22,7 @@ GPIO pin and solder that to some tiny wire. As the chip package really is tiny
there are some advanced soldering skills needed in any case.
The physical pinouts are drawn in the following ASCII art.
-The GPIO pins are marked with G00-G23
+The GPIO pins are marked with G00-G23::
G G G G G G G G G G G G G G G G G G
0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 1
--
2.9.4
^ permalink raw reply related [flat|nested] 37+ messages in thread* [PATCH 03/31] btmrvl.txt: standardize document format
2017-05-19 1:22 [PATCH 00/31] Standardize doc formats - part 1 Mauro Carvalho Chehab
2017-05-19 1:22 ` [PATCH 01/31] bcache.txt: standardize document format Mauro Carvalho Chehab
2017-05-19 1:22 ` [PATCH 02/31] bt8xxgpio.txt: " Mauro Carvalho Chehab
@ 2017-05-19 1:22 ` Mauro Carvalho Chehab
2017-05-19 1:22 ` [PATCH 04/31] bus-virt-phys-mapping.txt: " Mauro Carvalho Chehab
` (27 subsequent siblings)
30 siblings, 0 replies; 37+ messages in thread
From: Mauro Carvalho Chehab @ 2017-05-19 1:22 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, David Woodhouse, Brian Norris, Boris Brezillon,
Marek Vasut, Richard Weinberger, Cyrille Pitchen, linux-mtd
Each text file under Documentation follows a different
format. Some doesn't even have titles!
Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- Use the right notation for titles;
- Use a list for image names;
- Use literal blocks where needed;
- Whitespace fixes.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/btmrvl.txt | 64 +++++++++++++++++++++++++-----------------------
1 file changed, 34 insertions(+), 30 deletions(-)
diff --git a/Documentation/btmrvl.txt b/Documentation/btmrvl.txt
index 34916a46c099..575512415c2b 100644
--- a/Documentation/btmrvl.txt
+++ b/Documentation/btmrvl.txt
@@ -1,18 +1,15 @@
-=======================================================================
- README for btmrvl driver
-=======================================================================
-
+btmrvl driver
+=============
All commands are used via debugfs interface.
-=====================
-Set/get driver configurations:
+Set/get driver configurations
+=============================
Path: /debug/btmrvl/config/
-gpiogap=[n]
-hscfgcmd
- These commands are used to configure the host sleep parameters.
+gpiogap=[n], hscfgcmd
+ These commands are used to configure the host sleep parameters::
bit 8:0 -- Gap
bit 16:8 -- GPIO
@@ -23,7 +20,8 @@ hscfgcmd
where Gap is the gap in milli seconds between wakeup signal and
wakeup event, or 0xff for special host sleep setting.
- Usage:
+ Usage::
+
# Use SDIO interface to wake up the host and set GAP to 0x80:
echo 0xff80 > /debug/btmrvl/config/gpiogap
echo 1 > /debug/btmrvl/config/hscfgcmd
@@ -32,15 +30,16 @@ hscfgcmd
echo 0x03ff > /debug/btmrvl/config/gpiogap
echo 1 > /debug/btmrvl/config/hscfgcmd
-psmode=[n]
-pscmd
+psmode=[n], pscmd
These commands are used to enable/disable auto sleep mode
- where the option is:
+ where the option is::
+
1 -- Enable auto sleep mode
0 -- Disable auto sleep mode
- Usage:
+ Usage::
+
# Enable auto sleep mode
echo 1 > /debug/btmrvl/config/psmode
echo 1 > /debug/btmrvl/config/pscmd
@@ -50,15 +49,16 @@ pscmd
echo 1 > /debug/btmrvl/config/pscmd
-hsmode=[n]
-hscmd
+hsmode=[n], hscmd
These commands are used to enable host sleep or wake up firmware
- where the option is:
+ where the option is::
+
1 -- Enable host sleep
0 -- Wake up firmware
- Usage:
+ Usage::
+
# Enable host sleep
echo 1 > /debug/btmrvl/config/hsmode
echo 1 > /debug/btmrvl/config/hscmd
@@ -68,12 +68,13 @@ hscmd
echo 1 > /debug/btmrvl/config/hscmd
-======================
-Get driver status:
+Get driver status
+=================
Path: /debug/btmrvl/status/
-Usage:
+Usage::
+
cat /debug/btmrvl/status/<args>
where the args are:
@@ -90,14 +91,17 @@ hsstate
txdnldrdy
This command displays the value of Tx download ready flag.
-
-=====================
+Issuing a raw hci command
+=========================
Use hcitool to issue raw hci command, refer to hcitool manual
- Usage: Hcitool cmd <ogf> <ocf> [Parameters]
+Usage::
+
+ Hcitool cmd <ogf> <ocf> [Parameters]
+
+Interface Control Command::
- Interface Control Command
hcitool cmd 0x3f 0x5b 0xf5 0x01 0x00 --Enable All interface
hcitool cmd 0x3f 0x5b 0xf5 0x01 0x01 --Enable Wlan interface
hcitool cmd 0x3f 0x5b 0xf5 0x01 0x02 --Enable BT interface
@@ -105,13 +109,13 @@ Use hcitool to issue raw hci command, refer to hcitool manual
hcitool cmd 0x3f 0x5b 0xf5 0x00 0x01 --Disable Wlan interface
hcitool cmd 0x3f 0x5b 0xf5 0x00 0x02 --Disable BT interface
-=======================================================================
+SD8688 firmware
+===============
+Images:
-SD8688 firmware:
-
-/lib/firmware/sd8688_helper.bin
-/lib/firmware/sd8688.bin
+- /lib/firmware/sd8688_helper.bin
+- /lib/firmware/sd8688.bin
The images can be downloaded from:
--
2.9.4
^ permalink raw reply related [flat|nested] 37+ messages in thread* [PATCH 04/31] bus-virt-phys-mapping.txt: standardize document format
2017-05-19 1:22 [PATCH 00/31] Standardize doc formats - part 1 Mauro Carvalho Chehab
` (2 preceding siblings ...)
2017-05-19 1:22 ` [PATCH 03/31] btmrvl.txt: " Mauro Carvalho Chehab
@ 2017-05-19 1:22 ` Mauro Carvalho Chehab
2017-05-19 1:22 ` [PATCH 05/31] cachetlb.txt: " Mauro Carvalho Chehab
` (26 subsequent siblings)
30 siblings, 0 replies; 37+ messages in thread
From: Mauro Carvalho Chehab @ 2017-05-19 1:22 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, David Woodhouse, Brian Norris, Boris Brezillon,
Marek Vasut, Richard Weinberger, Cyrille Pitchen, linux-mtd
Each text file under Documentation follows a different
format. Some doesn't even have titles!
Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- Move author info to the beginning of file and use :Author:
- use warning/note annotation;
- mark literal blocks as such;
- Add a title for the document;
- use **emphasis** instead of _emphasis_.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/bus-virt-phys-mapping.txt | 63 +++++++++++++++++++--------------
1 file changed, 37 insertions(+), 26 deletions(-)
diff --git a/Documentation/bus-virt-phys-mapping.txt b/Documentation/bus-virt-phys-mapping.txt
index 2bc55ff3b4d1..26918b64bd6b 100644
--- a/Documentation/bus-virt-phys-mapping.txt
+++ b/Documentation/bus-virt-phys-mapping.txt
@@ -1,17 +1,26 @@
-[ NOTE: The virt_to_bus() and bus_to_virt() functions have been
+How to access I/O mapped memory from within device drivers
+==========================================================
+
+:Author: Linus
+
+.. warning::
+
+ The virt_to_bus() and bus_to_virt() functions have been
superseded by the functionality provided by the PCI DMA interface
(see Documentation/DMA-API-HOWTO.txt). They continue
to be documented below for historical purposes, but new code
- must not use them. --davidm 00/12/12 ]
+ must not use them. --davidm 00/12/12
-[ This is a mail message in response to a query on IO mapping, thus the
- strange format for a "document" ]
+::
+
+ [ This is a mail message in response to a query on IO mapping, thus the
+ strange format for a "document" ]
The AHA-1542 is a bus-master device, and your patch makes the driver give the
controller the physical address of the buffers, which is correct on x86
(because all bus master devices see the physical memory mappings directly).
-However, on many setups, there are actually _three_ different ways of looking
+However, on many setups, there are actually **three** different ways of looking
at memory addresses, and in this case we actually want the third, the
so-called "bus address".
@@ -38,7 +47,7 @@ because the memory and the devices share the same address space, and that is
not generally necessarily true on other PCI/ISA setups.
Now, just as an example, on the PReP (PowerPC Reference Platform), the
-CPU sees a memory map something like this (this is from memory):
+CPU sees a memory map something like this (this is from memory)::
0-2 GB "real memory"
2 GB-3 GB "system IO" (inb/out and similar accesses on x86)
@@ -52,7 +61,7 @@ So when the CPU wants any bus master to write to physical memory 0, it
has to give the master address 0x80000000 as the memory address.
So, for example, depending on how the kernel is actually mapped on the
-PPC, you can end up with a setup like this:
+PPC, you can end up with a setup like this::
physical address: 0
virtual address: 0xC0000000
@@ -61,7 +70,7 @@ PPC, you can end up with a setup like this:
where all the addresses actually point to the same thing. It's just seen
through different translations..
-Similarly, on the Alpha, the normal translation is
+Similarly, on the Alpha, the normal translation is::
physical address: 0
virtual address: 0xfffffc0000000000
@@ -70,7 +79,7 @@ Similarly, on the Alpha, the normal translation is
(but there are also Alphas where the physical address and the bus address
are the same).
-Anyway, the way to look up all these translations, you do
+Anyway, the way to look up all these translations, you do::
#include <asm/io.h>
@@ -81,8 +90,8 @@ Anyway, the way to look up all these translations, you do
Now, when do you need these?
-You want the _virtual_ address when you are actually going to access that
-pointer from the kernel. So you can have something like this:
+You want the **virtual** address when you are actually going to access that
+pointer from the kernel. So you can have something like this::
/*
* this is the hardware "mailbox" we use to communicate with
@@ -104,7 +113,7 @@ pointer from the kernel. So you can have something like this:
...
on the other hand, you want the bus address when you have a buffer that
-you want to give to the controller:
+you want to give to the controller::
/* ask the controller to read the sense status into "sense_buffer" */
mbox.bufstart = virt_to_bus(&sense_buffer);
@@ -112,7 +121,7 @@ you want to give to the controller:
mbox.status = 0;
notify_controller(&mbox);
-And you generally _never_ want to use the physical address, because you can't
+And you generally **never** want to use the physical address, because you can't
use that from the CPU (the CPU only uses translated virtual addresses), and
you can't use it from the bus master.
@@ -124,8 +133,10 @@ be remapped as measured in units of pages, a.k.a. the pfn (the memory
management layer doesn't know about devices outside the CPU, so it
shouldn't need to know about "bus addresses" etc).
-NOTE NOTE NOTE! The above is only one part of the whole equation. The above
-only talks about "real memory", that is, CPU memory (RAM).
+.. note::
+
+ The above is only one part of the whole equation. The above
+ only talks about "real memory", that is, CPU memory (RAM).
There is a completely different type of memory too, and that's the "shared
memory" on the PCI or ISA bus. That's generally not RAM (although in the case
@@ -137,20 +148,22 @@ whatever, and there is only one way to access it: the readb/writeb and
related functions. You should never take the address of such memory, because
there is really nothing you can do with such an address: it's not
conceptually in the same memory space as "real memory" at all, so you cannot
-just dereference a pointer. (Sadly, on x86 it _is_ in the same memory space,
+just dereference a pointer. (Sadly, on x86 it **is** in the same memory space,
so on x86 it actually works to just deference a pointer, but it's not
portable).
-For such memory, you can do things like
+For such memory, you can do things like:
+
+ - reading::
- - reading:
/*
* read first 32 bits from ISA memory at 0xC0000, aka
* C000:0000 in DOS terms
*/
unsigned int signature = isa_readl(0xC0000);
- - remapping and writing:
+ - remapping and writing::
+
/*
* remap framebuffer PCI memory area at 0xFC000000,
* size 1MB, so that we can access it: We can directly
@@ -165,7 +178,8 @@ For such memory, you can do things like
/* unmap when we unload the driver */
iounmap(baseptr);
- - copying and clearing:
+ - copying and clearing::
+
/* get the 6-byte Ethernet address at ISA address E000:0040 */
memcpy_fromio(kernel_buffer, 0xE0040, 6);
/* write a packet to the driver */
@@ -181,10 +195,10 @@ happy that your driver works ;)
Note that kernel versions 2.0.x (and earlier) mistakenly called the
ioremap() function "vremap()". ioremap() is the proper name, but I
didn't think straight when I wrote it originally. People who have to
-support both can do something like:
+support both can do something like::
/* support old naming silliness */
- #if LINUX_VERSION_CODE < 0x020100
+ #if LINUX_VERSION_CODE < 0x020100
#define ioremap vremap
#define iounmap vfree
#endif
@@ -196,13 +210,10 @@ And the above sounds worse than it really is. Most real drivers really
don't do all that complex things (or rather: the complexity is not so
much in the actual IO accesses as in error handling and timeouts etc).
It's generally not hard to fix drivers, and in many cases the code
-actually looks better afterwards:
+actually looks better afterwards::
unsigned long signature = *(unsigned int *) 0xC0000;
vs
unsigned long signature = readl(0xC0000);
I think the second version actually is more readable, no?
-
- Linus
-
--
2.9.4
^ permalink raw reply related [flat|nested] 37+ messages in thread* [PATCH 05/31] cachetlb.txt: standardize document format
2017-05-19 1:22 [PATCH 00/31] Standardize doc formats - part 1 Mauro Carvalho Chehab
` (3 preceding siblings ...)
2017-05-19 1:22 ` [PATCH 04/31] bus-virt-phys-mapping.txt: " Mauro Carvalho Chehab
@ 2017-05-19 1:22 ` Mauro Carvalho Chehab
2017-05-19 1:22 ` [PATCH 06/31] cgroup-v2.txt: " Mauro Carvalho Chehab
` (25 subsequent siblings)
30 siblings, 0 replies; 37+ messages in thread
From: Mauro Carvalho Chehab @ 2017-05-19 1:22 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, David Woodhouse, Brian Norris, Boris Brezillon,
Marek Vasut, Richard Weinberger, Cyrille Pitchen, linux-mtd
Each text file under Documentation follows a different
format. Some doesn't even have titles!
Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- Adjust the title format;
- use :Author: for author's name;
- mark literals as such;
- use note and important notation.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/cachetlb.txt | 92 ++++++++++++++++++++++++++--------------------
1 file changed, 52 insertions(+), 40 deletions(-)
diff --git a/Documentation/cachetlb.txt b/Documentation/cachetlb.txt
index 3f9f808b5119..6eb9d3f090cd 100644
--- a/Documentation/cachetlb.txt
+++ b/Documentation/cachetlb.txt
@@ -1,7 +1,8 @@
- Cache and TLB Flushing
- Under Linux
+==================================
+Cache and TLB Flushing Under Linux
+==================================
- David S. Miller <davem@redhat.com>
+:Author: David S. Miller <davem@redhat.com>
This document describes the cache/tlb flushing interfaces called
by the Linux VM subsystem. It enumerates over each interface,
@@ -28,7 +29,7 @@ Therefore when software page table changes occur, the kernel will
invoke one of the following flush methods _after_ the page table
changes occur:
-1) void flush_tlb_all(void)
+1) ``void flush_tlb_all(void)``
The most severe flush of all. After this interface runs,
any previous page table modification whatsoever will be
@@ -37,7 +38,7 @@ changes occur:
This is usually invoked when the kernel page tables are
changed, since such translations are "global" in nature.
-2) void flush_tlb_mm(struct mm_struct *mm)
+2) ``void flush_tlb_mm(struct mm_struct *mm)``
This interface flushes an entire user address space from
the TLB. After running, this interface must make sure that
@@ -49,8 +50,8 @@ changes occur:
page table operations such as what happens during
fork, and exec.
-3) void flush_tlb_range(struct vm_area_struct *vma,
- unsigned long start, unsigned long end)
+3) ``void flush_tlb_range(struct vm_area_struct *vma,
+ unsigned long start, unsigned long end)``
Here we are flushing a specific range of (user) virtual
address translations from the TLB. After running, this
@@ -69,7 +70,7 @@ changes occur:
call flush_tlb_page (see below) for each entry which may be
modified.
-4) void flush_tlb_page(struct vm_area_struct *vma, unsigned long addr)
+4) ``void flush_tlb_page(struct vm_area_struct *vma, unsigned long addr)``
This time we need to remove the PAGE_SIZE sized translation
from the TLB. The 'vma' is the backing structure used by
@@ -87,8 +88,8 @@ changes occur:
This is used primarily during fault processing.
-5) void update_mmu_cache(struct vm_area_struct *vma,
- unsigned long address, pte_t *ptep)
+5) ``void update_mmu_cache(struct vm_area_struct *vma,
+ unsigned long address, pte_t *ptep)``
At the end of every page fault, this routine is invoked to
tell the architecture specific code that a translation
@@ -100,7 +101,7 @@ changes occur:
translations for software managed TLB configurations.
The sparc64 port currently does this.
-6) void tlb_migrate_finish(struct mm_struct *mm)
+6) ``void tlb_migrate_finish(struct mm_struct *mm)``
This interface is called at the end of an explicit
process migration. This interface provides a hook
@@ -112,7 +113,7 @@ changes occur:
Next, we have the cache flushing interfaces. In general, when Linux
is changing an existing virtual-->physical mapping to a new value,
-the sequence will be in one of the following forms:
+the sequence will be in one of the following forms::
1) flush_cache_mm(mm);
change_all_page_tables_of(mm);
@@ -143,7 +144,7 @@ and have no dependency on translation information.
Here are the routines, one by one:
-1) void flush_cache_mm(struct mm_struct *mm)
+1) ``void flush_cache_mm(struct mm_struct *mm)``
This interface flushes an entire user address space from
the caches. That is, after running, there will be no cache
@@ -152,7 +153,7 @@ Here are the routines, one by one:
This interface is used to handle whole address space
page table operations such as what happens during exit and exec.
-2) void flush_cache_dup_mm(struct mm_struct *mm)
+2) ``void flush_cache_dup_mm(struct mm_struct *mm)``
This interface flushes an entire user address space from
the caches. That is, after running, there will be no cache
@@ -164,8 +165,8 @@ Here are the routines, one by one:
This option is separate from flush_cache_mm to allow some
optimizations for VIPT caches.
-3) void flush_cache_range(struct vm_area_struct *vma,
- unsigned long start, unsigned long end)
+3) ``void flush_cache_range(struct vm_area_struct *vma,
+ unsigned long start, unsigned long end)``
Here we are flushing a specific range of (user) virtual
addresses from the cache. After running, there will be no
@@ -181,7 +182,7 @@ Here are the routines, one by one:
call flush_cache_page (see below) for each entry which may be
modified.
-4) void flush_cache_page(struct vm_area_struct *vma, unsigned long addr, unsigned long pfn)
+4) ``void flush_cache_page(struct vm_area_struct *vma, unsigned long addr, unsigned long pfn)``
This time we need to remove a PAGE_SIZE sized range
from the cache. The 'vma' is the backing structure used by
@@ -202,7 +203,7 @@ Here are the routines, one by one:
This is used primarily during fault processing.
-5) void flush_cache_kmaps(void)
+5) ``void flush_cache_kmaps(void)``
This routine need only be implemented if the platform utilizes
highmem. It will be called right before all of the kmaps
@@ -214,8 +215,8 @@ Here are the routines, one by one:
This routing should be implemented in asm/highmem.h
-6) void flush_cache_vmap(unsigned long start, unsigned long end)
- void flush_cache_vunmap(unsigned long start, unsigned long end)
+6) ``void flush_cache_vmap(unsigned long start, unsigned long end)``
+ ``void flush_cache_vunmap(unsigned long start, unsigned long end)``
Here in these two interfaces we are flushing a specific range
of (kernel) virtual addresses from the cache. After running,
@@ -243,8 +244,10 @@ size). This setting will force the SYSv IPC layer to only allow user
processes to mmap shared memory at address which are a multiple of
this value.
-NOTE: This does not fix shared mmaps, check out the sparc64 port for
-one way to solve this (in particular SPARC_FLAG_MMAPSHARED).
+.. note::
+
+ This does not fix shared mmaps, check out the sparc64 port for
+ one way to solve this (in particular SPARC_FLAG_MMAPSHARED).
Next, you have to solve the D-cache aliasing issue for all
other cases. Please keep in mind that fact that, for a given page
@@ -255,8 +258,8 @@ physical page into its address space, by implication the D-cache
aliasing problem has the potential to exist since the kernel already
maps this page at its virtual address.
- void copy_user_page(void *to, void *from, unsigned long addr, struct page *page)
- void clear_user_page(void *to, unsigned long addr, struct page *page)
+ ``void copy_user_page(void *to, void *from, unsigned long addr, struct page *page)``
+ ``void clear_user_page(void *to, unsigned long addr, struct page *page)``
These two routines store data in user anonymous or COW
pages. It allows a port to efficiently avoid D-cache alias
@@ -276,14 +279,16 @@ maps this page at its virtual address.
If D-cache aliasing is not an issue, these two routines may
simply call memcpy/memset directly and do nothing more.
- void flush_dcache_page(struct page *page)
+ ``void flush_dcache_page(struct page *page)``
Any time the kernel writes to a page cache page, _OR_
the kernel is about to read from a page cache page and
user space shared/writable mappings of this page potentially
exist, this routine is called.
- NOTE: This routine need only be called for page cache pages
+ .. note::
+
+ This routine need only be called for page cache pages
which can potentially ever be mapped into the address
space of a user process. So for example, VFS layer code
handling vfs symlinks in the page cache need not call
@@ -322,18 +327,19 @@ maps this page at its virtual address.
made of this flag bit, and if set the flush is done and the flag
bit is cleared.
- IMPORTANT NOTE: It is often important, if you defer the flush,
+ .. important::
+
+ It is often important, if you defer the flush,
that the actual flush occurs on the same CPU
as did the cpu stores into the page to make it
dirty. Again, see sparc64 for examples of how
to deal with this.
- void copy_to_user_page(struct vm_area_struct *vma, struct page *page,
- unsigned long user_vaddr,
- void *dst, void *src, int len)
- void copy_from_user_page(struct vm_area_struct *vma, struct page *page,
- unsigned long user_vaddr,
- void *dst, void *src, int len)
+ ``void copy_to_user_page(struct vm_area_struct *vma, struct page *page,
+ unsigned long user_vaddr, void *dst, void *src, int len)``
+ ``void copy_from_user_page(struct vm_area_struct *vma, struct page *page,
+ unsigned long user_vaddr, void *dst, void *src, int len)``
+
When the kernel needs to copy arbitrary data in and out
of arbitrary user pages (f.e. for ptrace()) it will use
these two routines.
@@ -344,8 +350,9 @@ maps this page at its virtual address.
likely that you will need to flush the instruction cache
for copy_to_user_page().
- void flush_anon_page(struct vm_area_struct *vma, struct page *page,
- unsigned long vmaddr)
+ ``void flush_anon_page(struct vm_area_struct *vma, struct page *page,
+ unsigned long vmaddr)``
+
When the kernel needs to access the contents of an anonymous
page, it calls this function (currently only
get_user_pages()). Note: flush_dcache_page() deliberately
@@ -354,7 +361,8 @@ maps this page at its virtual address.
architectures). For incoherent architectures, it should flush
the cache of the page at vmaddr.
- void flush_kernel_dcache_page(struct page *page)
+ ``void flush_kernel_dcache_page(struct page *page)``
+
When the kernel needs to modify a user page is has obtained
with kmap, it calls this function after all modifications are
complete (but before kunmapping it) to bring the underlying
@@ -366,14 +374,16 @@ maps this page at its virtual address.
the kernel cache for page (using page_address(page)).
- void flush_icache_range(unsigned long start, unsigned long end)
+ ``void flush_icache_range(unsigned long start, unsigned long end)``
+
When the kernel stores into addresses that it will execute
out of (eg when loading modules), this function is called.
If the icache does not snoop stores then this routine will need
to flush it.
- void flush_icache_page(struct vm_area_struct *vma, struct page *page)
+ ``void flush_icache_page(struct vm_area_struct *vma, struct page *page)``
+
All the functionality of flush_icache_page can be implemented in
flush_dcache_page and update_mmu_cache. In the future, the hope
is to remove this interface completely.
@@ -387,7 +397,8 @@ the kernel trying to do I/O to vmap areas must manually manage
coherency. It must do this by flushing the vmap range before doing
I/O and invalidating it after the I/O returns.
- void flush_kernel_vmap_range(void *vaddr, int size)
+ ``void flush_kernel_vmap_range(void *vaddr, int size)``
+
flushes the kernel cache for a given virtual address range in
the vmap area. This is to make sure that any data the kernel
modified in the vmap range is made visible to the physical
@@ -395,7 +406,8 @@ I/O and invalidating it after the I/O returns.
Note that this API does *not* also flush the offset map alias
of the area.
- void invalidate_kernel_vmap_range(void *vaddr, int size) invalidates
+ ``void invalidate_kernel_vmap_range(void *vaddr, int size) invalidates``
+
the cache for a given virtual address range in the vmap area
which prevents the processor from making the cache stale by
speculatively reading data while the I/O was occurring to the
--
2.9.4
^ permalink raw reply related [flat|nested] 37+ messages in thread* [PATCH 06/31] cgroup-v2.txt: standardize document format
2017-05-19 1:22 [PATCH 00/31] Standardize doc formats - part 1 Mauro Carvalho Chehab
` (4 preceding siblings ...)
2017-05-19 1:22 ` [PATCH 05/31] cachetlb.txt: " Mauro Carvalho Chehab
@ 2017-05-19 1:22 ` Mauro Carvalho Chehab
2017-05-19 14:59 ` Tejun Heo
2017-05-19 1:22 ` [PATCH 07/31] circular-buffers.txt: " Mauro Carvalho Chehab
` (24 subsequent siblings)
30 siblings, 1 reply; 37+ messages in thread
From: Mauro Carvalho Chehab @ 2017-05-19 1:22 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, David Woodhouse, Brian Norris, Boris Brezillon,
Marek Vasut, Richard Weinberger, Cyrille Pitchen, linux-mtd,
Tejun Heo, Li Zefan, Johannes Weiner, cgroups
Each text file under Documentation follows a different
format. Some doesn't even have titles!
Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- Comment the internal index;
- Use :Date: and :Author: for authorship;
- Mark titles;
- Mark literal blocks;
- Adjust witespaces;
- Mark notes;
- Use table notation for the existing tables.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/cgroup-v2.txt | 449 +++++++++++++++++++++++---------------------
1 file changed, 234 insertions(+), 215 deletions(-)
diff --git a/Documentation/cgroup-v2.txt b/Documentation/cgroup-v2.txt
index dc5e2dcdbef4..491dd0200395 100644
--- a/Documentation/cgroup-v2.txt
+++ b/Documentation/cgroup-v2.txt
@@ -1,7 +1,9 @@
-
+================
Control Group v2
+================
-October, 2015 Tejun Heo <tj@kernel.org>
+:Date: October, 2015
+:Author: Tejun Heo <tj@kernel.org>
This is the authoritative documentation on the design, interface and
conventions of cgroup v2. It describes all userland-visible aspects
@@ -9,70 +11,72 @@ of cgroup including core and specific controller behaviors. All
future changes must be reflected in this document. Documentation for
v1 is available under Documentation/cgroup-v1/.
-CONTENTS
+.. CONTENTS
-1. Introduction
- 1-1. Terminology
- 1-2. What is cgroup?
-2. Basic Operations
- 2-1. Mounting
- 2-2. Organizing Processes
- 2-3. [Un]populated Notification
- 2-4. Controlling Controllers
- 2-4-1. Enabling and Disabling
- 2-4-2. Top-down Constraint
- 2-4-3. No Internal Process Constraint
- 2-5. Delegation
- 2-5-1. Model of Delegation
- 2-5-2. Delegation Containment
- 2-6. Guidelines
- 2-6-1. Organize Once and Control
- 2-6-2. Avoid Name Collisions
-3. Resource Distribution Models
- 3-1. Weights
- 3-2. Limits
- 3-3. Protections
- 3-4. Allocations
-4. Interface Files
- 4-1. Format
- 4-2. Conventions
- 4-3. Core Interface Files
-5. Controllers
- 5-1. CPU
- 5-1-1. CPU Interface Files
- 5-2. Memory
- 5-2-1. Memory Interface Files
- 5-2-2. Usage Guidelines
- 5-2-3. Memory Ownership
- 5-3. IO
- 5-3-1. IO Interface Files
- 5-3-2. Writeback
- 5-4. PID
- 5-4-1. PID Interface Files
- 5-5. RDMA
- 5-5-1. RDMA Interface Files
- 5-6. Misc
- 5-6-1. perf_event
-6. Namespace
- 6-1. Basics
- 6-2. The Root and Views
- 6-3. Migration and setns(2)
- 6-4. Interaction with Other Namespaces
-P. Information on Kernel Programming
- P-1. Filesystem Support for Writeback
-D. Deprecated v1 Core Features
-R. Issues with v1 and Rationales for v2
- R-1. Multiple Hierarchies
- R-2. Thread Granularity
- R-3. Competition Between Inner Nodes and Threads
- R-4. Other Interface Issues
- R-5. Controller Issues and Remedies
- R-5-1. Memory
+ 1. Introduction
+ 1-1. Terminology
+ 1-2. What is cgroup?
+ 2. Basic Operations
+ 2-1. Mounting
+ 2-2. Organizing Processes
+ 2-3. [Un]populated Notification
+ 2-4. Controlling Controllers
+ 2-4-1. Enabling and Disabling
+ 2-4-2. Top-down Constraint
+ 2-4-3. No Internal Process Constraint
+ 2-5. Delegation
+ 2-5-1. Model of Delegation
+ 2-5-2. Delegation Containment
+ 2-6. Guidelines
+ 2-6-1. Organize Once and Control
+ 2-6-2. Avoid Name Collisions
+ 3. Resource Distribution Models
+ 3-1. Weights
+ 3-2. Limits
+ 3-3. Protections
+ 3-4. Allocations
+ 4. Interface Files
+ 4-1. Format
+ 4-2. Conventions
+ 4-3. Core Interface Files
+ 5. Controllers
+ 5-1. CPU
+ 5-1-1. CPU Interface Files
+ 5-2. Memory
+ 5-2-1. Memory Interface Files
+ 5-2-2. Usage Guidelines
+ 5-2-3. Memory Ownership
+ 5-3. IO
+ 5-3-1. IO Interface Files
+ 5-3-2. Writeback
+ 5-4. PID
+ 5-4-1. PID Interface Files
+ 5-5. RDMA
+ 5-5-1. RDMA Interface Files
+ 5-6. Misc
+ 5-6-1. perf_event
+ 6. Namespace
+ 6-1. Basics
+ 6-2. The Root and Views
+ 6-3. Migration and setns(2)
+ 6-4. Interaction with Other Namespaces
+ P. Information on Kernel Programming
+ P-1. Filesystem Support for Writeback
+ D. Deprecated v1 Core Features
+ R. Issues with v1 and Rationales for v2
+ R-1. Multiple Hierarchies
+ R-2. Thread Granularity
+ R-3. Competition Between Inner Nodes and Threads
+ R-4. Other Interface Issues
+ R-5. Controller Issues and Remedies
+ R-5-1. Memory
-1. Introduction
+Introduction
+============
-1-1. Terminology
+Terminology
+-----------
"cgroup" stands for "control group" and is never capitalized. The
singular form is used to designate the whole feature and also as a
@@ -80,7 +84,8 @@ qualifier as in "cgroup controllers". When explicitly referring to
multiple individual control groups, the plural form "cgroups" is used.
-1-2. What is cgroup?
+What is cgroup?
+---------------
cgroup is a mechanism to organize processes hierarchically and
distribute system resources along the hierarchy in a controlled and
@@ -110,12 +115,14 @@ restrictions set closer to the root in the hierarchy can not be
overridden from further away.
-2. Basic Operations
+Basic Operations
+================
-2-1. Mounting
+Mounting
+--------
Unlike v1, cgroup v2 has only single hierarchy. The cgroup v2
-hierarchy can be mounted with the following mount command.
+hierarchy can be mounted with the following mount command::
# mount -t cgroup2 none $MOUNT_POINT
@@ -150,10 +157,11 @@ and experimenting easier, the kernel parameter cgroup_no_v1= allows
disabling controllers in v1 and make them always available in v2.
-2-2. Organizing Processes
+Organizing Processes
+--------------------
Initially, only the root cgroup exists to which all processes belong.
-A child cgroup can be created by creating a sub-directory.
+A child cgroup can be created by creating a sub-directory::
# mkdir $CGROUP_NAME
@@ -180,28 +188,29 @@ moved to another cgroup.
A cgroup which doesn't have any children or live processes can be
destroyed by removing the directory. Note that a cgroup which doesn't
have any children and is associated only with zombie processes is
-considered empty and can be removed.
+considered empty and can be removed::
# rmdir $CGROUP_NAME
"/proc/$PID/cgroup" lists a process's cgroup membership. If legacy
cgroup is in use in the system, this file may contain multiple lines,
one for each hierarchy. The entry for cgroup v2 is always in the
-format "0::$PATH".
+format "0::$PATH"::
# cat /proc/842/cgroup
...
0::/test-cgroup/test-cgroup-nested
If the process becomes a zombie and the cgroup it was associated with
-is removed subsequently, " (deleted)" is appended to the path.
+is removed subsequently, " (deleted)" is appended to the path::
# cat /proc/842/cgroup
...
0::/test-cgroup/test-cgroup-nested (deleted)
-2-3. [Un]populated Notification
+[Un]populated Notification
+--------------------------
Each non-root cgroup has a "cgroup.events" file which contains
"populated" field indicating whether the cgroup's sub-hierarchy has
@@ -212,7 +221,7 @@ example, to start a clean-up operation after all processes of a given
sub-hierarchy have exited. The populated state updates and
notifications are recursive. Consider the following sub-hierarchy
where the numbers in the parentheses represent the numbers of processes
-in each cgroup.
+in each cgroup::
A(4) - B(0) - C(1)
\ D(0)
@@ -223,18 +232,20 @@ file modified events will be generated on the "cgroup.events" files of
both cgroups.
-2-4. Controlling Controllers
+Controlling Controllers
+-----------------------
-2-4-1. Enabling and Disabling
+Enabling and Disabling
+~~~~~~~~~~~~~~~~~~~~~~
Each cgroup has a "cgroup.controllers" file which lists all
-controllers available for the cgroup to enable.
+controllers available for the cgroup to enable::
# cat cgroup.controllers
cpu io memory
No controller is enabled by default. Controllers can be enabled and
-disabled by writing to the "cgroup.subtree_control" file.
+disabled by writing to the "cgroup.subtree_control" file::
# echo "+cpu +memory -io" > cgroup.subtree_control
@@ -246,7 +257,7 @@ are specified, the last one is effective.
Enabling a controller in a cgroup indicates that the distribution of
the target resource across its immediate children will be controlled.
Consider the following sub-hierarchy. The enabled controllers are
-listed in parentheses.
+listed in parentheses::
A(cpu,memory) - B(memory) - C()
\ D()
@@ -266,7 +277,8 @@ controller interface files - anything which doesn't start with
"cgroup." are owned by the parent rather than the cgroup itself.
-2-4-2. Top-down Constraint
+Top-down Constraint
+~~~~~~~~~~~~~~~~~~~
Resources are distributed top-down and a cgroup can further distribute
a resource only if the resource has been distributed to it from the
@@ -277,7 +289,8 @@ the parent has the controller enabled and a controller can't be
disabled if one or more children have it enabled.
-2-4-3. No Internal Process Constraint
+No Internal Process Constraint
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Non-root cgroups can only distribute resources to their children when
they don't have any processes of their own. In other words, only
@@ -304,9 +317,11 @@ children before enabling controllers in its "cgroup.subtree_control"
file.
-2-5. Delegation
+Delegation
+----------
-2-5-1. Model of Delegation
+Model of Delegation
+~~~~~~~~~~~~~~~~~~~
A cgroup can be delegated to a less privileged user by granting write
access of the directory and its "cgroup.procs" file to the user. Note
@@ -326,7 +341,8 @@ cgroups in or nesting depth of a delegated sub-hierarchy; however,
this may be limited explicitly in the future.
-2-5-2. Delegation Containment
+Delegation Containment
+~~~~~~~~~~~~~~~~~~~~~~
A delegated sub-hierarchy is contained in the sense that processes
can't be moved into or out of the sub-hierarchy by the delegatee. For
@@ -345,7 +361,7 @@ in from or push out to outside the sub-hierarchy.
For an example, let's assume cgroups C0 and C1 have been delegated to
user U0 who created C00, C01 under C0 and C10 under C1 as follows and
-all processes under C0 and C1 belong to U0.
+all processes under C0 and C1 belong to U0::
~~~~~~~~~~~~~ - C0 - C00
~ cgroup ~ \ C01
@@ -360,9 +376,11 @@ not have write access to its "cgroup.procs" files and thus the write
will be denied with -EACCES.
-2-6. Guidelines
+Guidelines
+----------
-2-6-1. Organize Once and Control
+Organize Once and Control
+~~~~~~~~~~~~~~~~~~~~~~~~~
Migrating a process across cgroups is a relatively expensive operation
and stateful resources such as memory are not moved together with the
@@ -378,7 +396,8 @@ distribution can be made by changing controller configuration through
the interface files.
-2-6-2. Avoid Name Collisions
+Avoid Name Collisions
+~~~~~~~~~~~~~~~~~~~~~
Interface files for a cgroup and its children cgroups occupy the same
directory and it is possible to create children cgroups which collide
@@ -396,14 +415,16 @@ cgroup doesn't do anything to prevent name collisions and it's the
user's responsibility to avoid them.
-3. Resource Distribution Models
+Resource Distribution Models
+============================
cgroup controllers implement several resource distribution schemes
depending on the resource type and expected use cases. This section
describes major schemes in use along with their expected behaviors.
-3-1. Weights
+Weights
+-------
A parent's resource is distributed by adding up the weights of all
active children and giving each the fraction matching the ratio of its
@@ -424,7 +445,8 @@ process migrations.
and is an example of this type.
-3-2. Limits
+Limits
+------
A child can only consume upto the configured amount of the resource.
Limits can be over-committed - the sum of the limits of children can
@@ -440,7 +462,8 @@ process migrations.
on an IO device and is an example of this type.
-3-3. Protections
+Protections
+-----------
A cgroup is protected to be allocated upto the configured amount of
the resource if the usages of all its ancestors are under their
@@ -460,7 +483,8 @@ process migrations.
example of this type.
-3-4. Allocations
+Allocations
+-----------
A cgroup is exclusively allocated a certain amount of a finite
resource. Allocations can't be over-committed - the sum of the
@@ -479,12 +503,14 @@ may be rejected.
type.
-4. Interface Files
+Interface Files
+===============
-4-1. Format
+Format
+------
All interface files should be in one of the following formats whenever
-possible.
+possible::
New-line separated values
(when only one value can be written at once)
@@ -519,7 +545,8 @@ can be written at a time. For nested keyed files, the sub key pairs
may be specified in any order and not all pairs have to be specified.
-4-2. Conventions
+Conventions
+-----------
- Settings for a single feature should be contained in a single file.
@@ -555,25 +582,25 @@ may be specified in any order and not all pairs have to be specified.
with "default" as the value must not appear when read.
For example, a setting which is keyed by major:minor device numbers
- with integer values may look like the following.
+ with integer values may look like the following::
# cat cgroup-example-interface-file
default 150
8:0 300
- The default value can be updated by
+ The default value can be updated by::
# echo 125 > cgroup-example-interface-file
- or
+ or::
# echo "default 125" > cgroup-example-interface-file
- An override can be set by
+ An override can be set by::
# echo "8:16 170" > cgroup-example-interface-file
- and cleared by
+ and cleared by::
# echo "8:0 default" > cgroup-example-interface-file
# cat cgroup-example-interface-file
@@ -586,12 +613,12 @@ may be specified in any order and not all pairs have to be specified.
generated on the file.
-4-3. Core Interface Files
+Core Interface Files
+--------------------
All cgroup core files are prefixed with "cgroup."
cgroup.procs
-
A read-write new-line separated values file which exists on
all cgroups.
@@ -617,7 +644,6 @@ All cgroup core files are prefixed with "cgroup."
should be granted along with the containing directory.
cgroup.controllers
-
A read-only space separated values file which exists on all
cgroups.
@@ -625,7 +651,6 @@ All cgroup core files are prefixed with "cgroup."
the cgroup. The controllers are not ordered.
cgroup.subtree_control
-
A read-write space separated values file which exists on all
cgroups. Starts out empty.
@@ -641,23 +666,25 @@ All cgroup core files are prefixed with "cgroup."
operations are specified, either all succeed or all fail.
cgroup.events
-
A read-only flat-keyed file which exists on non-root cgroups.
The following entries are defined. Unless specified
otherwise, a value change in this file generates a file
modified event.
populated
-
1 if the cgroup or its descendants contains any live
processes; otherwise, 0.
-5. Controllers
+Controllers
+===========
-5-1. CPU
+CPU
+---
-[NOTE: The interface for the cpu controller hasn't been merged yet]
+.. note::
+
+ The interface for the cpu controller hasn't been merged yet
The "cpu" controllers regulates distribution of CPU cycles. This
controller implements weight and absolute bandwidth limit models for
@@ -665,36 +692,34 @@ normal scheduling policy and absolute bandwidth allocation model for
realtime scheduling policy.
-5-1-1. CPU Interface Files
+CPU Interface Files
+~~~~~~~~~~~~~~~~~~~
All time durations are in microseconds.
cpu.stat
-
A read-only flat-keyed file which exists on non-root cgroups.
- It reports the following six stats.
+ It reports the following six stats:
- usage_usec
- user_usec
- system_usec
- nr_periods
- nr_throttled
- throttled_usec
+ - usage_usec
+ - user_usec
+ - system_usec
+ - nr_periods
+ - nr_throttled
+ - throttled_usec
cpu.weight
-
A read-write single value file which exists on non-root
cgroups. The default is "100".
The weight in the range [1, 10000].
cpu.max
-
A read-write two value file which exists on non-root cgroups.
The default is "max 100000".
- The maximum bandwidth limit. It's in the following format.
+ The maximum bandwidth limit. It's in the following format::
$MAX $PERIOD
@@ -703,9 +728,10 @@ All time durations are in microseconds.
one number is written, $MAX is updated.
cpu.rt.max
+ .. note::
- [NOTE: The semantics of this file is still under discussion and the
- interface hasn't been merged yet]
+ The semantics of this file is still under discussion and the
+ interface hasn't been merged yet
A read-write two value file which exists on all cgroups.
The default is "0 100000".
@@ -713,7 +739,7 @@ All time durations are in microseconds.
The maximum realtime runtime allocation. Over-committing
configurations are disallowed and process migrations are
rejected if not enough bandwidth is available. It's in the
- following format.
+ following format::
$MAX $PERIOD
@@ -722,7 +748,8 @@ All time durations are in microseconds.
updated.
-5-2. Memory
+Memory
+------
The "memory" controller regulates distribution of memory. Memory is
stateful and implements both limit and protection models. Due to the
@@ -744,14 +771,14 @@ following types of memory usages are tracked.
The above list may expand in the future for better coverage.
-5-2-1. Memory Interface Files
+Memory Interface Files
+~~~~~~~~~~~~~~~~~~~~~~
All memory amounts are in bytes. If a value which is not aligned to
PAGE_SIZE is written, the value may be rounded up to the closest
PAGE_SIZE multiple when read back.
memory.current
-
A read-only single value file which exists on non-root
cgroups.
@@ -759,7 +786,6 @@ PAGE_SIZE multiple when read back.
and its descendants.
memory.low
-
A read-write single value file which exists on non-root
cgroups. The default is "0".
@@ -772,7 +798,6 @@ PAGE_SIZE multiple when read back.
protection is discouraged.
memory.high
-
A read-write single value file which exists on non-root
cgroups. The default is "max".
@@ -785,7 +810,6 @@ PAGE_SIZE multiple when read back.
under extreme conditions the limit may be breached.
memory.max
-
A read-write single value file which exists on non-root
cgroups. The default is "max".
@@ -800,21 +824,18 @@ PAGE_SIZE multiple when read back.
utility is limited to providing the final safety net.
memory.events
-
A read-only flat-keyed file which exists on non-root cgroups.
The following entries are defined. Unless specified
otherwise, a value change in this file generates a file
modified event.
low
-
The number of times the cgroup is reclaimed due to
high memory pressure even though its usage is under
the low boundary. This usually indicates that the low
boundary is over-committed.
high
-
The number of times processes of the cgroup are
throttled and routed to perform direct memory reclaim
because the high memory boundary was exceeded. For a
@@ -823,19 +844,16 @@ PAGE_SIZE multiple when read back.
occurrences are expected.
max
-
The number of times the cgroup's memory usage was
about to go over the max boundary. If direct reclaim
fails to bring it down, the OOM killer is invoked.
oom
-
The number of times the OOM killer has been invoked in
the cgroup. This may not exactly match the number of
processes killed but should generally be close.
memory.stat
-
A read-only flat-keyed file which exists on non-root cgroups.
This breaks down the cgroup's memory footprint into different
@@ -849,73 +867,55 @@ PAGE_SIZE multiple when read back.
fixed position; use the keys to look up specific values!
anon
-
Amount of memory used in anonymous mappings such as
brk(), sbrk(), and mmap(MAP_ANONYMOUS)
file
-
Amount of memory used to cache filesystem data,
including tmpfs and shared memory.
kernel_stack
-
Amount of memory allocated to kernel stacks.
slab
-
Amount of memory used for storing in-kernel data
structures.
sock
-
Amount of memory used in network transmission buffers
shmem
-
Amount of cached filesystem data that is swap-backed,
such as tmpfs, shm segments, shared anonymous mmap()s
file_mapped
-
Amount of cached filesystem data mapped with mmap()
file_dirty
-
Amount of cached filesystem data that was modified but
not yet written back to disk
file_writeback
-
Amount of cached filesystem data that was modified and
is currently being written back to disk
- inactive_anon
- active_anon
- inactive_file
- active_file
- unevictable
-
+ inactive_anon, active_anon, inactive_file, active_file, unevictable
Amount of memory, swap-backed and filesystem-backed,
on the internal memory management lists used by the
page reclaim algorithm
slab_reclaimable
-
Part of "slab" that might be reclaimed, such as
dentries and inodes.
slab_unreclaimable
-
Part of "slab" that cannot be reclaimed on memory
pressure.
pgfault
-
Total number of page faults incurred
pgmajfault
-
Number of major page faults incurred
workingset_refault
@@ -931,7 +931,6 @@ PAGE_SIZE multiple when read back.
Number of times a shadow node has been reclaimed
memory.swap.current
-
A read-only single value file which exists on non-root
cgroups.
@@ -939,7 +938,6 @@ PAGE_SIZE multiple when read back.
and its descendants.
memory.swap.max
-
A read-write single value file which exists on non-root
cgroups. The default is "max".
@@ -947,7 +945,8 @@ PAGE_SIZE multiple when read back.
limit, anonymous meomry of the cgroup will not be swapped out.
-5-2-2. Usage Guidelines
+Usage Guidelines
+~~~~~~~~~~~~~~~~
"memory.high" is the main mechanism to control memory usage.
Over-committing on high limit (sum of high limits > available memory)
@@ -970,7 +969,8 @@ memory; unfortunately, memory pressure monitoring mechanism isn't
implemented yet.
-5-2-3. Memory Ownership
+Memory Ownership
+~~~~~~~~~~~~~~~~
A memory area is charged to the cgroup which instantiated it and stays
charged to the cgroup until the area is released. Migrating a process
@@ -988,7 +988,8 @@ POSIX_FADV_DONTNEED to relinquish the ownership of memory areas
belonging to the affected files to ensure correct memory ownership.
-5-3. IO
+IO
+--
The "io" controller regulates the distribution of IO resources. This
controller implements both weight based and absolute bandwidth or IOPS
@@ -997,28 +998,29 @@ only if cfq-iosched is in use and neither scheme is available for
blk-mq devices.
-5-3-1. IO Interface Files
+IO Interface Files
+~~~~~~~~~~~~~~~~~~
io.stat
-
A read-only nested-keyed file which exists on non-root
cgroups.
Lines are keyed by $MAJ:$MIN device numbers and not ordered.
The following nested keys are defined.
+ ====== ===================
rbytes Bytes read
wbytes Bytes written
rios Number of read IOs
wios Number of write IOs
+ ====== ===================
- An example read output follows.
+ An example read output follows:
8:16 rbytes=1459200 wbytes=314773504 rios=192 wios=353
8:0 rbytes=90430464 wbytes=299008000 rios=8950 wios=1252
io.weight
-
A read-write flat-keyed file which exists on non-root cgroups.
The default is "default 100".
@@ -1032,14 +1034,13 @@ blk-mq devices.
$WEIGHT" or simply "$WEIGHT". Overrides can be set by writing
"$MAJ:$MIN $WEIGHT" and unset by writing "$MAJ:$MIN default".
- An example read output follows.
+ An example read output follows::
default 100
8:16 200
8:0 50
io.max
-
A read-write nested-keyed file which exists on non-root
cgroups.
@@ -1047,10 +1048,12 @@ blk-mq devices.
device numbers and not ordered. The following nested keys are
defined.
+ ===== ==================================
rbps Max read bytes per second
wbps Max write bytes per second
riops Max read IO operations per second
wiops Max write IO operations per second
+ ===== ==================================
When writing, any number of nested key-value pairs can be
specified in any order. "max" can be specified as the value
@@ -1060,24 +1063,25 @@ blk-mq devices.
BPS and IOPS are measured in each IO direction and IOs are
delayed if limit is reached. Temporary bursts are allowed.
- Setting read limit at 2M BPS and write at 120 IOPS for 8:16.
+ Setting read limit at 2M BPS and write at 120 IOPS for 8:16::
echo "8:16 rbps=2097152 wiops=120" > io.max
- Reading returns the following.
+ Reading returns the following::
8:16 rbps=2097152 wbps=max riops=max wiops=120
- Write IOPS limit can be removed by writing the following.
+ Write IOPS limit can be removed by writing the following::
echo "8:16 wiops=max" > io.max
- Reading now returns the following.
+ Reading now returns the following::
8:16 rbps=2097152 wbps=max riops=max wiops=max
-5-3-2. Writeback
+Writeback
+~~~~~~~~~
Page cache is dirtied through buffered writes and shared mmaps and
written asynchronously to the backing filesystem by the writeback
@@ -1125,22 +1129,19 @@ patterns.
The sysctl knobs which affect writeback behavior are applied to cgroup
writeback as follows.
- vm.dirty_background_ratio
- vm.dirty_ratio
-
+ vm.dirty_background_ratio, vm.dirty_ratio
These ratios apply the same to cgroup writeback with the
amount of available memory capped by limits imposed by the
memory controller and system-wide clean memory.
- vm.dirty_background_bytes
- vm.dirty_bytes
-
+ vm.dirty_background_bytes, vm.dirty_bytes
For cgroup writeback, this is calculated into ratio against
total available memory and applied the same way as
vm.dirty[_background]_ratio.
-5-4. PID
+PID
+---
The process number controller is used to allow a cgroup to stop any
new tasks from being fork()'d or clone()'d after a specified limit is
@@ -1155,17 +1156,16 @@ Note that PIDs used in this controller refer to TIDs, process IDs as
used by the kernel.
-5-4-1. PID Interface Files
+PID Interface Files
+~~~~~~~~~~~~~~~~~~~
pids.max
-
A read-write single value file which exists on non-root
cgroups. The default is "max".
Hard limit of number of processes.
pids.current
-
A read-only single value file which exists on all cgroups.
The number of processes currently in the cgroup and its
@@ -1180,12 +1180,14 @@ through fork() or clone(). These will return -EAGAIN if the creation
of a new process would cause a cgroup policy to be violated.
-5-5. RDMA
+RDMA
+----
The "rdma" controller regulates the distribution and accounting of
of RDMA resources.
-5-5-1. RDMA Interface Files
+RDMA Interface Files
+~~~~~~~~~~~~~~~~~~~~
rdma.max
A readwrite nested-keyed file that exists for all the cgroups
@@ -1198,10 +1200,12 @@ of RDMA resources.
The following nested keys are defined.
+ ========== =============================
hca_handle Maximum number of HCA Handles
hca_object Maximum number of HCA Objects
+ ========== =============================
- An example for mlx4 and ocrdma device follows.
+ An example for mlx4 and ocrdma device follows::
mlx4_0 hca_handle=2 hca_object=2000
ocrdma1 hca_handle=3 hca_object=max
@@ -1210,15 +1214,17 @@ of RDMA resources.
A read-only file that describes current resource usage.
It exists for all the cgroup except root.
- An example for mlx4 and ocrdma device follows.
+ An example for mlx4 and ocrdma device follows::
mlx4_0 hca_handle=1 hca_object=20
ocrdma1 hca_handle=1 hca_object=23
-5-6. Misc
+Misc
+----
-5-6-1. perf_event
+perf_event
+~~~~~~~~~~
perf_event controller, if not mounted on a legacy hierarchy, is
automatically enabled on the v2 hierarchy so that perf events can
@@ -1226,9 +1232,11 @@ always be filtered by cgroup v2 path. The controller can still be
moved to a legacy hierarchy after v2 hierarchy is populated.
-6. Namespace
+Namespace
+=========
-6-1. Basics
+Basics
+------
cgroup namespace provides a mechanism to virtualize the view of the
"/proc/$PID/cgroup" file and cgroup mounts. The CLONE_NEWCGROUP clone
@@ -1242,7 +1250,7 @@ Without cgroup namespace, the "/proc/$PID/cgroup" file shows the
complete path of the cgroup of a process. In a container setup where
a set of cgroups and namespaces are intended to isolate processes the
"/proc/$PID/cgroup" file may leak potential system level information
-to the isolated processes. For Example:
+to the isolated processes. For Example::
# cat /proc/self/cgroup
0::/batchjobs/container_id1
@@ -1250,14 +1258,14 @@ to the isolated processes. For Example:
The path '/batchjobs/container_id1' can be considered as system-data
and undesirable to expose to the isolated processes. cgroup namespace
can be used to restrict visibility of this path. For example, before
-creating a cgroup namespace, one would see:
+creating a cgroup namespace, one would see::
# ls -l /proc/self/ns/cgroup
lrwxrwxrwx 1 root root 0 2014-07-15 10:37 /proc/self/ns/cgroup -> cgroup:[4026531835]
# cat /proc/self/cgroup
0::/batchjobs/container_id1
-After unsharing a new namespace, the view changes.
+After unsharing a new namespace, the view changes::
# ls -l /proc/self/ns/cgroup
lrwxrwxrwx 1 root root 0 2014-07-15 10:35 /proc/self/ns/cgroup -> cgroup:[4026532183]
@@ -1275,7 +1283,8 @@ namespace is destroyed. The cgroupns root and the actual cgroups
remain.
-6-2. The Root and Views
+The Root and Views
+------------------
The 'cgroupns root' for a cgroup namespace is the cgroup in which the
process calling unshare(2) is running. For example, if a process in
@@ -1284,7 +1293,7 @@ process calling unshare(2) is running. For example, if a process in
init_cgroup_ns, this is the real root ('/') cgroup.
The cgroupns root cgroup does not change even if the namespace creator
-process later moves to a different cgroup.
+process later moves to a different cgroup::
# ~/unshare -c # unshare cgroupns in some cgroup
# cat /proc/self/cgroup
@@ -1298,7 +1307,7 @@ Each process gets its namespace-specific view of "/proc/$PID/cgroup"
Processes running inside the cgroup namespace will be able to see
cgroup paths (in /proc/self/cgroup) only inside their root cgroup.
-From within an unshared cgroupns:
+From within an unshared cgroupns::
# sleep 100000 &
[1] 7353
@@ -1307,7 +1316,7 @@ From within an unshared cgroupns:
0::/sub_cgrp_1
From the initial cgroup namespace, the real cgroup path will be
-visible:
+visible::
$ cat /proc/7353/cgroup
0::/batchjobs/container_id1/sub_cgrp_1
@@ -1315,7 +1324,7 @@ visible:
From a sibling cgroup namespace (that is, a namespace rooted at a
different cgroup), the cgroup path relative to its own cgroup
namespace root will be shown. For instance, if PID 7353's cgroup
-namespace root is at '/batchjobs/container_id2', then it will see
+namespace root is at '/batchjobs/container_id2', then it will see::
# cat /proc/7353/cgroup
0::/../container_id2/sub_cgrp_1
@@ -1324,13 +1333,14 @@ Note that the relative path always starts with '/' to indicate that
its relative to the cgroup namespace root of the caller.
-6-3. Migration and setns(2)
+Migration and setns(2)
+----------------------
Processes inside a cgroup namespace can move into and out of the
namespace root if they have proper access to external cgroups. For
example, from inside a namespace with cgroupns root at
/batchjobs/container_id1, and assuming that the global hierarchy is
-still accessible inside cgroupns:
+still accessible inside cgroupns::
# cat /proc/7353/cgroup
0::/sub_cgrp_1
@@ -1352,10 +1362,11 @@ namespace. It is expected that the someone moves the attaching
process under the target cgroup namespace root.
-6-4. Interaction with Other Namespaces
+Interaction with Other Namespaces
+---------------------------------
Namespace specific cgroup hierarchy can be mounted by a process
-running inside a non-init cgroup namespace.
+running inside a non-init cgroup namespace::
# mount -t cgroup2 none $MOUNT_POINT
@@ -1368,27 +1379,27 @@ the view of cgroup hierarchy by namespace-private cgroupfs mount
provides a properly isolated cgroup view inside the container.
-P. Information on Kernel Programming
+Information on Kernel Programming
+=================================
This section contains kernel programming information in the areas
where interacting with cgroup is necessary. cgroup core and
controllers are not covered.
-P-1. Filesystem Support for Writeback
+Filesystem Support for Writeback
+--------------------------------
A filesystem can support cgroup writeback by updating
address_space_operations->writepage[s]() to annotate bio's using the
following two functions.
wbc_init_bio(@wbc, @bio)
-
Should be called for each bio carrying writeback data and
associates the bio with the inode's owner cgroup. Can be
called anytime between bio allocation and submission.
wbc_account_io(@wbc, @page, @bytes)
-
Should be called for each data segment being written out.
While this function doesn't care exactly when it's called
during the writeback session, it's the easiest and most
@@ -1409,7 +1420,8 @@ cases by skipping wbc_init_bio() or using bio_associate_blkcg()
directly.
-D. Deprecated v1 Core Features
+Deprecated v1 Core Features
+===========================
- Multiple hierarchies including named ones are not supported.
@@ -1423,9 +1435,11 @@ D. Deprecated v1 Core Features
at the root instead.
-R. Issues with v1 and Rationales for v2
+Issues with v1 and Rationales for v2
+====================================
-R-1. Multiple Hierarchies
+Multiple Hierarchies
+--------------------
cgroup v1 allowed an arbitrary number of hierarchies and each
hierarchy could host any number of controllers. While this seemed to
@@ -1477,7 +1491,8 @@ how memory is distributed beyond a certain level while still wanting
to control how CPU cycles are distributed.
-R-2. Thread Granularity
+Thread Granularity
+------------------
cgroup v1 allowed threads of a process to belong to different cgroups.
This didn't make sense for some controllers and those controllers
@@ -1520,7 +1535,8 @@ misbehaving and poorly abstracted interfaces and kernel exposing and
locked into constructs inadvertently.
-R-3. Competition Between Inner Nodes and Threads
+Competition Between Inner Nodes and Threads
+-------------------------------------------
cgroup v1 allowed threads to be in any cgroups which created an
interesting problem where threads belonging to a parent cgroup and its
@@ -1539,7 +1555,7 @@ simply weren't available for threads.
The io controller implicitly created a hidden leaf node for each
cgroup to host the threads. The hidden leaf had its own copies of all
-the knobs with "leaf_" prefixed. While this allowed equivalent
+the knobs with ``leaf_`` prefixed. While this allowed equivalent
control over internal threads, it was with serious drawbacks. It
always added an extra layer of nesting which wouldn't be necessary
otherwise, made the interface messy and significantly complicated the
@@ -1560,7 +1576,8 @@ This clearly is a problem which needs to be addressed from cgroup core
in a uniform way.
-R-4. Other Interface Issues
+Other Interface Issues
+----------------------
cgroup v1 grew without oversight and developed a large number of
idiosyncrasies and inconsistencies. One issue on the cgroup core side
@@ -1588,9 +1605,11 @@ cgroup v2 establishes common conventions where appropriate and updates
controllers so that they expose minimal and consistent interfaces.
-R-5. Controller Issues and Remedies
+Controller Issues and Remedies
+------------------------------
-R-5-1. Memory
+Memory
+~~~~~~
The original lower boundary, the soft limit, is defined as a limit
that is per default unset. As a result, the set of cgroups that
--
2.9.4
^ permalink raw reply related [flat|nested] 37+ messages in thread* Re: [PATCH 06/31] cgroup-v2.txt: standardize document format
2017-05-19 1:22 ` [PATCH 06/31] cgroup-v2.txt: " Mauro Carvalho Chehab
@ 2017-05-19 14:59 ` Tejun Heo
2017-06-17 15:18 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 37+ messages in thread
From: Tejun Heo @ 2017-05-19 14:59 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, David Woodhouse, Brian Norris, Boris Brezillon,
Marek Vasut, Richard Weinberger, Cyrille Pitchen, linux-mtd,
Li Zefan, Johannes Weiner, cgroups
Hello, Mauro.
On Thu, May 18, 2017 at 10:22:11PM -0300, Mauro Carvalho Chehab wrote:
> Each text file under Documentation follows a different
> format. Some doesn't even have titles!
>
> Change its representation to follow the adopted standard,
> using ReST markups for it to be parseable by Sphinx:
>
> - Comment the internal index;
> - Use :Date: and :Author: for authorship;
> - Mark titles;
> - Mark literal blocks;
> - Adjust witespaces;
> - Mark notes;
> - Use table notation for the existing tables.
If this is the direction we're taking for all docs, looks good to me.
Do you want me to take the patch through the cgroup tree?
Thanks.
--
tejun
^ permalink raw reply [flat|nested] 37+ messages in thread
* Re: [PATCH 06/31] cgroup-v2.txt: standardize document format
2017-05-19 14:59 ` Tejun Heo
@ 2017-06-17 15:18 ` Mauro Carvalho Chehab
2017-06-18 10:46 ` Tejun Heo
0 siblings, 1 reply; 37+ messages in thread
From: Mauro Carvalho Chehab @ 2017-06-17 15:18 UTC (permalink / raw)
To: Tejun Heo
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, David Woodhouse, Brian Norris, Boris Brezillon,
Marek Vasut, Richard Weinberger, Cyrille Pitchen, linux-mtd,
Li Zefan, Johannes Weiner, cgroups
Em Fri, 19 May 2017 10:59:21 -0400
Tejun Heo <tj@kernel.org> escreveu:
> Hello, Mauro.
>
> On Thu, May 18, 2017 at 10:22:11PM -0300, Mauro Carvalho Chehab wrote:
> > Each text file under Documentation follows a different
> > format. Some doesn't even have titles!
> >
> > Change its representation to follow the adopted standard,
> > using ReST markups for it to be parseable by Sphinx:
> >
> > - Comment the internal index;
> > - Use :Date: and :Author: for authorship;
> > - Mark titles;
> > - Mark literal blocks;
> > - Adjust witespaces;
> > - Mark notes;
> > - Use table notation for the existing tables.
>
> If this is the direction we're taking for all docs, looks good to me.
> Do you want me to take the patch through the cgroup tree?
Sorry to take so long to answer... I traveled to a place without access to
my emails, and then got sidetracked by other things after returning from
it.
Yeah, feel free to apply it via your tree. I'm enclosing a
version rebased from linux-next. I solved a few conflicts on it.
Thanks,
Mauro
-
[PATCH v2] cgroup-v2.txt: standardize document format
Each text file under Documentation follows a different
format. Some doesn't even have titles!
Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- Comment the internal index;
- Use :Date: and :Author: for authorship;
- Mark titles;
- Mark literal blocks;
- Adjust witespaces;
- Mark notes;
- Use table notation for the existing tables.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
diff --git a/Documentation/cgroup-v2.txt b/Documentation/cgroup-v2.txt
index a86f3cb88125..1e198bb07eb5 100644
--- a/Documentation/cgroup-v2.txt
+++ b/Documentation/cgroup-v2.txt
@@ -1,7 +1,9 @@
-
+================
Control Group v2
+================
-October, 2015 Tejun Heo <tj@kernel.org>
+:Date: October, 2015
+:Author: Tejun Heo <tj@kernel.org>
This is the authoritative documentation on the design, interface and
conventions of cgroup v2. It describes all userland-visible aspects
@@ -9,70 +11,72 @@ of cgroup including core and specific controller behaviors. All
future changes must be reflected in this document. Documentation for
v1 is available under Documentation/cgroup-v1/.
-CONTENTS
-
-1. Introduction
- 1-1. Terminology
- 1-2. What is cgroup?
-2. Basic Operations
- 2-1. Mounting
- 2-2. Organizing Processes
- 2-3. [Un]populated Notification
- 2-4. Controlling Controllers
- 2-4-1. Enabling and Disabling
- 2-4-2. Top-down Constraint
- 2-4-3. No Internal Process Constraint
- 2-5. Delegation
- 2-5-1. Model of Delegation
- 2-5-2. Delegation Containment
- 2-6. Guidelines
- 2-6-1. Organize Once and Control
- 2-6-2. Avoid Name Collisions
-3. Resource Distribution Models
- 3-1. Weights
- 3-2. Limits
- 3-3. Protections
- 3-4. Allocations
-4. Interface Files
- 4-1. Format
- 4-2. Conventions
- 4-3. Core Interface Files
-5. Controllers
- 5-1. CPU
- 5-1-1. CPU Interface Files
- 5-2. Memory
- 5-2-1. Memory Interface Files
- 5-2-2. Usage Guidelines
- 5-2-3. Memory Ownership
- 5-3. IO
- 5-3-1. IO Interface Files
- 5-3-2. Writeback
- 5-4. PID
- 5-4-1. PID Interface Files
- 5-5. RDMA
- 5-5-1. RDMA Interface Files
- 5-6. Misc
- 5-6-1. perf_event
-6. Namespace
- 6-1. Basics
- 6-2. The Root and Views
- 6-3. Migration and setns(2)
- 6-4. Interaction with Other Namespaces
-P. Information on Kernel Programming
- P-1. Filesystem Support for Writeback
-D. Deprecated v1 Core Features
-R. Issues with v1 and Rationales for v2
- R-1. Multiple Hierarchies
- R-2. Thread Granularity
- R-3. Competition Between Inner Nodes and Threads
- R-4. Other Interface Issues
- R-5. Controller Issues and Remedies
- R-5-1. Memory
-
-
-1. Introduction
-
-1-1. Terminology
+.. CONTENTS
+
+ 1. Introduction
+ 1-1. Terminology
+ 1-2. What is cgroup?
+ 2. Basic Operations
+ 2-1. Mounting
+ 2-2. Organizing Processes
+ 2-3. [Un]populated Notification
+ 2-4. Controlling Controllers
+ 2-4-1. Enabling and Disabling
+ 2-4-2. Top-down Constraint
+ 2-4-3. No Internal Process Constraint
+ 2-5. Delegation
+ 2-5-1. Model of Delegation
+ 2-5-2. Delegation Containment
+ 2-6. Guidelines
+ 2-6-1. Organize Once and Control
+ 2-6-2. Avoid Name Collisions
+ 3. Resource Distribution Models
+ 3-1. Weights
+ 3-2. Limits
+ 3-3. Protections
+ 3-4. Allocations
+ 4. Interface Files
+ 4-1. Format
+ 4-2. Conventions
+ 4-3. Core Interface Files
+ 5. Controllers
+ 5-1. CPU
+ 5-1-1. CPU Interface Files
+ 5-2. Memory
+ 5-2-1. Memory Interface Files
+ 5-2-2. Usage Guidelines
+ 5-2-3. Memory Ownership
+ 5-3. IO
+ 5-3-1. IO Interface Files
+ 5-3-2. Writeback
+ 5-4. PID
+ 5-4-1. PID Interface Files
+ 5-5. RDMA
+ 5-5-1. RDMA Interface Files
+ 5-6. Misc
+ 5-6-1. perf_event
+ 6. Namespace
+ 6-1. Basics
+ 6-2. The Root and Views
+ 6-3. Migration and setns(2)
+ 6-4. Interaction with Other Namespaces
+ P. Information on Kernel Programming
+ P-1. Filesystem Support for Writeback
+ D. Deprecated v1 Core Features
+ R. Issues with v1 and Rationales for v2
+ R-1. Multiple Hierarchies
+ R-2. Thread Granularity
+ R-3. Competition Between Inner Nodes and Threads
+ R-4. Other Interface Issues
+ R-5. Controller Issues and Remedies
+ R-5-1. Memory
+
+
+Introduction
+============
+
+Terminology
+-----------
"cgroup" stands for "control group" and is never capitalized. The
singular form is used to designate the whole feature and also as a
@@ -80,7 +84,8 @@ qualifier as in "cgroup controllers". When explicitly referring to
multiple individual control groups, the plural form "cgroups" is used.
-1-2. What is cgroup?
+What is cgroup?
+---------------
cgroup is a mechanism to organize processes hierarchically and
distribute system resources along the hierarchy in a controlled and
@@ -110,12 +115,14 @@ restrictions set closer to the root in the hierarchy can not be
overridden from further away.
-2. Basic Operations
+Basic Operations
+================
-2-1. Mounting
+Mounting
+--------
Unlike v1, cgroup v2 has only single hierarchy. The cgroup v2
-hierarchy can be mounted with the following mount command.
+hierarchy can be mounted with the following mount command::
# mount -t cgroup2 none $MOUNT_POINT
@@ -150,10 +157,11 @@ and experimenting easier, the kernel parameter cgroup_no_v1= allows
disabling controllers in v1 and make them always available in v2.
-2-2. Organizing Processes
+Organizing Processes
+--------------------
Initially, only the root cgroup exists to which all processes belong.
-A child cgroup can be created by creating a sub-directory.
+A child cgroup can be created by creating a sub-directory::
# mkdir $CGROUP_NAME
@@ -180,28 +188,29 @@ moved to another cgroup.
A cgroup which doesn't have any children or live processes can be
destroyed by removing the directory. Note that a cgroup which doesn't
have any children and is associated only with zombie processes is
-considered empty and can be removed.
+considered empty and can be removed::
# rmdir $CGROUP_NAME
"/proc/$PID/cgroup" lists a process's cgroup membership. If legacy
cgroup is in use in the system, this file may contain multiple lines,
one for each hierarchy. The entry for cgroup v2 is always in the
-format "0::$PATH".
+format "0::$PATH"::
# cat /proc/842/cgroup
...
0::/test-cgroup/test-cgroup-nested
If the process becomes a zombie and the cgroup it was associated with
-is removed subsequently, " (deleted)" is appended to the path.
+is removed subsequently, " (deleted)" is appended to the path::
# cat /proc/842/cgroup
...
0::/test-cgroup/test-cgroup-nested (deleted)
-2-3. [Un]populated Notification
+[Un]populated Notification
+--------------------------
Each non-root cgroup has a "cgroup.events" file which contains
"populated" field indicating whether the cgroup's sub-hierarchy has
@@ -212,7 +221,7 @@ example, to start a clean-up operation after all processes of a given
sub-hierarchy have exited. The populated state updates and
notifications are recursive. Consider the following sub-hierarchy
where the numbers in the parentheses represent the numbers of processes
-in each cgroup.
+in each cgroup::
A(4) - B(0) - C(1)
\ D(0)
@@ -223,18 +232,20 @@ file modified events will be generated on the "cgroup.events" files of
both cgroups.
-2-4. Controlling Controllers
+Controlling Controllers
+-----------------------
-2-4-1. Enabling and Disabling
+Enabling and Disabling
+~~~~~~~~~~~~~~~~~~~~~~
Each cgroup has a "cgroup.controllers" file which lists all
-controllers available for the cgroup to enable.
+controllers available for the cgroup to enable::
# cat cgroup.controllers
cpu io memory
No controller is enabled by default. Controllers can be enabled and
-disabled by writing to the "cgroup.subtree_control" file.
+disabled by writing to the "cgroup.subtree_control" file::
# echo "+cpu +memory -io" > cgroup.subtree_control
@@ -246,7 +257,7 @@ are specified, the last one is effective.
Enabling a controller in a cgroup indicates that the distribution of
the target resource across its immediate children will be controlled.
Consider the following sub-hierarchy. The enabled controllers are
-listed in parentheses.
+listed in parentheses::
A(cpu,memory) - B(memory) - C()
\ D()
@@ -266,7 +277,8 @@ controller interface files - anything which doesn't start with
"cgroup." are owned by the parent rather than the cgroup itself.
-2-4-2. Top-down Constraint
+Top-down Constraint
+~~~~~~~~~~~~~~~~~~~
Resources are distributed top-down and a cgroup can further distribute
a resource only if the resource has been distributed to it from the
@@ -277,7 +289,8 @@ the parent has the controller enabled and a controller can't be
disabled if one or more children have it enabled.
-2-4-3. No Internal Process Constraint
+No Internal Process Constraint
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Non-root cgroups can only distribute resources to their children when
they don't have any processes of their own. In other words, only
@@ -304,9 +317,11 @@ children before enabling controllers in its "cgroup.subtree_control"
file.
-2-5. Delegation
+Delegation
+----------
-2-5-1. Model of Delegation
+Model of Delegation
+~~~~~~~~~~~~~~~~~~~
A cgroup can be delegated to a less privileged user by granting write
access of the directory and its "cgroup.procs" file to the user. Note
@@ -326,7 +341,8 @@ cgroups in or nesting depth of a delegated sub-hierarchy; however,
this may be limited explicitly in the future.
-2-5-2. Delegation Containment
+Delegation Containment
+~~~~~~~~~~~~~~~~~~~~~~
A delegated sub-hierarchy is contained in the sense that processes
can't be moved into or out of the sub-hierarchy by the delegatee. For
@@ -345,7 +361,7 @@ in from or push out to outside the sub-hierarchy.
For an example, let's assume cgroups C0 and C1 have been delegated to
user U0 who created C00, C01 under C0 and C10 under C1 as follows and
-all processes under C0 and C1 belong to U0.
+all processes under C0 and C1 belong to U0::
~~~~~~~~~~~~~ - C0 - C00
~ cgroup ~ \ C01
@@ -360,9 +376,11 @@ not have write access to its "cgroup.procs" files and thus the write
will be denied with -EACCES.
-2-6. Guidelines
+Guidelines
+----------
-2-6-1. Organize Once and Control
+Organize Once and Control
+~~~~~~~~~~~~~~~~~~~~~~~~~
Migrating a process across cgroups is a relatively expensive operation
and stateful resources such as memory are not moved together with the
@@ -378,7 +396,8 @@ distribution can be made by changing controller configuration through
the interface files.
-2-6-2. Avoid Name Collisions
+Avoid Name Collisions
+~~~~~~~~~~~~~~~~~~~~~
Interface files for a cgroup and its children cgroups occupy the same
directory and it is possible to create children cgroups which collide
@@ -396,14 +415,16 @@ cgroup doesn't do anything to prevent name collisions and it's the
user's responsibility to avoid them.
-3. Resource Distribution Models
+Resource Distribution Models
+============================
cgroup controllers implement several resource distribution schemes
depending on the resource type and expected use cases. This section
describes major schemes in use along with their expected behaviors.
-3-1. Weights
+Weights
+-------
A parent's resource is distributed by adding up the weights of all
active children and giving each the fraction matching the ratio of its
@@ -424,7 +445,8 @@ process migrations.
and is an example of this type.
-3-2. Limits
+Limits
+------
A child can only consume upto the configured amount of the resource.
Limits can be over-committed - the sum of the limits of children can
@@ -440,7 +462,8 @@ process migrations.
on an IO device and is an example of this type.
-3-3. Protections
+Protections
+-----------
A cgroup is protected to be allocated upto the configured amount of
the resource if the usages of all its ancestors are under their
@@ -460,7 +483,8 @@ process migrations.
example of this type.
-3-4. Allocations
+Allocations
+-----------
A cgroup is exclusively allocated a certain amount of a finite
resource. Allocations can't be over-committed - the sum of the
@@ -479,12 +503,14 @@ may be rejected.
type.
-4. Interface Files
+Interface Files
+===============
-4-1. Format
+Format
+------
All interface files should be in one of the following formats whenever
-possible.
+possible::
New-line separated values
(when only one value can be written at once)
@@ -519,7 +545,8 @@ can be written at a time. For nested keyed files, the sub key pairs
may be specified in any order and not all pairs have to be specified.
-4-2. Conventions
+Conventions
+-----------
- Settings for a single feature should be contained in a single file.
@@ -555,25 +582,25 @@ may be specified in any order and not all pairs have to be specified.
with "default" as the value must not appear when read.
For example, a setting which is keyed by major:minor device numbers
- with integer values may look like the following.
+ with integer values may look like the following::
# cat cgroup-example-interface-file
default 150
8:0 300
- The default value can be updated by
+ The default value can be updated by::
# echo 125 > cgroup-example-interface-file
- or
+ or::
# echo "default 125" > cgroup-example-interface-file
- An override can be set by
+ An override can be set by::
# echo "8:16 170" > cgroup-example-interface-file
- and cleared by
+ and cleared by::
# echo "8:0 default" > cgroup-example-interface-file
# cat cgroup-example-interface-file
@@ -586,12 +613,12 @@ may be specified in any order and not all pairs have to be specified.
generated on the file.
-4-3. Core Interface Files
+Core Interface Files
+--------------------
All cgroup core files are prefixed with "cgroup."
cgroup.procs
-
A read-write new-line separated values file which exists on
all cgroups.
@@ -617,7 +644,6 @@ All cgroup core files are prefixed with "cgroup."
should be granted along with the containing directory.
cgroup.controllers
-
A read-only space separated values file which exists on all
cgroups.
@@ -625,7 +651,6 @@ All cgroup core files are prefixed with "cgroup."
the cgroup. The controllers are not ordered.
cgroup.subtree_control
-
A read-write space separated values file which exists on all
cgroups. Starts out empty.
@@ -641,23 +666,25 @@ All cgroup core files are prefixed with "cgroup."
operations are specified, either all succeed or all fail.
cgroup.events
-
A read-only flat-keyed file which exists on non-root cgroups.
The following entries are defined. Unless specified
otherwise, a value change in this file generates a file
modified event.
populated
-
1 if the cgroup or its descendants contains any live
processes; otherwise, 0.
-5. Controllers
+Controllers
+===========
-5-1. CPU
+CPU
+---
-[NOTE: The interface for the cpu controller hasn't been merged yet]
+.. note::
+
+ The interface for the cpu controller hasn't been merged yet
The "cpu" controllers regulates distribution of CPU cycles. This
controller implements weight and absolute bandwidth limit models for
@@ -665,36 +692,34 @@ normal scheduling policy and absolute bandwidth allocation model for
realtime scheduling policy.
-5-1-1. CPU Interface Files
+CPU Interface Files
+~~~~~~~~~~~~~~~~~~~
All time durations are in microseconds.
cpu.stat
-
A read-only flat-keyed file which exists on non-root cgroups.
- It reports the following six stats.
+ It reports the following six stats:
- usage_usec
- user_usec
- system_usec
- nr_periods
- nr_throttled
- throttled_usec
+ - usage_usec
+ - user_usec
+ - system_usec
+ - nr_periods
+ - nr_throttled
+ - throttled_usec
cpu.weight
-
A read-write single value file which exists on non-root
cgroups. The default is "100".
The weight in the range [1, 10000].
cpu.max
-
A read-write two value file which exists on non-root cgroups.
The default is "max 100000".
- The maximum bandwidth limit. It's in the following format.
+ The maximum bandwidth limit. It's in the following format::
$MAX $PERIOD
@@ -703,9 +728,10 @@ All time durations are in microseconds.
one number is written, $MAX is updated.
cpu.rt.max
+ .. note::
- [NOTE: The semantics of this file is still under discussion and the
- interface hasn't been merged yet]
+ The semantics of this file is still under discussion and the
+ interface hasn't been merged yet
A read-write two value file which exists on all cgroups.
The default is "0 100000".
@@ -713,7 +739,7 @@ All time durations are in microseconds.
The maximum realtime runtime allocation. Over-committing
configurations are disallowed and process migrations are
rejected if not enough bandwidth is available. It's in the
- following format.
+ following format::
$MAX $PERIOD
@@ -722,7 +748,8 @@ All time durations are in microseconds.
updated.
-5-2. Memory
+Memory
+------
The "memory" controller regulates distribution of memory. Memory is
stateful and implements both limit and protection models. Due to the
@@ -744,14 +771,14 @@ following types of memory usages are tracked.
The above list may expand in the future for better coverage.
-5-2-1. Memory Interface Files
+Memory Interface Files
+~~~~~~~~~~~~~~~~~~~~~~
All memory amounts are in bytes. If a value which is not aligned to
PAGE_SIZE is written, the value may be rounded up to the closest
PAGE_SIZE multiple when read back.
memory.current
-
A read-only single value file which exists on non-root
cgroups.
@@ -759,7 +786,6 @@ PAGE_SIZE multiple when read back.
and its descendants.
memory.low
-
A read-write single value file which exists on non-root
cgroups. The default is "0".
@@ -772,7 +798,6 @@ PAGE_SIZE multiple when read back.
protection is discouraged.
memory.high
-
A read-write single value file which exists on non-root
cgroups. The default is "max".
@@ -785,7 +810,6 @@ PAGE_SIZE multiple when read back.
under extreme conditions the limit may be breached.
memory.max
-
A read-write single value file which exists on non-root
cgroups. The default is "max".
@@ -800,21 +824,18 @@ PAGE_SIZE multiple when read back.
utility is limited to providing the final safety net.
memory.events
-
A read-only flat-keyed file which exists on non-root cgroups.
The following entries are defined. Unless specified
otherwise, a value change in this file generates a file
modified event.
low
-
The number of times the cgroup is reclaimed due to
high memory pressure even though its usage is under
the low boundary. This usually indicates that the low
boundary is over-committed.
high
-
The number of times processes of the cgroup are
throttled and routed to perform direct memory reclaim
because the high memory boundary was exceeded. For a
@@ -823,13 +844,11 @@ PAGE_SIZE multiple when read back.
occurrences are expected.
max
-
The number of times the cgroup's memory usage was
about to go over the max boundary. If direct reclaim
fails to bring it down, the cgroup goes to OOM state.
oom
-
The number of time the cgroup's memory usage was
reached the limit and allocation was about to fail.
@@ -838,16 +857,14 @@ PAGE_SIZE multiple when read back.
Failed allocation in its turn could be returned into
userspace as -ENOMEM or siletly ignored in cases like
- disk readahead. For now OOM in memory cgroup kills
+ disk readahead. For now OOM in memory cgroup kills
tasks iff shortage has happened inside page fault.
oom_kill
-
The number of processes belonging to this cgroup
killed by any kind of OOM killer.
memory.stat
-
A read-only flat-keyed file which exists on non-root cgroups.
This breaks down the cgroup's memory footprint into different
@@ -861,73 +878,55 @@ PAGE_SIZE multiple when read back.
fixed position; use the keys to look up specific values!
anon
-
Amount of memory used in anonymous mappings such as
brk(), sbrk(), and mmap(MAP_ANONYMOUS)
file
-
Amount of memory used to cache filesystem data,
including tmpfs and shared memory.
kernel_stack
-
Amount of memory allocated to kernel stacks.
slab
-
Amount of memory used for storing in-kernel data
structures.
sock
-
Amount of memory used in network transmission buffers
shmem
-
Amount of cached filesystem data that is swap-backed,
such as tmpfs, shm segments, shared anonymous mmap()s
file_mapped
-
Amount of cached filesystem data mapped with mmap()
file_dirty
-
Amount of cached filesystem data that was modified but
not yet written back to disk
file_writeback
-
Amount of cached filesystem data that was modified and
is currently being written back to disk
- inactive_anon
- active_anon
- inactive_file
- active_file
- unevictable
-
+ inactive_anon, active_anon, inactive_file, active_file, unevictable
Amount of memory, swap-backed and filesystem-backed,
on the internal memory management lists used by the
page reclaim algorithm
slab_reclaimable
-
Part of "slab" that might be reclaimed, such as
dentries and inodes.
slab_unreclaimable
-
Part of "slab" that cannot be reclaimed on memory
pressure.
pgfault
-
Total number of page faults incurred
pgmajfault
-
Number of major page faults incurred
workingset_refault
@@ -971,7 +970,6 @@ PAGE_SIZE multiple when read back.
Amount of reclaimed lazyfree pages
memory.swap.current
-
A read-only single value file which exists on non-root
cgroups.
@@ -979,7 +977,6 @@ PAGE_SIZE multiple when read back.
and its descendants.
memory.swap.max
-
A read-write single value file which exists on non-root
cgroups. The default is "max".
@@ -987,7 +984,8 @@ PAGE_SIZE multiple when read back.
limit, anonymous meomry of the cgroup will not be swapped out.
-5-2-2. Usage Guidelines
+Usage Guidelines
+~~~~~~~~~~~~~~~~
"memory.high" is the main mechanism to control memory usage.
Over-committing on high limit (sum of high limits > available memory)
@@ -1010,7 +1008,8 @@ memory; unfortunately, memory pressure monitoring mechanism isn't
implemented yet.
-5-2-3. Memory Ownership
+Memory Ownership
+~~~~~~~~~~~~~~~~
A memory area is charged to the cgroup which instantiated it and stays
charged to the cgroup until the area is released. Migrating a process
@@ -1028,7 +1027,8 @@ POSIX_FADV_DONTNEED to relinquish the ownership of memory areas
belonging to the affected files to ensure correct memory ownership.
-5-3. IO
+IO
+--
The "io" controller regulates the distribution of IO resources. This
controller implements both weight based and absolute bandwidth or IOPS
@@ -1037,28 +1037,29 @@ only if cfq-iosched is in use and neither scheme is available for
blk-mq devices.
-5-3-1. IO Interface Files
+IO Interface Files
+~~~~~~~~~~~~~~~~~~
io.stat
-
A read-only nested-keyed file which exists on non-root
cgroups.
Lines are keyed by $MAJ:$MIN device numbers and not ordered.
The following nested keys are defined.
+ ====== ===================
rbytes Bytes read
wbytes Bytes written
rios Number of read IOs
wios Number of write IOs
+ ====== ===================
- An example read output follows.
+ An example read output follows:
8:16 rbytes=1459200 wbytes=314773504 rios=192 wios=353
8:0 rbytes=90430464 wbytes=299008000 rios=8950 wios=1252
io.weight
-
A read-write flat-keyed file which exists on non-root cgroups.
The default is "default 100".
@@ -1072,14 +1073,13 @@ blk-mq devices.
$WEIGHT" or simply "$WEIGHT". Overrides can be set by writing
"$MAJ:$MIN $WEIGHT" and unset by writing "$MAJ:$MIN default".
- An example read output follows.
+ An example read output follows::
default 100
8:16 200
8:0 50
io.max
-
A read-write nested-keyed file which exists on non-root
cgroups.
@@ -1087,10 +1087,12 @@ blk-mq devices.
device numbers and not ordered. The following nested keys are
defined.
+ ===== ==================================
rbps Max read bytes per second
wbps Max write bytes per second
riops Max read IO operations per second
wiops Max write IO operations per second
+ ===== ==================================
When writing, any number of nested key-value pairs can be
specified in any order. "max" can be specified as the value
@@ -1100,24 +1102,25 @@ blk-mq devices.
BPS and IOPS are measured in each IO direction and IOs are
delayed if limit is reached. Temporary bursts are allowed.
- Setting read limit at 2M BPS and write at 120 IOPS for 8:16.
+ Setting read limit at 2M BPS and write at 120 IOPS for 8:16::
echo "8:16 rbps=2097152 wiops=120" > io.max
- Reading returns the following.
+ Reading returns the following::
8:16 rbps=2097152 wbps=max riops=max wiops=120
- Write IOPS limit can be removed by writing the following.
+ Write IOPS limit can be removed by writing the following::
echo "8:16 wiops=max" > io.max
- Reading now returns the following.
+ Reading now returns the following::
8:16 rbps=2097152 wbps=max riops=max wiops=max
-5-3-2. Writeback
+Writeback
+~~~~~~~~~
Page cache is dirtied through buffered writes and shared mmaps and
written asynchronously to the backing filesystem by the writeback
@@ -1165,22 +1168,19 @@ patterns.
The sysctl knobs which affect writeback behavior are applied to cgroup
writeback as follows.
- vm.dirty_background_ratio
- vm.dirty_ratio
-
+ vm.dirty_background_ratio, vm.dirty_ratio
These ratios apply the same to cgroup writeback with the
amount of available memory capped by limits imposed by the
memory controller and system-wide clean memory.
- vm.dirty_background_bytes
- vm.dirty_bytes
-
+ vm.dirty_background_bytes, vm.dirty_bytes
For cgroup writeback, this is calculated into ratio against
total available memory and applied the same way as
vm.dirty[_background]_ratio.
-5-4. PID
+PID
+---
The process number controller is used to allow a cgroup to stop any
new tasks from being fork()'d or clone()'d after a specified limit is
@@ -1195,17 +1195,16 @@ Note that PIDs used in this controller refer to TIDs, process IDs as
used by the kernel.
-5-4-1. PID Interface Files
+PID Interface Files
+~~~~~~~~~~~~~~~~~~~
pids.max
-
A read-write single value file which exists on non-root
cgroups. The default is "max".
Hard limit of number of processes.
pids.current
-
A read-only single value file which exists on all cgroups.
The number of processes currently in the cgroup and its
@@ -1220,12 +1219,14 @@ through fork() or clone(). These will return -EAGAIN if the creation
of a new process would cause a cgroup policy to be violated.
-5-5. RDMA
+RDMA
+----
The "rdma" controller regulates the distribution and accounting of
of RDMA resources.
-5-5-1. RDMA Interface Files
+RDMA Interface Files
+~~~~~~~~~~~~~~~~~~~~
rdma.max
A readwrite nested-keyed file that exists for all the cgroups
@@ -1238,10 +1239,12 @@ of RDMA resources.
The following nested keys are defined.
+ ========== =============================
hca_handle Maximum number of HCA Handles
hca_object Maximum number of HCA Objects
+ ========== =============================
- An example for mlx4 and ocrdma device follows.
+ An example for mlx4 and ocrdma device follows::
mlx4_0 hca_handle=2 hca_object=2000
ocrdma1 hca_handle=3 hca_object=max
@@ -1250,15 +1253,17 @@ of RDMA resources.
A read-only file that describes current resource usage.
It exists for all the cgroup except root.
- An example for mlx4 and ocrdma device follows.
+ An example for mlx4 and ocrdma device follows::
mlx4_0 hca_handle=1 hca_object=20
ocrdma1 hca_handle=1 hca_object=23
-5-6. Misc
+Misc
+----
-5-6-1. perf_event
+perf_event
+~~~~~~~~~~
perf_event controller, if not mounted on a legacy hierarchy, is
automatically enabled on the v2 hierarchy so that perf events can
@@ -1266,9 +1271,11 @@ always be filtered by cgroup v2 path. The controller can still be
moved to a legacy hierarchy after v2 hierarchy is populated.
-6. Namespace
+Namespace
+=========
-6-1. Basics
+Basics
+------
cgroup namespace provides a mechanism to virtualize the view of the
"/proc/$PID/cgroup" file and cgroup mounts. The CLONE_NEWCGROUP clone
@@ -1282,7 +1289,7 @@ Without cgroup namespace, the "/proc/$PID/cgroup" file shows the
complete path of the cgroup of a process. In a container setup where
a set of cgroups and namespaces are intended to isolate processes the
"/proc/$PID/cgroup" file may leak potential system level information
-to the isolated processes. For Example:
+to the isolated processes. For Example::
# cat /proc/self/cgroup
0::/batchjobs/container_id1
@@ -1290,14 +1297,14 @@ to the isolated processes. For Example:
The path '/batchjobs/container_id1' can be considered as system-data
and undesirable to expose to the isolated processes. cgroup namespace
can be used to restrict visibility of this path. For example, before
-creating a cgroup namespace, one would see:
+creating a cgroup namespace, one would see::
# ls -l /proc/self/ns/cgroup
lrwxrwxrwx 1 root root 0 2014-07-15 10:37 /proc/self/ns/cgroup -> cgroup:[4026531835]
# cat /proc/self/cgroup
0::/batchjobs/container_id1
-After unsharing a new namespace, the view changes.
+After unsharing a new namespace, the view changes::
# ls -l /proc/self/ns/cgroup
lrwxrwxrwx 1 root root 0 2014-07-15 10:35 /proc/self/ns/cgroup -> cgroup:[4026532183]
@@ -1315,7 +1322,8 @@ namespace is destroyed. The cgroupns root and the actual cgroups
remain.
-6-2. The Root and Views
+The Root and Views
+------------------
The 'cgroupns root' for a cgroup namespace is the cgroup in which the
process calling unshare(2) is running. For example, if a process in
@@ -1324,7 +1332,7 @@ process calling unshare(2) is running. For example, if a process in
init_cgroup_ns, this is the real root ('/') cgroup.
The cgroupns root cgroup does not change even if the namespace creator
-process later moves to a different cgroup.
+process later moves to a different cgroup::
# ~/unshare -c # unshare cgroupns in some cgroup
# cat /proc/self/cgroup
@@ -1338,7 +1346,7 @@ Each process gets its namespace-specific view of "/proc/$PID/cgroup"
Processes running inside the cgroup namespace will be able to see
cgroup paths (in /proc/self/cgroup) only inside their root cgroup.
-From within an unshared cgroupns:
+From within an unshared cgroupns::
# sleep 100000 &
[1] 7353
@@ -1347,7 +1355,7 @@ From within an unshared cgroupns:
0::/sub_cgrp_1
From the initial cgroup namespace, the real cgroup path will be
-visible:
+visible::
$ cat /proc/7353/cgroup
0::/batchjobs/container_id1/sub_cgrp_1
@@ -1355,7 +1363,7 @@ visible:
From a sibling cgroup namespace (that is, a namespace rooted at a
different cgroup), the cgroup path relative to its own cgroup
namespace root will be shown. For instance, if PID 7353's cgroup
-namespace root is at '/batchjobs/container_id2', then it will see
+namespace root is at '/batchjobs/container_id2', then it will see::
# cat /proc/7353/cgroup
0::/../container_id2/sub_cgrp_1
@@ -1364,13 +1372,14 @@ Note that the relative path always starts with '/' to indicate that
its relative to the cgroup namespace root of the caller.
-6-3. Migration and setns(2)
+Migration and setns(2)
+----------------------
Processes inside a cgroup namespace can move into and out of the
namespace root if they have proper access to external cgroups. For
example, from inside a namespace with cgroupns root at
/batchjobs/container_id1, and assuming that the global hierarchy is
-still accessible inside cgroupns:
+still accessible inside cgroupns::
# cat /proc/7353/cgroup
0::/sub_cgrp_1
@@ -1392,10 +1401,11 @@ namespace. It is expected that the someone moves the attaching
process under the target cgroup namespace root.
-6-4. Interaction with Other Namespaces
+Interaction with Other Namespaces
+---------------------------------
Namespace specific cgroup hierarchy can be mounted by a process
-running inside a non-init cgroup namespace.
+running inside a non-init cgroup namespace::
# mount -t cgroup2 none $MOUNT_POINT
@@ -1408,27 +1418,27 @@ the view of cgroup hierarchy by namespace-private cgroupfs mount
provides a properly isolated cgroup view inside the container.
-P. Information on Kernel Programming
+Information on Kernel Programming
+=================================
This section contains kernel programming information in the areas
where interacting with cgroup is necessary. cgroup core and
controllers are not covered.
-P-1. Filesystem Support for Writeback
+Filesystem Support for Writeback
+--------------------------------
A filesystem can support cgroup writeback by updating
address_space_operations->writepage[s]() to annotate bio's using the
following two functions.
wbc_init_bio(@wbc, @bio)
-
Should be called for each bio carrying writeback data and
associates the bio with the inode's owner cgroup. Can be
called anytime between bio allocation and submission.
wbc_account_io(@wbc, @page, @bytes)
-
Should be called for each data segment being written out.
While this function doesn't care exactly when it's called
during the writeback session, it's the easiest and most
@@ -1449,7 +1459,8 @@ cases by skipping wbc_init_bio() or using bio_associate_blkcg()
directly.
-D. Deprecated v1 Core Features
+Deprecated v1 Core Features
+===========================
- Multiple hierarchies including named ones are not supported.
@@ -1463,9 +1474,11 @@ D. Deprecated v1 Core Features
at the root instead.
-R. Issues with v1 and Rationales for v2
+Issues with v1 and Rationales for v2
+====================================
-R-1. Multiple Hierarchies
+Multiple Hierarchies
+--------------------
cgroup v1 allowed an arbitrary number of hierarchies and each
hierarchy could host any number of controllers. While this seemed to
@@ -1517,7 +1530,8 @@ how memory is distributed beyond a certain level while still wanting
to control how CPU cycles are distributed.
-R-2. Thread Granularity
+Thread Granularity
+------------------
cgroup v1 allowed threads of a process to belong to different cgroups.
This didn't make sense for some controllers and those controllers
@@ -1560,7 +1574,8 @@ misbehaving and poorly abstracted interfaces and kernel exposing and
locked into constructs inadvertently.
-R-3. Competition Between Inner Nodes and Threads
+Competition Between Inner Nodes and Threads
+-------------------------------------------
cgroup v1 allowed threads to be in any cgroups which created an
interesting problem where threads belonging to a parent cgroup and its
@@ -1579,7 +1594,7 @@ simply weren't available for threads.
The io controller implicitly created a hidden leaf node for each
cgroup to host the threads. The hidden leaf had its own copies of all
-the knobs with "leaf_" prefixed. While this allowed equivalent
+the knobs with ``leaf_`` prefixed. While this allowed equivalent
control over internal threads, it was with serious drawbacks. It
always added an extra layer of nesting which wouldn't be necessary
otherwise, made the interface messy and significantly complicated the
@@ -1600,7 +1615,8 @@ This clearly is a problem which needs to be addressed from cgroup core
in a uniform way.
-R-4. Other Interface Issues
+Other Interface Issues
+----------------------
cgroup v1 grew without oversight and developed a large number of
idiosyncrasies and inconsistencies. One issue on the cgroup core side
@@ -1628,9 +1644,11 @@ cgroup v2 establishes common conventions where appropriate and updates
controllers so that they expose minimal and consistent interfaces.
-R-5. Controller Issues and Remedies
+Controller Issues and Remedies
+------------------------------
-R-5-1. Memory
+Memory
+~~~~~~
The original lower boundary, the soft limit, is defined as a limit
that is per default unset. As a result, the set of cgroups that
^ permalink raw reply related [flat|nested] 37+ messages in thread* Re: [PATCH 06/31] cgroup-v2.txt: standardize document format
2017-06-17 15:18 ` Mauro Carvalho Chehab
@ 2017-06-18 10:46 ` Tejun Heo
0 siblings, 0 replies; 37+ messages in thread
From: Tejun Heo @ 2017-06-18 10:46 UTC (permalink / raw)
To: Andrew Morton
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, David Woodhouse, Brian Norris, Boris Brezillon,
Marek Vasut, Richard Weinberger, Cyrille Pitchen, linux-mtd,
Li Zefan, Johannes Weiner, cgroups, Mauro Carvalho Chehab
Hello, Andrew.
Can you please apply Mauro's doc format update patch for
cgroup-v2.txt? The mm part causes conflicts, so I think it'd be
easier to route it through -mm.
The patch to apply is in the following message.
https://marc.info/?l=linux-cgroups&m=149771274105674&q=raw
Thanks.
--
tejun
^ permalink raw reply [flat|nested] 37+ messages in thread
* [PATCH 07/31] circular-buffers.txt: standardize document format
2017-05-19 1:22 [PATCH 00/31] Standardize doc formats - part 1 Mauro Carvalho Chehab
` (5 preceding siblings ...)
2017-05-19 1:22 ` [PATCH 06/31] cgroup-v2.txt: " Mauro Carvalho Chehab
@ 2017-05-19 1:22 ` Mauro Carvalho Chehab
2017-05-19 1:22 ` [PATCH 08/31] clk.txt: " Mauro Carvalho Chehab
` (23 subsequent siblings)
30 siblings, 0 replies; 37+ messages in thread
From: Mauro Carvalho Chehab @ 2017-05-19 1:22 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, David Woodhouse, Brian Norris, Boris Brezillon,
Marek Vasut, Richard Weinberger, Cyrille Pitchen, linux-mtd
Each text file under Documentation follows a different
format. Some doesn't even have titles!
Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- Mark titles with ReST notation;
- comment the contents table;
- Use :Author: tag for authorship;
- mark literal blocks as such;
- use valid numbered list markups;
- Don't capitalize titles.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/circular-buffers.txt | 51 +++++++++++++++++---------------------
1 file changed, 23 insertions(+), 28 deletions(-)
diff --git a/Documentation/circular-buffers.txt b/Documentation/circular-buffers.txt
index 4a824d232472..d4628174b7c5 100644
--- a/Documentation/circular-buffers.txt
+++ b/Documentation/circular-buffers.txt
@@ -1,9 +1,9 @@
- ================
- CIRCULAR BUFFERS
- ================
+================
+Circular Buffers
+================
-By: David Howells <dhowells@redhat.com>
- Paul E. McKenney <paulmck@linux.vnet.ibm.com>
+:Author: David Howells <dhowells@redhat.com>
+:Author: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
Linux provides a number of features that can be used to implement circular
@@ -20,7 +20,7 @@ producer and just one consumer. It is possible to handle multiple producers by
serialising them, and to handle multiple consumers by serialising them.
-Contents:
+.. Contents:
(*) What is a circular buffer?
@@ -31,8 +31,8 @@ Contents:
- The consumer.
-==========================
-WHAT IS A CIRCULAR BUFFER?
+
+What is a circular buffer?
==========================
First of all, what is a circular buffer? A circular buffer is a buffer of
@@ -60,9 +60,7 @@ buffer, provided that neither index overtakes the other. The implementer must
be careful, however, as a region more than one unit in size may wrap the end of
the buffer and be broken into two segments.
-
-============================
-MEASURING POWER-OF-2 BUFFERS
+Measuring power-of-2 buffers
============================
Calculation of the occupancy or the remaining capacity of an arbitrarily sized
@@ -71,13 +69,13 @@ modulus (divide) instruction. However, if the buffer is of a power-of-2 size,
then a much quicker bitwise-AND instruction can be used instead.
Linux provides a set of macros for handling power-of-2 circular buffers. These
-can be made use of by:
+can be made use of by::
#include <linux/circ_buf.h>
The macros are:
- (*) Measure the remaining capacity of a buffer:
+ (#) Measure the remaining capacity of a buffer::
CIRC_SPACE(head_index, tail_index, buffer_size);
@@ -85,7 +83,7 @@ The macros are:
can be inserted.
- (*) Measure the maximum consecutive immediate space in a buffer:
+ (#) Measure the maximum consecutive immediate space in a buffer::
CIRC_SPACE_TO_END(head_index, tail_index, buffer_size);
@@ -94,14 +92,14 @@ The macros are:
beginning of the buffer.
- (*) Measure the occupancy of a buffer:
+ (#) Measure the occupancy of a buffer::
CIRC_CNT(head_index, tail_index, buffer_size);
This returns the number of items currently occupying a buffer[2].
- (*) Measure the non-wrapping occupancy of a buffer:
+ (#) Measure the non-wrapping occupancy of a buffer::
CIRC_CNT_TO_END(head_index, tail_index, buffer_size);
@@ -112,7 +110,7 @@ The macros are:
Each of these macros will nominally return a value between 0 and buffer_size-1,
however:
- [1] CIRC_SPACE*() are intended to be used in the producer. To the producer
+ (1) CIRC_SPACE*() are intended to be used in the producer. To the producer
they will return a lower bound as the producer controls the head index,
but the consumer may still be depleting the buffer on another CPU and
moving the tail index.
@@ -120,7 +118,7 @@ however:
To the consumer it will show an upper bound as the producer may be busy
depleting the space.
- [2] CIRC_CNT*() are intended to be used in the consumer. To the consumer they
+ (2) CIRC_CNT*() are intended to be used in the consumer. To the consumer they
will return a lower bound as the consumer controls the tail index, but the
producer may still be filling the buffer on another CPU and moving the
head index.
@@ -128,14 +126,12 @@ however:
To the producer it will show an upper bound as the consumer may be busy
emptying the buffer.
- [3] To a third party, the order in which the writes to the indices by the
+ (3) To a third party, the order in which the writes to the indices by the
producer and consumer become visible cannot be guaranteed as they are
independent and may be made on different CPUs - so the result in such a
situation will merely be a guess, and may even be negative.
-
-===========================================
-USING MEMORY BARRIERS WITH CIRCULAR BUFFERS
+Using memory barriers with circular buffers
===========================================
By using memory barriers in conjunction with circular buffers, you can avoid
@@ -152,10 +148,10 @@ time, and only one thing should be emptying a buffer at any one time, but the
two sides can operate simultaneously.
-THE PRODUCER
+The producer
------------
-The producer will look something like this:
+The producer will look something like this::
spin_lock(&producer_lock);
@@ -193,10 +189,10 @@ ordering between the read of the index indicating that the consumer has
vacated a given element and the write by the producer to that same element.
-THE CONSUMER
+The Consumer
------------
-The consumer will look something like this:
+The consumer will look something like this::
spin_lock(&consumer_lock);
@@ -235,8 +231,7 @@ prevents the compiler from tearing the store, and enforces ordering
against previous accesses.
-===============
-FURTHER READING
+Further reading
===============
See also Documentation/memory-barriers.txt for a description of Linux's memory
--
2.9.4
^ permalink raw reply related [flat|nested] 37+ messages in thread* [PATCH 08/31] clk.txt: standardize document format
2017-05-19 1:22 [PATCH 00/31] Standardize doc formats - part 1 Mauro Carvalho Chehab
` (6 preceding siblings ...)
2017-05-19 1:22 ` [PATCH 07/31] circular-buffers.txt: " Mauro Carvalho Chehab
@ 2017-05-19 1:22 ` Mauro Carvalho Chehab
2017-05-19 1:22 ` [PATCH 09/31] cpu-load: " Mauro Carvalho Chehab
` (22 subsequent siblings)
30 siblings, 0 replies; 37+ messages in thread
From: Mauro Carvalho Chehab @ 2017-05-19 1:22 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, David Woodhouse, Brian Norris, Boris Brezillon,
Marek Vasut, Richard Weinberger, Cyrille Pitchen, linux-mtd
Each text file under Documentation follows a different
format. Some doesn't even have titles!
Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- Use section/title markups;
- Use :Author: for authorship;
- Mark literals and literal blocks;
- Mark tables;
- Use ReST notation for footnotes.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/clk.txt | 189 ++++++++++++++++++++++++++++----------------------
1 file changed, 106 insertions(+), 83 deletions(-)
diff --git a/Documentation/clk.txt b/Documentation/clk.txt
index 22f026aa2f34..be909ed45970 100644
--- a/Documentation/clk.txt
+++ b/Documentation/clk.txt
@@ -1,12 +1,16 @@
- The Common Clk Framework
- Mike Turquette <mturquette@ti.com>
+========================
+The Common Clk Framework
+========================
+
+:Author: Mike Turquette <mturquette@ti.com>
This document endeavours to explain the common clk framework details,
and how to port a platform over to this framework. It is not yet a
detailed explanation of the clock api in include/linux/clk.h, but
perhaps someday it will include that information.
- Part 1 - introduction and interface split
+Introduction and interface split
+================================
The common clk framework is an interface to control the clock nodes
available on various devices today. This may come in the form of clock
@@ -35,10 +39,11 @@ is defined in struct clk_foo and pointed to within struct clk_core. This
allows for easy navigation between the two discrete halves of the common
clock interface.
- Part 2 - common data structures and api
+Common data structures and api
+==============================
Below is the common struct clk_core definition from
-drivers/clk/clk.c, modified for brevity:
+drivers/clk/clk.c, modified for brevity::
struct clk_core {
const char *name;
@@ -59,7 +64,7 @@ struct clk. That api is documented in include/linux/clk.h.
Platforms and devices utilizing the common struct clk_core use the struct
clk_ops pointer in struct clk_core to perform the hardware-specific parts of
-the operations defined in clk-provider.h:
+the operations defined in clk-provider.h::
struct clk_ops {
int (*prepare)(struct clk_hw *hw);
@@ -95,19 +100,20 @@ the operations defined in clk-provider.h:
struct dentry *dentry);
};
- Part 3 - hardware clk implementations
+Hardware clk implementations
+============================
The strength of the common struct clk_core comes from its .ops and .hw pointers
which abstract the details of struct clk from the hardware-specific bits, and
vice versa. To illustrate consider the simple gateable clk implementation in
-drivers/clk/clk-gate.c:
+drivers/clk/clk-gate.c::
-struct clk_gate {
- struct clk_hw hw;
- void __iomem *reg;
- u8 bit_idx;
- ...
-};
+ struct clk_gate {
+ struct clk_hw hw;
+ void __iomem *reg;
+ u8 bit_idx;
+ ...
+ };
struct clk_gate contains struct clk_hw hw as well as hardware-specific
knowledge about which register and bit controls this clk's gating.
@@ -115,7 +121,7 @@ Nothing about clock topology or accounting, such as enable_count or
notifier_count, is needed here. That is all handled by the common
framework code and struct clk_core.
-Let's walk through enabling this clk from driver code:
+Let's walk through enabling this clk from driver code::
struct clk *clk;
clk = clk_get(NULL, "my_gateable_clk");
@@ -123,70 +129,71 @@ Let's walk through enabling this clk from driver code:
clk_prepare(clk);
clk_enable(clk);
-The call graph for clk_enable is very simple:
+The call graph for clk_enable is very simple::
-clk_enable(clk);
- clk->ops->enable(clk->hw);
- [resolves to...]
- clk_gate_enable(hw);
- [resolves struct clk gate with to_clk_gate(hw)]
- clk_gate_set_bit(gate);
+ clk_enable(clk);
+ clk->ops->enable(clk->hw);
+ [resolves to...]
+ clk_gate_enable(hw);
+ [resolves struct clk gate with to_clk_gate(hw)]
+ clk_gate_set_bit(gate);
-And the definition of clk_gate_set_bit:
+And the definition of clk_gate_set_bit::
-static void clk_gate_set_bit(struct clk_gate *gate)
-{
- u32 reg;
+ static void clk_gate_set_bit(struct clk_gate *gate)
+ {
+ u32 reg;
- reg = __raw_readl(gate->reg);
- reg |= BIT(gate->bit_idx);
- writel(reg, gate->reg);
-}
+ reg = __raw_readl(gate->reg);
+ reg |= BIT(gate->bit_idx);
+ writel(reg, gate->reg);
+ }
-Note that to_clk_gate is defined as:
+Note that to_clk_gate is defined as::
-#define to_clk_gate(_hw) container_of(_hw, struct clk_gate, hw)
+ #define to_clk_gate(_hw) container_of(_hw, struct clk_gate, hw)
This pattern of abstraction is used for every clock hardware
representation.
- Part 4 - supporting your own clk hardware
+Supporting your own clk hardware
+================================
When implementing support for a new type of clock it is only necessary to
-include the following header:
+include the following header::
-#include <linux/clk-provider.h>
+ #include <linux/clk-provider.h>
To construct a clk hardware structure for your platform you must define
-the following:
+the following::
-struct clk_foo {
- struct clk_hw hw;
- ... hardware specific data goes here ...
-};
+ struct clk_foo {
+ struct clk_hw hw;
+ ... hardware specific data goes here ...
+ };
To take advantage of your data you'll need to support valid operations
-for your clk:
+for your clk::
-struct clk_ops clk_foo_ops {
- .enable = &clk_foo_enable;
- .disable = &clk_foo_disable;
-};
+ struct clk_ops clk_foo_ops {
+ .enable = &clk_foo_enable;
+ .disable = &clk_foo_disable;
+ };
-Implement the above functions using container_of:
+Implement the above functions using container_of::
-#define to_clk_foo(_hw) container_of(_hw, struct clk_foo, hw)
+ #define to_clk_foo(_hw) container_of(_hw, struct clk_foo, hw)
-int clk_foo_enable(struct clk_hw *hw)
-{
- struct clk_foo *foo;
+ int clk_foo_enable(struct clk_hw *hw)
+ {
+ struct clk_foo *foo;
- foo = to_clk_foo(hw);
+ foo = to_clk_foo(hw);
- ... perform magic on foo ...
+ ... perform magic on foo ...
- return 0;
-};
+ return 0;
+ };
Below is a matrix detailing which clk_ops are mandatory based upon the
hardware capabilities of that clock. A cell marked as "y" means
@@ -194,41 +201,56 @@ mandatory, a cell marked as "n" implies that either including that
callback is invalid or otherwise unnecessary. Empty cells are either
optional or must be evaluated on a case-by-case basis.
- clock hardware characteristics
- -----------------------------------------------------------
- | gate | change rate | single parent | multiplexer | root |
- |------|-------------|---------------|-------------|------|
-.prepare | | | | | |
-.unprepare | | | | | |
- | | | | | |
-.enable | y | | | | |
-.disable | y | | | | |
-.is_enabled | y | | | | |
- | | | | | |
-.recalc_rate | | y | | | |
-.round_rate | | y [1] | | | |
-.determine_rate | | y [1] | | | |
-.set_rate | | y | | | |
- | | | | | |
-.set_parent | | | n | y | n |
-.get_parent | | | n | y | n |
- | | | | | |
-.recalc_accuracy| | | | | |
- | | | | | |
-.init | | | | | |
- -----------------------------------------------------------
-[1] either one of round_rate or determine_rate is required.
+.. table:: clock hardware characteristics
+
+ +----------------+------+-------------+---------------+-------------+------+
+ | | gate | change rate | single parent | multiplexer | root |
+ +================+======+=============+===============+=============+======+
+ |.prepare | | | | | |
+ +----------------+------+-------------+---------------+-------------+------+
+ |.unprepare | | | | | |
+ +----------------+------+-------------+---------------+-------------+------+
+ +----------------+------+-------------+---------------+-------------+------+
+ |.enable | y | | | | |
+ +----------------+------+-------------+---------------+-------------+------+
+ |.disable | y | | | | |
+ +----------------+------+-------------+---------------+-------------+------+
+ |.is_enabled | y | | | | |
+ +----------------+------+-------------+---------------+-------------+------+
+ +----------------+------+-------------+---------------+-------------+------+
+ |.recalc_rate | | y | | | |
+ +----------------+------+-------------+---------------+-------------+------+
+ |.round_rate | | y [1]_ | | | |
+ +----------------+------+-------------+---------------+-------------+------+
+ |.determine_rate | | y [1]_ | | | |
+ +----------------+------+-------------+---------------+-------------+------+
+ |.set_rate | | y | | | |
+ +----------------+------+-------------+---------------+-------------+------+
+ +----------------+------+-------------+---------------+-------------+------+
+ |.set_parent | | | n | y | n |
+ +----------------+------+-------------+---------------+-------------+------+
+ |.get_parent | | | n | y | n |
+ +----------------+------+-------------+---------------+-------------+------+
+ +----------------+------+-------------+---------------+-------------+------+
+ |.recalc_accuracy| | | | | |
+ +----------------+------+-------------+---------------+-------------+------+
+ +----------------+------+-------------+---------------+-------------+------+
+ |.init | | | | | |
+ +----------------+------+-------------+---------------+-------------+------+
+
+.. [1] either one of round_rate or determine_rate is required.
Finally, register your clock at run-time with a hardware-specific
registration function. This function simply populates struct clk_foo's
data and then passes the common struct clk parameters to the framework
-with a call to:
+with a call to::
-clk_register(...)
+ clk_register(...)
-See the basic clock types in drivers/clk/clk-*.c for examples.
+See the basic clock types in ``drivers/clk/clk-*.c`` for examples.
- Part 5 - Disabling clock gating of unused clocks
+Disabling clock gating of unused clocks
+=======================================
Sometimes during development it can be useful to be able to bypass the
default disabling of unused clocks. For example, if drivers aren't enabling
@@ -239,7 +261,8 @@ are sorted out.
To bypass this disabling, include "clk_ignore_unused" in the bootargs to the
kernel.
- Part 6 - Locking
+Locking
+=======
The common clock framework uses two global locks, the prepare lock and the
enable lock.
--
2.9.4
^ permalink raw reply related [flat|nested] 37+ messages in thread* [PATCH 09/31] cpu-load: standardize document format
2017-05-19 1:22 [PATCH 00/31] Standardize doc formats - part 1 Mauro Carvalho Chehab
` (7 preceding siblings ...)
2017-05-19 1:22 ` [PATCH 08/31] clk.txt: " Mauro Carvalho Chehab
@ 2017-05-19 1:22 ` Mauro Carvalho Chehab
2017-05-19 1:22 ` [PATCH 10/31] cputopology.txt: " Mauro Carvalho Chehab
` (21 subsequent siblings)
30 siblings, 0 replies; 37+ messages in thread
From: Mauro Carvalho Chehab @ 2017-05-19 1:22 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, David Woodhouse, Brian Norris, Boris Brezillon,
Marek Vasut, Richard Weinberger, Cyrille Pitchen, linux-mtd
Each text file under Documentation follows a different
format. Some doesn't even have titles!
Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- mark literals;
- Adjust document title;
- Use a list for references.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/cpu-load.txt | 117 +++++++++++++++++++++++----------------------
1 file changed, 59 insertions(+), 58 deletions(-)
diff --git a/Documentation/cpu-load.txt b/Documentation/cpu-load.txt
index 287224e57cfc..2d01ce43d2a2 100644
--- a/Documentation/cpu-load.txt
+++ b/Documentation/cpu-load.txt
@@ -1,9 +1,10 @@
+========
CPU load
---------
+========
-Linux exports various bits of information via `/proc/stat' and
-`/proc/uptime' that userland tools, such as top(1), use to calculate
-the average time system spent in a particular state, for example:
+Linux exports various bits of information via ``/proc/stat`` and
+``/proc/uptime`` that userland tools, such as top(1), use to calculate
+the average time system spent in a particular state, for example::
$ iostat
Linux 2.6.18.3-exp (linmac) 02/20/2007
@@ -17,7 +18,7 @@ Here the system thinks that over the default sampling period the
system spent 10.01% of the time doing work in user space, 2.92% in the
kernel, and was overall 81.63% of the time idle.
-In most cases the `/proc/stat' information reflects the reality quite
+In most cases the ``/proc/stat`` information reflects the reality quite
closely, however due to the nature of how/when the kernel collects
this data sometimes it can not be trusted at all.
@@ -33,78 +34,78 @@ Example
-------
If we imagine the system with one task that periodically burns cycles
-in the following manner:
+in the following manner::
- time line between two timer interrupts
-|--------------------------------------|
- ^ ^
- |_ something begins working |
- |_ something goes to sleep
- (only to be awaken quite soon)
+ time line between two timer interrupts
+ |--------------------------------------|
+ ^ ^
+ |_ something begins working |
+ |_ something goes to sleep
+ (only to be awaken quite soon)
In the above situation the system will be 0% loaded according to the
-`/proc/stat' (since the timer interrupt will always happen when the
+``/proc/stat`` (since the timer interrupt will always happen when the
system is executing the idle handler), but in reality the load is
closer to 99%.
One can imagine many more situations where this behavior of the kernel
-will lead to quite erratic information inside `/proc/stat'.
+will lead to quite erratic information inside ``/proc/stat``::
-/* gcc -o hog smallhog.c */
-#include <time.h>
-#include <limits.h>
-#include <signal.h>
-#include <sys/time.h>
-#define HIST 10
+ /* gcc -o hog smallhog.c */
+ #include <time.h>
+ #include <limits.h>
+ #include <signal.h>
+ #include <sys/time.h>
+ #define HIST 10
-static volatile sig_atomic_t stop;
+ static volatile sig_atomic_t stop;
-static void sighandler (int signr)
-{
- (void) signr;
- stop = 1;
-}
-static unsigned long hog (unsigned long niters)
-{
- stop = 0;
- while (!stop && --niters);
- return niters;
-}
-int main (void)
-{
- int i;
- struct itimerval it = { .it_interval = { .tv_sec = 0, .tv_usec = 1 },
- .it_value = { .tv_sec = 0, .tv_usec = 1 } };
- sigset_t set;
- unsigned long v[HIST];
- double tmp = 0.0;
- unsigned long n;
- signal (SIGALRM, &sighandler);
- setitimer (ITIMER_REAL, &it, NULL);
+ static void sighandler (int signr)
+ {
+ (void) signr;
+ stop = 1;
+ }
+ static unsigned long hog (unsigned long niters)
+ {
+ stop = 0;
+ while (!stop && --niters);
+ return niters;
+ }
+ int main (void)
+ {
+ int i;
+ struct itimerval it = { .it_interval = { .tv_sec = 0, .tv_usec = 1 },
+ .it_value = { .tv_sec = 0, .tv_usec = 1 } };
+ sigset_t set;
+ unsigned long v[HIST];
+ double tmp = 0.0;
+ unsigned long n;
+ signal (SIGALRM, &sighandler);
+ setitimer (ITIMER_REAL, &it, NULL);
- hog (ULONG_MAX);
- for (i = 0; i < HIST; ++i) v[i] = ULONG_MAX - hog (ULONG_MAX);
- for (i = 0; i < HIST; ++i) tmp += v[i];
- tmp /= HIST;
- n = tmp - (tmp / 3.0);
+ hog (ULONG_MAX);
+ for (i = 0; i < HIST; ++i) v[i] = ULONG_MAX - hog (ULONG_MAX);
+ for (i = 0; i < HIST; ++i) tmp += v[i];
+ tmp /= HIST;
+ n = tmp - (tmp / 3.0);
- sigemptyset (&set);
- sigaddset (&set, SIGALRM);
+ sigemptyset (&set);
+ sigaddset (&set, SIGALRM);
- for (;;) {
- hog (n);
- sigwait (&set, &i);
- }
- return 0;
-}
+ for (;;) {
+ hog (n);
+ sigwait (&set, &i);
+ }
+ return 0;
+ }
References
----------
-http://lkml.org/lkml/2007/2/12/6
-Documentation/filesystems/proc.txt (1.8)
+- http://lkml.org/lkml/2007/2/12/6
+- Documentation/filesystems/proc.txt (1.8)
Thanks
--
2.9.4
^ permalink raw reply related [flat|nested] 37+ messages in thread* [PATCH 10/31] cputopology.txt: standardize document format
2017-05-19 1:22 [PATCH 00/31] Standardize doc formats - part 1 Mauro Carvalho Chehab
` (8 preceding siblings ...)
2017-05-19 1:22 ` [PATCH 09/31] cpu-load: " Mauro Carvalho Chehab
@ 2017-05-19 1:22 ` Mauro Carvalho Chehab
2017-05-19 1:22 ` [PATCH 11/31] crc32.txt: " Mauro Carvalho Chehab
` (20 subsequent siblings)
30 siblings, 0 replies; 37+ messages in thread
From: Mauro Carvalho Chehab @ 2017-05-19 1:22 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, David Woodhouse, Brian Norris, Boris Brezillon,
Marek Vasut, Richard Weinberger, Cyrille Pitchen, linux-mtd
Each text file under Documentation follows a different
format. Some doesn't even have titles!
Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- Add a title for the document;
- mark literals;
- use table markup for existing table.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/cputopology.txt | 35 +++++++++++++++++++++--------------
1 file changed, 21 insertions(+), 14 deletions(-)
diff --git a/Documentation/cputopology.txt b/Documentation/cputopology.txt
index 127c9d8c2174..c6e7e9196a8b 100644
--- a/Documentation/cputopology.txt
+++ b/Documentation/cputopology.txt
@@ -1,3 +1,6 @@
+===========================================
+How CPU topology info is exported via sysfs
+===========================================
Export CPU topology info via sysfs. Items (attributes) are similar
to /proc/cpuinfo output of some architectures:
@@ -75,24 +78,26 @@ CONFIG_SCHED_BOOK and CONFIG_DRAWER are currently only used on s390, where
they reflect the cpu and cache hierarchy.
For an architecture to support this feature, it must define some of
-these macros in include/asm-XXX/topology.h:
-#define topology_physical_package_id(cpu)
-#define topology_core_id(cpu)
-#define topology_book_id(cpu)
-#define topology_drawer_id(cpu)
-#define topology_sibling_cpumask(cpu)
-#define topology_core_cpumask(cpu)
-#define topology_book_cpumask(cpu)
-#define topology_drawer_cpumask(cpu)
+these macros in include/asm-XXX/topology.h::
-The type of **_id macros is int.
-The type of **_cpumask macros is (const) struct cpumask *. The latter
-correspond with appropriate **_siblings sysfs attributes (except for
+ #define topology_physical_package_id(cpu)
+ #define topology_core_id(cpu)
+ #define topology_book_id(cpu)
+ #define topology_drawer_id(cpu)
+ #define topology_sibling_cpumask(cpu)
+ #define topology_core_cpumask(cpu)
+ #define topology_book_cpumask(cpu)
+ #define topology_drawer_cpumask(cpu)
+
+The type of ``**_id macros`` is int.
+The type of ``**_cpumask macros`` is ``(const) struct cpumask *``. The latter
+correspond with appropriate ``**_siblings`` sysfs attributes (except for
topology_sibling_cpumask() which corresponds with thread_siblings).
To be consistent on all architectures, include/linux/topology.h
provides default definitions for any of the above macros that are
not defined by include/asm-XXX/topology.h:
+
1) physical_package_id: -1
2) core_id: 0
3) sibling_cpumask: just the given CPU
@@ -107,6 +112,7 @@ Additionally, CPU topology information is provided under
/sys/devices/system/cpu and includes these files. The internal
source for the output is in brackets ("[]").
+ =========== ==========================================================
kernel_max: the maximum CPU index allowed by the kernel configuration.
[NR_CPUS-1]
@@ -122,6 +128,7 @@ source for the output is in brackets ("[]").
present: CPUs that have been identified as being present in the
system. [cpu_present_mask]
+ =========== ==========================================================
The format for the above output is compatible with cpulist_parse()
[see <linux/cpumask.h>]. Some examples follow.
@@ -129,7 +136,7 @@ The format for the above output is compatible with cpulist_parse()
In this example, there are 64 CPUs in the system but cpus 32-63 exceed
the kernel max which is limited to 0..31 by the NR_CPUS config option
being 32. Note also that CPUs 2 and 4-31 are not online but could be
-brought online as they are both present and possible.
+brought online as they are both present and possible::
kernel_max: 31
offline: 2,4-31,32-63
@@ -140,7 +147,7 @@ brought online as they are both present and possible.
In this example, the NR_CPUS config option is 128, but the kernel was
started with possible_cpus=144. There are 4 CPUs in the system and cpu2
was manually taken offline (and is the only CPU that can be brought
-online.)
+online.)::
kernel_max: 127
offline: 2,4-127,128-143
--
2.9.4
^ permalink raw reply related [flat|nested] 37+ messages in thread* [PATCH 11/31] crc32.txt: standardize document format
2017-05-19 1:22 [PATCH 00/31] Standardize doc formats - part 1 Mauro Carvalho Chehab
` (9 preceding siblings ...)
2017-05-19 1:22 ` [PATCH 10/31] cputopology.txt: " Mauro Carvalho Chehab
@ 2017-05-19 1:22 ` Mauro Carvalho Chehab
2017-05-19 1:22 ` [PATCH 12/31] dcdbas.txt: " Mauro Carvalho Chehab
` (19 subsequent siblings)
30 siblings, 0 replies; 37+ messages in thread
From: Mauro Carvalho Chehab @ 2017-05-19 1:22 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, David Woodhouse, Brian Norris, Boris Brezillon,
Marek Vasut, Richard Weinberger, Cyrille Pitchen, linux-mtd
Each text file under Documentation follows a different
format. Some doesn't even have titles!
Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- Add a title for the document;
- Mark literal blocks.
While here, replace a comma by a dot at the end of a paragraph.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/crc32.txt | 75 +++++++++++++++++++++++++++----------------------
1 file changed, 41 insertions(+), 34 deletions(-)
diff --git a/Documentation/crc32.txt b/Documentation/crc32.txt
index a08a7dd9d625..8a6860f33b4e 100644
--- a/Documentation/crc32.txt
+++ b/Documentation/crc32.txt
@@ -1,4 +1,6 @@
-A brief CRC tutorial.
+=================================
+brief tutorial on CRC computation
+=================================
A CRC is a long-division remainder. You add the CRC to the message,
and the whole thing (message+CRC) is a multiple of the given
@@ -8,7 +10,8 @@ remainder computed on the message+CRC is 0. This latter approach
is used by a lot of hardware implementations, and is why so many
protocols put the end-of-frame flag after the CRC.
-It's actually the same long division you learned in school, except that
+It's actually the same long division you learned in school, except that:
+
- We're working in binary, so the digits are only 0 and 1, and
- When dividing polynomials, there are no carries. Rather than add and
subtract, we just xor. Thus, we tend to get a bit sloppy about
@@ -40,11 +43,12 @@ throw the quotient bit away, but subtract the appropriate multiple of
the polynomial from the remainder and we're back to where we started,
ready to process the next bit.
-A big-endian CRC written this way would be coded like:
-for (i = 0; i < input_bits; i++) {
- multiple = remainder & 0x80000000 ? CRCPOLY : 0;
- remainder = (remainder << 1 | next_input_bit()) ^ multiple;
-}
+A big-endian CRC written this way would be coded like::
+
+ for (i = 0; i < input_bits; i++) {
+ multiple = remainder & 0x80000000 ? CRCPOLY : 0;
+ remainder = (remainder << 1 | next_input_bit()) ^ multiple;
+ }
Notice how, to get at bit 32 of the shifted remainder, we look
at bit 31 of the remainder *before* shifting it.
@@ -54,25 +58,26 @@ the remainder don't actually affect any decision-making until
32 bits later. Thus, the first 32 cycles of this are pretty boring.
Also, to add the CRC to a message, we need a 32-bit-long hole for it at
the end, so we have to add 32 extra cycles shifting in zeros at the
-end of every message,
+end of every message.
These details lead to a standard trick: rearrange merging in the
next_input_bit() until the moment it's needed. Then the first 32 cycles
can be precomputed, and merging in the final 32 zero bits to make room
-for the CRC can be skipped entirely. This changes the code to:
+for the CRC can be skipped entirely. This changes the code to::
-for (i = 0; i < input_bits; i++) {
- remainder ^= next_input_bit() << 31;
- multiple = (remainder & 0x80000000) ? CRCPOLY : 0;
- remainder = (remainder << 1) ^ multiple;
-}
+ for (i = 0; i < input_bits; i++) {
+ remainder ^= next_input_bit() << 31;
+ multiple = (remainder & 0x80000000) ? CRCPOLY : 0;
+ remainder = (remainder << 1) ^ multiple;
+ }
-With this optimization, the little-endian code is particularly simple:
-for (i = 0; i < input_bits; i++) {
- remainder ^= next_input_bit();
- multiple = (remainder & 1) ? CRCPOLY : 0;
- remainder = (remainder >> 1) ^ multiple;
-}
+With this optimization, the little-endian code is particularly simple::
+
+ for (i = 0; i < input_bits; i++) {
+ remainder ^= next_input_bit();
+ multiple = (remainder & 1) ? CRCPOLY : 0;
+ remainder = (remainder >> 1) ^ multiple;
+ }
The most significant coefficient of the remainder polynomial is stored
in the least significant bit of the binary "remainder" variable.
@@ -81,23 +86,25 @@ be bit-reversed) and next_input_bit().
As long as next_input_bit is returning the bits in a sensible order, we don't
*have* to wait until the last possible moment to merge in additional bits.
-We can do it 8 bits at a time rather than 1 bit at a time:
-for (i = 0; i < input_bytes; i++) {
- remainder ^= next_input_byte() << 24;
- for (j = 0; j < 8; j++) {
- multiple = (remainder & 0x80000000) ? CRCPOLY : 0;
- remainder = (remainder << 1) ^ multiple;
+We can do it 8 bits at a time rather than 1 bit at a time::
+
+ for (i = 0; i < input_bytes; i++) {
+ remainder ^= next_input_byte() << 24;
+ for (j = 0; j < 8; j++) {
+ multiple = (remainder & 0x80000000) ? CRCPOLY : 0;
+ remainder = (remainder << 1) ^ multiple;
+ }
}
-}
-Or in little-endian:
-for (i = 0; i < input_bytes; i++) {
- remainder ^= next_input_byte();
- for (j = 0; j < 8; j++) {
- multiple = (remainder & 1) ? CRCPOLY : 0;
- remainder = (remainder >> 1) ^ multiple;
+Or in little-endian::
+
+ for (i = 0; i < input_bytes; i++) {
+ remainder ^= next_input_byte();
+ for (j = 0; j < 8; j++) {
+ multiple = (remainder & 1) ? CRCPOLY : 0;
+ remainder = (remainder >> 1) ^ multiple;
+ }
}
-}
If the input is a multiple of 32 bits, you can even XOR in a 32-bit
word at a time and increase the inner loop count to 32.
--
2.9.4
^ permalink raw reply related [flat|nested] 37+ messages in thread* [PATCH 12/31] dcdbas.txt: standardize document format
2017-05-19 1:22 [PATCH 00/31] Standardize doc formats - part 1 Mauro Carvalho Chehab
` (10 preceding siblings ...)
2017-05-19 1:22 ` [PATCH 11/31] crc32.txt: " Mauro Carvalho Chehab
@ 2017-05-19 1:22 ` Mauro Carvalho Chehab
2017-05-19 1:22 ` [PATCH 13/31] digsig.txt: " Mauro Carvalho Chehab
` (18 subsequent siblings)
30 siblings, 0 replies; 37+ messages in thread
From: Mauro Carvalho Chehab @ 2017-05-19 1:22 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, David Woodhouse, Brian Norris, Boris Brezillon,
Marek Vasut, Richard Weinberger, Cyrille Pitchen, linux-mtd,
Doug Warzecha, Mauro Carvalho Chehab
From: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
Each text file under Documentation follows a different
format. Some doesn't even have titles!
Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- Mark titles;
- Mark literal blocks;
- Mark table.
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/dcdbas.txt | 24 ++++++++++++++++--------
1 file changed, 16 insertions(+), 8 deletions(-)
diff --git a/Documentation/dcdbas.txt b/Documentation/dcdbas.txt
index e1c52e2dc361..309cc57a7c1c 100644
--- a/Documentation/dcdbas.txt
+++ b/Documentation/dcdbas.txt
@@ -1,4 +1,9 @@
+===================================
+Dell Systems Management Base Driver
+===================================
+
Overview
+========
The Dell Systems Management Base Driver provides a sysfs interface for
systems management software such as Dell OpenManage to perform system
@@ -17,6 +22,7 @@ more information about the libsmbios project.
System Management Interrupt
+===========================
On some Dell systems, systems management software must access certain
management information via a system management interrupt (SMI). The SMI data
@@ -24,12 +30,12 @@ buffer must reside in 32-bit address space, and the physical address of the
buffer is required for the SMI. The driver maintains the memory required for
the SMI and provides a way for the application to generate the SMI.
The driver creates the following sysfs entries for systems management
-software to perform these system management interrupts:
+software to perform these system management interrupts::
-/sys/devices/platform/dcdbas/smi_data
-/sys/devices/platform/dcdbas/smi_data_buf_phys_addr
-/sys/devices/platform/dcdbas/smi_data_buf_size
-/sys/devices/platform/dcdbas/smi_request
+ /sys/devices/platform/dcdbas/smi_data
+ /sys/devices/platform/dcdbas/smi_data_buf_phys_addr
+ /sys/devices/platform/dcdbas/smi_data_buf_size
+ /sys/devices/platform/dcdbas/smi_request
Systems management software must perform the following steps to execute
a SMI using this driver:
@@ -43,6 +49,7 @@ a SMI using this driver:
Host Control Action
+===================
Dell OpenManage supports a host control feature that allows the administrator
to perform a power cycle or power off of the system after the OS has finished
@@ -69,12 +76,14 @@ power off host control action using this driver:
Host Control SMI Type
+=====================
The following table shows the value to write to host_control_smi_type to
perform a power cycle or power off host control action:
+=================== =====================
PowerEdge System Host Control SMI Type
----------------- ---------------------
+=================== =====================
300 HC_SMITYPE_TYPE1
1300 HC_SMITYPE_TYPE1
1400 HC_SMITYPE_TYPE2
@@ -87,5 +96,4 @@ PowerEdge System Host Control SMI Type
1655MC HC_SMITYPE_TYPE2
700 HC_SMITYPE_TYPE3
750 HC_SMITYPE_TYPE3
-
-
+=================== =====================
--
2.9.4
^ permalink raw reply related [flat|nested] 37+ messages in thread* [PATCH 13/31] digsig.txt: standardize document format
2017-05-19 1:22 [PATCH 00/31] Standardize doc formats - part 1 Mauro Carvalho Chehab
` (11 preceding siblings ...)
2017-05-19 1:22 ` [PATCH 12/31] dcdbas.txt: " Mauro Carvalho Chehab
@ 2017-05-19 1:22 ` Mauro Carvalho Chehab
2017-05-19 1:22 ` [PATCH 14/31] DMA-API.txt: " Mauro Carvalho Chehab
` (17 subsequent siblings)
30 siblings, 0 replies; 37+ messages in thread
From: Mauro Carvalho Chehab @ 2017-05-19 1:22 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, David Woodhouse, Brian Norris, Boris Brezillon,
Marek Vasut, Richard Weinberger, Cyrille Pitchen, linux-mtd
Each text file under Documentation follows a different
format. Some doesn't even have titles!
Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- comment the internal index;
- use the proper markups for titles;
- mark literal blocks.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/digsig.txt | 124 ++++++++++++++++++++++++-----------------------
1 file changed, 64 insertions(+), 60 deletions(-)
diff --git a/Documentation/digsig.txt b/Documentation/digsig.txt
index 3f682889068b..7ce23eddee37 100644
--- a/Documentation/digsig.txt
+++ b/Documentation/digsig.txt
@@ -1,13 +1,19 @@
Digital Signature Verification API
+----------------------------------
-CONTENTS
+:Author: Dmitry Kasatkin
+:Date: 06.10.2011
-1. Introduction
-2. API
-3. User-space utilities
+.. CONTENTS
-1. Introduction
+ 1. Introduction
+ 2. API
+ 3. User-space utilities
+
+
+Introduction
+============
Digital signature verification API provides a method to verify digital signature.
Currently digital signatures are used by the IMA/EVM integrity protection subsystem.
@@ -17,25 +23,25 @@ GnuPG multi-precision integers (MPI) library. The kernel port provides
memory allocation errors handling, has been refactored according to kernel
coding style, and checkpatch.pl reported errors and warnings have been fixed.
-Public key and signature consist of header and MPIs.
+Public key and signature consist of header and MPIs::
-struct pubkey_hdr {
- uint8_t version; /* key format version */
- time_t timestamp; /* key made, always 0 for now */
- uint8_t algo;
- uint8_t nmpi;
- char mpi[0];
-} __packed;
+ struct pubkey_hdr {
+ uint8_t version; /* key format version */
+ time_t timestamp; /* key made, always 0 for now */
+ uint8_t algo;
+ uint8_t nmpi;
+ char mpi[0];
+ } __packed;
-struct signature_hdr {
- uint8_t version; /* signature format version */
- time_t timestamp; /* signature made */
- uint8_t algo;
- uint8_t hash;
- uint8_t keyid[8];
- uint8_t nmpi;
- char mpi[0];
-} __packed;
+ struct signature_hdr {
+ uint8_t version; /* signature format version */
+ time_t timestamp; /* signature made */
+ uint8_t algo;
+ uint8_t hash;
+ uint8_t keyid[8];
+ uint8_t nmpi;
+ char mpi[0];
+ } __packed;
keyid equals to SHA1[12-19] over the total key content.
Signature header is used as an input to generate a signature.
@@ -43,31 +49,33 @@ Such approach insures that key or signature header could not be changed.
It protects timestamp from been changed and can be used for rollback
protection.
-2. API
+API
+===
-API currently includes only 1 function:
+API currently includes only 1 function::
digsig_verify() - digital signature verification with public key
-/**
- * digsig_verify() - digital signature verification with public key
- * @keyring: keyring to search key in
- * @sig: digital signature
- * @sigen: length of the signature
- * @data: data
- * @datalen: length of the data
- * @return: 0 on success, -EINVAL otherwise
- *
- * Verifies data integrity against digital signature.
- * Currently only RSA is supported.
- * Normally hash of the content is used as a data for this function.
- *
- */
-int digsig_verify(struct key *keyring, const char *sig, int siglen,
- const char *data, int datalen);
+ /**
+ * digsig_verify() - digital signature verification with public key
+ * @keyring: keyring to search key in
+ * @sig: digital signature
+ * @sigen: length of the signature
+ * @data: data
+ * @datalen: length of the data
+ * @return: 0 on success, -EINVAL otherwise
+ *
+ * Verifies data integrity against digital signature.
+ * Currently only RSA is supported.
+ * Normally hash of the content is used as a data for this function.
+ *
+ */
+ int digsig_verify(struct key *keyring, const char *sig, int siglen,
+ const char *data, int datalen);
-3. User-space utilities
+User-space utilities
+====================
The signing and key management utilities evm-utils provide functionality
to generate signatures, to load keys into the kernel keyring.
@@ -75,22 +83,18 @@ Keys can be in PEM or converted to the kernel format.
When the key is added to the kernel keyring, the keyid defines the name
of the key: 5D2B05FC633EE3E8 in the example bellow.
-Here is example output of the keyctl utility.
-
-$ keyctl show
-Session Keyring
- -3 --alswrv 0 0 keyring: _ses
-603976250 --alswrv 0 -1 \_ keyring: _uid.0
-817777377 --alswrv 0 0 \_ user: kmk
-891974900 --alswrv 0 0 \_ encrypted: evm-key
-170323636 --alswrv 0 0 \_ keyring: _module
-548221616 --alswrv 0 0 \_ keyring: _ima
-128198054 --alswrv 0 0 \_ keyring: _evm
-
-$ keyctl list 128198054
-1 key in keyring:
-620789745: --alswrv 0 0 user: 5D2B05FC633EE3E8
-
-
-Dmitry Kasatkin
-06.10.2011
+Here is example output of the keyctl utility::
+
+ $ keyctl show
+ Session Keyring
+ -3 --alswrv 0 0 keyring: _ses
+ 603976250 --alswrv 0 -1 \_ keyring: _uid.0
+ 817777377 --alswrv 0 0 \_ user: kmk
+ 891974900 --alswrv 0 0 \_ encrypted: evm-key
+ 170323636 --alswrv 0 0 \_ keyring: _module
+ 548221616 --alswrv 0 0 \_ keyring: _ima
+ 128198054 --alswrv 0 0 \_ keyring: _evm
+
+ $ keyctl list 128198054
+ 1 key in keyring:
+ 620789745: --alswrv 0 0 user: 5D2B05FC633EE3E8
--
2.9.4
^ permalink raw reply related [flat|nested] 37+ messages in thread* [PATCH 14/31] DMA-API.txt: standardize document format
2017-05-19 1:22 [PATCH 00/31] Standardize doc formats - part 1 Mauro Carvalho Chehab
` (12 preceding siblings ...)
2017-05-19 1:22 ` [PATCH 13/31] digsig.txt: " Mauro Carvalho Chehab
@ 2017-05-19 1:22 ` Mauro Carvalho Chehab
2017-05-19 1:22 ` [PATCH 15/31] DMA-API-HOWTO.txt: " Mauro Carvalho Chehab
` (16 subsequent siblings)
30 siblings, 0 replies; 37+ messages in thread
From: Mauro Carvalho Chehab @ 2017-05-19 1:22 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, David Woodhouse, Brian Norris, Boris Brezillon,
Marek Vasut, Richard Weinberger, Cyrille Pitchen, linux-mtd
Each text file under Documentation follows a different
format. Some doesn't even have titles!
Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- Fix some title marks to match ReST;
- use :Author: for author name;
- foo_ is an hyperlink. Get rid of it;
- Mark literal blocks as such;
- Use tables on some places that are almost using the
table format.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/DMA-API.txt | 575 ++++++++++++++++++++++++++--------------------
1 file changed, 326 insertions(+), 249 deletions(-)
diff --git a/Documentation/DMA-API.txt b/Documentation/DMA-API.txt
index 6b20128fab8a..2104686b9f02 100644
--- a/Documentation/DMA-API.txt
+++ b/Documentation/DMA-API.txt
@@ -1,7 +1,7 @@
- Dynamic DMA mapping using the generic device
- ============================================
+Dynamic DMA mapping using the generic device
+============================================
- James E.J. Bottomley <James.Bottomley@HansenPartnership.com>
+:Author: James E.J. Bottomley <James.Bottomley@HansenPartnership.com>
This document describes the DMA API. For a more gentle introduction
of the API (and actual examples), see Documentation/DMA-API-HOWTO.txt.
@@ -12,10 +12,10 @@ machines. Unless you know that your driver absolutely has to support
non-consistent platforms (this is usually only legacy platforms) you
should only use the API described in part I.
-Part I - dma_ API
--------------------------------------
+Part I - dma_API
+----------------
-To get the dma_ API, you must #include <linux/dma-mapping.h>. This
+To get the dma_API, you must #include <linux/dma-mapping.h>. This
provides dma_addr_t and the interfaces described below.
A dma_addr_t can hold any valid DMA address for the platform. It can be
@@ -26,9 +26,11 @@ address space and the DMA address space.
Part Ia - Using large DMA-coherent buffers
------------------------------------------
-void *
-dma_alloc_coherent(struct device *dev, size_t size,
- dma_addr_t *dma_handle, gfp_t flag)
+::
+
+ void *
+ dma_alloc_coherent(struct device *dev, size_t size,
+ dma_addr_t *dma_handle, gfp_t flag)
Consistent memory is memory for which a write by either the device or
the processor can immediately be read by the processor or device
@@ -51,20 +53,24 @@ consolidate your requests for consistent memory as much as possible.
The simplest way to do that is to use the dma_pool calls (see below).
The flag parameter (dma_alloc_coherent() only) allows the caller to
-specify the GFP_ flags (see kmalloc()) for the allocation (the
+specify the ``GFP_`` flags (see kmalloc()) for the allocation (the
implementation may choose to ignore flags that affect the location of
the returned memory, like GFP_DMA).
-void *
-dma_zalloc_coherent(struct device *dev, size_t size,
- dma_addr_t *dma_handle, gfp_t flag)
+::
+
+ void *
+ dma_zalloc_coherent(struct device *dev, size_t size,
+ dma_addr_t *dma_handle, gfp_t flag)
Wraps dma_alloc_coherent() and also zeroes the returned memory if the
allocation attempt succeeded.
-void
-dma_free_coherent(struct device *dev, size_t size, void *cpu_addr,
- dma_addr_t dma_handle)
+::
+
+ void
+ dma_free_coherent(struct device *dev, size_t size, void *cpu_addr,
+ dma_addr_t dma_handle)
Free a region of consistent memory you previously allocated. dev,
size and dma_handle must all be the same as those passed into
@@ -78,7 +84,7 @@ may only be called with IRQs enabled.
Part Ib - Using small DMA-coherent buffers
------------------------------------------
-To get this part of the dma_ API, you must #include <linux/dmapool.h>
+To get this part of the dma_API, you must #include <linux/dmapool.h>
Many drivers need lots of small DMA-coherent memory regions for DMA
descriptors or I/O buffers. Rather than allocating in units of a page
@@ -88,6 +94,8 @@ not __get_free_pages(). Also, they understand common hardware constraints
for alignment, like queue heads needing to be aligned on N-byte boundaries.
+::
+
struct dma_pool *
dma_pool_create(const char *name, struct device *dev,
size_t size, size_t align, size_t alloc);
@@ -103,16 +111,21 @@ in bytes, and must be a power of two). If your device has no boundary
crossing restrictions, pass 0 for alloc; passing 4096 says memory allocated
from this pool must not cross 4KByte boundaries.
+::
- void *dma_pool_zalloc(struct dma_pool *pool, gfp_t mem_flags,
- dma_addr_t *handle)
+ void *
+ dma_pool_zalloc(struct dma_pool *pool, gfp_t mem_flags,
+ dma_addr_t *handle)
Wraps dma_pool_alloc() and also zeroes the returned memory if the
allocation attempt succeeded.
- void *dma_pool_alloc(struct dma_pool *pool, gfp_t gfp_flags,
- dma_addr_t *dma_handle);
+::
+
+ void *
+ dma_pool_alloc(struct dma_pool *pool, gfp_t gfp_flags,
+ dma_addr_t *dma_handle);
This allocates memory from the pool; the returned memory will meet the
size and alignment requirements specified at creation time. Pass
@@ -122,16 +135,20 @@ blocking. Like dma_alloc_coherent(), this returns two values: an
address usable by the CPU, and the DMA address usable by the pool's
device.
+::
- void dma_pool_free(struct dma_pool *pool, void *vaddr,
- dma_addr_t addr);
+ void
+ dma_pool_free(struct dma_pool *pool, void *vaddr,
+ dma_addr_t addr);
This puts memory back into the pool. The pool is what was passed to
dma_pool_alloc(); the CPU (vaddr) and DMA addresses are what
were returned when that routine allocated the memory being freed.
+::
- void dma_pool_destroy(struct dma_pool *pool);
+ void
+ dma_pool_destroy(struct dma_pool *pool);
dma_pool_destroy() frees the resources of the pool. It must be
called in a context which can sleep. Make sure you've freed all allocated
@@ -141,32 +158,40 @@ memory back to the pool before you destroy it.
Part Ic - DMA addressing limitations
------------------------------------
-int
-dma_set_mask_and_coherent(struct device *dev, u64 mask)
+::
+
+ int
+ dma_set_mask_and_coherent(struct device *dev, u64 mask)
Checks to see if the mask is possible and updates the device
streaming and coherent DMA mask parameters if it is.
Returns: 0 if successful and a negative error if not.
-int
-dma_set_mask(struct device *dev, u64 mask)
+::
+
+ int
+ dma_set_mask(struct device *dev, u64 mask)
Checks to see if the mask is possible and updates the device
parameters if it is.
Returns: 0 if successful and a negative error if not.
-int
-dma_set_coherent_mask(struct device *dev, u64 mask)
+::
+
+ int
+ dma_set_coherent_mask(struct device *dev, u64 mask)
Checks to see if the mask is possible and updates the device
parameters if it is.
Returns: 0 if successful and a negative error if not.
-u64
-dma_get_required_mask(struct device *dev)
+::
+
+ u64
+ dma_get_required_mask(struct device *dev)
This API returns the mask that the platform requires to
operate efficiently. Usually this means the returned mask
@@ -182,94 +207,107 @@ call to set the mask to the value returned.
Part Id - Streaming DMA mappings
--------------------------------
-dma_addr_t
-dma_map_single(struct device *dev, void *cpu_addr, size_t size,
- enum dma_data_direction direction)
+::
+
+ dma_addr_t
+ dma_map_single(struct device *dev, void *cpu_addr, size_t size,
+ enum dma_data_direction direction)
Maps a piece of processor virtual memory so it can be accessed by the
device and returns the DMA address of the memory.
The direction for both APIs may be converted freely by casting.
-However the dma_ API uses a strongly typed enumerator for its
+However the dma_API uses a strongly typed enumerator for its
direction:
+======================= =============================================
DMA_NONE no direction (used for debugging)
DMA_TO_DEVICE data is going from the memory to the device
DMA_FROM_DEVICE data is coming from the device to the memory
DMA_BIDIRECTIONAL direction isn't known
+======================= =============================================
-Notes: Not all memory regions in a machine can be mapped by this API.
-Further, contiguous kernel virtual space may not be contiguous as
-physical memory. Since this API does not provide any scatter/gather
-capability, it will fail if the user tries to map a non-physically
-contiguous piece of memory. For this reason, memory to be mapped by
-this API should be obtained from sources which guarantee it to be
-physically contiguous (like kmalloc).
-
-Further, the DMA address of the memory must be within the
-dma_mask of the device (the dma_mask is a bit mask of the
-addressable region for the device, i.e., if the DMA address of
-the memory ANDed with the dma_mask is still equal to the DMA
-address, then the device can perform DMA to the memory). To
-ensure that the memory allocated by kmalloc is within the dma_mask,
-the driver may specify various platform-dependent flags to restrict
-the DMA address range of the allocation (e.g., on x86, GFP_DMA
-guarantees to be within the first 16MB of available DMA addresses,
-as required by ISA devices).
-
-Note also that the above constraints on physical contiguity and
-dma_mask may not apply if the platform has an IOMMU (a device which
-maps an I/O DMA address to a physical memory address). However, to be
-portable, device driver writers may *not* assume that such an IOMMU
-exists.
-
-Warnings: Memory coherency operates at a granularity called the cache
-line width. In order for memory mapped by this API to operate
-correctly, the mapped region must begin exactly on a cache line
-boundary and end exactly on one (to prevent two separately mapped
-regions from sharing a single cache line). Since the cache line size
-may not be known at compile time, the API will not enforce this
-requirement. Therefore, it is recommended that driver writers who
-don't take special care to determine the cache line size at run time
-only map virtual regions that begin and end on page boundaries (which
-are guaranteed also to be cache line boundaries).
-
-DMA_TO_DEVICE synchronisation must be done after the last modification
-of the memory region by the software and before it is handed off to
-the device. Once this primitive is used, memory covered by this
-primitive should be treated as read-only by the device. If the device
-may write to it at any point, it should be DMA_BIDIRECTIONAL (see
-below).
-
-DMA_FROM_DEVICE synchronisation must be done before the driver
-accesses data that may be changed by the device. This memory should
-be treated as read-only by the driver. If the driver needs to write
-to it at any point, it should be DMA_BIDIRECTIONAL (see below).
-
-DMA_BIDIRECTIONAL requires special handling: it means that the driver
-isn't sure if the memory was modified before being handed off to the
-device and also isn't sure if the device will also modify it. Thus,
-you must always sync bidirectional memory twice: once before the
-memory is handed off to the device (to make sure all memory changes
-are flushed from the processor) and once before the data may be
-accessed after being used by the device (to make sure any processor
-cache lines are updated with data that the device may have changed).
-
-void
-dma_unmap_single(struct device *dev, dma_addr_t dma_addr, size_t size,
- enum dma_data_direction direction)
+.. note::
+
+ Not all memory regions in a machine can be mapped by this API.
+ Further, contiguous kernel virtual space may not be contiguous as
+ physical memory. Since this API does not provide any scatter/gather
+ capability, it will fail if the user tries to map a non-physically
+ contiguous piece of memory. For this reason, memory to be mapped by
+ this API should be obtained from sources which guarantee it to be
+ physically contiguous (like kmalloc).
+
+ Further, the DMA address of the memory must be within the
+ dma_mask of the device (the dma_mask is a bit mask of the
+ addressable region for the device, i.e., if the DMA address of
+ the memory ANDed with the dma_mask is still equal to the DMA
+ address, then the device can perform DMA to the memory). To
+ ensure that the memory allocated by kmalloc is within the dma_mask,
+ the driver may specify various platform-dependent flags to restrict
+ the DMA address range of the allocation (e.g., on x86, GFP_DMA
+ guarantees to be within the first 16MB of available DMA addresses,
+ as required by ISA devices).
+
+ Note also that the above constraints on physical contiguity and
+ dma_mask may not apply if the platform has an IOMMU (a device which
+ maps an I/O DMA address to a physical memory address). However, to be
+ portable, device driver writers may *not* assume that such an IOMMU
+ exists.
+
+.. warning::
+
+ Memory coherency operates at a granularity called the cache
+ line width. In order for memory mapped by this API to operate
+ correctly, the mapped region must begin exactly on a cache line
+ boundary and end exactly on one (to prevent two separately mapped
+ regions from sharing a single cache line). Since the cache line size
+ may not be known at compile time, the API will not enforce this
+ requirement. Therefore, it is recommended that driver writers who
+ don't take special care to determine the cache line size at run time
+ only map virtual regions that begin and end on page boundaries (which
+ are guaranteed also to be cache line boundaries).
+
+ DMA_TO_DEVICE synchronisation must be done after the last modification
+ of the memory region by the software and before it is handed off to
+ the device. Once this primitive is used, memory covered by this
+ primitive should be treated as read-only by the device. If the device
+ may write to it at any point, it should be DMA_BIDIRECTIONAL (see
+ below).
+
+ DMA_FROM_DEVICE synchronisation must be done before the driver
+ accesses data that may be changed by the device. This memory should
+ be treated as read-only by the driver. If the driver needs to write
+ to it at any point, it should be DMA_BIDIRECTIONAL (see below).
+
+ DMA_BIDIRECTIONAL requires special handling: it means that the driver
+ isn't sure if the memory was modified before being handed off to the
+ device and also isn't sure if the device will also modify it. Thus,
+ you must always sync bidirectional memory twice: once before the
+ memory is handed off to the device (to make sure all memory changes
+ are flushed from the processor) and once before the data may be
+ accessed after being used by the device (to make sure any processor
+ cache lines are updated with data that the device may have changed).
+
+::
+
+ void
+ dma_unmap_single(struct device *dev, dma_addr_t dma_addr, size_t size,
+ enum dma_data_direction direction)
Unmaps the region previously mapped. All the parameters passed in
must be identical to those passed in (and returned) by the mapping
API.
-dma_addr_t
-dma_map_page(struct device *dev, struct page *page,
- unsigned long offset, size_t size,
- enum dma_data_direction direction)
-void
-dma_unmap_page(struct device *dev, dma_addr_t dma_address, size_t size,
- enum dma_data_direction direction)
+::
+
+ dma_addr_t
+ dma_map_page(struct device *dev, struct page *page,
+ unsigned long offset, size_t size,
+ enum dma_data_direction direction)
+
+ void
+ dma_unmap_page(struct device *dev, dma_addr_t dma_address, size_t size,
+ enum dma_data_direction direction)
API for mapping and unmapping for pages. All the notes and warnings
for the other mapping APIs apply here. Also, although the <offset>
@@ -277,20 +315,24 @@ and <size> parameters are provided to do partial page mapping, it is
recommended that you never use these unless you really know what the
cache width is.
-dma_addr_t
-dma_map_resource(struct device *dev, phys_addr_t phys_addr, size_t size,
- enum dma_data_direction dir, unsigned long attrs)
+::
-void
-dma_unmap_resource(struct device *dev, dma_addr_t addr, size_t size,
- enum dma_data_direction dir, unsigned long attrs)
+ dma_addr_t
+ dma_map_resource(struct device *dev, phys_addr_t phys_addr, size_t size,
+ enum dma_data_direction dir, unsigned long attrs)
+
+ void
+ dma_unmap_resource(struct device *dev, dma_addr_t addr, size_t size,
+ enum dma_data_direction dir, unsigned long attrs)
API for mapping and unmapping for MMIO resources. All the notes and
warnings for the other mapping APIs apply here. The API should only be
used to map device MMIO resources, mapping of RAM is not permitted.
-int
-dma_mapping_error(struct device *dev, dma_addr_t dma_addr)
+::
+
+ int
+ dma_mapping_error(struct device *dev, dma_addr_t dma_addr)
In some circumstances dma_map_single(), dma_map_page() and dma_map_resource()
will fail to create a mapping. A driver can check for these errors by testing
@@ -298,9 +340,11 @@ the returned DMA address with dma_mapping_error(). A non-zero return value
means the mapping could not be created and the driver should take appropriate
action (e.g. reduce current DMA mapping usage or delay and try again later).
+::
+
int
dma_map_sg(struct device *dev, struct scatterlist *sg,
- int nents, enum dma_data_direction direction)
+ int nents, enum dma_data_direction direction)
Returns: the number of DMA address segments mapped (this may be shorter
than <nents> passed in if some elements of the scatter/gather list are
@@ -316,7 +360,7 @@ critical that the driver do something, in the case of a block driver
aborting the request or even oopsing is better than doing nothing and
corrupting the filesystem.
-With scatterlists, you use the resulting mapping like this:
+With scatterlists, you use the resulting mapping like this::
int i, count = dma_map_sg(dev, sglist, nents, direction);
struct scatterlist *sg;
@@ -337,9 +381,11 @@ Then you should loop count times (note: this can be less than nents times)
and use sg_dma_address() and sg_dma_len() macros where you previously
accessed sg->address and sg->length as shown above.
+::
+
void
dma_unmap_sg(struct device *dev, struct scatterlist *sg,
- int nents, enum dma_data_direction direction)
+ int nents, enum dma_data_direction direction)
Unmap the previously mapped scatter/gather list. All the parameters
must be the same as those and passed in to the scatter/gather mapping
@@ -348,18 +394,27 @@ API.
Note: <nents> must be the number you passed in, *not* the number of
DMA address entries returned.
-void
-dma_sync_single_for_cpu(struct device *dev, dma_addr_t dma_handle, size_t size,
- enum dma_data_direction direction)
-void
-dma_sync_single_for_device(struct device *dev, dma_addr_t dma_handle, size_t size,
- enum dma_data_direction direction)
-void
-dma_sync_sg_for_cpu(struct device *dev, struct scatterlist *sg, int nents,
- enum dma_data_direction direction)
-void
-dma_sync_sg_for_device(struct device *dev, struct scatterlist *sg, int nents,
- enum dma_data_direction direction)
+::
+
+ void
+ dma_sync_single_for_cpu(struct device *dev, dma_addr_t dma_handle,
+ size_t size,
+ enum dma_data_direction direction)
+
+ void
+ dma_sync_single_for_device(struct device *dev, dma_addr_t dma_handle,
+ size_t size,
+ enum dma_data_direction direction)
+
+ void
+ dma_sync_sg_for_cpu(struct device *dev, struct scatterlist *sg,
+ int nents,
+ enum dma_data_direction direction)
+
+ void
+ dma_sync_sg_for_device(struct device *dev, struct scatterlist *sg,
+ int nents,
+ enum dma_data_direction direction)
Synchronise a single contiguous or scatter/gather mapping for the CPU
and device. With the sync_sg API, all the parameters must be the same
@@ -367,36 +422,41 @@ as those passed into the single mapping API. With the sync_single API,
you can use dma_handle and size parameters that aren't identical to
those passed into the single mapping API to do a partial sync.
-Notes: You must do this:
-- Before reading values that have been written by DMA from the device
- (use the DMA_FROM_DEVICE direction)
-- After writing values that will be written to the device using DMA
- (use the DMA_TO_DEVICE) direction
-- before *and* after handing memory to the device if the memory is
- DMA_BIDIRECTIONAL
+.. note::
+
+ You must do this:
+
+ - Before reading values that have been written by DMA from the device
+ (use the DMA_FROM_DEVICE direction)
+ - After writing values that will be written to the device using DMA
+ (use the DMA_TO_DEVICE) direction
+ - before *and* after handing memory to the device if the memory is
+ DMA_BIDIRECTIONAL
See also dma_map_single().
-dma_addr_t
-dma_map_single_attrs(struct device *dev, void *cpu_addr, size_t size,
- enum dma_data_direction dir,
- unsigned long attrs)
+::
-void
-dma_unmap_single_attrs(struct device *dev, dma_addr_t dma_addr,
- size_t size, enum dma_data_direction dir,
- unsigned long attrs)
+ dma_addr_t
+ dma_map_single_attrs(struct device *dev, void *cpu_addr, size_t size,
+ enum dma_data_direction dir,
+ unsigned long attrs)
-int
-dma_map_sg_attrs(struct device *dev, struct scatterlist *sgl,
- int nents, enum dma_data_direction dir,
- unsigned long attrs)
+ void
+ dma_unmap_single_attrs(struct device *dev, dma_addr_t dma_addr,
+ size_t size, enum dma_data_direction dir,
+ unsigned long attrs)
-void
-dma_unmap_sg_attrs(struct device *dev, struct scatterlist *sgl,
- int nents, enum dma_data_direction dir,
- unsigned long attrs)
+ int
+ dma_map_sg_attrs(struct device *dev, struct scatterlist *sgl,
+ int nents, enum dma_data_direction dir,
+ unsigned long attrs)
+
+ void
+ dma_unmap_sg_attrs(struct device *dev, struct scatterlist *sgl,
+ int nents, enum dma_data_direction dir,
+ unsigned long attrs)
The four functions above are just like the counterpart functions
without the _attrs suffixes, except that they pass an optional
@@ -410,37 +470,38 @@ is identical to those of the corresponding function
without the _attrs suffix. As a result dma_map_single_attrs()
can generally replace dma_map_single(), etc.
-As an example of the use of the *_attrs functions, here's how
+As an example of the use of the ``*_attrs`` functions, here's how
you could pass an attribute DMA_ATTR_FOO when mapping memory
-for DMA:
+for DMA::
-#include <linux/dma-mapping.h>
-/* DMA_ATTR_FOO should be defined in linux/dma-mapping.h and
- * documented in Documentation/DMA-attributes.txt */
-...
+ #include <linux/dma-mapping.h>
+ /* DMA_ATTR_FOO should be defined in linux/dma-mapping.h and
+ * documented in Documentation/DMA-attributes.txt */
+ ...
- unsigned long attr;
- attr |= DMA_ATTR_FOO;
- ....
- n = dma_map_sg_attrs(dev, sg, nents, DMA_TO_DEVICE, attr);
- ....
+ unsigned long attr;
+ attr |= DMA_ATTR_FOO;
+ ....
+ n = dma_map_sg_attrs(dev, sg, nents, DMA_TO_DEVICE, attr);
+ ....
Architectures that care about DMA_ATTR_FOO would check for its
presence in their implementations of the mapping and unmapping
-routines, e.g.:
+routines, e.g.:::
-void whizco_dma_map_sg_attrs(struct device *dev, dma_addr_t dma_addr,
- size_t size, enum dma_data_direction dir,
- unsigned long attrs)
-{
- ....
- if (attrs & DMA_ATTR_FOO)
- /* twizzle the frobnozzle */
- ....
+ void whizco_dma_map_sg_attrs(struct device *dev, dma_addr_t dma_addr,
+ size_t size, enum dma_data_direction dir,
+ unsigned long attrs)
+ {
+ ....
+ if (attrs & DMA_ATTR_FOO)
+ /* twizzle the frobnozzle */
+ ....
+ }
-Part II - Advanced dma_ usage
------------------------------
+Part II - Advanced dma usage
+----------------------------
Warning: These pieces of the DMA API should not be used in the
majority of cases, since they cater for unlikely corner cases that
@@ -450,9 +511,11 @@ If you don't understand how cache line coherency works between a
processor and an I/O device, you should not be using this part of the
API at all.
-void *
-dma_alloc_noncoherent(struct device *dev, size_t size,
- dma_addr_t *dma_handle, gfp_t flag)
+::
+
+ void *
+ dma_alloc_noncoherent(struct device *dev, size_t size,
+ dma_addr_t *dma_handle, gfp_t flag)
Identical to dma_alloc_coherent() except that the platform will
choose to return either consistent or non-consistent memory as it sees
@@ -468,39 +531,49 @@ only use this API if you positively know your driver will be
required to work on one of the rare (usually non-PCI) architectures
that simply cannot make consistent memory.
-void
-dma_free_noncoherent(struct device *dev, size_t size, void *cpu_addr,
- dma_addr_t dma_handle)
+::
+
+ void
+ dma_free_noncoherent(struct device *dev, size_t size, void *cpu_addr,
+ dma_addr_t dma_handle)
Free memory allocated by the nonconsistent API. All parameters must
be identical to those passed in (and returned by
dma_alloc_noncoherent()).
-int
-dma_get_cache_alignment(void)
+::
+
+ int
+ dma_get_cache_alignment(void)
Returns the processor cache alignment. This is the absolute minimum
alignment *and* width that you must observe when either mapping
memory or doing partial flushes.
-Notes: This API may return a number *larger* than the actual cache
-line, but it will guarantee that one or more cache lines fit exactly
-into the width returned by this call. It will also always be a power
-of two for easy alignment.
+.. note::
-void
-dma_cache_sync(struct device *dev, void *vaddr, size_t size,
- enum dma_data_direction direction)
+ This API may return a number *larger* than the actual cache
+ line, but it will guarantee that one or more cache lines fit exactly
+ into the width returned by this call. It will also always be a power
+ of two for easy alignment.
+
+::
+
+ void
+ dma_cache_sync(struct device *dev, void *vaddr, size_t size,
+ enum dma_data_direction direction)
Do a partial sync of memory that was allocated by
dma_alloc_noncoherent(), starting at virtual address vaddr and
continuing on for size. Again, you *must* observe the cache line
boundaries when doing this.
-int
-dma_declare_coherent_memory(struct device *dev, phys_addr_t phys_addr,
- dma_addr_t device_addr, size_t size, int
- flags)
+::
+
+ int
+ dma_declare_coherent_memory(struct device *dev, phys_addr_t phys_addr,
+ dma_addr_t device_addr, size_t size, int
+ flags)
Declare region of memory to be handed out by dma_alloc_coherent() when
it's asked for coherent memory for this device.
@@ -516,21 +589,21 @@ size is the size of the area (must be multiples of PAGE_SIZE).
flags can be ORed together and are:
-DMA_MEMORY_MAP - request that the memory returned from
-dma_alloc_coherent() be directly writable.
+- DMA_MEMORY_MAP - request that the memory returned from
+ dma_alloc_coherent() be directly writable.
-DMA_MEMORY_IO - request that the memory returned from
-dma_alloc_coherent() be addressable using read()/write()/memcpy_toio() etc.
+- DMA_MEMORY_IO - request that the memory returned from
+ dma_alloc_coherent() be addressable using read()/write()/memcpy_toio() etc.
One or both of these flags must be present.
-DMA_MEMORY_INCLUDES_CHILDREN - make the declared memory be allocated by
-dma_alloc_coherent of any child devices of this one (for memory residing
-on a bridge).
+- DMA_MEMORY_INCLUDES_CHILDREN - make the declared memory be allocated by
+ dma_alloc_coherent of any child devices of this one (for memory residing
+ on a bridge).
-DMA_MEMORY_EXCLUSIVE - only allocate memory from the declared regions.
-Do not allow dma_alloc_coherent() to fall back to system memory when
-it's out of memory in the declared region.
+- DMA_MEMORY_EXCLUSIVE - only allocate memory from the declared regions.
+ Do not allow dma_alloc_coherent() to fall back to system memory when
+ it's out of memory in the declared region.
The return value will be either DMA_MEMORY_MAP or DMA_MEMORY_IO and
must correspond to a passed in flag (i.e. no returning DMA_MEMORY_IO
@@ -543,15 +616,17 @@ must be accessed using the correct bus functions. If your driver
isn't prepared to handle this contingency, it should not specify
DMA_MEMORY_IO in the input flags.
-As a simplification for the platforms, only *one* such region of
+As a simplification for the platforms, only **one** such region of
memory may be declared per device.
For reasons of efficiency, most platforms choose to track the declared
region only at the granularity of a page. For smaller allocations,
you should use the dma_pool() API.
-void
-dma_release_declared_memory(struct device *dev)
+::
+
+ void
+ dma_release_declared_memory(struct device *dev)
Remove the memory region previously declared from the system. This
API performs *no* in-use checking for this region and will return
@@ -559,9 +634,11 @@ unconditionally having removed all the required structures. It is the
driver's job to ensure that no parts of this memory region are
currently in use.
-void *
-dma_mark_declared_memory_occupied(struct device *dev,
- dma_addr_t device_addr, size_t size)
+::
+
+ void *
+ dma_mark_declared_memory_occupied(struct device *dev,
+ dma_addr_t device_addr, size_t size)
This is used to occupy specific regions of the declared space
(dma_alloc_coherent() will hand out the first free region it finds).
@@ -592,38 +669,37 @@ option has a performance impact. Do not enable it in production kernels.
If you boot the resulting kernel will contain code which does some bookkeeping
about what DMA memory was allocated for which device. If this code detects an
error it prints a warning message with some details into your kernel log. An
-example warning message may look like this:
+example warning message may look like this::
-------------[ cut here ]------------
-WARNING: at /data2/repos/linux-2.6-iommu/lib/dma-debug.c:448
- check_unmap+0x203/0x490()
-Hardware name:
-forcedeth 0000:00:08.0: DMA-API: device driver frees DMA memory with wrong
- function [device address=0x00000000640444be] [size=66 bytes] [mapped as
-single] [unmapped as page]
-Modules linked in: nfsd exportfs bridge stp llc r8169
-Pid: 0, comm: swapper Tainted: G W 2.6.28-dmatest-09289-g8bb99c0 #1
-Call Trace:
- <IRQ> [<ffffffff80240b22>] warn_slowpath+0xf2/0x130
- [<ffffffff80647b70>] _spin_unlock+0x10/0x30
- [<ffffffff80537e75>] usb_hcd_link_urb_to_ep+0x75/0xc0
- [<ffffffff80647c22>] _spin_unlock_irqrestore+0x12/0x40
- [<ffffffff8055347f>] ohci_urb_enqueue+0x19f/0x7c0
- [<ffffffff80252f96>] queue_work+0x56/0x60
- [<ffffffff80237e10>] enqueue_task_fair+0x20/0x50
- [<ffffffff80539279>] usb_hcd_submit_urb+0x379/0xbc0
- [<ffffffff803b78c3>] cpumask_next_and+0x23/0x40
- [<ffffffff80235177>] find_busiest_group+0x207/0x8a0
- [<ffffffff8064784f>] _spin_lock_irqsave+0x1f/0x50
- [<ffffffff803c7ea3>] check_unmap+0x203/0x490
- [<ffffffff803c8259>] debug_dma_unmap_page+0x49/0x50
- [<ffffffff80485f26>] nv_tx_done_optimized+0xc6/0x2c0
- [<ffffffff80486c13>] nv_nic_irq_optimized+0x73/0x2b0
- [<ffffffff8026df84>] handle_IRQ_event+0x34/0x70
- [<ffffffff8026ffe9>] handle_edge_irq+0xc9/0x150
- [<ffffffff8020e3ab>] do_IRQ+0xcb/0x1c0
- [<ffffffff8020c093>] ret_from_intr+0x0/0xa
- <EOI> <4>---[ end trace f6435a98e2a38c0e ]---
+ WARNING: at /data2/repos/linux-2.6-iommu/lib/dma-debug.c:448
+ check_unmap+0x203/0x490()
+ Hardware name:
+ forcedeth 0000:00:08.0: DMA-API: device driver frees DMA memory with wrong
+ function [device address=0x00000000640444be] [size=66 bytes] [mapped as
+ single] [unmapped as page]
+ Modules linked in: nfsd exportfs bridge stp llc r8169
+ Pid: 0, comm: swapper Tainted: G W 2.6.28-dmatest-09289-g8bb99c0 #1
+ Call Trace:
+ <IRQ> [<ffffffff80240b22>] warn_slowpath+0xf2/0x130
+ [<ffffffff80647b70>] _spin_unlock+0x10/0x30
+ [<ffffffff80537e75>] usb_hcd_link_urb_to_ep+0x75/0xc0
+ [<ffffffff80647c22>] _spin_unlock_irqrestore+0x12/0x40
+ [<ffffffff8055347f>] ohci_urb_enqueue+0x19f/0x7c0
+ [<ffffffff80252f96>] queue_work+0x56/0x60
+ [<ffffffff80237e10>] enqueue_task_fair+0x20/0x50
+ [<ffffffff80539279>] usb_hcd_submit_urb+0x379/0xbc0
+ [<ffffffff803b78c3>] cpumask_next_and+0x23/0x40
+ [<ffffffff80235177>] find_busiest_group+0x207/0x8a0
+ [<ffffffff8064784f>] _spin_lock_irqsave+0x1f/0x50
+ [<ffffffff803c7ea3>] check_unmap+0x203/0x490
+ [<ffffffff803c8259>] debug_dma_unmap_page+0x49/0x50
+ [<ffffffff80485f26>] nv_tx_done_optimized+0xc6/0x2c0
+ [<ffffffff80486c13>] nv_nic_irq_optimized+0x73/0x2b0
+ [<ffffffff8026df84>] handle_IRQ_event+0x34/0x70
+ [<ffffffff8026ffe9>] handle_edge_irq+0xc9/0x150
+ [<ffffffff8020e3ab>] do_IRQ+0xcb/0x1c0
+ [<ffffffff8020c093>] ret_from_intr+0x0/0xa
+ <EOI> <4>---[ end trace f6435a98e2a38c0e ]---
The driver developer can find the driver and the device including a stacktrace
of the DMA-API call which caused this warning.
@@ -637,43 +713,42 @@ details.
The debugfs directory for the DMA-API debugging code is called dma-api/. In
this directory the following files can currently be found:
- dma-api/all_errors This file contains a numeric value. If this
+=============================== ===============================================
+dma-api/all_errors This file contains a numeric value. If this
value is not equal to zero the debugging code
will print a warning for every error it finds
into the kernel log. Be careful with this
option, as it can easily flood your logs.
- dma-api/disabled This read-only file contains the character 'Y'
+dma-api/disabled This read-only file contains the character 'Y'
if the debugging code is disabled. This can
happen when it runs out of memory or if it was
disabled at boot time
- dma-api/error_count This file is read-only and shows the total
+dma-api/error_count This file is read-only and shows the total
numbers of errors found.
- dma-api/num_errors The number in this file shows how many
+dma-api/num_errors The number in this file shows how many
warnings will be printed to the kernel log
before it stops. This number is initialized to
one at system boot and be set by writing into
this file
- dma-api/min_free_entries
- This read-only file can be read to get the
+dma-api/min_free_entries This read-only file can be read to get the
minimum number of free dma_debug_entries the
allocator has ever seen. If this value goes
down to zero the code will disable itself
because it is not longer reliable.
- dma-api/num_free_entries
- The current number of free dma_debug_entries
+dma-api/num_free_entries The current number of free dma_debug_entries
in the allocator.
- dma-api/driver-filter
- You can write a name of a driver into this file
+dma-api/driver-filter You can write a name of a driver into this file
to limit the debug output to requests from that
particular driver. Write an empty string to
that file to disable the filter and see
all errors again.
+=============================== ===============================================
If you have this code compiled into your kernel it will be enabled by default.
If you want to boot without the bookkeeping anyway you can provide
@@ -692,7 +767,10 @@ of preallocated entries is defined per architecture. If it is too low for you
boot with 'dma_debug_entries=<your_desired_number>' to overwrite the
architectural default.
-void debug_dmap_mapping_error(struct device *dev, dma_addr_t dma_addr);
+::
+
+ void
+ debug_dmap_mapping_error(struct device *dev, dma_addr_t dma_addr);
dma-debug interface debug_dma_mapping_error() to debug drivers that fail
to check DMA mapping errors on addresses returned by dma_map_single() and
@@ -702,4 +780,3 @@ the driver. When driver does unmap, debug_dma_unmap() checks the flag and if
this flag is still set, prints warning message that includes call trace that
leads up to the unmap. This interface can be called from dma_mapping_error()
routines to enable DMA mapping error check debugging.
-
--
2.9.4
^ permalink raw reply related [flat|nested] 37+ messages in thread* [PATCH 15/31] DMA-API-HOWTO.txt: standardize document format
2017-05-19 1:22 [PATCH 00/31] Standardize doc formats - part 1 Mauro Carvalho Chehab
` (13 preceding siblings ...)
2017-05-19 1:22 ` [PATCH 14/31] DMA-API.txt: " Mauro Carvalho Chehab
@ 2017-05-19 1:22 ` Mauro Carvalho Chehab
2017-05-19 1:22 ` [PATCH 16/31] DMA-attributes.txt: " Mauro Carvalho Chehab
` (15 subsequent siblings)
30 siblings, 0 replies; 37+ messages in thread
From: Mauro Carvalho Chehab @ 2017-05-19 1:22 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, David Woodhouse, Brian Norris, Boris Brezillon,
Marek Vasut, Richard Weinberger, Cyrille Pitchen, linux-mtd
Each text file under Documentation follows a different
format. Some doesn't even have titles!
Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- Mark titles;
- Mark literal blocks;
- Mark some literals that would otherwise produce warnings;
- Mark authorship.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/DMA-API-HOWTO.txt | 159 +++++++++++++++++++++++-----------------
1 file changed, 92 insertions(+), 67 deletions(-)
diff --git a/Documentation/DMA-API-HOWTO.txt b/Documentation/DMA-API-HOWTO.txt
index 979228bc9035..7c0a0ae4ab83 100644
--- a/Documentation/DMA-API-HOWTO.txt
+++ b/Documentation/DMA-API-HOWTO.txt
@@ -1,22 +1,24 @@
- Dynamic DMA mapping Guide
- =========================
+=========================
+Dynamic DMA mapping Guide
+=========================
- David S. Miller <davem@redhat.com>
- Richard Henderson <rth@cygnus.com>
- Jakub Jelinek <jakub@redhat.com>
+:Author: David S. Miller <davem@redhat.com>
+:Author: Richard Henderson <rth@cygnus.com>
+:Author: Jakub Jelinek <jakub@redhat.com>
This is a guide to device driver writers on how to use the DMA API
with example pseudo-code. For a concise description of the API, see
DMA-API.txt.
- CPU and DMA addresses
+CPU and DMA addresses
+=====================
There are several kinds of addresses involved in the DMA API, and it's
important to understand the differences.
The kernel normally uses virtual addresses. Any address returned by
kmalloc(), vmalloc(), and similar interfaces is a virtual address and can
-be stored in a "void *".
+be stored in a ``void *``.
The virtual memory system (TLB, page tables, etc.) translates virtual
addresses to CPU physical addresses, which are stored as "phys_addr_t" or
@@ -37,7 +39,7 @@ be restricted to a subset of that space. For example, even if a system
supports 64-bit addresses for main memory and PCI BARs, it may use an IOMMU
so devices only need to use 32-bit DMA addresses.
-Here's a picture and some examples:
+Here's a picture and some examples::
CPU CPU Bus
Virtual Physical Address
@@ -98,15 +100,16 @@ microprocessor architecture. You should use the DMA API rather than the
bus-specific DMA API, i.e., use the dma_map_*() interfaces rather than the
pci_map_*() interfaces.
-First of all, you should make sure
+First of all, you should make sure::
-#include <linux/dma-mapping.h>
+ #include <linux/dma-mapping.h>
is in your driver, which provides the definition of dma_addr_t. This type
can hold any valid DMA address for the platform and should be used
everywhere you hold a DMA address returned from the DMA mapping functions.
- What memory is DMA'able?
+What memory is DMA'able?
+========================
The first piece of information you must know is what kernel memory can
be used with the DMA mapping facilities. There has been an unwritten
@@ -143,7 +146,8 @@ What about block I/O and networking buffers? The block I/O and
networking subsystems make sure that the buffers they use are valid
for you to DMA from/to.
- DMA addressing limitations
+DMA addressing limitations
+==========================
Does your device have any DMA addressing limitations? For example, is
your device only capable of driving the low order 24-bits of address?
@@ -166,7 +170,7 @@ style to do this even if your device holds the default setting,
because this shows that you did think about these issues wrt. your
device.
-The query is performed via a call to dma_set_mask_and_coherent():
+The query is performed via a call to dma_set_mask_and_coherent()::
int dma_set_mask_and_coherent(struct device *dev, u64 mask);
@@ -175,12 +179,12 @@ If you have some special requirements, then the following two separate
queries can be used instead:
The query for streaming mappings is performed via a call to
- dma_set_mask():
+ dma_set_mask()::
int dma_set_mask(struct device *dev, u64 mask);
The query for consistent allocations is performed via a call
- to dma_set_coherent_mask():
+ to dma_set_coherent_mask()::
int dma_set_coherent_mask(struct device *dev, u64 mask);
@@ -209,7 +213,7 @@ of your driver reports that performance is bad or that the device is not
even detected, you can ask them for the kernel messages to find out
exactly why.
-The standard 32-bit addressing device would do something like this:
+The standard 32-bit addressing device would do something like this::
if (dma_set_mask_and_coherent(dev, DMA_BIT_MASK(32))) {
dev_warn(dev, "mydev: No suitable DMA available\n");
@@ -225,7 +229,7 @@ than 64-bit addressing. For example, Sparc64 PCI SAC addressing is
more efficient than DAC addressing.
Here is how you would handle a 64-bit capable device which can drive
-all 64-bits when accessing streaming DMA:
+all 64-bits when accessing streaming DMA::
int using_dac;
@@ -239,7 +243,7 @@ all 64-bits when accessing streaming DMA:
}
If a card is capable of using 64-bit consistent allocations as well,
-the case would look like this:
+the case would look like this::
int using_dac, consistent_using_dac;
@@ -260,7 +264,7 @@ uses consistent allocations, one would have to check the return value from
dma_set_coherent_mask().
Finally, if your device can only drive the low 24-bits of
-address you might do something like:
+address you might do something like::
if (dma_set_mask(dev, DMA_BIT_MASK(24))) {
dev_warn(dev, "mydev: 24-bit DMA addressing not available\n");
@@ -280,7 +284,7 @@ only provide the functionality which the machine can handle. It
is important that the last call to dma_set_mask() be for the
most specific mask.
-Here is pseudo-code showing how this might be done:
+Here is pseudo-code showing how this might be done::
#define PLAYBACK_ADDRESS_BITS DMA_BIT_MASK(32)
#define RECORD_ADDRESS_BITS DMA_BIT_MASK(24)
@@ -308,7 +312,8 @@ A sound card was used as an example here because this genre of PCI
devices seems to be littered with ISA chips given a PCI front end,
and thus retaining the 16MB DMA addressing limitations of ISA.
- Types of DMA mappings
+Types of DMA mappings
+=====================
There are two types of DMA mappings:
@@ -336,12 +341,14 @@ There are two types of DMA mappings:
to memory is immediately visible to the device, and vice
versa. Consistent mappings guarantee this.
- IMPORTANT: Consistent DMA memory does not preclude the usage of
- proper memory barriers. The CPU may reorder stores to
+ .. important::
+
+ Consistent DMA memory does not preclude the usage of
+ proper memory barriers. The CPU may reorder stores to
consistent memory just as it may normal memory. Example:
if it is important for the device to see the first word
of a descriptor updated before the second, you must do
- something like:
+ something like::
desc->word0 = address;
wmb();
@@ -377,16 +384,17 @@ Also, systems with caches that aren't DMA-coherent will work better
when the underlying buffers don't share cache lines with other data.
- Using Consistent DMA mappings.
+Using Consistent DMA mappings
+=============================
To allocate and map large (PAGE_SIZE or so) consistent DMA regions,
-you should do:
+you should do::
dma_addr_t dma_handle;
cpu_addr = dma_alloc_coherent(dev, size, &dma_handle, gfp);
-where device is a struct device *. This may be called in interrupt
+where device is a ``struct device *``. This may be called in interrupt
context with the GFP_ATOMIC flag.
Size is the length of the region you want to allocate, in bytes.
@@ -415,7 +423,7 @@ exists (for example) to guarantee that if you allocate a chunk
which is smaller than or equal to 64 kilobytes, the extent of the
buffer you receive will not cross a 64K boundary.
-To unmap and free such a DMA region, you call:
+To unmap and free such a DMA region, you call::
dma_free_coherent(dev, size, cpu_addr, dma_handle);
@@ -430,7 +438,7 @@ a kmem_cache, but it uses dma_alloc_coherent(), not __get_free_pages().
Also, it understands common hardware constraints for alignment,
like queue heads needing to be aligned on N byte boundaries.
-Create a dma_pool like this:
+Create a dma_pool like this::
struct dma_pool *pool;
@@ -444,7 +452,7 @@ pass 0 for boundary; passing 4096 says memory allocated from this pool
must not cross 4KByte boundaries (but at that time it may be better to
use dma_alloc_coherent() directly instead).
-Allocate memory from a DMA pool like this:
+Allocate memory from a DMA pool like this::
cpu_addr = dma_pool_alloc(pool, flags, &dma_handle);
@@ -452,7 +460,7 @@ flags are GFP_KERNEL if blocking is permitted (not in_interrupt nor
holding SMP locks), GFP_ATOMIC otherwise. Like dma_alloc_coherent(),
this returns two values, cpu_addr and dma_handle.
-Free memory that was allocated from a dma_pool like this:
+Free memory that was allocated from a dma_pool like this::
dma_pool_free(pool, cpu_addr, dma_handle);
@@ -460,7 +468,7 @@ where pool is what you passed to dma_pool_alloc(), and cpu_addr and
dma_handle are the values dma_pool_alloc() returned. This function
may be called in interrupt context.
-Destroy a dma_pool by calling:
+Destroy a dma_pool by calling::
dma_pool_destroy(pool);
@@ -468,11 +476,12 @@ Make sure you've called dma_pool_free() for all memory allocated
from a pool before you destroy the pool. This function may not
be called in interrupt context.
- DMA Direction
+DMA Direction
+=============
The interfaces described in subsequent portions of this document
take a DMA direction argument, which is an integer and takes on
-one of the following values:
+one of the following values::
DMA_BIDIRECTIONAL
DMA_TO_DEVICE
@@ -521,14 +530,15 @@ packets, map/unmap them with the DMA_TO_DEVICE direction
specifier. For receive packets, just the opposite, map/unmap them
with the DMA_FROM_DEVICE direction specifier.
- Using Streaming DMA mappings
+Using Streaming DMA mappings
+============================
The streaming DMA mapping routines can be called from interrupt
context. There are two versions of each map/unmap, one which will
map/unmap a single memory region, and one which will map/unmap a
scatterlist.
-To map a single region, you do:
+To map a single region, you do::
struct device *dev = &my_dev->dev;
dma_addr_t dma_handle;
@@ -545,7 +555,7 @@ To map a single region, you do:
goto map_error_handling;
}
-and to unmap it:
+and to unmap it::
dma_unmap_single(dev, dma_handle, size, direction);
@@ -561,7 +571,8 @@ to check for errors that make assumptions about the underlying DMA
implementation are as follows and these are applicable to dma_map_page() as
well.
-Incorrect example 1:
+Incorrect example 1::
+
dma_addr_t dma_handle;
dma_handle = dma_map_single(dev, addr, size, direction);
@@ -569,7 +580,8 @@ Incorrect example 1:
goto map_error;
}
-Incorrect example 2:
+Incorrect example 2::
+
dma_addr_t dma_handle;
dma_handle = dma_map_single(dev, addr, size, direction);
@@ -584,7 +596,7 @@ Using CPU pointers like this for single mappings has a disadvantage:
you cannot reference HIGHMEM memory in this way. Thus, there is a
map/unmap interface pair akin to dma_{map,unmap}_single(). These
interfaces deal with page/offset pairs instead of CPU pointers.
-Specifically:
+Specifically::
struct device *dev = &my_dev->dev;
dma_addr_t dma_handle;
@@ -614,7 +626,7 @@ error as outlined under the dma_map_single() discussion.
You should call dma_unmap_page() when the DMA activity is finished, e.g.,
from the interrupt which told you that the DMA transfer is done.
-With scatterlists, you map a region gathered from several regions by:
+With scatterlists, you map a region gathered from several regions by::
int i, count = dma_map_sg(dev, sglist, nents, direction);
struct scatterlist *sg;
@@ -638,16 +650,18 @@ Then you should loop count times (note: this can be less than nents times)
and use sg_dma_address() and sg_dma_len() macros where you previously
accessed sg->address and sg->length as shown above.
-To unmap a scatterlist, just call:
+To unmap a scatterlist, just call::
dma_unmap_sg(dev, sglist, nents, direction);
Again, make sure DMA activity has already finished.
-PLEASE NOTE: The 'nents' argument to the dma_unmap_sg call must be
- the _same_ one you passed into the dma_map_sg call,
- it should _NOT_ be the 'count' value _returned_ from the
- dma_map_sg call.
+.. note::
+
+ The 'nents' argument to the dma_unmap_sg call must be
+ the _same_ one you passed into the dma_map_sg call,
+ it should _NOT_ be the 'count' value _returned_ from the
+ dma_map_sg call.
Every dma_map_{single,sg}() call should have its dma_unmap_{single,sg}()
counterpart, because the DMA address space is a shared resource and
@@ -659,11 +673,11 @@ properly in order for the CPU and device to see the most up-to-date and
correct copy of the DMA buffer.
So, firstly, just map it with dma_map_{single,sg}(), and after each DMA
-transfer call either:
+transfer call either::
dma_sync_single_for_cpu(dev, dma_handle, size, direction);
-or:
+or::
dma_sync_sg_for_cpu(dev, sglist, nents, direction);
@@ -671,17 +685,19 @@ as appropriate.
Then, if you wish to let the device get at the DMA area again,
finish accessing the data with the CPU, and then before actually
-giving the buffer to the hardware call either:
+giving the buffer to the hardware call either::
dma_sync_single_for_device(dev, dma_handle, size, direction);
-or:
+or::
dma_sync_sg_for_device(dev, sglist, nents, direction);
as appropriate.
-PLEASE NOTE: The 'nents' argument to dma_sync_sg_for_cpu() and
+.. note::
+
+ The 'nents' argument to dma_sync_sg_for_cpu() and
dma_sync_sg_for_device() must be the same passed to
dma_map_sg(). It is _NOT_ the count returned by
dma_map_sg().
@@ -692,7 +708,7 @@ dma_map_*() call till dma_unmap_*(), then you don't have to call the
dma_sync_*() routines at all.
Here is pseudo code which shows a situation in which you would need
-to use the dma_sync_*() interfaces.
+to use the dma_sync_*() interfaces::
my_card_setup_receive_buffer(struct my_card *cp, char *buffer, int len)
{
@@ -768,7 +784,8 @@ is planned to completely remove virt_to_bus() and bus_to_virt() as
they are entirely deprecated. Some ports already do not provide these
as it is impossible to correctly support them.
- Handling Errors
+Handling Errors
+===============
DMA address space is limited on some architectures and an allocation
failure can be determined by:
@@ -776,7 +793,7 @@ failure can be determined by:
- checking if dma_alloc_coherent() returns NULL or dma_map_sg returns 0
- checking the dma_addr_t returned from dma_map_single() and dma_map_page()
- by using dma_mapping_error():
+ by using dma_mapping_error()::
dma_addr_t dma_handle;
@@ -794,7 +811,8 @@ failure can be determined by:
of a multiple page mapping attempt. These example are applicable to
dma_map_page() as well.
-Example 1:
+Example 1::
+
dma_addr_t dma_handle1;
dma_addr_t dma_handle2;
@@ -823,8 +841,12 @@ Example 1:
dma_unmap_single(dma_handle1);
map_error_handling1:
-Example 2: (if buffers are allocated in a loop, unmap all mapped buffers when
- mapping error is detected in the middle)
+Example 2::
+
+ /*
+ * if buffers are allocated in a loop, unmap all mapped buffers when
+ * mapping error is detected in the middle
+ */
dma_addr_t dma_addr;
dma_addr_t array[DMA_BUFFERS];
@@ -867,7 +889,8 @@ SCSI drivers must return SCSI_MLQUEUE_HOST_BUSY if the DMA mapping
fails in the queuecommand hook. This means that the SCSI subsystem
passes the command to the driver again later.
- Optimizing Unmap State Space Consumption
+Optimizing Unmap State Space Consumption
+========================================
On many platforms, dma_unmap_{single,page}() is simply a nop.
Therefore, keeping track of the mapping address and length is a waste
@@ -879,7 +902,7 @@ Actually, instead of describing the macros one by one, we'll
transform some example code.
1) Use DEFINE_DMA_UNMAP_{ADDR,LEN} in state saving structures.
- Example, before:
+ Example, before::
struct ring_state {
struct sk_buff *skb;
@@ -887,7 +910,7 @@ transform some example code.
__u32 len;
};
- after:
+ after::
struct ring_state {
struct sk_buff *skb;
@@ -896,23 +919,23 @@ transform some example code.
};
2) Use dma_unmap_{addr,len}_set() to set these values.
- Example, before:
+ Example, before::
ringp->mapping = FOO;
ringp->len = BAR;
- after:
+ after::
dma_unmap_addr_set(ringp, mapping, FOO);
dma_unmap_len_set(ringp, len, BAR);
3) Use dma_unmap_{addr,len}() to access these values.
- Example, before:
+ Example, before::
dma_unmap_single(dev, ringp->mapping, ringp->len,
DMA_FROM_DEVICE);
- after:
+ after::
dma_unmap_single(dev,
dma_unmap_addr(ringp, mapping),
@@ -923,7 +946,8 @@ It really should be self-explanatory. We treat the ADDR and LEN
separately, because it is possible for an implementation to only
need the address in order to perform the unmap operation.
- Platform Issues
+Platform Issues
+===============
If you are just writing drivers for Linux and do not maintain
an architecture port for the kernel, you can safely skip down
@@ -949,12 +973,13 @@ to "Closing".
alignment constraints (e.g. the alignment constraints about 64-bit
objects).
- Closing
+Closing
+=======
This document, and the API itself, would not be in its current
form without the feedback and suggestions from numerous individuals.
We would like to specifically mention, in no particular order, the
-following people:
+following people::
Russell King <rmk@arm.linux.org.uk>
Leo Dagum <dagum@barrel.engr.sgi.com>
--
2.9.4
^ permalink raw reply related [flat|nested] 37+ messages in thread* [PATCH 16/31] DMA-attributes.txt: standardize document format
2017-05-19 1:22 [PATCH 00/31] Standardize doc formats - part 1 Mauro Carvalho Chehab
` (14 preceding siblings ...)
2017-05-19 1:22 ` [PATCH 15/31] DMA-API-HOWTO.txt: " Mauro Carvalho Chehab
@ 2017-05-19 1:22 ` Mauro Carvalho Chehab
2017-05-19 1:22 ` [PATCH 17/31] DMA-ISA-LPC.txt: " Mauro Carvalho Chehab
` (14 subsequent siblings)
30 siblings, 0 replies; 37+ messages in thread
From: Mauro Carvalho Chehab @ 2017-05-19 1:22 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, David Woodhouse, Brian Norris, Boris Brezillon,
Marek Vasut, Richard Weinberger, Cyrille Pitchen, linux-mtd
Each text file under Documentation follows a different
format. Some doesn't even have titles!
Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
This file is almost on the standard format. All it needs
to be parsed by Sphinx is to fix its main title and add
a few blank lines.
Yet, it is worth to replace NOTE: by the corresponding
ReST markup.
While here, remove the extra "---" from a subtitle.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/DMA-attributes.txt | 15 +++++++++------
1 file changed, 9 insertions(+), 6 deletions(-)
diff --git a/Documentation/DMA-attributes.txt b/Documentation/DMA-attributes.txt
index 44c6bc496eee..8f8d97f65d73 100644
--- a/Documentation/DMA-attributes.txt
+++ b/Documentation/DMA-attributes.txt
@@ -1,5 +1,6 @@
- DMA attributes
- ==============
+==============
+DMA attributes
+==============
This document describes the semantics of the DMA attributes that are
defined in linux/dma-mapping.h.
@@ -108,6 +109,7 @@ This is a hint to the DMA-mapping subsystem that it's probably not worth
the time to try to allocate memory to in a way that gives better TLB
efficiency (AKA it's not worth trying to build the mapping out of larger
pages). You might want to specify this if:
+
- You know that the accesses to this memory won't thrash the TLB.
You might know that the accesses are likely to be sequential or
that they aren't sequential but it's unlikely you'll ping-pong
@@ -121,11 +123,12 @@ pages). You might want to specify this if:
the mapping to have a short lifetime then it may be worth it to
optimize allocation (avoid coming up with large pages) instead of
getting the slight performance win of larger pages.
+
Setting this hint doesn't guarantee that you won't get huge pages, but it
means that we won't try quite as hard to get them.
-NOTE: At the moment DMA_ATTR_ALLOC_SINGLE_PAGES is only implemented on ARM,
-though ARM64 patches will likely be posted soon.
+.. note:: At the moment DMA_ATTR_ALLOC_SINGLE_PAGES is only implemented on ARM,
+ though ARM64 patches will likely be posted soon.
DMA_ATTR_NO_WARN
----------------
@@ -142,10 +145,10 @@ problem at all, depending on the implementation of the retry mechanism.
So, this provides a way for drivers to avoid those error messages on calls
where allocation failures are not a problem, and shouldn't bother the logs.
-NOTE: At the moment DMA_ATTR_NO_WARN is only implemented on PowerPC.
+.. note:: At the moment DMA_ATTR_NO_WARN is only implemented on PowerPC.
DMA_ATTR_PRIVILEGED
-------------------------------
+-------------------
Some advanced peripherals such as remote processors and GPUs perform
accesses to DMA buffers in both privileged "supervisor" and unprivileged
--
2.9.4
^ permalink raw reply related [flat|nested] 37+ messages in thread* [PATCH 17/31] DMA-ISA-LPC.txt: standardize document format
2017-05-19 1:22 [PATCH 00/31] Standardize doc formats - part 1 Mauro Carvalho Chehab
` (15 preceding siblings ...)
2017-05-19 1:22 ` [PATCH 16/31] DMA-attributes.txt: " Mauro Carvalho Chehab
@ 2017-05-19 1:22 ` Mauro Carvalho Chehab
2017-05-19 1:22 ` [PATCH 18/31] debugging-via-ohci1394.txt: " Mauro Carvalho Chehab
` (13 subsequent siblings)
30 siblings, 0 replies; 37+ messages in thread
From: Mauro Carvalho Chehab @ 2017-05-19 1:22 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, David Woodhouse, Brian Norris, Boris Brezillon,
Marek Vasut, Richard Weinberger, Cyrille Pitchen, linux-mtd
Each text file under Documentation follows a different
format. Some doesn't even have titles!
Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- use proper markups for titles;
- use :Author: for authorship;
- identify the literal blocks.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/DMA-ISA-LPC.txt | 71 ++++++++++++++++++++++---------------------
1 file changed, 36 insertions(+), 35 deletions(-)
diff --git a/Documentation/DMA-ISA-LPC.txt b/Documentation/DMA-ISA-LPC.txt
index c41331398752..c44be1a2176f 100644
--- a/Documentation/DMA-ISA-LPC.txt
+++ b/Documentation/DMA-ISA-LPC.txt
@@ -1,19 +1,20 @@
- DMA with ISA and LPC devices
- ============================
+============================
+DMA with ISA and LPC devices
+============================
- Pierre Ossman <drzeus@drzeus.cx>
+:Author: Pierre Ossman <drzeus@drzeus.cx>
This document describes how to do DMA transfers using the old ISA DMA
controller. Even though ISA is more or less dead today the LPC bus
uses the same DMA system so it will be around for quite some time.
-Part I - Headers and dependencies
----------------------------------
+Headers and dependencies
+------------------------
-To do ISA style DMA you need to include two headers:
+To do ISA style DMA you need to include two headers::
-#include <linux/dma-mapping.h>
-#include <asm/dma.h>
+ #include <linux/dma-mapping.h>
+ #include <asm/dma.h>
The first is the generic DMA API used to convert virtual addresses to
bus addresses (see Documentation/DMA-API.txt for details).
@@ -23,8 +24,8 @@ this is not present on all platforms make sure you construct your
Kconfig to be dependent on ISA_DMA_API (not ISA) so that nobody tries
to build your driver on unsupported platforms.
-Part II - Buffer allocation
----------------------------
+Buffer allocation
+-----------------
The ISA DMA controller has some very strict requirements on which
memory it can access so extra care must be taken when allocating
@@ -47,8 +48,8 @@ __GFP_REPEAT and __GFP_NOWARN to make the allocator try a bit harder.
(This scarcity also means that you should allocate the buffer as
early as possible and not release it until the driver is unloaded.)
-Part III - Address translation
-------------------------------
+Address translation
+-------------------
To translate the virtual address to a bus address, use the normal DMA
API. Do _not_ use isa_virt_to_phys() even though it does the same
@@ -61,8 +62,8 @@ Note: x86_64 had a broken DMA API when it came to ISA but has since
been fixed. If your arch has problems then fix the DMA API instead of
reverting to the ISA functions.
-Part IV - Channels
-------------------
+Channels
+--------
A normal ISA DMA controller has 8 channels. The lower four are for
8-bit transfers and the upper four are for 16-bit transfers.
@@ -80,8 +81,8 @@ The ability to use 16-bit or 8-bit transfers is _not_ up to you as a
driver author but depends on what the hardware supports. Check your
specs or test different channels.
-Part V - Transfer data
-----------------------
+Transfer data
+-------------
Now for the good stuff, the actual DMA transfer. :)
@@ -112,37 +113,37 @@ Once the DMA transfer is finished (or timed out) you should disable
the channel again. You should also check get_dma_residue() to make
sure that all data has been transferred.
-Example:
+Example::
-int flags, residue;
+ int flags, residue;
-flags = claim_dma_lock();
+ flags = claim_dma_lock();
-clear_dma_ff();
+ clear_dma_ff();
-set_dma_mode(channel, DMA_MODE_WRITE);
-set_dma_addr(channel, phys_addr);
-set_dma_count(channel, num_bytes);
+ set_dma_mode(channel, DMA_MODE_WRITE);
+ set_dma_addr(channel, phys_addr);
+ set_dma_count(channel, num_bytes);
-dma_enable(channel);
+ dma_enable(channel);
-release_dma_lock(flags);
+ release_dma_lock(flags);
-while (!device_done());
+ while (!device_done());
-flags = claim_dma_lock();
+ flags = claim_dma_lock();
-dma_disable(channel);
+ dma_disable(channel);
-residue = dma_get_residue(channel);
-if (residue != 0)
- printk(KERN_ERR "driver: Incomplete DMA transfer!"
- " %d bytes left!\n", residue);
+ residue = dma_get_residue(channel);
+ if (residue != 0)
+ printk(KERN_ERR "driver: Incomplete DMA transfer!"
+ " %d bytes left!\n", residue);
-release_dma_lock(flags);
+ release_dma_lock(flags);
-Part VI - Suspend/resume
-------------------------
+Suspend/resume
+--------------
It is the driver's responsibility to make sure that the machine isn't
suspended while a DMA transfer is in progress. Also, all DMA settings
--
2.9.4
^ permalink raw reply related [flat|nested] 37+ messages in thread* [PATCH 18/31] debugging-via-ohci1394.txt: standardize document format
2017-05-19 1:22 [PATCH 00/31] Standardize doc formats - part 1 Mauro Carvalho Chehab
` (16 preceding siblings ...)
2017-05-19 1:22 ` [PATCH 17/31] DMA-ISA-LPC.txt: " Mauro Carvalho Chehab
@ 2017-05-19 1:22 ` Mauro Carvalho Chehab
2017-05-19 1:22 ` [PATCH 19/31] efi-stub.txt: " Mauro Carvalho Chehab
` (12 subsequent siblings)
30 siblings, 0 replies; 37+ messages in thread
From: Mauro Carvalho Chehab @ 2017-05-19 1:22 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, David Woodhouse, Brian Norris, Boris Brezillon,
Marek Vasut, Richard Weinberger, Cyrille Pitchen, linux-mtd
Each text file under Documentation follows a different
format. Some doesn't even have titles!
Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- Mark and adjust titles;
- Mark and indent literal blocks.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/debugging-via-ohci1394.txt | 21 +++++++++++----------
1 file changed, 11 insertions(+), 10 deletions(-)
diff --git a/Documentation/debugging-via-ohci1394.txt b/Documentation/debugging-via-ohci1394.txt
index 9ff026d22b75..981ad4f89fd3 100644
--- a/Documentation/debugging-via-ohci1394.txt
+++ b/Documentation/debugging-via-ohci1394.txt
@@ -1,6 +1,6 @@
-
- Using physical DMA provided by OHCI-1394 FireWire controllers for debugging
- ---------------------------------------------------------------------------
+===========================================================================
+Using physical DMA provided by OHCI-1394 FireWire controllers for debugging
+===========================================================================
Introduction
------------
@@ -91,10 +91,10 @@ Step-by-step instructions for using firescope with early OHCI initialization:
1) Verify that your hardware is supported:
Load the firewire-ohci module and check your kernel logs.
- You should see a line similar to
+ You should see a line similar to::
- firewire_ohci 0000:15:00.1: added OHCI v1.0 device as card 2, 4 IR + 4 IT
- ... contexts, quirks 0x11
+ firewire_ohci 0000:15:00.1: added OHCI v1.0 device as card 2, 4 IR + 4 IT
+ ... contexts, quirks 0x11
when loading the driver. If you have no supported controller, many PCI,
CardBus and even some Express cards which are fully compliant to OHCI-1394
@@ -113,9 +113,9 @@ Step-by-step instructions for using firescope with early OHCI initialization:
stable connection and has matching connectors (there are small 4-pin and
large 6-pin FireWire ports) will do.
- If an driver is running on both machines you should see a line like
+ If an driver is running on both machines you should see a line like::
- firewire_core 0000:15:00.1: created device fw1: GUID 00061b0020105917, S400
+ firewire_core 0000:15:00.1: created device fw1: GUID 00061b0020105917, S400
on both machines in the kernel log when the cable is plugged in
and connects the two machines.
@@ -123,7 +123,7 @@ Step-by-step instructions for using firescope with early OHCI initialization:
3) Test physical DMA using firescope:
On the debug host, make sure that /dev/fw* is accessible,
- then start firescope:
+ then start firescope::
$ firescope
Port 0 (/dev/fw1) opened, 2 nodes detected
@@ -163,7 +163,7 @@ Step-by-step instructions for using firescope with early OHCI initialization:
host loaded, reboot the debugged machine, booting the kernel which has
CONFIG_PROVIDE_OHCI1394_DMA_INIT enabled, with the option ohci1394_dma=early.
- Then, on the debugging host, run firescope, for example by using -A:
+ Then, on the debugging host, run firescope, for example by using -A::
firescope -A System.map-of-debug-target-kernel
@@ -178,6 +178,7 @@ Step-by-step instructions for using firescope with early OHCI initialization:
Notes
-----
+
Documentation and specifications: http://halobates.de/firewire/
FireWire is a trademark of Apple Inc. - for more information please refer to:
--
2.9.4
^ permalink raw reply related [flat|nested] 37+ messages in thread* [PATCH 19/31] efi-stub.txt: standardize document format
2017-05-19 1:22 [PATCH 00/31] Standardize doc formats - part 1 Mauro Carvalho Chehab
` (17 preceding siblings ...)
2017-05-19 1:22 ` [PATCH 18/31] debugging-via-ohci1394.txt: " Mauro Carvalho Chehab
@ 2017-05-19 1:22 ` Mauro Carvalho Chehab
2017-05-19 1:22 ` [PATCH 20/31] eisa.txt: " Mauro Carvalho Chehab
` (11 subsequent siblings)
30 siblings, 0 replies; 37+ messages in thread
From: Mauro Carvalho Chehab @ 2017-05-19 1:22 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, David Woodhouse, Brian Norris, Boris Brezillon,
Marek Vasut, Richard Weinberger, Cyrille Pitchen, linux-mtd
Each text file under Documentation follows a different
format. Some doesn't even have titles!
Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- use proper markups for titles;
- identify literal blocks.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/efi-stub.txt | 25 +++++++++++++++----------
1 file changed, 15 insertions(+), 10 deletions(-)
diff --git a/Documentation/efi-stub.txt b/Documentation/efi-stub.txt
index e15746988261..41df801f9a50 100644
--- a/Documentation/efi-stub.txt
+++ b/Documentation/efi-stub.txt
@@ -1,5 +1,6 @@
- The EFI Boot Stub
- ---------------------------
+=================
+The EFI Boot Stub
+=================
On the x86 and ARM platforms, a kernel zImage/bzImage can masquerade
as a PE/COFF image, thereby convincing EFI firmware loaders to load
@@ -25,7 +26,8 @@ a certain sense it *IS* the boot loader.
The EFI boot stub is enabled with the CONFIG_EFI_STUB kernel option.
-**** How to install bzImage.efi
+How to install bzImage.efi
+--------------------------
The bzImage located in arch/x86/boot/bzImage must be copied to the EFI
System Partition (ESP) and renamed with the extension ".efi". Without
@@ -37,14 +39,16 @@ may not need to be renamed. Similarly for arm64, arch/arm64/boot/Image
should be copied but not necessarily renamed.
-**** Passing kernel parameters from the EFI shell
+Passing kernel parameters from the EFI shell
+--------------------------------------------
-Arguments to the kernel can be passed after bzImage.efi, e.g.
+Arguments to the kernel can be passed after bzImage.efi, e.g.::
fs0:> bzImage.efi console=ttyS0 root=/dev/sda4
-**** The "initrd=" option
+The "initrd=" option
+--------------------
Like most boot loaders, the EFI stub allows the user to specify
multiple initrd files using the "initrd=" option. This is the only EFI
@@ -54,9 +58,9 @@ kernel when it boots.
The path to the initrd file must be an absolute path from the
beginning of the ESP, relative path names do not work. Also, the path
is an EFI-style path and directory elements must be separated with
-backslashes (\). For example, given the following directory layout,
+backslashes (\). For example, given the following directory layout::
-fs0:>
+ fs0:>
Kernels\
bzImage.efi
initrd-large.img
@@ -66,7 +70,7 @@ fs0:>
initrd-medium.img
to boot with the initrd-large.img file if the current working
-directory is fs0:\Kernels, the following command must be used,
+directory is fs0:\Kernels, the following command must be used::
fs0:\Kernels> bzImage.efi initrd=\Kernels\initrd-large.img
@@ -76,7 +80,8 @@ which understands relative paths, whereas the rest of the command line
is passed to bzImage.efi.
-**** The "dtb=" option
+The "dtb=" option
+-----------------
For the ARM and arm64 architectures, we also need to be able to provide a
device tree to the kernel. This is done with the "dtb=" command line option,
--
2.9.4
^ permalink raw reply related [flat|nested] 37+ messages in thread* [PATCH 20/31] eisa.txt: standardize document format
2017-05-19 1:22 [PATCH 00/31] Standardize doc formats - part 1 Mauro Carvalho Chehab
` (18 preceding siblings ...)
2017-05-19 1:22 ` [PATCH 19/31] efi-stub.txt: " Mauro Carvalho Chehab
@ 2017-05-19 1:22 ` Mauro Carvalho Chehab
2017-05-19 1:22 ` [PATCH 21/31] flexible-arrays.txt: " Mauro Carvalho Chehab
` (10 subsequent siblings)
30 siblings, 0 replies; 37+ messages in thread
From: Mauro Carvalho Chehab @ 2017-05-19 1:22 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, David Woodhouse, Brian Norris, Boris Brezillon,
Marek Vasut, Richard Weinberger, Cyrille Pitchen, linux-mtd
Each text file under Documentation follows a different
format. Some doesn't even have titles!
Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- use ReST notation for titles;
- identify literal blocks;
- use :Author: for document authorship;
- use the proper notation for tables;
- adjust whitespaces where needed.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/eisa.txt | 260 +++++++++++++++++++++++++++----------------------
1 file changed, 143 insertions(+), 117 deletions(-)
diff --git a/Documentation/eisa.txt b/Documentation/eisa.txt
index a55e4910924e..8e2c6e2b2a19 100644
--- a/Documentation/eisa.txt
+++ b/Documentation/eisa.txt
@@ -1,4 +1,7 @@
-EISA bus support (Marc Zyngier <maz@wild-wind.fr.eu.org>)
+EISA bus support
+================
+
+:Author: Marc Zyngier <maz@wild-wind.fr.eu.org>
This document groups random notes about porting EISA drivers to the
new EISA/sysfs API.
@@ -14,168 +17,189 @@ detection code is generally also used to probe ISA cards). Moreover,
most EISA drivers are among the oldest Linux drivers so, as you can
imagine, some dust has settled here over the years.
-The EISA infrastructure is made up of three parts :
+The EISA infrastructure is made up of three parts:
- The bus code implements most of the generic code. It is shared
- among all the architectures that the EISA code runs on. It
- implements bus probing (detecting EISA cards available on the bus),
- allocates I/O resources, allows fancy naming through sysfs, and
- offers interfaces for driver to register.
+ among all the architectures that the EISA code runs on. It
+ implements bus probing (detecting EISA cards available on the bus),
+ allocates I/O resources, allows fancy naming through sysfs, and
+ offers interfaces for driver to register.
- The bus root driver implements the glue between the bus hardware
- and the generic bus code. It is responsible for discovering the
- device implementing the bus, and setting it up to be latter probed
- by the bus code. This can go from something as simple as reserving
- an I/O region on x86, to the rather more complex, like the hppa
- EISA code. This is the part to implement in order to have EISA
- running on an "new" platform.
+ and the generic bus code. It is responsible for discovering the
+ device implementing the bus, and setting it up to be latter probed
+ by the bus code. This can go from something as simple as reserving
+ an I/O region on x86, to the rather more complex, like the hppa
+ EISA code. This is the part to implement in order to have EISA
+ running on an "new" platform.
- The driver offers the bus a list of devices that it manages, and
- implements the necessary callbacks to probe and release devices
- whenever told to.
+ implements the necessary callbacks to probe and release devices
+ whenever told to.
Every function/structure below lives in <linux/eisa.h>, which depends
heavily on <linux/device.h>.
-** Bus root driver :
+Bus root driver
+===============
-int eisa_root_register (struct eisa_root_device *root);
+::
+
+ int eisa_root_register (struct eisa_root_device *root);
The eisa_root_register function is used to declare a device as the
root of an EISA bus. The eisa_root_device structure holds a reference
-to this device, as well as some parameters for probing purposes.
+to this device, as well as some parameters for probing purposes::
-struct eisa_root_device {
- struct device *dev; /* Pointer to bridge device */
- struct resource *res;
- unsigned long bus_base_addr;
- int slots; /* Max slot number */
- int force_probe; /* Probe even when no slot 0 */
- u64 dma_mask; /* from bridge device */
- int bus_nr; /* Set by eisa_root_register */
- struct resource eisa_root_res; /* ditto */
-};
+ struct eisa_root_device {
+ struct device *dev; /* Pointer to bridge device */
+ struct resource *res;
+ unsigned long bus_base_addr;
+ int slots; /* Max slot number */
+ int force_probe; /* Probe even when no slot 0 */
+ u64 dma_mask; /* from bridge device */
+ int bus_nr; /* Set by eisa_root_register */
+ struct resource eisa_root_res; /* ditto */
+ };
-node : used for eisa_root_register internal purpose
-dev : pointer to the root device
-res : root device I/O resource
-bus_base_addr : slot 0 address on this bus
-slots : max slot number to probe
-force_probe : Probe even when slot 0 is empty (no EISA mainboard)
-dma_mask : Default DMA mask. Usually the bridge device dma_mask.
-bus_nr : unique bus id, set by eisa_root_register
+============= ======================================================
+node used for eisa_root_register internal purpose
+dev pointer to the root device
+res root device I/O resource
+bus_base_addr slot 0 address on this bus
+slots max slot number to probe
+force_probe Probe even when slot 0 is empty (no EISA mainboard)
+dma_mask Default DMA mask. Usually the bridge device dma_mask.
+bus_nr unique bus id, set by eisa_root_register
+============= ======================================================
-** Driver :
+Driver
+======
-int eisa_driver_register (struct eisa_driver *edrv);
-void eisa_driver_unregister (struct eisa_driver *edrv);
+::
+
+ int eisa_driver_register (struct eisa_driver *edrv);
+ void eisa_driver_unregister (struct eisa_driver *edrv);
Clear enough ?
-struct eisa_device_id {
- char sig[EISA_SIG_LEN];
- unsigned long driver_data;
-};
-
-struct eisa_driver {
- const struct eisa_device_id *id_table;
- struct device_driver driver;
-};
-
-id_table : an array of NULL terminated EISA id strings,
- followed by an empty string. Each string can
- optionally be paired with a driver-dependent value
- (driver_data).
-
-driver : a generic driver, such as described in
- Documentation/driver-model/driver.txt. Only .name,
- .probe and .remove members are mandatory.
-
-An example is the 3c59x driver :
-
-static struct eisa_device_id vortex_eisa_ids[] = {
- { "TCM5920", EISA_3C592_OFFSET },
- { "TCM5970", EISA_3C597_OFFSET },
- { "" }
-};
-
-static struct eisa_driver vortex_eisa_driver = {
- .id_table = vortex_eisa_ids,
- .driver = {
- .name = "3c59x",
- .probe = vortex_eisa_probe,
- .remove = vortex_eisa_remove
- }
-};
-
-** Device :
+::
+
+ struct eisa_device_id {
+ char sig[EISA_SIG_LEN];
+ unsigned long driver_data;
+ };
+
+ struct eisa_driver {
+ const struct eisa_device_id *id_table;
+ struct device_driver driver;
+ };
+
+=============== ====================================================
+id_table an array of NULL terminated EISA id strings,
+ followed by an empty string. Each string can
+ optionally be paired with a driver-dependent value
+ (driver_data).
+
+driver a generic driver, such as described in
+ Documentation/driver-model/driver.txt. Only .name,
+ .probe and .remove members are mandatory.
+=============== ====================================================
+
+An example is the 3c59x driver::
+
+ static struct eisa_device_id vortex_eisa_ids[] = {
+ { "TCM5920", EISA_3C592_OFFSET },
+ { "TCM5970", EISA_3C597_OFFSET },
+ { "" }
+ };
+
+ static struct eisa_driver vortex_eisa_driver = {
+ .id_table = vortex_eisa_ids,
+ .driver = {
+ .name = "3c59x",
+ .probe = vortex_eisa_probe,
+ .remove = vortex_eisa_remove
+ }
+ };
+
+Device
+======
The sysfs framework calls .probe and .remove functions upon device
discovery and removal (note that the .remove function is only called
when driver is built as a module).
Both functions are passed a pointer to a 'struct device', which is
-encapsulated in a 'struct eisa_device' described as follows :
+encapsulated in a 'struct eisa_device' described as follows::
-struct eisa_device {
- struct eisa_device_id id;
- int slot;
- int state;
- unsigned long base_addr;
- struct resource res[EISA_MAX_RESOURCES];
- u64 dma_mask;
- struct device dev; /* generic device */
-};
+ struct eisa_device {
+ struct eisa_device_id id;
+ int slot;
+ int state;
+ unsigned long base_addr;
+ struct resource res[EISA_MAX_RESOURCES];
+ u64 dma_mask;
+ struct device dev; /* generic device */
+ };
-id : EISA id, as read from device. id.driver_data is set from the
- matching driver EISA id.
-slot : slot number which the device was detected on
-state : set of flags indicating the state of the device. Current
- flags are EISA_CONFIG_ENABLED and EISA_CONFIG_FORCED.
-res : set of four 256 bytes I/O regions allocated to this device
-dma_mask: DMA mask set from the parent device.
-dev : generic device (see Documentation/driver-model/device.txt)
+======== ============================================================
+id EISA id, as read from device. id.driver_data is set from the
+ matching driver EISA id.
+slot slot number which the device was detected on
+state set of flags indicating the state of the device. Current
+ flags are EISA_CONFIG_ENABLED and EISA_CONFIG_FORCED.
+res set of four 256 bytes I/O regions allocated to this device
+dma_mask DMA mask set from the parent device.
+dev generic device (see Documentation/driver-model/device.txt)
+======== ============================================================
You can get the 'struct eisa_device' from 'struct device' using the
'to_eisa_device' macro.
-** Misc stuff :
+Misc stuff
+==========
-void eisa_set_drvdata (struct eisa_device *edev, void *data);
+::
+
+ void eisa_set_drvdata (struct eisa_device *edev, void *data);
Stores data into the device's driver_data area.
-void *eisa_get_drvdata (struct eisa_device *edev):
+::
+
+ void *eisa_get_drvdata (struct eisa_device *edev):
Gets the pointer previously stored into the device's driver_data area.
-int eisa_get_region_index (void *addr);
+::
+
+ int eisa_get_region_index (void *addr);
Returns the region number (0 <= x < EISA_MAX_RESOURCES) of a given
address.
-** Kernel parameters :
+Kernel parameters
+=================
-eisa_bus.enable_dev :
+eisa_bus.enable_dev
+ A comma-separated list of slots to be enabled, even if the firmware
+ set the card as disabled. The driver must be able to properly
+ initialize the device in such conditions.
-A comma-separated list of slots to be enabled, even if the firmware
-set the card as disabled. The driver must be able to properly
-initialize the device in such conditions.
+eisa_bus.disable_dev
+ A comma-separated list of slots to be enabled, even if the firmware
+ set the card as enabled. The driver won't be called to handle this
+ device.
-eisa_bus.disable_dev :
+virtual_root.force_probe
+ Force the probing code to probe EISA slots even when it cannot find an
+ EISA compliant mainboard (nothing appears on slot 0). Defaults to 0
+ (don't force), and set to 1 (force probing) when either
+ CONFIG_ALPHA_JENSEN or CONFIG_EISA_VLB_PRIMING are set.
-A comma-separated list of slots to be enabled, even if the firmware
-set the card as enabled. The driver won't be called to handle this
-device.
-
-virtual_root.force_probe :
-
-Force the probing code to probe EISA slots even when it cannot find an
-EISA compliant mainboard (nothing appears on slot 0). Defaults to 0
-(don't force), and set to 1 (force probing) when either
-CONFIG_ALPHA_JENSEN or CONFIG_EISA_VLB_PRIMING are set.
-
-** Random notes :
+Random notes
+============
Converting an EISA driver to the new API mostly involves *deleting*
code (since probing is now in the core EISA code). Unfortunately, most
@@ -194,9 +218,11 @@ routine.
For example, switching your favorite EISA SCSI card to the "hotplug"
model is "the right thing"(tm).
-** Thanks :
+Thanks
+======
+
+I'd like to thank the following people for their help:
-I'd like to thank the following people for their help :
- Xavier Benigni for lending me a wonderful Alpha Jensen,
- James Bottomley, Jeff Garzik for getting this stuff into the kernel,
- Andries Brouwer for contributing numerous EISA ids,
--
2.9.4
^ permalink raw reply related [flat|nested] 37+ messages in thread* [PATCH 21/31] flexible-arrays.txt: standardize document format
2017-05-19 1:22 [PATCH 00/31] Standardize doc formats - part 1 Mauro Carvalho Chehab
` (19 preceding siblings ...)
2017-05-19 1:22 ` [PATCH 20/31] eisa.txt: " Mauro Carvalho Chehab
@ 2017-05-19 1:22 ` Mauro Carvalho Chehab
2017-05-19 1:22 ` [PATCH 22/31] futex-requeue-pi.txt: " Mauro Carvalho Chehab
` (9 subsequent siblings)
30 siblings, 0 replies; 37+ messages in thread
From: Mauro Carvalho Chehab @ 2017-05-19 1:22 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, David Woodhouse, Brian Norris, Boris Brezillon,
Marek Vasut, Richard Weinberger, Cyrille Pitchen, linux-mtd
Each text file under Documentation follows a different
format. Some doesn't even have titles!
Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- use :Author: and :Updated: markups;
- use proper markup for the document title;
- mark the literal-blocks.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/flexible-arrays.txt | 24 +++++++++++++-----------
1 file changed, 13 insertions(+), 11 deletions(-)
diff --git a/Documentation/flexible-arrays.txt b/Documentation/flexible-arrays.txt
index df904aec9904..45aec4d354f7 100644
--- a/Documentation/flexible-arrays.txt
+++ b/Documentation/flexible-arrays.txt
@@ -1,6 +1,8 @@
Using flexible arrays in the kernel
-Last updated for 2.6.32
-Jonathan Corbet <corbet@lwn.net>
+===================================
+
+:Updated: Last updated for 2.6.32
+:Author: Jonathan Corbet <corbet@lwn.net>
Large contiguous memory allocations can be unreliable in the Linux kernel.
Kernel programmers will sometimes respond to this problem by allocating
@@ -26,7 +28,7 @@ operation. It's also worth noting that flexible arrays do no internal
locking at all; if concurrent access to an array is possible, then the
caller must arrange for appropriate mutual exclusion.
-The creation of a flexible array is done with:
+The creation of a flexible array is done with::
#include <linux/flex_array.h>
@@ -40,14 +42,14 @@ argument is passed directly to the internal memory allocation calls. With
the current code, using flags to ask for high memory is likely to lead to
notably unpleasant side effects.
-It is also possible to define flexible arrays at compile time with:
+It is also possible to define flexible arrays at compile time with::
DEFINE_FLEX_ARRAY(name, element_size, total);
This macro will result in a definition of an array with the given name; the
element size and total will be checked for validity at compile time.
-Storing data into a flexible array is accomplished with a call to:
+Storing data into a flexible array is accomplished with a call to::
int flex_array_put(struct flex_array *array, unsigned int element_nr,
void *src, gfp_t flags);
@@ -63,7 +65,7 @@ running in some sort of atomic context; in this situation, sleeping in the
memory allocator would be a bad thing. That can be avoided by using
GFP_ATOMIC for the flags value, but, often, there is a better way. The
trick is to ensure that any needed memory allocations are done before
-entering atomic context, using:
+entering atomic context, using::
int flex_array_prealloc(struct flex_array *array, unsigned int start,
unsigned int nr_elements, gfp_t flags);
@@ -73,7 +75,7 @@ defined by start and nr_elements has been allocated. Thereafter, a
flex_array_put() call on an element in that range is guaranteed not to
block.
-Getting data back out of the array is done with:
+Getting data back out of the array is done with::
void *flex_array_get(struct flex_array *fa, unsigned int element_nr);
@@ -89,7 +91,7 @@ involving that number probably result from use of unstored array entries.
Note that, if array elements are allocated with __GFP_ZERO, they will be
initialized to zero and this poisoning will not happen.
-Individual elements in the array can be cleared with:
+Individual elements in the array can be cleared with::
int flex_array_clear(struct flex_array *array, unsigned int element_nr);
@@ -97,7 +99,7 @@ This function will set the given element to FLEX_ARRAY_FREE and return
zero. If storage for the indicated element is not allocated for the array,
flex_array_clear() will return -EINVAL instead. Note that clearing an
element does not release the storage associated with it; to reduce the
-allocated size of an array, call:
+allocated size of an array, call::
int flex_array_shrink(struct flex_array *array);
@@ -106,12 +108,12 @@ This function works by scanning the array for pages containing nothing but
FLEX_ARRAY_FREE bytes, so (1) it can be expensive, and (2) it will not work
if the array's pages are allocated with __GFP_ZERO.
-It is possible to remove all elements of an array with a call to:
+It is possible to remove all elements of an array with a call to::
void flex_array_free_parts(struct flex_array *array);
This call frees all elements, but leaves the array itself in place.
-Freeing the entire array is done with:
+Freeing the entire array is done with::
void flex_array_free(struct flex_array *array);
--
2.9.4
^ permalink raw reply related [flat|nested] 37+ messages in thread* [PATCH 22/31] futex-requeue-pi.txt: standardize document format
2017-05-19 1:22 [PATCH 00/31] Standardize doc formats - part 1 Mauro Carvalho Chehab
` (20 preceding siblings ...)
2017-05-19 1:22 ` [PATCH 21/31] flexible-arrays.txt: " Mauro Carvalho Chehab
@ 2017-05-19 1:22 ` Mauro Carvalho Chehab
2017-05-19 1:22 ` [PATCH 23/31] gcc-plugins.txt: " Mauro Carvalho Chehab
` (8 subsequent siblings)
30 siblings, 0 replies; 37+ messages in thread
From: Mauro Carvalho Chehab @ 2017-05-19 1:22 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, David Woodhouse, Brian Norris, Boris Brezillon,
Marek Vasut, Richard Weinberger, Cyrille Pitchen, linux-mtd,
Thomas Gleixner, Ingo Molnar, Peter Zijlstra, Darren Hart
Each text file under Documentation follows a different
format. Some doesn't even have titles!
Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- promote level for the document title;
- mark literal blocks.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/futex-requeue-pi.txt | 83 +++++++++++++++++++-------------------
1 file changed, 42 insertions(+), 41 deletions(-)
diff --git a/Documentation/futex-requeue-pi.txt b/Documentation/futex-requeue-pi.txt
index 77b36f59d16b..14ab5787b9a7 100644
--- a/Documentation/futex-requeue-pi.txt
+++ b/Documentation/futex-requeue-pi.txt
@@ -1,5 +1,6 @@
+================
Futex Requeue PI
-----------------
+================
Requeueing of tasks from a non-PI futex to a PI futex requires
special handling in order to ensure the underlying rt_mutex is never
@@ -20,28 +21,28 @@ implementation would wake the highest-priority waiter, and leave the
rest to the natural wakeup inherent in unlocking the mutex
associated with the condvar.
-Consider the simplified glibc calls:
+Consider the simplified glibc calls::
-/* caller must lock mutex */
-pthread_cond_wait(cond, mutex)
-{
- lock(cond->__data.__lock);
- unlock(mutex);
- do {
- unlock(cond->__data.__lock);
- futex_wait(cond->__data.__futex);
- lock(cond->__data.__lock);
- } while(...)
- unlock(cond->__data.__lock);
- lock(mutex);
-}
+ /* caller must lock mutex */
+ pthread_cond_wait(cond, mutex)
+ {
+ lock(cond->__data.__lock);
+ unlock(mutex);
+ do {
+ unlock(cond->__data.__lock);
+ futex_wait(cond->__data.__futex);
+ lock(cond->__data.__lock);
+ } while(...)
+ unlock(cond->__data.__lock);
+ lock(mutex);
+ }
-pthread_cond_broadcast(cond)
-{
- lock(cond->__data.__lock);
- unlock(cond->__data.__lock);
- futex_requeue(cond->data.__futex, cond->mutex);
-}
+ pthread_cond_broadcast(cond)
+ {
+ lock(cond->__data.__lock);
+ unlock(cond->__data.__lock);
+ futex_requeue(cond->data.__futex, cond->mutex);
+ }
Once pthread_cond_broadcast() requeues the tasks, the cond->mutex
has waiters. Note that pthread_cond_wait() attempts to lock the
@@ -53,29 +54,29 @@ In order to support PI-aware pthread_condvar's, the kernel needs to
be able to requeue tasks to PI futexes. This support implies that
upon a successful futex_wait system call, the caller would return to
user space already holding the PI futex. The glibc implementation
-would be modified as follows:
+would be modified as follows::
-/* caller must lock mutex */
-pthread_cond_wait_pi(cond, mutex)
-{
- lock(cond->__data.__lock);
- unlock(mutex);
- do {
- unlock(cond->__data.__lock);
- futex_wait_requeue_pi(cond->__data.__futex);
- lock(cond->__data.__lock);
- } while(...)
- unlock(cond->__data.__lock);
- /* the kernel acquired the mutex for us */
-}
+ /* caller must lock mutex */
+ pthread_cond_wait_pi(cond, mutex)
+ {
+ lock(cond->__data.__lock);
+ unlock(mutex);
+ do {
+ unlock(cond->__data.__lock);
+ futex_wait_requeue_pi(cond->__data.__futex);
+ lock(cond->__data.__lock);
+ } while(...)
+ unlock(cond->__data.__lock);
+ /* the kernel acquired the mutex for us */
+ }
-pthread_cond_broadcast_pi(cond)
-{
- lock(cond->__data.__lock);
- unlock(cond->__data.__lock);
- futex_requeue_pi(cond->data.__futex, cond->mutex);
-}
+ pthread_cond_broadcast_pi(cond)
+ {
+ lock(cond->__data.__lock);
+ unlock(cond->__data.__lock);
+ futex_requeue_pi(cond->data.__futex, cond->mutex);
+ }
The actual glibc implementation will likely test for PI and make the
necessary changes inside the existing calls rather than creating new
--
2.9.4
^ permalink raw reply related [flat|nested] 37+ messages in thread* [PATCH 23/31] gcc-plugins.txt: standardize document format
2017-05-19 1:22 [PATCH 00/31] Standardize doc formats - part 1 Mauro Carvalho Chehab
` (21 preceding siblings ...)
2017-05-19 1:22 ` [PATCH 22/31] futex-requeue-pi.txt: " Mauro Carvalho Chehab
@ 2017-05-19 1:22 ` Mauro Carvalho Chehab
2017-05-24 17:35 ` Kees Cook
2017-05-19 1:22 ` [PATCH 24/31] highuid.txt: " Mauro Carvalho Chehab
` (7 subsequent siblings)
30 siblings, 1 reply; 37+ messages in thread
From: Mauro Carvalho Chehab @ 2017-05-19 1:22 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, David Woodhouse, Brian Norris, Boris Brezillon,
Marek Vasut, Richard Weinberger, Cyrille Pitchen, linux-mtd,
Kees Cook, Emese Revfy, kernel-hardening
Each text file under Documentation follows a different
format. Some doesn't even have titles!
Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- promote main title;
- use the right markup for footnotes;
- use bold markup for files name;
- identify literal blocks;
- add blank lines to avoid Sphinx to complain;
- remove numeration from titles.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/gcc-plugins.txt | 58 ++++++++++++++++++++++++-------------------
1 file changed, 32 insertions(+), 26 deletions(-)
diff --git a/Documentation/gcc-plugins.txt b/Documentation/gcc-plugins.txt
index 433eaefb4aa1..8502f24396fb 100644
--- a/Documentation/gcc-plugins.txt
+++ b/Documentation/gcc-plugins.txt
@@ -1,14 +1,15 @@
+=========================
GCC plugin infrastructure
=========================
-1. Introduction
-===============
+Introduction
+============
GCC plugins are loadable modules that provide extra features to the
-compiler [1]. They are useful for runtime instrumentation and static analysis.
+compiler [1]_. They are useful for runtime instrumentation and static analysis.
We can analyse, change and add further code during compilation via
-callbacks [2], GIMPLE [3], IPA [4] and RTL passes [5].
+callbacks [2]_, GIMPLE [3]_, IPA [4]_ and RTL passes [5]_.
The GCC plugin infrastructure of the kernel supports all gcc versions from
4.5 to 6.0, building out-of-tree modules, cross-compilation and building in a
@@ -21,56 +22,61 @@ and versions 4.8+ can only be compiled by a C++ compiler.
Currently the GCC plugin infrastructure supports only the x86, arm, arm64 and
powerpc architectures.
-This infrastructure was ported from grsecurity [6] and PaX [7].
+This infrastructure was ported from grsecurity [6]_ and PaX [7]_.
--
-[1] https://gcc.gnu.org/onlinedocs/gccint/Plugins.html
-[2] https://gcc.gnu.org/onlinedocs/gccint/Plugin-API.html#Plugin-API
-[3] https://gcc.gnu.org/onlinedocs/gccint/GIMPLE.html
-[4] https://gcc.gnu.org/onlinedocs/gccint/IPA.html
-[5] https://gcc.gnu.org/onlinedocs/gccint/RTL.html
-[6] https://grsecurity.net/
-[7] https://pax.grsecurity.net/
+.. [1] https://gcc.gnu.org/onlinedocs/gccint/Plugins.html
+.. [2] https://gcc.gnu.org/onlinedocs/gccint/Plugin-API.html#Plugin-API
+.. [3] https://gcc.gnu.org/onlinedocs/gccint/GIMPLE.html
+.. [4] https://gcc.gnu.org/onlinedocs/gccint/IPA.html
+.. [5] https://gcc.gnu.org/onlinedocs/gccint/RTL.html
+.. [6] https://grsecurity.net/
+.. [7] https://pax.grsecurity.net/
-2. Files
-========
-$(src)/scripts/gcc-plugins
+Files
+=====
+
+**$(src)/scripts/gcc-plugins**
+
This is the directory of the GCC plugins.
-$(src)/scripts/gcc-plugins/gcc-common.h
+**$(src)/scripts/gcc-plugins/gcc-common.h**
+
This is a compatibility header for GCC plugins.
It should be always included instead of individual gcc headers.
-$(src)/scripts/gcc-plugin.sh
+**$(src)/scripts/gcc-plugin.sh**
+
This script checks the availability of the included headers in
gcc-common.h and chooses the proper host compiler to build the plugins
(gcc-4.7 can be built by either gcc or g++).
-$(src)/scripts/gcc-plugins/gcc-generate-gimple-pass.h
-$(src)/scripts/gcc-plugins/gcc-generate-ipa-pass.h
-$(src)/scripts/gcc-plugins/gcc-generate-simple_ipa-pass.h
-$(src)/scripts/gcc-plugins/gcc-generate-rtl-pass.h
+**$(src)/scripts/gcc-plugins/gcc-generate-gimple-pass.h,
+$(src)/scripts/gcc-plugins/gcc-generate-ipa-pass.h,
+$(src)/scripts/gcc-plugins/gcc-generate-simple_ipa-pass.h,
+$(src)/scripts/gcc-plugins/gcc-generate-rtl-pass.h**
+
These headers automatically generate the registration structures for
GIMPLE, SIMPLE_IPA, IPA and RTL passes. They support all gcc versions
from 4.5 to 6.0.
They should be preferred to creating the structures by hand.
-3. Usage
-========
+Usage
+=====
You must install the gcc plugin headers for your gcc version,
-e.g., on Ubuntu for gcc-4.9:
+e.g., on Ubuntu for gcc-4.9::
apt-get install gcc-4.9-plugin-dev
-Enable a GCC plugin based feature in the kernel config:
+Enable a GCC plugin based feature in the kernel config::
CONFIG_GCC_PLUGIN_CYC_COMPLEXITY = y
-To compile only the plugin(s):
+To compile only the plugin(s)::
make gcc-plugins
--
2.9.4
^ permalink raw reply related [flat|nested] 37+ messages in thread* Re: [PATCH 23/31] gcc-plugins.txt: standardize document format
2017-05-19 1:22 ` [PATCH 23/31] gcc-plugins.txt: " Mauro Carvalho Chehab
@ 2017-05-24 17:35 ` Kees Cook
2017-05-24 20:18 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 37+ messages in thread
From: Kees Cook @ 2017-05-24 17:35 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, LKML,
Jonathan Corbet, David Woodhouse, Brian Norris, Boris Brezillon,
Marek Vasut, Richard Weinberger, Cyrille Pitchen, Linux mtd,
Emese Revfy, kernel-hardening
On Thu, May 18, 2017 at 6:22 PM, Mauro Carvalho Chehab
<mchehab@s-opensource.com> wrote:
> Each text file under Documentation follows a different
> format. Some doesn't even have titles!
>
> Change its representation to follow the adopted standard,
> using ReST markups for it to be parseable by Sphinx:
>
> - promote main title;
> - use the right markup for footnotes;
> - use bold markup for files name;
> - identify literal blocks;
> - add blank lines to avoid Sphinx to complain;
> - remove numeration from titles.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Acked-by: Kees Cook <keescook@chromium.org>
This should probably get moved under "Kernel API documentation" but
may need a new sub-category, maybe "instrumentation"? Things like
KASan could be put under that too.
-Kees
--
Kees Cook
Pixel Security
^ permalink raw reply [flat|nested] 37+ messages in thread
* Re: [PATCH 23/31] gcc-plugins.txt: standardize document format
2017-05-24 17:35 ` Kees Cook
@ 2017-05-24 20:18 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 37+ messages in thread
From: Mauro Carvalho Chehab @ 2017-05-24 20:18 UTC (permalink / raw)
To: Kees Cook
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, LKML,
Jonathan Corbet, David Woodhouse, Brian Norris, Boris Brezillon,
Marek Vasut, Richard Weinberger, Cyrille Pitchen, Linux mtd,
Emese Revfy, kernel-hardening
Em Wed, 24 May 2017 10:35:42 -0700
Kees Cook <keescook@google.com> escreveu:
> On Thu, May 18, 2017 at 6:22 PM, Mauro Carvalho Chehab
> <mchehab@s-opensource.com> wrote:
> > Each text file under Documentation follows a different
> > format. Some doesn't even have titles!
> >
> > Change its representation to follow the adopted standard,
> > using ReST markups for it to be parseable by Sphinx:
> >
> > - promote main title;
> > - use the right markup for footnotes;
> > - use bold markup for files name;
> > - identify literal blocks;
> > - add blank lines to avoid Sphinx to complain;
> > - remove numeration from titles.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
>
> Acked-by: Kees Cook <keescook@chromium.org>
>
> This should probably get moved under "Kernel API documentation" but
> may need a new sub-category, maybe "instrumentation"? Things like
> KASan could be put under that too.
Yeah, I guess that most documents under Documentation/
will need to be renamed and placed into an existing or new book.
Kasan documentation is currently under dev-tools, with is, currently,
an unsorted book with:
coccinelle
sparse
kcov
gcov
kasan
ubsan
kmemleak
kmemcheck
gdb-kernel-debugging
kgdb
I agree with you: it probably makes sense to split external development
tools, like coccinelle/sparse from Kernel instrumentation, like kgdb,
kasan, gcc-plugins, etc.
So, perhaps we can change the content of Documentation/dev-tools/index.rst
to something like.
================================
Development tools for the kernel
================================
This document describe tools and instrumentation features of the Linux Kernel
used by developers to do quality assurance (QA).
This section describes Kernel internal features designed to provide mechanisms
for developers to test their code.
.. toctree::
:maxdepth: 2
(add here books like kasan, printk related docs, gcc-plugins, etc)
This section describes external tools used to ensure Kernel quality
assurance (QA).
.. toctree::
:maxdepth: 2
(add here books related external tools and robots, like coccinelle,
sparse, kernel build robot, ktest, Coverity, etc)
.. only:: subproject and html
Indices
=======
* :ref:`genindex`
Cheers,
Mauro
^ permalink raw reply [flat|nested] 37+ messages in thread
* [PATCH 24/31] highuid.txt: standardize document format
2017-05-19 1:22 [PATCH 00/31] Standardize doc formats - part 1 Mauro Carvalho Chehab
` (22 preceding siblings ...)
2017-05-19 1:22 ` [PATCH 23/31] gcc-plugins.txt: " Mauro Carvalho Chehab
@ 2017-05-19 1:22 ` Mauro Carvalho Chehab
2017-05-19 1:22 ` [PATCH 25/31] hw_random.txt: " Mauro Carvalho Chehab
` (6 subsequent siblings)
30 siblings, 0 replies; 37+ messages in thread
From: Mauro Carvalho Chehab @ 2017-05-19 1:22 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, David Woodhouse, Brian Norris, Boris Brezillon,
Marek Vasut, Richard Weinberger, Cyrille Pitchen, linux-mtd
Each text file under Documentation follows a different
format. Some doesn't even have titles!
Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- use a markup for the title;
- use :Author: and :Last updated: markups at the beginning with
authorship info;
- use proper markups for the lists.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/highuid.txt | 46 ++++++++++++++++++++++++----------------------
1 file changed, 24 insertions(+), 22 deletions(-)
diff --git a/Documentation/highuid.txt b/Documentation/highuid.txt
index 6bad6f1d1cac..ae024b3fe4ef 100644
--- a/Documentation/highuid.txt
+++ b/Documentation/highuid.txt
@@ -1,4 +1,8 @@
-Notes on the change from 16-bit UIDs to 32-bit UIDs:
+Notes on the change from 16-bit UIDs to 32-bit UIDs
+===================================================
+
+:Author: Chris Wing <wingc@umich.edu>
+:Last updated: January 11, 2000
- kernel code MUST take into account __kernel_uid_t and __kernel_uid32_t
when communicating between user and kernel space in an ioctl or data
@@ -28,30 +32,34 @@ What's left to be done for 32-bit UIDs on all Linux architectures:
uses the 32-bit UID system calls properly otherwise.
This affects at least:
- iBCS on Intel
- sparc32 emulation on sparc64
- (need to support whatever new 32-bit UID system calls are added to
- sparc32)
+ - iBCS on Intel
+
+ - sparc32 emulation on sparc64
+ (need to support whatever new 32-bit UID system calls are added to
+ sparc32)
- Validate that all filesystems behave properly.
At present, 32-bit UIDs _should_ work for:
- ext2
- ufs
- isofs
- nfs
- coda
- udf
+
+ - ext2
+ - ufs
+ - isofs
+ - nfs
+ - coda
+ - udf
Ioctl() fixups have been made for:
- ncpfs
- smbfs
+
+ - ncpfs
+ - smbfs
Filesystems with simple fixups to prevent 16-bit UID wraparound:
- minix
- sysv
- qnx4
+
+ - minix
+ - sysv
+ - qnx4
Other filesystems have not been checked yet.
@@ -69,9 +77,3 @@ What's left to be done for 32-bit UIDs on all Linux architectures:
- make sure that the UID mapping feature of AX25 networking works properly
(it should be safe because it's always used a 32-bit integer to
communicate between user and kernel)
-
-
-Chris Wing
-wingc@umich.edu
-
-last updated: January 11, 2000
--
2.9.4
^ permalink raw reply related [flat|nested] 37+ messages in thread* [PATCH 25/31] hw_random.txt: standardize document format
2017-05-19 1:22 [PATCH 00/31] Standardize doc formats - part 1 Mauro Carvalho Chehab
` (23 preceding siblings ...)
2017-05-19 1:22 ` [PATCH 24/31] highuid.txt: " Mauro Carvalho Chehab
@ 2017-05-19 1:22 ` Mauro Carvalho Chehab
2017-05-19 1:22 ` [PATCH 26/31] hwspinlock.txt: " Mauro Carvalho Chehab
` (5 subsequent siblings)
30 siblings, 0 replies; 37+ messages in thread
From: Mauro Carvalho Chehab @ 2017-05-19 1:22 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, David Woodhouse, Brian Norris, Boris Brezillon,
Marek Vasut, Richard Weinberger, Cyrille Pitchen, linux-mtd,
Matt Mackall, Herbert Xu, linux-crypto
Each text file under Documentation follows a different
format. Some doesn't even have titles!
Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- use proper markups for titles;
- adjust section identation;
- use proper markup for notes and fix it to properly show the
numbered list.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/hw_random.txt | 158 ++++++++++++++++++++++++--------------------
1 file changed, 86 insertions(+), 72 deletions(-)
diff --git a/Documentation/hw_random.txt b/Documentation/hw_random.txt
index fce1634907d0..865e997d9d3b 100644
--- a/Documentation/hw_random.txt
+++ b/Documentation/hw_random.txt
@@ -1,90 +1,104 @@
-Introduction:
-
- The hw_random framework is software that makes use of a
- special hardware feature on your CPU or motherboard,
- a Random Number Generator (RNG). The software has two parts:
- a core providing the /dev/hwrng character device and its
- sysfs support, plus a hardware-specific driver that plugs
- into that core.
-
- To make the most effective use of these mechanisms, you
- should download the support software as well. Download the
- latest version of the "rng-tools" package from the
- hw_random driver's official Web site:
-
- http://sourceforge.net/projects/gkernel/
-
- Those tools use /dev/hwrng to fill the kernel entropy pool,
- which is used internally and exported by the /dev/urandom and
- /dev/random special files.
-
-Theory of operation:
-
- CHARACTER DEVICE. Using the standard open()
- and read() system calls, you can read random data from
- the hardware RNG device. This data is NOT CHECKED by any
- fitness tests, and could potentially be bogus (if the
- hardware is faulty or has been tampered with). Data is only
- output if the hardware "has-data" flag is set, but nevertheless
- a security-conscious person would run fitness tests on the
- data before assuming it is truly random.
-
- The rng-tools package uses such tests in "rngd", and lets you
- run them by hand with a "rngtest" utility.
-
- /dev/hwrng is char device major 10, minor 183.
-
- CLASS DEVICE. There is a /sys/class/misc/hw_random node with
- two unique attributes, "rng_available" and "rng_current". The
- "rng_available" attribute lists the hardware-specific drivers
- available, while "rng_current" lists the one which is currently
- connected to /dev/hwrng. If your system has more than one
- RNG available, you may change the one used by writing a name from
- the list in "rng_available" into "rng_current".
+Linux support for random number generator in i8xx chipsets
+==========================================================
+
+Introduction
+============
+
+The hw_random framework is software that makes use of a
+special hardware feature on your CPU or motherboard,
+a Random Number Generator (RNG). The software has two parts:
+a core providing the /dev/hwrng character device and its
+sysfs support, plus a hardware-specific driver that plugs
+into that core.
+
+To make the most effective use of these mechanisms, you
+should download the support software as well. Download the
+latest version of the "rng-tools" package from the
+hw_random driver's official Web site:
+
+ http://sourceforge.net/projects/gkernel/
+
+Those tools use /dev/hwrng to fill the kernel entropy pool,
+which is used internally and exported by the /dev/urandom and
+/dev/random special files.
+
+Theory of operation
+===================
+
+CHARACTER DEVICE. Using the standard open()
+and read() system calls, you can read random data from
+the hardware RNG device. This data is NOT CHECKED by any
+fitness tests, and could potentially be bogus (if the
+hardware is faulty or has been tampered with). Data is only
+output if the hardware "has-data" flag is set, but nevertheless
+a security-conscious person would run fitness tests on the
+data before assuming it is truly random.
+
+The rng-tools package uses such tests in "rngd", and lets you
+run them by hand with a "rngtest" utility.
+
+/dev/hwrng is char device major 10, minor 183.
+
+CLASS DEVICE. There is a /sys/class/misc/hw_random node with
+two unique attributes, "rng_available" and "rng_current". The
+"rng_available" attribute lists the hardware-specific drivers
+available, while "rng_current" lists the one which is currently
+connected to /dev/hwrng. If your system has more than one
+RNG available, you may change the one used by writing a name from
+the list in "rng_available" into "rng_current".
==========================================================================
- Hardware driver for Intel/AMD/VIA Random Number Generators (RNG)
- Copyright 2000,2001 Jeff Garzik <jgarzik@pobox.com>
- Copyright 2000,2001 Philipp Rumpf <prumpf@mandrakesoft.com>
+Hardware driver for Intel/AMD/VIA Random Number Generators (RNG)
+ - Copyright 2000,2001 Jeff Garzik <jgarzik@pobox.com>
+ - Copyright 2000,2001 Philipp Rumpf <prumpf@mandrakesoft.com>
-About the Intel RNG hardware, from the firmware hub datasheet:
- The Firmware Hub integrates a Random Number Generator (RNG)
- using thermal noise generated from inherently random quantum
- mechanical properties of silicon. When not generating new random
- bits the RNG circuitry will enter a low power state. Intel will
- provide a binary software driver to give third party software
- access to our RNG for use as a security feature. At this time,
- the RNG is only to be used with a system in an OS-present state.
+About the Intel RNG hardware, from the firmware hub datasheet
+=============================================================
-Intel RNG Driver notes:
+The Firmware Hub integrates a Random Number Generator (RNG)
+using thermal noise generated from inherently random quantum
+mechanical properties of silicon. When not generating new random
+bits the RNG circuitry will enter a low power state. Intel will
+provide a binary software driver to give third party software
+access to our RNG for use as a security feature. At this time,
+the RNG is only to be used with a system in an OS-present state.
- * FIXME: support poll(2)
+Intel RNG Driver notes
+======================
- NOTE: request_mem_region was removed, for three reasons:
- 1) Only one RNG is supported by this driver, 2) The location
- used by the RNG is a fixed location in MMIO-addressable memory,
+FIXME: support poll(2)
+
+.. note::
+
+ request_mem_region was removed, for three reasons:
+
+ 1) Only one RNG is supported by this driver;
+ 2) The location used by the RNG is a fixed location in
+ MMIO-addressable memory;
3) users with properly working BIOS e820 handling will always
- have the region in which the RNG is located reserved, so
- request_mem_region calls always fail for proper setups.
- However, for people who use mem=XX, BIOS e820 information is
- -not- in /proc/iomem, and request_mem_region(RNG_ADDR) can
- succeed.
+ have the region in which the RNG is located reserved, so
+ request_mem_region calls always fail for proper setups.
+ However, for people who use mem=XX, BIOS e820 information is
+ **not** in /proc/iomem, and request_mem_region(RNG_ADDR) can
+ succeed.
-Driver details:
+Driver details
+==============
- Based on:
+Based on:
Intel 82802AB/82802AC Firmware Hub (FWH) Datasheet
- May 1999 Order Number: 290658-002 R
+ May 1999 Order Number: 290658-002 R
- Intel 82802 Firmware Hub: Random Number Generator
+Intel 82802 Firmware Hub:
+ Random Number Generator
Programmer's Reference Manual
- December 1999 Order Number: 298029-001 R
+ December 1999 Order Number: 298029-001 R
- Intel 82802 Firmware HUB Random Number Generator Driver
+Intel 82802 Firmware HUB Random Number Generator Driver
Copyright (c) 2000 Matt Sottek <msottek@quiknet.com>
- Special thanks to Matt Sottek. I did the "guts", he
- did the "brains" and all the testing.
+Special thanks to Matt Sottek. I did the "guts", he
+did the "brains" and all the testing.
--
2.9.4
^ permalink raw reply related [flat|nested] 37+ messages in thread* [PATCH 26/31] hwspinlock.txt: standardize document format
2017-05-19 1:22 [PATCH 00/31] Standardize doc formats - part 1 Mauro Carvalho Chehab
` (24 preceding siblings ...)
2017-05-19 1:22 ` [PATCH 25/31] hw_random.txt: " Mauro Carvalho Chehab
@ 2017-05-19 1:22 ` Mauro Carvalho Chehab
2017-05-19 1:22 ` [PATCH 27/31] intel_txt.txt: " Mauro Carvalho Chehab
` (4 subsequent siblings)
30 siblings, 0 replies; 37+ messages in thread
From: Mauro Carvalho Chehab @ 2017-05-19 1:22 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, David Woodhouse, Brian Norris, Boris Brezillon,
Marek Vasut, Richard Weinberger, Cyrille Pitchen, linux-mtd,
Ohad Ben-Cohen, Bjorn Andersson, linux-remoteproc
Each text file under Documentation follows a different
format. Some doesn't even have titles!
Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- Adjust title markups;
- remove explicit numeration from titles;
- mark literal blocks as such;
- replace _foo_ by **foo** for emphasis;
- adjust whitespaces and add blank lines where needed.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/hwspinlock.txt | 527 +++++++++++++++++++++++++------------------
1 file changed, 307 insertions(+), 220 deletions(-)
diff --git a/Documentation/hwspinlock.txt b/Documentation/hwspinlock.txt
index 61c1ee98e59f..ed640a278185 100644
--- a/Documentation/hwspinlock.txt
+++ b/Documentation/hwspinlock.txt
@@ -1,6 +1,9 @@
+===========================
Hardware Spinlock Framework
+===========================
-1. Introduction
+Introduction
+============
Hardware spinlock modules provide hardware assistance for synchronization
and mutual exclusion between heterogeneous processors and those not operating
@@ -32,286 +35,370 @@ structure).
A common hwspinlock interface makes it possible to have generic, platform-
independent, drivers.
-2. User API
+User API
+========
+
+::
struct hwspinlock *hwspin_lock_request(void);
- - dynamically assign an hwspinlock and return its address, or NULL
- in case an unused hwspinlock isn't available. Users of this
- API will usually want to communicate the lock's id to the remote core
- before it can be used to achieve synchronization.
- Should be called from a process context (might sleep).
+
+Dynamically assign an hwspinlock and return its address, or NULL
+in case an unused hwspinlock isn't available. Users of this
+API will usually want to communicate the lock's id to the remote core
+before it can be used to achieve synchronization.
+
+Should be called from a process context (might sleep).
+
+::
struct hwspinlock *hwspin_lock_request_specific(unsigned int id);
- - assign a specific hwspinlock id and return its address, or NULL
- if that hwspinlock is already in use. Usually board code will
- be calling this function in order to reserve specific hwspinlock
- ids for predefined purposes.
- Should be called from a process context (might sleep).
+
+Assign a specific hwspinlock id and return its address, or NULL
+if that hwspinlock is already in use. Usually board code will
+be calling this function in order to reserve specific hwspinlock
+ids for predefined purposes.
+
+Should be called from a process context (might sleep).
+
+::
int of_hwspin_lock_get_id(struct device_node *np, int index);
- - retrieve the global lock id for an OF phandle-based specific lock.
- This function provides a means for DT users of a hwspinlock module
- to get the global lock id of a specific hwspinlock, so that it can
- be requested using the normal hwspin_lock_request_specific() API.
- The function returns a lock id number on success, -EPROBE_DEFER if
- the hwspinlock device is not yet registered with the core, or other
- error values.
- Should be called from a process context (might sleep).
+
+Retrieve the global lock id for an OF phandle-based specific lock.
+This function provides a means for DT users of a hwspinlock module
+to get the global lock id of a specific hwspinlock, so that it can
+be requested using the normal hwspin_lock_request_specific() API.
+
+The function returns a lock id number on success, -EPROBE_DEFER if
+the hwspinlock device is not yet registered with the core, or other
+error values.
+
+Should be called from a process context (might sleep).
+
+::
int hwspin_lock_free(struct hwspinlock *hwlock);
- - free a previously-assigned hwspinlock; returns 0 on success, or an
- appropriate error code on failure (e.g. -EINVAL if the hwspinlock
- is already free).
- Should be called from a process context (might sleep).
+
+Free a previously-assigned hwspinlock; returns 0 on success, or an
+appropriate error code on failure (e.g. -EINVAL if the hwspinlock
+is already free).
+
+Should be called from a process context (might sleep).
+
+::
int hwspin_lock_timeout(struct hwspinlock *hwlock, unsigned int timeout);
- - lock a previously-assigned hwspinlock with a timeout limit (specified in
- msecs). If the hwspinlock is already taken, the function will busy loop
- waiting for it to be released, but give up when the timeout elapses.
- Upon a successful return from this function, preemption is disabled so
- the caller must not sleep, and is advised to release the hwspinlock as
- soon as possible, in order to minimize remote cores polling on the
- hardware interconnect.
- Returns 0 when successful and an appropriate error code otherwise (most
- notably -ETIMEDOUT if the hwspinlock is still busy after timeout msecs).
- The function will never sleep.
+
+Lock a previously-assigned hwspinlock with a timeout limit (specified in
+msecs). If the hwspinlock is already taken, the function will busy loop
+waiting for it to be released, but give up when the timeout elapses.
+Upon a successful return from this function, preemption is disabled so
+the caller must not sleep, and is advised to release the hwspinlock as
+soon as possible, in order to minimize remote cores polling on the
+hardware interconnect.
+
+Returns 0 when successful and an appropriate error code otherwise (most
+notably -ETIMEDOUT if the hwspinlock is still busy after timeout msecs).
+The function will never sleep.
+
+::
int hwspin_lock_timeout_irq(struct hwspinlock *hwlock, unsigned int timeout);
- - lock a previously-assigned hwspinlock with a timeout limit (specified in
- msecs). If the hwspinlock is already taken, the function will busy loop
- waiting for it to be released, but give up when the timeout elapses.
- Upon a successful return from this function, preemption and the local
- interrupts are disabled, so the caller must not sleep, and is advised to
- release the hwspinlock as soon as possible.
- Returns 0 when successful and an appropriate error code otherwise (most
- notably -ETIMEDOUT if the hwspinlock is still busy after timeout msecs).
- The function will never sleep.
+
+Lock a previously-assigned hwspinlock with a timeout limit (specified in
+msecs). If the hwspinlock is already taken, the function will busy loop
+waiting for it to be released, but give up when the timeout elapses.
+Upon a successful return from this function, preemption and the local
+interrupts are disabled, so the caller must not sleep, and is advised to
+release the hwspinlock as soon as possible.
+
+Returns 0 when successful and an appropriate error code otherwise (most
+notably -ETIMEDOUT if the hwspinlock is still busy after timeout msecs).
+The function will never sleep.
+
+::
int hwspin_lock_timeout_irqsave(struct hwspinlock *hwlock, unsigned int to,
- unsigned long *flags);
- - lock a previously-assigned hwspinlock with a timeout limit (specified in
- msecs). If the hwspinlock is already taken, the function will busy loop
- waiting for it to be released, but give up when the timeout elapses.
- Upon a successful return from this function, preemption is disabled,
- local interrupts are disabled and their previous state is saved at the
- given flags placeholder. The caller must not sleep, and is advised to
- release the hwspinlock as soon as possible.
- Returns 0 when successful and an appropriate error code otherwise (most
- notably -ETIMEDOUT if the hwspinlock is still busy after timeout msecs).
- The function will never sleep.
+ unsigned long *flags);
+
+Lock a previously-assigned hwspinlock with a timeout limit (specified in
+msecs). If the hwspinlock is already taken, the function will busy loop
+waiting for it to be released, but give up when the timeout elapses.
+Upon a successful return from this function, preemption is disabled,
+local interrupts are disabled and their previous state is saved at the
+given flags placeholder. The caller must not sleep, and is advised to
+release the hwspinlock as soon as possible.
+
+Returns 0 when successful and an appropriate error code otherwise (most
+notably -ETIMEDOUT if the hwspinlock is still busy after timeout msecs).
+
+The function will never sleep.
+
+::
int hwspin_trylock(struct hwspinlock *hwlock);
- - attempt to lock a previously-assigned hwspinlock, but immediately fail if
- it is already taken.
- Upon a successful return from this function, preemption is disabled so
- caller must not sleep, and is advised to release the hwspinlock as soon as
- possible, in order to minimize remote cores polling on the hardware
- interconnect.
- Returns 0 on success and an appropriate error code otherwise (most
- notably -EBUSY if the hwspinlock was already taken).
- The function will never sleep.
+
+
+Attempt to lock a previously-assigned hwspinlock, but immediately fail if
+it is already taken.
+
+Upon a successful return from this function, preemption is disabled so
+caller must not sleep, and is advised to release the hwspinlock as soon as
+possible, in order to minimize remote cores polling on the hardware
+interconnect.
+
+Returns 0 on success and an appropriate error code otherwise (most
+notably -EBUSY if the hwspinlock was already taken).
+The function will never sleep.
+
+::
int hwspin_trylock_irq(struct hwspinlock *hwlock);
- - attempt to lock a previously-assigned hwspinlock, but immediately fail if
- it is already taken.
- Upon a successful return from this function, preemption and the local
- interrupts are disabled so caller must not sleep, and is advised to
- release the hwspinlock as soon as possible.
- Returns 0 on success and an appropriate error code otherwise (most
- notably -EBUSY if the hwspinlock was already taken).
- The function will never sleep.
+
+
+Attempt to lock a previously-assigned hwspinlock, but immediately fail if
+it is already taken.
+
+Upon a successful return from this function, preemption and the local
+interrupts are disabled so caller must not sleep, and is advised to
+release the hwspinlock as soon as possible.
+
+Returns 0 on success and an appropriate error code otherwise (most
+notably -EBUSY if the hwspinlock was already taken).
+
+The function will never sleep.
+
+::
int hwspin_trylock_irqsave(struct hwspinlock *hwlock, unsigned long *flags);
- - attempt to lock a previously-assigned hwspinlock, but immediately fail if
- it is already taken.
- Upon a successful return from this function, preemption is disabled,
- the local interrupts are disabled and their previous state is saved
- at the given flags placeholder. The caller must not sleep, and is advised
- to release the hwspinlock as soon as possible.
- Returns 0 on success and an appropriate error code otherwise (most
- notably -EBUSY if the hwspinlock was already taken).
- The function will never sleep.
+
+Attempt to lock a previously-assigned hwspinlock, but immediately fail if
+it is already taken.
+
+Upon a successful return from this function, preemption is disabled,
+the local interrupts are disabled and their previous state is saved
+at the given flags placeholder. The caller must not sleep, and is advised
+to release the hwspinlock as soon as possible.
+
+Returns 0 on success and an appropriate error code otherwise (most
+notably -EBUSY if the hwspinlock was already taken).
+The function will never sleep.
+
+::
void hwspin_unlock(struct hwspinlock *hwlock);
- - unlock a previously-locked hwspinlock. Always succeed, and can be called
- from any context (the function never sleeps). Note: code should _never_
- unlock an hwspinlock which is already unlocked (there is no protection
- against this).
+
+Unlock a previously-locked hwspinlock. Always succeed, and can be called
+from any context (the function never sleeps).
+
+.. note::
+
+ code should **never** unlock an hwspinlock which is already unlocked
+ (there is no protection against this).
+
+::
void hwspin_unlock_irq(struct hwspinlock *hwlock);
- - unlock a previously-locked hwspinlock and enable local interrupts.
- The caller should _never_ unlock an hwspinlock which is already unlocked.
- Doing so is considered a bug (there is no protection against this).
- Upon a successful return from this function, preemption and local
- interrupts are enabled. This function will never sleep.
+
+Unlock a previously-locked hwspinlock and enable local interrupts.
+The caller should **never** unlock an hwspinlock which is already unlocked.
+
+Doing so is considered a bug (there is no protection against this).
+Upon a successful return from this function, preemption and local
+interrupts are enabled. This function will never sleep.
+
+::
void
hwspin_unlock_irqrestore(struct hwspinlock *hwlock, unsigned long *flags);
- - unlock a previously-locked hwspinlock.
- The caller should _never_ unlock an hwspinlock which is already unlocked.
- Doing so is considered a bug (there is no protection against this).
- Upon a successful return from this function, preemption is reenabled,
- and the state of the local interrupts is restored to the state saved at
- the given flags. This function will never sleep.
+
+Unlock a previously-locked hwspinlock.
+
+The caller should **never** unlock an hwspinlock which is already unlocked.
+Doing so is considered a bug (there is no protection against this).
+Upon a successful return from this function, preemption is reenabled,
+and the state of the local interrupts is restored to the state saved at
+the given flags. This function will never sleep.
+
+::
int hwspin_lock_get_id(struct hwspinlock *hwlock);
- - retrieve id number of a given hwspinlock. This is needed when an
- hwspinlock is dynamically assigned: before it can be used to achieve
- mutual exclusion with a remote cpu, the id number should be communicated
- to the remote task with which we want to synchronize.
- Returns the hwspinlock id number, or -EINVAL if hwlock is null.
-
-3. Typical usage
-
-#include <linux/hwspinlock.h>
-#include <linux/err.h>
-
-int hwspinlock_example1(void)
-{
- struct hwspinlock *hwlock;
- int ret;
-
- /* dynamically assign a hwspinlock */
- hwlock = hwspin_lock_request();
- if (!hwlock)
- ...
-
- id = hwspin_lock_get_id(hwlock);
- /* probably need to communicate id to a remote processor now */
-
- /* take the lock, spin for 1 sec if it's already taken */
- ret = hwspin_lock_timeout(hwlock, 1000);
- if (ret)
- ...
-
- /*
- * we took the lock, do our thing now, but do NOT sleep
- */
-
- /* release the lock */
- hwspin_unlock(hwlock);
-
- /* free the lock */
- ret = hwspin_lock_free(hwlock);
- if (ret)
- ...
-
- return ret;
-}
-
-int hwspinlock_example2(void)
-{
- struct hwspinlock *hwlock;
- int ret;
-
- /*
- * assign a specific hwspinlock id - this should be called early
- * by board init code.
- */
- hwlock = hwspin_lock_request_specific(PREDEFINED_LOCK_ID);
- if (!hwlock)
- ...
-
- /* try to take it, but don't spin on it */
- ret = hwspin_trylock(hwlock);
- if (!ret) {
- pr_info("lock is already taken\n");
- return -EBUSY;
- }
- /*
- * we took the lock, do our thing now, but do NOT sleep
- */
+Retrieve id number of a given hwspinlock. This is needed when an
+hwspinlock is dynamically assigned: before it can be used to achieve
+mutual exclusion with a remote cpu, the id number should be communicated
+to the remote task with which we want to synchronize.
+
+Returns the hwspinlock id number, or -EINVAL if hwlock is null.
+
+Typical usage
+=============
+
+::
+
+ #include <linux/hwspinlock.h>
+ #include <linux/err.h>
+
+ int hwspinlock_example1(void)
+ {
+ struct hwspinlock *hwlock;
+ int ret;
+
+ /* dynamically assign a hwspinlock */
+ hwlock = hwspin_lock_request();
+ if (!hwlock)
+ ...
- /* release the lock */
- hwspin_unlock(hwlock);
+ id = hwspin_lock_get_id(hwlock);
+ /* probably need to communicate id to a remote processor now */
- /* free the lock */
- ret = hwspin_lock_free(hwlock);
- if (ret)
- ...
+ /* take the lock, spin for 1 sec if it's already taken */
+ ret = hwspin_lock_timeout(hwlock, 1000);
+ if (ret)
+ ...
+
+ /*
+ * we took the lock, do our thing now, but do NOT sleep
+ */
+
+ /* release the lock */
+ hwspin_unlock(hwlock);
+
+ /* free the lock */
+ ret = hwspin_lock_free(hwlock);
+ if (ret)
+ ...
+
+ return ret;
+ }
+
+ int hwspinlock_example2(void)
+ {
+ struct hwspinlock *hwlock;
+ int ret;
+
+ /*
+ * assign a specific hwspinlock id - this should be called early
+ * by board init code.
+ */
+ hwlock = hwspin_lock_request_specific(PREDEFINED_LOCK_ID);
+ if (!hwlock)
+ ...
+
+ /* try to take it, but don't spin on it */
+ ret = hwspin_trylock(hwlock);
+ if (!ret) {
+ pr_info("lock is already taken\n");
+ return -EBUSY;
+ }
+
+ /*
+ * we took the lock, do our thing now, but do NOT sleep
+ */
+
+ /* release the lock */
+ hwspin_unlock(hwlock);
+
+ /* free the lock */
+ ret = hwspin_lock_free(hwlock);
+ if (ret)
+ ...
+
+ return ret;
+ }
- return ret;
-}
+API for implementors
+====================
-4. API for implementors
+::
int hwspin_lock_register(struct hwspinlock_device *bank, struct device *dev,
const struct hwspinlock_ops *ops, int base_id, int num_locks);
- - to be called from the underlying platform-specific implementation, in
- order to register a new hwspinlock device (which is usually a bank of
- numerous locks). Should be called from a process context (this function
- might sleep).
- Returns 0 on success, or appropriate error code on failure.
+
+To be called from the underlying platform-specific implementation, in
+order to register a new hwspinlock device (which is usually a bank of
+numerous locks). Should be called from a process context (this function
+might sleep).
+
+Returns 0 on success, or appropriate error code on failure.
+
+::
int hwspin_lock_unregister(struct hwspinlock_device *bank);
- - to be called from the underlying vendor-specific implementation, in order
- to unregister an hwspinlock device (which is usually a bank of numerous
- locks).
- Should be called from a process context (this function might sleep).
- Returns the address of hwspinlock on success, or NULL on error (e.g.
- if the hwspinlock is still in use).
-
-5. Important structs
+
+To be called from the underlying vendor-specific implementation, in order
+to unregister an hwspinlock device (which is usually a bank of numerous
+locks).
+
+Should be called from a process context (this function might sleep).
+
+Returns the address of hwspinlock on success, or NULL on error (e.g.
+if the hwspinlock is still in use).
+
+Important structs
+=================
struct hwspinlock_device is a device which usually contains a bank
of hardware locks. It is registered by the underlying hwspinlock
implementation using the hwspin_lock_register() API.
-/**
- * struct hwspinlock_device - a device which usually spans numerous hwspinlocks
- * @dev: underlying device, will be used to invoke runtime PM api
- * @ops: platform-specific hwspinlock handlers
- * @base_id: id index of the first lock in this device
- * @num_locks: number of locks in this device
- * @lock: dynamically allocated array of 'struct hwspinlock'
- */
-struct hwspinlock_device {
- struct device *dev;
- const struct hwspinlock_ops *ops;
- int base_id;
- int num_locks;
- struct hwspinlock lock[0];
-};
+::
+
+ /**
+ * struct hwspinlock_device - a device which usually spans numerous hwspinlocks
+ * @dev: underlying device, will be used to invoke runtime PM api
+ * @ops: platform-specific hwspinlock handlers
+ * @base_id: id index of the first lock in this device
+ * @num_locks: number of locks in this device
+ * @lock: dynamically allocated array of 'struct hwspinlock'
+ */
+ struct hwspinlock_device {
+ struct device *dev;
+ const struct hwspinlock_ops *ops;
+ int base_id;
+ int num_locks;
+ struct hwspinlock lock[0];
+ };
struct hwspinlock_device contains an array of hwspinlock structs, each
-of which represents a single hardware lock:
+of which represents a single hardware lock::
-/**
- * struct hwspinlock - this struct represents a single hwspinlock instance
- * @bank: the hwspinlock_device structure which owns this lock
- * @lock: initialized and used by hwspinlock core
- * @priv: private data, owned by the underlying platform-specific hwspinlock drv
- */
-struct hwspinlock {
- struct hwspinlock_device *bank;
- spinlock_t lock;
- void *priv;
-};
+ /**
+ * struct hwspinlock - this struct represents a single hwspinlock instance
+ * @bank: the hwspinlock_device structure which owns this lock
+ * @lock: initialized and used by hwspinlock core
+ * @priv: private data, owned by the underlying platform-specific hwspinlock drv
+ */
+ struct hwspinlock {
+ struct hwspinlock_device *bank;
+ spinlock_t lock;
+ void *priv;
+ };
When registering a bank of locks, the hwspinlock driver only needs to
set the priv members of the locks. The rest of the members are set and
initialized by the hwspinlock core itself.
-6. Implementation callbacks
+Implementation callbacks
+========================
-There are three possible callbacks defined in 'struct hwspinlock_ops':
+There are three possible callbacks defined in 'struct hwspinlock_ops'::
-struct hwspinlock_ops {
- int (*trylock)(struct hwspinlock *lock);
- void (*unlock)(struct hwspinlock *lock);
- void (*relax)(struct hwspinlock *lock);
-};
+ struct hwspinlock_ops {
+ int (*trylock)(struct hwspinlock *lock);
+ void (*unlock)(struct hwspinlock *lock);
+ void (*relax)(struct hwspinlock *lock);
+ };
The first two callbacks are mandatory:
The ->trylock() callback should make a single attempt to take the lock, and
-return 0 on failure and 1 on success. This callback may _not_ sleep.
+return 0 on failure and 1 on success. This callback may **not** sleep.
The ->unlock() callback releases the lock. It always succeed, and it, too,
-may _not_ sleep.
+may **not** sleep.
The ->relax() callback is optional. It is called by hwspinlock core while
spinning on a lock, and can be used by the underlying implementation to force
-a delay between two successive invocations of ->trylock(). It may _not_ sleep.
+a delay between two successive invocations of ->trylock(). It may **not** sleep.
--
2.9.4
^ permalink raw reply related [flat|nested] 37+ messages in thread* [PATCH 27/31] intel_txt.txt: standardize document format
2017-05-19 1:22 [PATCH 00/31] Standardize doc formats - part 1 Mauro Carvalho Chehab
` (25 preceding siblings ...)
2017-05-19 1:22 ` [PATCH 26/31] hwspinlock.txt: " Mauro Carvalho Chehab
@ 2017-05-19 1:22 ` Mauro Carvalho Chehab
2017-05-19 1:22 ` [PATCH 28/31] Intel-IOMMU.txt: " Mauro Carvalho Chehab
` (3 subsequent siblings)
30 siblings, 0 replies; 37+ messages in thread
From: Mauro Carvalho Chehab @ 2017-05-19 1:22 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, David Woodhouse, Brian Norris, Boris Brezillon,
Marek Vasut, Richard Weinberger, Cyrille Pitchen, linux-mtd,
Ning Sun, tboot-devel
Each text file under Documentation follows a different
format. Some doesn't even have titles!
Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- promote main title one level;
- fix the bulleted list markup;
- use bulletted list markup where needed;
- add whitespaces where needed;
- mark literal blocks;
- remove extra ":" after section titles.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/intel_txt.txt | 63 ++++++++++++++++++++++++++++-----------------
1 file changed, 40 insertions(+), 23 deletions(-)
diff --git a/Documentation/intel_txt.txt b/Documentation/intel_txt.txt
index 91d89c540709..d83c1a2122c9 100644
--- a/Documentation/intel_txt.txt
+++ b/Documentation/intel_txt.txt
@@ -1,4 +1,5 @@
-Intel(R) TXT Overview:
+=====================
+Intel(R) TXT Overview
=====================
Intel's technology for safer computing, Intel(R) Trusted Execution
@@ -8,9 +9,10 @@ provide the building blocks for creating trusted platforms.
Intel TXT was formerly known by the code name LaGrande Technology (LT).
Intel TXT in Brief:
-o Provides dynamic root of trust for measurement (DRTM)
-o Data protection in case of improper shutdown
-o Measurement and verification of launched environment
+
+- Provides dynamic root of trust for measurement (DRTM)
+- Data protection in case of improper shutdown
+- Measurement and verification of launched environment
Intel TXT is part of the vPro(TM) brand and is also available some
non-vPro systems. It is currently available on desktop systems
@@ -24,16 +26,21 @@ which has been updated for the new released platforms.
Intel TXT has been presented at various events over the past few
years, some of which are:
- LinuxTAG 2008:
+
+ - LinuxTAG 2008:
http://www.linuxtag.org/2008/en/conf/events/vp-donnerstag.html
- TRUST2008:
+
+ - TRUST2008:
http://www.trust-conference.eu/downloads/Keynote-Speakers/
3_David-Grawrock_The-Front-Door-of-Trusted-Computing.pdf
- IDF, Shanghai:
+
+ - IDF, Shanghai:
http://www.prcidf.com.cn/index_en.html
- IDFs 2006, 2007 (I'm not sure if/where they are online)
-Trusted Boot Project Overview:
+ - IDFs 2006, 2007
+ (I'm not sure if/where they are online)
+
+Trusted Boot Project Overview
=============================
Trusted Boot (tboot) is an open source, pre-kernel/VMM module that
@@ -87,11 +94,12 @@ Intel-provided firmware).
How Does it Work?
=================
-o Tboot is an executable that is launched by the bootloader as
+- Tboot is an executable that is launched by the bootloader as
the "kernel" (the binary the bootloader executes).
-o It performs all of the work necessary to determine if the
+- It performs all of the work necessary to determine if the
platform supports Intel TXT and, if so, executes the GETSEC[SENTER]
processor instruction that initiates the dynamic root of trust.
+
- If tboot determines that the system does not support Intel TXT
or is not configured correctly (e.g. the SINIT AC Module was
incorrect), it will directly launch the kernel with no changes
@@ -99,12 +107,14 @@ o It performs all of the work necessary to determine if the
- Tboot will output various information about its progress to the
terminal, serial port, and/or an in-memory log; the output
locations can be configured with a command line switch.
-o The GETSEC[SENTER] instruction will return control to tboot and
+
+- The GETSEC[SENTER] instruction will return control to tboot and
tboot then verifies certain aspects of the environment (e.g. TPM NV
lock, e820 table does not have invalid entries, etc.).
-o It will wake the APs from the special sleep state the GETSEC[SENTER]
+- It will wake the APs from the special sleep state the GETSEC[SENTER]
instruction had put them in and place them into a wait-for-SIPI
state.
+
- Because the processors will not respond to an INIT or SIPI when
in the TXT environment, it is necessary to create a small VT-x
guest for the APs. When they run in this guest, they will
@@ -112,8 +122,10 @@ o It will wake the APs from the special sleep state the GETSEC[SENTER]
VMEXITs, and then disable VT and jump to the SIPI vector. This
approach seemed like a better choice than having to insert
special code into the kernel's MP wakeup sequence.
-o Tboot then applies an (optional) user-defined launch policy to
+
+- Tboot then applies an (optional) user-defined launch policy to
verify the kernel and initrd.
+
- This policy is rooted in TPM NV and is described in the tboot
project. The tboot project also contains code for tools to
create and provision the policy.
@@ -121,30 +133,34 @@ o Tboot then applies an (optional) user-defined launch policy to
then any kernel will be launched.
- Policy action is flexible and can include halting on failures
or simply logging them and continuing.
-o Tboot adjusts the e820 table provided by the bootloader to reserve
+
+- Tboot adjusts the e820 table provided by the bootloader to reserve
its own location in memory as well as to reserve certain other
TXT-related regions.
-o As part of its launch, tboot DMA protects all of RAM (using the
+- As part of its launch, tboot DMA protects all of RAM (using the
VT-d PMRs). Thus, the kernel must be booted with 'intel_iommu=on'
in order to remove this blanket protection and use VT-d's
page-level protection.
-o Tboot will populate a shared page with some data about itself and
+- Tboot will populate a shared page with some data about itself and
pass this to the Linux kernel as it transfers control.
+
- The location of the shared page is passed via the boot_params
struct as a physical address.
-o The kernel will look for the tboot shared page address and, if it
+
+- The kernel will look for the tboot shared page address and, if it
exists, map it.
-o As one of the checks/protections provided by TXT, it makes a copy
+- As one of the checks/protections provided by TXT, it makes a copy
of the VT-d DMARs in a DMA-protected region of memory and verifies
them for correctness. The VT-d code will detect if the kernel was
launched with tboot and use this copy instead of the one in the
ACPI table.
-o At this point, tboot and TXT are out of the picture until a
+- At this point, tboot and TXT are out of the picture until a
shutdown (S<n>)
-o In order to put a system into any of the sleep states after a TXT
+- In order to put a system into any of the sleep states after a TXT
launch, TXT must first be exited. This is to prevent attacks that
attempt to crash the system to gain control on reboot and steal
data left in memory.
+
- The kernel will perform all of its sleep preparation and
populate the shared page with the ACPI data needed to put the
platform in the desired sleep state.
@@ -172,7 +188,7 @@ o In order to put a system into any of the sleep states after a TXT
That's pretty much it for TXT support.
-Configuring the System:
+Configuring the System
======================
This code works with 32bit, 32bit PAE, and 64bit (x86_64) kernels.
@@ -181,7 +197,8 @@ In BIOS, the user must enable: TPM, TXT, VT-x, VT-d. Not all BIOSes
allow these to be individually enabled/disabled and the screens in
which to find them are BIOS-specific.
-grub.conf needs to be modified as follows:
+grub.conf needs to be modified as follows::
+
title Linux 2.6.29-tip w/ tboot
root (hd0,0)
kernel /tboot.gz logging=serial,vga,memory
--
2.9.4
^ permalink raw reply related [flat|nested] 37+ messages in thread* [PATCH 28/31] Intel-IOMMU.txt: standardize document format
2017-05-19 1:22 [PATCH 00/31] Standardize doc formats - part 1 Mauro Carvalho Chehab
` (26 preceding siblings ...)
2017-05-19 1:22 ` [PATCH 27/31] intel_txt.txt: " Mauro Carvalho Chehab
@ 2017-05-19 1:22 ` Mauro Carvalho Chehab
2017-05-19 1:22 ` [PATCH 29/31] io-mapping.txt: " Mauro Carvalho Chehab
` (2 subsequent siblings)
30 siblings, 0 replies; 37+ messages in thread
From: Mauro Carvalho Chehab @ 2017-05-19 1:22 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, David Woodhouse, Brian Norris, Boris Brezillon,
Marek Vasut, Richard Weinberger, Cyrille Pitchen, linux-mtd
Each text file under Documentation follows a different
format. Some doesn't even have titles!
Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
This file is almost in the right format. It only needed to
convert a list to bulleted list and to use the right markup
for literal blocks.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/Intel-IOMMU.txt | 36 +++++++++++++++++++-----------------
1 file changed, 19 insertions(+), 17 deletions(-)
diff --git a/Documentation/Intel-IOMMU.txt b/Documentation/Intel-IOMMU.txt
index 49585b6e1ea2..11151bd39b2f 100644
--- a/Documentation/Intel-IOMMU.txt
+++ b/Documentation/Intel-IOMMU.txt
@@ -9,11 +9,11 @@ This guide gives a quick cheat sheet for some basic understanding.
Some Keywords
-DMAR - DMA remapping
-DRHD - DMA Remapping Hardware Unit Definition
-RMRR - Reserved memory Region Reporting Structure
-ZLR - Zero length reads from PCI devices
-IOVA - IO Virtual address.
+- DMAR - DMA remapping
+- DRHD - DMA Remapping Hardware Unit Definition
+- RMRR - Reserved memory Region Reporting Structure
+- ZLR - Zero length reads from PCI devices
+- IOVA - IO Virtual address.
Basic stuff
-----------
@@ -33,7 +33,7 @@ devices that need to access these regions. OS is expected to setup
unity mappings for these regions for these devices to access these regions.
How is IOVA generated?
----------------------
+----------------------
Well behaved drivers call pci_map_*() calls before sending command to device
that needs to perform DMA. Once DMA is completed and mapping is no longer
@@ -82,14 +82,14 @@ in ACPI.
ACPI: DMAR (v001 A M I OEMDMAR 0x00000001 MSFT 0x00000097) @ 0x000000007f5b5ef0
When DMAR is being processed and initialized by ACPI, prints DMAR locations
-and any RMRR's processed.
+and any RMRR's processed::
-ACPI DMAR:Host address width 36
-ACPI DMAR:DRHD (flags: 0x00000000)base: 0x00000000fed90000
-ACPI DMAR:DRHD (flags: 0x00000000)base: 0x00000000fed91000
-ACPI DMAR:DRHD (flags: 0x00000001)base: 0x00000000fed93000
-ACPI DMAR:RMRR base: 0x00000000000ed000 end: 0x00000000000effff
-ACPI DMAR:RMRR base: 0x000000007f600000 end: 0x000000007fffffff
+ ACPI DMAR:Host address width 36
+ ACPI DMAR:DRHD (flags: 0x00000000)base: 0x00000000fed90000
+ ACPI DMAR:DRHD (flags: 0x00000000)base: 0x00000000fed91000
+ ACPI DMAR:DRHD (flags: 0x00000001)base: 0x00000000fed93000
+ ACPI DMAR:RMRR base: 0x00000000000ed000 end: 0x00000000000effff
+ ACPI DMAR:RMRR base: 0x000000007f600000 end: 0x000000007fffffff
When DMAR is enabled for use, you will notice..
@@ -98,10 +98,12 @@ PCI-DMA: Using DMAR IOMMU
Fault reporting
---------------
-DMAR:[DMA Write] Request device [00:02.0] fault addr 6df084000
-DMAR:[fault reason 05] PTE Write access is not set
-DMAR:[DMA Write] Request device [00:02.0] fault addr 6df084000
-DMAR:[fault reason 05] PTE Write access is not set
+::
+
+ DMAR:[DMA Write] Request device [00:02.0] fault addr 6df084000
+ DMAR:[fault reason 05] PTE Write access is not set
+ DMAR:[DMA Write] Request device [00:02.0] fault addr 6df084000
+ DMAR:[fault reason 05] PTE Write access is not set
TBD
----
--
2.9.4
^ permalink raw reply related [flat|nested] 37+ messages in thread* [PATCH 29/31] io-mapping.txt: standardize document format
2017-05-19 1:22 [PATCH 00/31] Standardize doc formats - part 1 Mauro Carvalho Chehab
` (27 preceding siblings ...)
2017-05-19 1:22 ` [PATCH 28/31] Intel-IOMMU.txt: " Mauro Carvalho Chehab
@ 2017-05-19 1:22 ` Mauro Carvalho Chehab
2017-05-19 1:22 ` [PATCH 30/31] io_ordering.txt: " Mauro Carvalho Chehab
2017-05-19 1:22 ` [PATCH 31/31] iostats.txt: " Mauro Carvalho Chehab
30 siblings, 0 replies; 37+ messages in thread
From: Mauro Carvalho Chehab @ 2017-05-19 1:22 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, David Woodhouse, Brian Norris, Boris Brezillon,
Marek Vasut, Richard Weinberger, Cyrille Pitchen, linux-mtd
Each text file under Documentation follows a different
format. Some doesn't even have titles!
Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- Add a title for the document and for API chapter;
- mark literal blocks;
- Adjust whitespacing.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/io-mapping.txt | 67 +++++++++++++++++++++++++++-----------------
1 file changed, 41 insertions(+), 26 deletions(-)
diff --git a/Documentation/io-mapping.txt b/Documentation/io-mapping.txt
index 5ca78426f54c..a966239f04e4 100644
--- a/Documentation/io-mapping.txt
+++ b/Documentation/io-mapping.txt
@@ -1,66 +1,81 @@
+========================
+The io_mapping functions
+========================
+
+API
+===
+
The io_mapping functions in linux/io-mapping.h provide an abstraction for
efficiently mapping small regions of an I/O device to the CPU. The initial
usage is to support the large graphics aperture on 32-bit processors where
ioremap_wc cannot be used to statically map the entire aperture to the CPU
as it would consume too much of the kernel address space.
-A mapping object is created during driver initialization using
+A mapping object is created during driver initialization using::
struct io_mapping *io_mapping_create_wc(unsigned long base,
unsigned long size)
- 'base' is the bus address of the region to be made
- mappable, while 'size' indicates how large a mapping region to
- enable. Both are in bytes.
+'base' is the bus address of the region to be made
+mappable, while 'size' indicates how large a mapping region to
+enable. Both are in bytes.
- This _wc variant provides a mapping which may only be used
- with the io_mapping_map_atomic_wc or io_mapping_map_wc.
+This _wc variant provides a mapping which may only be used
+with the io_mapping_map_atomic_wc or io_mapping_map_wc.
With this mapping object, individual pages can be mapped either atomically
or not, depending on the necessary scheduling environment. Of course, atomic
-maps are more efficient:
+maps are more efficient::
void *io_mapping_map_atomic_wc(struct io_mapping *mapping,
unsigned long offset)
- 'offset' is the offset within the defined mapping region.
- Accessing addresses beyond the region specified in the
- creation function yields undefined results. Using an offset
- which is not page aligned yields an undefined result. The
- return value points to a single page in CPU address space.
+'offset' is the offset within the defined mapping region.
+Accessing addresses beyond the region specified in the
+creation function yields undefined results. Using an offset
+which is not page aligned yields an undefined result. The
+return value points to a single page in CPU address space.
- This _wc variant returns a write-combining map to the
- page and may only be used with mappings created by
- io_mapping_create_wc
+This _wc variant returns a write-combining map to the
+page and may only be used with mappings created by
+io_mapping_create_wc
- Note that the task may not sleep while holding this page
- mapped.
+Note that the task may not sleep while holding this page
+mapped.
+
+::
void io_mapping_unmap_atomic(void *vaddr)
- 'vaddr' must be the value returned by the last
- io_mapping_map_atomic_wc call. This unmaps the specified
- page and allows the task to sleep once again.
+'vaddr' must be the value returned by the last
+io_mapping_map_atomic_wc call. This unmaps the specified
+page and allows the task to sleep once again.
If you need to sleep while holding the lock, you can use the non-atomic
variant, although they may be significantly slower.
+::
+
void *io_mapping_map_wc(struct io_mapping *mapping,
unsigned long offset)
- This works like io_mapping_map_atomic_wc except it allows
- the task to sleep while holding the page mapped.
+This works like io_mapping_map_atomic_wc except it allows
+the task to sleep while holding the page mapped.
+
+
+::
void io_mapping_unmap(void *vaddr)
- This works like io_mapping_unmap_atomic, except it is used
- for pages mapped with io_mapping_map_wc.
+This works like io_mapping_unmap_atomic, except it is used
+for pages mapped with io_mapping_map_wc.
-At driver close time, the io_mapping object must be freed:
+At driver close time, the io_mapping object must be freed::
void io_mapping_free(struct io_mapping *mapping)
-Current Implementation:
+Current Implementation
+======================
The initial implementation of these functions uses existing mapping
mechanisms and so provides only an abstraction layer and no new
--
2.9.4
^ permalink raw reply related [flat|nested] 37+ messages in thread* [PATCH 30/31] io_ordering.txt: standardize document format
2017-05-19 1:22 [PATCH 00/31] Standardize doc formats - part 1 Mauro Carvalho Chehab
` (28 preceding siblings ...)
2017-05-19 1:22 ` [PATCH 29/31] io-mapping.txt: " Mauro Carvalho Chehab
@ 2017-05-19 1:22 ` Mauro Carvalho Chehab
2017-05-19 1:22 ` [PATCH 31/31] iostats.txt: " Mauro Carvalho Chehab
30 siblings, 0 replies; 37+ messages in thread
From: Mauro Carvalho Chehab @ 2017-05-19 1:22 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, David Woodhouse, Brian Norris, Boris Brezillon,
Marek Vasut, Richard Weinberger, Cyrille Pitchen, linux-mtd
Each text file under Documentation follows a different
format. Some doesn't even have titles!
Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- Add a title;
- mark literal-blocks as such.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/io_ordering.txt | 61 +++++++++++++++++++++++--------------------
1 file changed, 32 insertions(+), 29 deletions(-)
diff --git a/Documentation/io_ordering.txt b/Documentation/io_ordering.txt
index 9faae6f26d32..01d2875b5076 100644
--- a/Documentation/io_ordering.txt
+++ b/Documentation/io_ordering.txt
@@ -1,3 +1,6 @@
+Ordering I/O writes to memory-mapped addresses
+==============================================
+
On some platforms, so-called memory-mapped I/O is weakly ordered. On such
platforms, driver writers are responsible for ensuring that I/O writes to
memory-mapped addresses on their device arrive in the order intended. This is
@@ -8,39 +11,39 @@ critical section of code protected by spinlocks. This would ensure that
subsequent writes to I/O space arrived only after all prior writes (much like a
memory barrier op, mb(), only with respect to I/O).
-A more concrete example from a hypothetical device driver:
+A more concrete example from a hypothetical device driver::
- ...
-CPU A: spin_lock_irqsave(&dev_lock, flags)
-CPU A: val = readl(my_status);
-CPU A: ...
-CPU A: writel(newval, ring_ptr);
-CPU A: spin_unlock_irqrestore(&dev_lock, flags)
- ...
-CPU B: spin_lock_irqsave(&dev_lock, flags)
-CPU B: val = readl(my_status);
-CPU B: ...
-CPU B: writel(newval2, ring_ptr);
-CPU B: spin_unlock_irqrestore(&dev_lock, flags)
- ...
+ ...
+ CPU A: spin_lock_irqsave(&dev_lock, flags)
+ CPU A: val = readl(my_status);
+ CPU A: ...
+ CPU A: writel(newval, ring_ptr);
+ CPU A: spin_unlock_irqrestore(&dev_lock, flags)
+ ...
+ CPU B: spin_lock_irqsave(&dev_lock, flags)
+ CPU B: val = readl(my_status);
+ CPU B: ...
+ CPU B: writel(newval2, ring_ptr);
+ CPU B: spin_unlock_irqrestore(&dev_lock, flags)
+ ...
In the case above, the device may receive newval2 before it receives newval,
-which could cause problems. Fixing it is easy enough though:
+which could cause problems. Fixing it is easy enough though::
- ...
-CPU A: spin_lock_irqsave(&dev_lock, flags)
-CPU A: val = readl(my_status);
-CPU A: ...
-CPU A: writel(newval, ring_ptr);
-CPU A: (void)readl(safe_register); /* maybe a config register? */
-CPU A: spin_unlock_irqrestore(&dev_lock, flags)
- ...
-CPU B: spin_lock_irqsave(&dev_lock, flags)
-CPU B: val = readl(my_status);
-CPU B: ...
-CPU B: writel(newval2, ring_ptr);
-CPU B: (void)readl(safe_register); /* maybe a config register? */
-CPU B: spin_unlock_irqrestore(&dev_lock, flags)
+ ...
+ CPU A: spin_lock_irqsave(&dev_lock, flags)
+ CPU A: val = readl(my_status);
+ CPU A: ...
+ CPU A: writel(newval, ring_ptr);
+ CPU A: (void)readl(safe_register); /* maybe a config register? */
+ CPU A: spin_unlock_irqrestore(&dev_lock, flags)
+ ...
+ CPU B: spin_lock_irqsave(&dev_lock, flags)
+ CPU B: val = readl(my_status);
+ CPU B: ...
+ CPU B: writel(newval2, ring_ptr);
+ CPU B: (void)readl(safe_register); /* maybe a config register? */
+ CPU B: spin_unlock_irqrestore(&dev_lock, flags)
Here, the reads from safe_register will cause the I/O chipset to flush any
pending writes before actually posting the read to the chipset, preventing
--
2.9.4
^ permalink raw reply related [flat|nested] 37+ messages in thread* [PATCH 31/31] iostats.txt: standardize document format
2017-05-19 1:22 [PATCH 00/31] Standardize doc formats - part 1 Mauro Carvalho Chehab
` (29 preceding siblings ...)
2017-05-19 1:22 ` [PATCH 30/31] io_ordering.txt: " Mauro Carvalho Chehab
@ 2017-05-19 1:22 ` Mauro Carvalho Chehab
30 siblings, 0 replies; 37+ messages in thread
From: Mauro Carvalho Chehab @ 2017-05-19 1:22 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, David Woodhouse, Brian Norris, Boris Brezillon,
Marek Vasut, Richard Weinberger, Cyrille Pitchen, linux-mtd
Each text file under Documentation follows a different
format. Some doesn't even have titles!
Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- promote main title level;
- mark literal blocks as such;
- Add blank lines to avoid Sphinx errors.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/iostats.txt | 40 +++++++++++++++++++++++++++-------------
1 file changed, 27 insertions(+), 13 deletions(-)
diff --git a/Documentation/iostats.txt b/Documentation/iostats.txt
index 65f694f2d1c9..456a5b5e0c53 100644
--- a/Documentation/iostats.txt
+++ b/Documentation/iostats.txt
@@ -1,5 +1,6 @@
+=====================
I/O statistics fields
----------------
+=====================
Since 2.4.20 (and some versions before, with patches), and 2.5.45,
more extensive disk statistics have been introduced to help measure disk
@@ -16,20 +17,20 @@ is mounted on /sys, although of course it may be mounted anywhere.
Both /proc/diskstats and sysfs use the same source for the information
and so should not differ.
-Here are examples of these different formats:
+Here are examples of these different formats::
-2.4:
- 3 0 39082680 hda 446216 784926 9550688 4382310 424847 312726 5922052 19310380 0 3376340 23705160
- 3 1 9221278 hda1 35486 0 35496 38030 0 0 0 0 0 38030 38030
+ 2.4:
+ 3 0 39082680 hda 446216 784926 9550688 4382310 424847 312726 5922052 19310380 0 3376340 23705160
+ 3 1 9221278 hda1 35486 0 35496 38030 0 0 0 0 0 38030 38030
-2.6 sysfs:
- 446216 784926 9550688 4382310 424847 312726 5922052 19310380 0 3376340 23705160
- 35486 38030 38030 38030
+ 2.6 sysfs:
+ 446216 784926 9550688 4382310 424847 312726 5922052 19310380 0 3376340 23705160
+ 35486 38030 38030 38030
-2.6 diskstats:
- 3 0 hda 446216 784926 9550688 4382310 424847 312726 5922052 19310380 0 3376340 23705160
- 3 1 hda1 35486 38030 38030 38030
+ 2.6 diskstats:
+ 3 0 hda 446216 784926 9550688 4382310 424847 312726 5922052 19310380 0 3376340 23705160
+ 3 1 hda1 35486 38030 38030 38030
On 2.4 you might execute "grep 'hda ' /proc/partitions". On 2.6, you have
a choice of "cat /sys/block/hda/stat" or "grep 'hda ' /proc/diskstats".
@@ -59,30 +60,40 @@ system-wide stats you'll have to find all the devices and sum them all up.
Field 1 -- # of reads completed
This is the total number of reads completed successfully.
+
Field 2 -- # of reads merged, field 6 -- # of writes merged
Reads and writes which are adjacent to each other may be merged for
efficiency. Thus two 4K reads may become one 8K read before it is
ultimately handed to the disk, and so it will be counted (and queued)
as only one I/O. This field lets you know how often this was done.
+
Field 3 -- # of sectors read
This is the total number of sectors read successfully.
+
Field 4 -- # of milliseconds spent reading
This is the total number of milliseconds spent by all reads (as
measured from __make_request() to end_that_request_last()).
+
Field 5 -- # of writes completed
This is the total number of writes completed successfully.
+
Field 6 -- # of writes merged
See the description of field 2.
+
Field 7 -- # of sectors written
This is the total number of sectors written successfully.
+
Field 8 -- # of milliseconds spent writing
This is the total number of milliseconds spent by all writes (as
measured from __make_request() to end_that_request_last()).
+
Field 9 -- # of I/Os currently in progress
The only field that should go to zero. Incremented as requests are
given to appropriate struct request_queue and decremented as they finish.
+
Field 10 -- # of milliseconds spent doing I/Os
This field increases so long as field 9 is nonzero.
+
Field 11 -- weighted # of milliseconds spent doing I/Os
This field is incremented at each I/O start, I/O completion, I/O
merge, or read of these stats by the number of I/Os in progress
@@ -117,11 +128,14 @@ for partitions on 2.6 machines. This is reflected in the examples above.
Field 1 -- # of reads issued
This is the total number of reads issued to this partition.
+
Field 2 -- # of sectors read
This is the total number of sectors requested to be read from this
partition.
+
Field 3 -- # of writes issued
This is the total number of writes issued to this partition.
+
Field 4 -- # of sectors written
This is the total number of sectors requested to be written to
this partition.
@@ -151,9 +165,9 @@ Additional notes
In 2.6, sysfs is not mounted by default. If your distribution of
Linux hasn't added it already, here's the line you'll want to add to
-your /etc/fstab:
+your /etc/fstab::
-none /sys sysfs defaults 0 0
+ none /sys sysfs defaults 0 0
In 2.6, all disk statistics were removed from /proc/stat. In 2.4, they
--
2.9.4
^ permalink raw reply related [flat|nested] 37+ messages in thread