From 387b14684f94483cbbb72843db406ec9a8d0d6d2 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 10 Apr 2019 08:32:41 -0300 Subject: [PATCH 01/77] docs: locking: convert docs to ReST and rename to *.rst Convert the locking documents to ReST and add them to the kernel development book where it belongs. Most of the stuff here is just to make Sphinx to properly parse the text file, as they're already in good shape, not requiring massive changes in order to be parsed. The conversion is actually: - add blank lines and identation in order to identify paragraphs; - fix tables markups; - add some lists markups; - mark literal blocks; - adjust title markups. At its new index.rst, let's add a :orphan: while this is not linked to the main index.rst file, in order to avoid build warnings. Signed-off-by: Mauro Carvalho Chehab Acked-by: Federico Vaga --- Documentation/kernel-hacking/locking.rst | 2 +- Documentation/locking/index.rst | 24 +++ ...{lockdep-design.txt => lockdep-design.rst} | 51 +++-- Documentation/locking/lockstat.rst | 204 ++++++++++++++++++ Documentation/locking/lockstat.txt | 183 ---------------- .../{locktorture.txt => locktorture.rst} | 105 +++++---- .../{mutex-design.txt => mutex-design.rst} | 26 ++- ...t-mutex-design.txt => rt-mutex-design.rst} | 139 ++++++------ .../locking/{rt-mutex.txt => rt-mutex.rst} | 30 +-- .../locking/{spinlocks.txt => spinlocks.rst} | 32 ++- ...w-mutex-design.txt => ww-mutex-design.rst} | 82 +++---- Documentation/pi-futex.txt | 2 +- .../it_IT/kernel-hacking/locking.rst | 2 +- drivers/gpu/drm/drm_modeset_lock.c | 2 +- include/linux/lockdep.h | 2 +- include/linux/mutex.h | 2 +- include/linux/rwsem.h | 2 +- kernel/locking/mutex.c | 2 +- kernel/locking/rtmutex.c | 2 +- lib/Kconfig.debug | 4 +- 20 files changed, 511 insertions(+), 387 deletions(-) create mode 100644 Documentation/locking/index.rst rename Documentation/locking/{lockdep-design.txt => lockdep-design.rst} (93%) create mode 100644 Documentation/locking/lockstat.rst delete mode 100644 Documentation/locking/lockstat.txt rename Documentation/locking/{locktorture.txt => locktorture.rst} (57%) rename Documentation/locking/{mutex-design.txt => mutex-design.rst} (94%) rename Documentation/locking/{rt-mutex-design.txt => rt-mutex-design.rst} (91%) rename Documentation/locking/{rt-mutex.txt => rt-mutex.rst} (71%) rename Documentation/locking/{spinlocks.txt => spinlocks.rst} (89%) rename Documentation/locking/{ww-mutex-design.txt => ww-mutex-design.rst} (93%) diff --git a/Documentation/kernel-hacking/locking.rst b/Documentation/kernel-hacking/locking.rst index dc698ea456e0..a8518ac0d31d 100644 --- a/Documentation/kernel-hacking/locking.rst +++ b/Documentation/kernel-hacking/locking.rst @@ -1364,7 +1364,7 @@ Futex API reference Further reading =============== -- ``Documentation/locking/spinlocks.txt``: Linus Torvalds' spinlocking +- ``Documentation/locking/spinlocks.rst``: Linus Torvalds' spinlocking tutorial in the kernel sources. - Unix Systems for Modern Architectures: Symmetric Multiprocessing and diff --git a/Documentation/locking/index.rst b/Documentation/locking/index.rst new file mode 100644 index 000000000000..ef5da7fe9aac --- /dev/null +++ b/Documentation/locking/index.rst @@ -0,0 +1,24 @@ +:orphan: + +======= +locking +======= + +.. toctree:: + :maxdepth: 1 + + lockdep-design + lockstat + locktorture + mutex-design + rt-mutex-design + rt-mutex + spinlocks + ww-mutex-design + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/locking/lockdep-design.txt b/Documentation/locking/lockdep-design.rst similarity index 93% rename from Documentation/locking/lockdep-design.txt rename to Documentation/locking/lockdep-design.rst index f189d130e543..23fcbc4d3fc0 100644 --- a/Documentation/locking/lockdep-design.txt +++ b/Documentation/locking/lockdep-design.rst @@ -2,6 +2,7 @@ Runtime locking correctness validator ===================================== started by Ingo Molnar + additions by Arjan van de Ven Lock-class @@ -56,7 +57,7 @@ where the last 1 category is: When locking rules are violated, these usage bits are presented in the locking error messages, inside curlies, with a total of 2 * n STATEs bits. -A contrived example: +A contrived example:: modprobe/2287 is trying to acquire lock: (&sio_locks[i].lock){-.-.}, at: [] mutex_lock+0x21/0x24 @@ -70,12 +71,14 @@ of the lock and readlock (if exists), for each of the n STATEs listed above respectively, and the character displayed at each bit position indicates: + === =================================================== '.' acquired while irqs disabled and not in irq context '-' acquired in irq context '+' acquired with irqs enabled '?' acquired in irq context with irqs enabled. + === =================================================== -The bits are illustrated with an example: +The bits are illustrated with an example:: (&sio_locks[i].lock){-.-.}, at: [] mutex_lock+0x21/0x24 |||| @@ -90,13 +93,13 @@ context and whether that STATE is enabled yields four possible cases as shown in the table below. The bit character is able to indicate which exact case is for the lock as of the reporting time. - ------------------------------------------- + +--------------+-------------+--------------+ | | irq enabled | irq disabled | - |-------------------------------------------| + +--------------+-------------+--------------+ | ever in irq | ? | - | - |-------------------------------------------| + +--------------+-------------+--------------+ | never in irq | + | . | - ------------------------------------------- + +--------------+-------------+--------------+ The character '-' suggests irq is disabled because if otherwise the charactor '?' would have been shown instead. Similar deduction can be @@ -113,7 +116,7 @@ is irq-unsafe means it was ever acquired with irq enabled. A softirq-unsafe lock-class is automatically hardirq-unsafe as well. The following states must be exclusive: only one of them is allowed to be set -for any lock-class based on its usage: +for any lock-class based on its usage:: or or @@ -134,7 +137,7 @@ Multi-lock dependency rules: The same lock-class must not be acquired twice, because this could lead to lock recursion deadlocks. -Furthermore, two locks can not be taken in inverse order: +Furthermore, two locks can not be taken in inverse order:: -> -> @@ -148,7 +151,7 @@ operations; the validator will still find whether these locks can be acquired in a circular fashion. Furthermore, the following usage based lock dependencies are not allowed -between any two lock-classes: +between any two lock-classes:: -> -> @@ -204,16 +207,16 @@ the ordering is not static. In order to teach the validator about this correct usage model, new versions of the various locking primitives were added that allow you to specify a "nesting level". An example call, for the block device mutex, -looks like this: +looks like this:: -enum bdev_bd_mutex_lock_class -{ + enum bdev_bd_mutex_lock_class + { BD_MUTEX_NORMAL, BD_MUTEX_WHOLE, BD_MUTEX_PARTITION -}; + }; - mutex_lock_nested(&bdev->bd_contains->bd_mutex, BD_MUTEX_PARTITION); +mutex_lock_nested(&bdev->bd_contains->bd_mutex, BD_MUTEX_PARTITION); In this case the locking is done on a bdev object that is known to be a partition. @@ -234,7 +237,7 @@ must be held: lockdep_assert_held*(&lock) and lockdep_*pin_lock(&lock). As the name suggests, lockdep_assert_held* family of macros assert that a particular lock is held at a certain time (and generate a WARN() otherwise). This annotation is largely used all over the kernel, e.g. kernel/sched/ -core.c +core.c:: void update_rq_clock(struct rq *rq) { @@ -253,7 +256,7 @@ out to be especially helpful to debug code with callbacks, where an upper layer assumes a lock remains taken, but a lower layer thinks it can maybe drop and reacquire the lock ("unwittingly" introducing races). lockdep_pin_lock() returns a 'struct pin_cookie' that is then used by lockdep_unpin_lock() to check -that nobody tampered with the lock, e.g. kernel/sched/sched.h +that nobody tampered with the lock, e.g. kernel/sched/sched.h:: static inline void rq_pin_lock(struct rq *rq, struct rq_flags *rf) { @@ -280,7 +283,7 @@ correctness) in the sense that for every simple, standalone single-task locking sequence that occurred at least once during the lifetime of the kernel, the validator proves it with a 100% certainty that no combination and timing of these locking sequences can cause any class of -lock related deadlock. [*] +lock related deadlock. [1]_ I.e. complex multi-CPU and multi-task locking scenarios do not have to occur in practice to prove a deadlock: only the simple 'component' @@ -299,7 +302,9 @@ possible combination of locking interaction between CPUs, combined with every possible hardirq and softirq nesting scenario (which is impossible to do in practice). -[*] assuming that the validator itself is 100% correct, and no other +.. [1] + + assuming that the validator itself is 100% correct, and no other part of the system corrupts the state of the validator in any way. We also assume that all NMI/SMM paths [which could interrupt even hardirq-disabled codepaths] are correct and do not interfere @@ -310,7 +315,7 @@ to do in practice). Performance: ------------ -The above rules require _massive_ amounts of runtime checking. If we did +The above rules require **massive** amounts of runtime checking. If we did that for every lock taken and for every irqs-enable event, it would render the system practically unusably slow. The complexity of checking is O(N^2), so even with just a few hundred lock-classes we'd have to do @@ -369,17 +374,17 @@ be harder to do than to say. Of course, if you do run out of lock classes, the next thing to do is to find the offending lock classes. First, the following command gives -you the number of lock classes currently in use along with the maximum: +you the number of lock classes currently in use along with the maximum:: grep "lock-classes" /proc/lockdep_stats -This command produces the following output on a modest system: +This command produces the following output on a modest system:: - lock-classes: 748 [max: 8191] + lock-classes: 748 [max: 8191] If the number allocated (748 above) increases continually over time, then there is likely a leak. The following command can be used to -identify the leaking lock classes: +identify the leaking lock classes:: grep "BD" /proc/lockdep diff --git a/Documentation/locking/lockstat.rst b/Documentation/locking/lockstat.rst new file mode 100644 index 000000000000..536eab8dbd99 --- /dev/null +++ b/Documentation/locking/lockstat.rst @@ -0,0 +1,204 @@ +=============== +Lock Statistics +=============== + +What +==== + +As the name suggests, it provides statistics on locks. + + +Why +=== + +Because things like lock contention can severely impact performance. + +How +=== + +Lockdep already has hooks in the lock functions and maps lock instances to +lock classes. We build on that (see Documentation/locking/lockdep-design.rst). +The graph below shows the relation between the lock functions and the various +hooks therein:: + + __acquire + | + lock _____ + | \ + | __contended + | | + | + | _______/ + |/ + | + __acquired + | + . + + . + | + __release + | + unlock + + lock, unlock - the regular lock functions + __* - the hooks + <> - states + +With these hooks we provide the following statistics: + + con-bounces + - number of lock contention that involved x-cpu data + contentions + - number of lock acquisitions that had to wait + wait time + min + - shortest (non-0) time we ever had to wait for a lock + max + - longest time we ever had to wait for a lock + total + - total time we spend waiting on this lock + avg + - average time spent waiting on this lock + acq-bounces + - number of lock acquisitions that involved x-cpu data + acquisitions + - number of times we took the lock + hold time + min + - shortest (non-0) time we ever held the lock + max + - longest time we ever held the lock + total + - total time this lock was held + avg + - average time this lock was held + +These numbers are gathered per lock class, per read/write state (when +applicable). + +It also tracks 4 contention points per class. A contention point is a call site +that had to wait on lock acquisition. + +Configuration +------------- + +Lock statistics are enabled via CONFIG_LOCK_STAT. + +Usage +----- + +Enable collection of statistics:: + + # echo 1 >/proc/sys/kernel/lock_stat + +Disable collection of statistics:: + + # echo 0 >/proc/sys/kernel/lock_stat + +Look at the current lock statistics:: + + ( line numbers not part of actual output, done for clarity in the explanation + below ) + + # less /proc/lock_stat + + 01 lock_stat version 0.4 + 02----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- + 03 class name con-bounces contentions waittime-min waittime-max waittime-total waittime-avg acq-bounces acquisitions holdtime-min holdtime-max holdtime-total holdtime-avg + 04----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- + 05 + 06 &mm->mmap_sem-W: 46 84 0.26 939.10 16371.53 194.90 47291 2922365 0.16 2220301.69 17464026916.32 5975.99 + 07 &mm->mmap_sem-R: 37 100 1.31 299502.61 325629.52 3256.30 212344 34316685 0.10 7744.91 95016910.20 2.77 + 08 --------------- + 09 &mm->mmap_sem 1 [] khugepaged_scan_mm_slot+0x57/0x280 + 10 &mm->mmap_sem 96 [] __do_page_fault+0x1d4/0x510 + 11 &mm->mmap_sem 34 [] vm_mmap_pgoff+0x87/0xd0 + 12 &mm->mmap_sem 17 [] vm_munmap+0x41/0x80 + 13 --------------- + 14 &mm->mmap_sem 1 [] dup_mmap+0x2a/0x3f0 + 15 &mm->mmap_sem 60 [] SyS_mprotect+0xe9/0x250 + 16 &mm->mmap_sem 41 [] __do_page_fault+0x1d4/0x510 + 17 &mm->mmap_sem 68 [] vm_mmap_pgoff+0x87/0xd0 + 18 + 19............................................................................................................................................................................................................................. + 20 + 21 unix_table_lock: 110 112 0.21 49.24 163.91 1.46 21094 66312 0.12 624.42 31589.81 0.48 + 22 --------------- + 23 unix_table_lock 45 [] unix_create1+0x16e/0x1b0 + 24 unix_table_lock 47 [] unix_release_sock+0x31/0x250 + 25 unix_table_lock 15 [] unix_find_other+0x117/0x230 + 26 unix_table_lock 5 [] unix_autobind+0x11f/0x1b0 + 27 --------------- + 28 unix_table_lock 39 [] unix_release_sock+0x31/0x250 + 29 unix_table_lock 49 [] unix_create1+0x16e/0x1b0 + 30 unix_table_lock 20 [] unix_find_other+0x117/0x230 + 31 unix_table_lock 4 [] unix_autobind+0x11f/0x1b0 + + +This excerpt shows the first two lock class statistics. Line 01 shows the +output version - each time the format changes this will be updated. Line 02-04 +show the header with column descriptions. Lines 05-18 and 20-31 show the actual +statistics. These statistics come in two parts; the actual stats separated by a +short separator (line 08, 13) from the contention points. + +Lines 09-12 show the first 4 recorded contention points (the code +which tries to get the lock) and lines 14-17 show the first 4 recorded +contended points (the lock holder). It is possible that the max +con-bounces point is missing in the statistics. + +The first lock (05-18) is a read/write lock, and shows two lines above the +short separator. The contention points don't match the column descriptors, +they have two: contentions and [] symbol. The second set of contention +points are the points we're contending with. + +The integer part of the time values is in us. + +Dealing with nested locks, subclasses may appear:: + + 32........................................................................................................................................................................................................................... + 33 + 34 &rq->lock: 13128 13128 0.43 190.53 103881.26 7.91 97454 3453404 0.00 401.11 13224683.11 3.82 + 35 --------- + 36 &rq->lock 645 [] task_rq_lock+0x43/0x75 + 37 &rq->lock 297 [] try_to_wake_up+0x127/0x25a + 38 &rq->lock 360 [] select_task_rq_fair+0x1f0/0x74a + 39 &rq->lock 428 [] scheduler_tick+0x46/0x1fb + 40 --------- + 41 &rq->lock 77 [] task_rq_lock+0x43/0x75 + 42 &rq->lock 174 [] try_to_wake_up+0x127/0x25a + 43 &rq->lock 4715 [] double_rq_lock+0x42/0x54 + 44 &rq->lock 893 [] schedule+0x157/0x7b8 + 45 + 46........................................................................................................................................................................................................................... + 47 + 48 &rq->lock/1: 1526 11488 0.33 388.73 136294.31 11.86 21461 38404 0.00 37.93 109388.53 2.84 + 49 ----------- + 50 &rq->lock/1 11526 [] double_rq_lock+0x4f/0x54 + 51 ----------- + 52 &rq->lock/1 5645 [] double_rq_lock+0x42/0x54 + 53 &rq->lock/1 1224 [] schedule+0x157/0x7b8 + 54 &rq->lock/1 4336 [] double_rq_lock+0x4f/0x54 + 55 &rq->lock/1 181 [] try_to_wake_up+0x127/0x25a + +Line 48 shows statistics for the second subclass (/1) of &rq->lock class +(subclass starts from 0), since in this case, as line 50 suggests, +double_rq_lock actually acquires a nested lock of two spinlocks. + +View the top contending locks:: + + # grep : /proc/lock_stat | head + clockevents_lock: 2926159 2947636 0.15 46882.81 1784540466.34 605.41 3381345 3879161 0.00 2260.97 53178395.68 13.71 + tick_broadcast_lock: 346460 346717 0.18 2257.43 39364622.71 113.54 3642919 4242696 0.00 2263.79 49173646.60 11.59 + &mapping->i_mmap_mutex: 203896 203899 3.36 645530.05 31767507988.39 155800.21 3361776 8893984 0.17 2254.15 14110121.02 1.59 + &rq->lock: 135014 136909 0.18 606.09 842160.68 6.15 1540728 10436146 0.00 728.72 17606683.41 1.69 + &(&zone->lru_lock)->rlock: 93000 94934 0.16 59.18 188253.78 1.98 1199912 3809894 0.15 391.40 3559518.81 0.93 + tasklist_lock-W: 40667 41130 0.23 1189.42 428980.51 10.43 270278 510106 0.16 653.51 3939674.91 7.72 + tasklist_lock-R: 21298 21305 0.20 1310.05 215511.12 10.12 186204 241258 0.14 1162.33 1179779.23 4.89 + rcu_node_1: 47656 49022 0.16 635.41 193616.41 3.95 844888 1865423 0.00 764.26 1656226.96 0.89 + &(&dentry->d_lockref.lock)->rlock: 39791 40179 0.15 1302.08 88851.96 2.21 2790851 12527025 0.10 1910.75 3379714.27 0.27 + rcu_node_0: 29203 30064 0.16 786.55 1555573.00 51.74 88963 244254 0.00 398.87 428872.51 1.76 + +Clear the statistics:: + + # echo 0 > /proc/lock_stat diff --git a/Documentation/locking/lockstat.txt b/Documentation/locking/lockstat.txt deleted file mode 100644 index fdbeb0c45ef3..000000000000 --- a/Documentation/locking/lockstat.txt +++ /dev/null @@ -1,183 +0,0 @@ - -LOCK STATISTICS - -- WHAT - -As the name suggests, it provides statistics on locks. - -- WHY - -Because things like lock contention can severely impact performance. - -- HOW - -Lockdep already has hooks in the lock functions and maps lock instances to -lock classes. We build on that (see Documentation/locking/lockdep-design.txt). -The graph below shows the relation between the lock functions and the various -hooks therein. - - __acquire - | - lock _____ - | \ - | __contended - | | - | - | _______/ - |/ - | - __acquired - | - . - - . - | - __release - | - unlock - -lock, unlock - the regular lock functions -__* - the hooks -<> - states - -With these hooks we provide the following statistics: - - con-bounces - number of lock contention that involved x-cpu data - contentions - number of lock acquisitions that had to wait - wait time min - shortest (non-0) time we ever had to wait for a lock - max - longest time we ever had to wait for a lock - total - total time we spend waiting on this lock - avg - average time spent waiting on this lock - acq-bounces - number of lock acquisitions that involved x-cpu data - acquisitions - number of times we took the lock - hold time min - shortest (non-0) time we ever held the lock - max - longest time we ever held the lock - total - total time this lock was held - avg - average time this lock was held - -These numbers are gathered per lock class, per read/write state (when -applicable). - -It also tracks 4 contention points per class. A contention point is a call site -that had to wait on lock acquisition. - - - CONFIGURATION - -Lock statistics are enabled via CONFIG_LOCK_STAT. - - - USAGE - -Enable collection of statistics: - -# echo 1 >/proc/sys/kernel/lock_stat - -Disable collection of statistics: - -# echo 0 >/proc/sys/kernel/lock_stat - -Look at the current lock statistics: - -( line numbers not part of actual output, done for clarity in the explanation - below ) - -# less /proc/lock_stat - -01 lock_stat version 0.4 -02----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- -03 class name con-bounces contentions waittime-min waittime-max waittime-total waittime-avg acq-bounces acquisitions holdtime-min holdtime-max holdtime-total holdtime-avg -04----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- -05 -06 &mm->mmap_sem-W: 46 84 0.26 939.10 16371.53 194.90 47291 2922365 0.16 2220301.69 17464026916.32 5975.99 -07 &mm->mmap_sem-R: 37 100 1.31 299502.61 325629.52 3256.30 212344 34316685 0.10 7744.91 95016910.20 2.77 -08 --------------- -09 &mm->mmap_sem 1 [] khugepaged_scan_mm_slot+0x57/0x280 -10 &mm->mmap_sem 96 [] __do_page_fault+0x1d4/0x510 -11 &mm->mmap_sem 34 [] vm_mmap_pgoff+0x87/0xd0 -12 &mm->mmap_sem 17 [] vm_munmap+0x41/0x80 -13 --------------- -14 &mm->mmap_sem 1 [] dup_mmap+0x2a/0x3f0 -15 &mm->mmap_sem 60 [] SyS_mprotect+0xe9/0x250 -16 &mm->mmap_sem 41 [] __do_page_fault+0x1d4/0x510 -17 &mm->mmap_sem 68 [] vm_mmap_pgoff+0x87/0xd0 -18 -19............................................................................................................................................................................................................................. -20 -21 unix_table_lock: 110 112 0.21 49.24 163.91 1.46 21094 66312 0.12 624.42 31589.81 0.48 -22 --------------- -23 unix_table_lock 45 [] unix_create1+0x16e/0x1b0 -24 unix_table_lock 47 [] unix_release_sock+0x31/0x250 -25 unix_table_lock 15 [] unix_find_other+0x117/0x230 -26 unix_table_lock 5 [] unix_autobind+0x11f/0x1b0 -27 --------------- -28 unix_table_lock 39 [] unix_release_sock+0x31/0x250 -29 unix_table_lock 49 [] unix_create1+0x16e/0x1b0 -30 unix_table_lock 20 [] unix_find_other+0x117/0x230 -31 unix_table_lock 4 [] unix_autobind+0x11f/0x1b0 - - -This excerpt shows the first two lock class statistics. Line 01 shows the -output version - each time the format changes this will be updated. Line 02-04 -show the header with column descriptions. Lines 05-18 and 20-31 show the actual -statistics. These statistics come in two parts; the actual stats separated by a -short separator (line 08, 13) from the contention points. - -Lines 09-12 show the first 4 recorded contention points (the code -which tries to get the lock) and lines 14-17 show the first 4 recorded -contended points (the lock holder). It is possible that the max -con-bounces point is missing in the statistics. - -The first lock (05-18) is a read/write lock, and shows two lines above the -short separator. The contention points don't match the column descriptors, -they have two: contentions and [] symbol. The second set of contention -points are the points we're contending with. - -The integer part of the time values is in us. - -Dealing with nested locks, subclasses may appear: - -32........................................................................................................................................................................................................................... -33 -34 &rq->lock: 13128 13128 0.43 190.53 103881.26 7.91 97454 3453404 0.00 401.11 13224683.11 3.82 -35 --------- -36 &rq->lock 645 [] task_rq_lock+0x43/0x75 -37 &rq->lock 297 [] try_to_wake_up+0x127/0x25a -38 &rq->lock 360 [] select_task_rq_fair+0x1f0/0x74a -39 &rq->lock 428 [] scheduler_tick+0x46/0x1fb -40 --------- -41 &rq->lock 77 [] task_rq_lock+0x43/0x75 -42 &rq->lock 174 [] try_to_wake_up+0x127/0x25a -43 &rq->lock 4715 [] double_rq_lock+0x42/0x54 -44 &rq->lock 893 [] schedule+0x157/0x7b8 -45 -46........................................................................................................................................................................................................................... -47 -48 &rq->lock/1: 1526 11488 0.33 388.73 136294.31 11.86 21461 38404 0.00 37.93 109388.53 2.84 -49 ----------- -50 &rq->lock/1 11526 [] double_rq_lock+0x4f/0x54 -51 ----------- -52 &rq->lock/1 5645 [] double_rq_lock+0x42/0x54 -53 &rq->lock/1 1224 [] schedule+0x157/0x7b8 -54 &rq->lock/1 4336 [] double_rq_lock+0x4f/0x54 -55 &rq->lock/1 181 [] try_to_wake_up+0x127/0x25a - -Line 48 shows statistics for the second subclass (/1) of &rq->lock class -(subclass starts from 0), since in this case, as line 50 suggests, -double_rq_lock actually acquires a nested lock of two spinlocks. - -View the top contending locks: - -# grep : /proc/lock_stat | head - clockevents_lock: 2926159 2947636 0.15 46882.81 1784540466.34 605.41 3381345 3879161 0.00 2260.97 53178395.68 13.71 - tick_broadcast_lock: 346460 346717 0.18 2257.43 39364622.71 113.54 3642919 4242696 0.00 2263.79 49173646.60 11.59 - &mapping->i_mmap_mutex: 203896 203899 3.36 645530.05 31767507988.39 155800.21 3361776 8893984 0.17 2254.15 14110121.02 1.59 - &rq->lock: 135014 136909 0.18 606.09 842160.68 6.15 1540728 10436146 0.00 728.72 17606683.41 1.69 - &(&zone->lru_lock)->rlock: 93000 94934 0.16 59.18 188253.78 1.98 1199912 3809894 0.15 391.40 3559518.81 0.93 - tasklist_lock-W: 40667 41130 0.23 1189.42 428980.51 10.43 270278 510106 0.16 653.51 3939674.91 7.72 - tasklist_lock-R: 21298 21305 0.20 1310.05 215511.12 10.12 186204 241258 0.14 1162.33 1179779.23 4.89 - rcu_node_1: 47656 49022 0.16 635.41 193616.41 3.95 844888 1865423 0.00 764.26 1656226.96 0.89 - &(&dentry->d_lockref.lock)->rlock: 39791 40179 0.15 1302.08 88851.96 2.21 2790851 12527025 0.10 1910.75 3379714.27 0.27 - rcu_node_0: 29203 30064 0.16 786.55 1555573.00 51.74 88963 244254 0.00 398.87 428872.51 1.76 - -Clear the statistics: - -# echo 0 > /proc/lock_stat diff --git a/Documentation/locking/locktorture.txt b/Documentation/locking/locktorture.rst similarity index 57% rename from Documentation/locking/locktorture.txt rename to Documentation/locking/locktorture.rst index 6a8df4cd19bf..e79eeeca3ac6 100644 --- a/Documentation/locking/locktorture.txt +++ b/Documentation/locking/locktorture.rst @@ -1,6 +1,9 @@ +================================== Kernel Lock Torture Test Operation +================================== CONFIG_LOCK_TORTURE_TEST +======================== The CONFIG LOCK_TORTURE_TEST config option provides a kernel module that runs torture tests on core kernel locking primitives. The kernel @@ -18,61 +21,77 @@ can be simulated by either enlarging this critical region hold time and/or creating more kthreads. -MODULE PARAMETERS +Module Parameters +================= This module has the following parameters: - ** Locktorture-specific ** +Locktorture-specific +-------------------- -nwriters_stress Number of kernel threads that will stress exclusive lock +nwriters_stress + Number of kernel threads that will stress exclusive lock ownership (writers). The default value is twice the number of online CPUs. -nreaders_stress Number of kernel threads that will stress shared lock +nreaders_stress + Number of kernel threads that will stress shared lock ownership (readers). The default is the same amount of writer locks. If the user did not specify nwriters_stress, then both readers and writers be the amount of online CPUs. -torture_type Type of lock to torture. By default, only spinlocks will +torture_type + Type of lock to torture. By default, only spinlocks will be tortured. This module can torture the following locks, with string values as follows: - o "lock_busted": Simulates a buggy lock implementation. + - "lock_busted": + Simulates a buggy lock implementation. - o "spin_lock": spin_lock() and spin_unlock() pairs. + - "spin_lock": + spin_lock() and spin_unlock() pairs. - o "spin_lock_irq": spin_lock_irq() and spin_unlock_irq() - pairs. + - "spin_lock_irq": + spin_lock_irq() and spin_unlock_irq() pairs. - o "rw_lock": read/write lock() and unlock() rwlock pairs. + - "rw_lock": + read/write lock() and unlock() rwlock pairs. - o "rw_lock_irq": read/write lock_irq() and unlock_irq() - rwlock pairs. + - "rw_lock_irq": + read/write lock_irq() and unlock_irq() + rwlock pairs. - o "mutex_lock": mutex_lock() and mutex_unlock() pairs. + - "mutex_lock": + mutex_lock() and mutex_unlock() pairs. - o "rtmutex_lock": rtmutex_lock() and rtmutex_unlock() - pairs. Kernel must have CONFIG_RT_MUTEX=y. + - "rtmutex_lock": + rtmutex_lock() and rtmutex_unlock() pairs. + Kernel must have CONFIG_RT_MUTEX=y. - o "rwsem_lock": read/write down() and up() semaphore pairs. + - "rwsem_lock": + read/write down() and up() semaphore pairs. - ** Torture-framework (RCU + locking) ** +Torture-framework (RCU + locking) +--------------------------------- -shutdown_secs The number of seconds to run the test before terminating +shutdown_secs + The number of seconds to run the test before terminating the test and powering off the system. The default is zero, which disables test termination and system shutdown. This capability is useful for automated testing. -onoff_interval The number of seconds between each attempt to execute a +onoff_interval + The number of seconds between each attempt to execute a randomly selected CPU-hotplug operation. Defaults to zero, which disables CPU hotplugging. In CONFIG_HOTPLUG_CPU=n kernels, locktorture will silently refuse to do any CPU-hotplug operations regardless of what value is specified for onoff_interval. -onoff_holdoff The number of seconds to wait until starting CPU-hotplug +onoff_holdoff + The number of seconds to wait until starting CPU-hotplug operations. This would normally only be used when locktorture was built into the kernel and started automatically at boot time, in which case it is useful @@ -80,53 +99,59 @@ onoff_holdoff The number of seconds to wait until starting CPU-hotplug coming and going. This parameter is only useful if CONFIG_HOTPLUG_CPU is enabled. -stat_interval Number of seconds between statistics-related printk()s. +stat_interval + Number of seconds between statistics-related printk()s. By default, locktorture will report stats every 60 seconds. Setting the interval to zero causes the statistics to be printed -only- when the module is unloaded, and this is the default. -stutter The length of time to run the test before pausing for this +stutter + The length of time to run the test before pausing for this same period of time. Defaults to "stutter=5", so as to run and pause for (roughly) five-second intervals. Specifying "stutter=0" causes the test to run continuously without pausing, which is the old default behavior. -shuffle_interval The number of seconds to keep the test threads affinitied +shuffle_interval + The number of seconds to keep the test threads affinitied to a particular subset of the CPUs, defaults to 3 seconds. Used in conjunction with test_no_idle_hz. -verbose Enable verbose debugging printing, via printk(). Enabled +verbose + Enable verbose debugging printing, via printk(). Enabled by default. This extra information is mostly related to high-level errors and reports from the main 'torture' framework. -STATISTICS +Statistics +========== -Statistics are printed in the following format: +Statistics are printed in the following format:: -spin_lock-torture: Writes: Total: 93746064 Max/Min: 0/0 Fail: 0 - (A) (B) (C) (D) (E) + spin_lock-torture: Writes: Total: 93746064 Max/Min: 0/0 Fail: 0 + (A) (B) (C) (D) (E) -(A): Lock type that is being tortured -- torture_type parameter. + (A): Lock type that is being tortured -- torture_type parameter. -(B): Number of writer lock acquisitions. If dealing with a read/write primitive - a second "Reads" statistics line is printed. + (B): Number of writer lock acquisitions. If dealing with a read/write + primitive a second "Reads" statistics line is printed. -(C): Number of times the lock was acquired. + (C): Number of times the lock was acquired. -(D): Min and max number of times threads failed to acquire the lock. + (D): Min and max number of times threads failed to acquire the lock. -(E): true/false values if there were errors acquiring the lock. This should - -only- be positive if there is a bug in the locking primitive's - implementation. Otherwise a lock should never fail (i.e., spin_lock()). - Of course, the same applies for (C), above. A dummy example of this is - the "lock_busted" type. + (E): true/false values if there were errors acquiring the lock. This should + -only- be positive if there is a bug in the locking primitive's + implementation. Otherwise a lock should never fail (i.e., spin_lock()). + Of course, the same applies for (C), above. A dummy example of this is + the "lock_busted" type. -USAGE +Usage +===== -The following script may be used to torture locks: +The following script may be used to torture locks:: #!/bin/sh diff --git a/Documentation/locking/mutex-design.txt b/Documentation/locking/mutex-design.rst similarity index 94% rename from Documentation/locking/mutex-design.txt rename to Documentation/locking/mutex-design.rst index 818aca19612f..4d8236b81fa5 100644 --- a/Documentation/locking/mutex-design.txt +++ b/Documentation/locking/mutex-design.rst @@ -1,6 +1,9 @@ +======================= Generic Mutex Subsystem +======================= started by Ingo Molnar + updated by Davidlohr Bueso What are mutexes? @@ -23,7 +26,7 @@ Implementation Mutexes are represented by 'struct mutex', defined in include/linux/mutex.h and implemented in kernel/locking/mutex.c. These locks use an atomic variable (->owner) to keep track of the lock state during its lifetime. Field owner -actually contains 'struct task_struct *' to the current lock owner and it is +actually contains `struct task_struct *` to the current lock owner and it is therefore NULL if not currently owned. Since task_struct pointers are aligned at at least L1_CACHE_BYTES, low bits (3) are used to store extra state (e.g., if waiter list is non-empty). In its most basic form it also includes a @@ -101,29 +104,36 @@ features that make lock debugging easier and faster: Interfaces ---------- -Statically define the mutex: +Statically define the mutex:: + DEFINE_MUTEX(name); -Dynamically initialize the mutex: +Dynamically initialize the mutex:: + mutex_init(mutex); -Acquire the mutex, uninterruptible: +Acquire the mutex, uninterruptible:: + void mutex_lock(struct mutex *lock); void mutex_lock_nested(struct mutex *lock, unsigned int subclass); int mutex_trylock(struct mutex *lock); -Acquire the mutex, interruptible: +Acquire the mutex, interruptible:: + int mutex_lock_interruptible_nested(struct mutex *lock, unsigned int subclass); int mutex_lock_interruptible(struct mutex *lock); -Acquire the mutex, interruptible, if dec to 0: +Acquire the mutex, interruptible, if dec to 0:: + int atomic_dec_and_mutex_lock(atomic_t *cnt, struct mutex *lock); -Unlock the mutex: +Unlock the mutex:: + void mutex_unlock(struct mutex *lock); -Test if the mutex is taken: +Test if the mutex is taken:: + int mutex_is_locked(struct mutex *lock); Disadvantages diff --git a/Documentation/locking/rt-mutex-design.txt b/Documentation/locking/rt-mutex-design.rst similarity index 91% rename from Documentation/locking/rt-mutex-design.txt rename to Documentation/locking/rt-mutex-design.rst index 3d7b865539cc..59c2a64efb21 100644 --- a/Documentation/locking/rt-mutex-design.txt +++ b/Documentation/locking/rt-mutex-design.rst @@ -1,14 +1,15 @@ -# -# Copyright (c) 2006 Steven Rostedt -# Licensed under the GNU Free Documentation License, Version 1.2 -# - +============================== RT-mutex implementation design ------------------------------- +============================== + +Copyright (c) 2006 Steven Rostedt + +Licensed under the GNU Free Documentation License, Version 1.2 + This document tries to describe the design of the rtmutex.c implementation. It doesn't describe the reasons why rtmutex.c exists. For that please see -Documentation/locking/rt-mutex.txt. Although this document does explain problems +Documentation/locking/rt-mutex.rst. Although this document does explain problems that happen without this code, but that is in the concept to understand what the code actually is doing. @@ -41,17 +42,17 @@ to release the lock, because for all we know, B is a CPU hog and will never give C a chance to release the lock. This is called unbounded priority inversion. -Here's a little ASCII art to show the problem. +Here's a little ASCII art to show the problem:: - grab lock L1 (owned by C) - | -A ---+ - C preempted by B - | -C +----+ + grab lock L1 (owned by C) + | + A ---+ + C preempted by B + | + C +----+ -B +--------> - B now keeps A from running. + B +--------> + B now keeps A from running. Priority Inheritance (PI) @@ -75,24 +76,29 @@ Terminology Here I explain some terminology that is used in this document to help describe the design that is used to implement PI. -PI chain - The PI chain is an ordered series of locks and processes that cause +PI chain + - The PI chain is an ordered series of locks and processes that cause processes to inherit priorities from a previous process that is blocked on one of its locks. This is described in more detail later in this document. -mutex - In this document, to differentiate from locks that implement +mutex + - In this document, to differentiate from locks that implement PI and spin locks that are used in the PI code, from now on the PI locks will be called a mutex. -lock - In this document from now on, I will use the term lock when +lock + - In this document from now on, I will use the term lock when referring to spin locks that are used to protect parts of the PI algorithm. These locks disable preemption for UP (when CONFIG_PREEMPT is enabled) and on SMP prevents multiple CPUs from entering critical sections simultaneously. -spin lock - Same as lock above. +spin lock + - Same as lock above. -waiter - A waiter is a struct that is stored on the stack of a blocked +waiter + - A waiter is a struct that is stored on the stack of a blocked process. Since the scope of the waiter is within the code for a process being blocked on the mutex, it is fine to allocate the waiter on the process's stack (local variable). This @@ -104,14 +110,18 @@ waiter - A waiter is a struct that is stored on the stack of a blocked waiter is sometimes used in reference to the task that is waiting on a mutex. This is the same as waiter->task. -waiters - A list of processes that are blocked on a mutex. +waiters + - A list of processes that are blocked on a mutex. -top waiter - The highest priority process waiting on a specific mutex. +top waiter + - The highest priority process waiting on a specific mutex. -top pi waiter - The highest priority process waiting on one of the mutexes +top pi waiter + - The highest priority process waiting on one of the mutexes that a specific process owns. -Note: task and process are used interchangeably in this document, mostly to +Note: + task and process are used interchangeably in this document, mostly to differentiate between two processes that are being described together. @@ -123,7 +133,7 @@ inheritance to take place. Multiple chains may converge, but a chain would never diverge, since a process can't be blocked on more than one mutex at a time. -Example: +Example:: Process: A, B, C, D, E Mutexes: L1, L2, L3, L4 @@ -137,21 +147,21 @@ Example: D owns L4 E blocked on L4 -The chain would be: +The chain would be:: E->L4->D->L3->C->L2->B->L1->A To show where two chains merge, we could add another process F and another mutex L5 where B owns L5 and F is blocked on mutex L5. -The chain for F would be: +The chain for F would be:: F->L5->B->L1->A Since a process may own more than one mutex, but never be blocked on more than one, the chains merge. -Here we show both chains: +Here we show both chains:: E->L4->D->L3->C->L2-+ | @@ -165,12 +175,12 @@ than the processes to the left or below in the chain. Also since a mutex may have more than one process blocked on it, we can have multiple chains merge at mutexes. If we add another process G that is -blocked on mutex L2: +blocked on mutex L2:: G->L2->B->L1->A And once again, to show how this can grow I will show the merging chains -again. +again:: E->L4->D->L3->C-+ +->L2-+ @@ -184,7 +194,7 @@ the chain (A and B in this example), must have their priorities increased to that of G. Mutex Waiters Tree ------------------ +------------------ Every mutex keeps track of all the waiters that are blocked on itself. The mutex has a rbtree to store these waiters by priority. This tree is protected @@ -219,19 +229,19 @@ defined. But is very complex to figure it out, since it depends on all the nesting of mutexes. Let's look at the example where we have 3 mutexes, L1, L2, and L3, and four separate functions func1, func2, func3 and func4. The following shows a locking order of L1->L2->L3, but may not actually -be directly nested that way. +be directly nested that way:: -void func1(void) -{ + void func1(void) + { mutex_lock(L1); /* do anything */ mutex_unlock(L1); -} + } -void func2(void) -{ + void func2(void) + { mutex_lock(L1); mutex_lock(L2); @@ -239,10 +249,10 @@ void func2(void) mutex_unlock(L2); mutex_unlock(L1); -} + } -void func3(void) -{ + void func3(void) + { mutex_lock(L2); mutex_lock(L3); @@ -250,30 +260,30 @@ void func3(void) mutex_unlock(L3); mutex_unlock(L2); -} + } -void func4(void) -{ + void func4(void) + { mutex_lock(L3); /* do something again */ mutex_unlock(L3); -} + } Now we add 4 processes that run each of these functions separately. Processes A, B, C, and D which run functions func1, func2, func3 and func4 respectively, and such that D runs first and A last. With D being preempted -in func4 in the "do something again" area, we have a locking that follows: +in func4 in the "do something again" area, we have a locking that follows:: -D owns L3 - C blocked on L3 - C owns L2 - B blocked on L2 - B owns L1 - A blocked on L1 + D owns L3 + C blocked on L3 + C owns L2 + B blocked on L2 + B owns L1 + A blocked on L1 -And thus we have the chain A->L1->B->L2->C->L3->D. + And thus we have the chain A->L1->B->L2->C->L3->D. This gives us a PI depth of 4 (four processes), but looking at any of the functions individually, it seems as though they only have at most a locking @@ -298,7 +308,7 @@ not true, the rtmutex.c code will be broken!), this allows for the least significant bit to be used as a flag. Bit 0 is used as the "Has Waiters" flag. It's set whenever there are waiters on a mutex. -See Documentation/locking/rt-mutex.txt for further details. +See Documentation/locking/rt-mutex.rst for further details. cmpxchg Tricks -------------- @@ -307,17 +317,17 @@ Some architectures implement an atomic cmpxchg (Compare and Exchange). This is used (when applicable) to keep the fast path of grabbing and releasing mutexes short. -cmpxchg is basically the following function performed atomically: +cmpxchg is basically the following function performed atomically:: -unsigned long _cmpxchg(unsigned long *A, unsigned long *B, unsigned long *C) -{ + unsigned long _cmpxchg(unsigned long *A, unsigned long *B, unsigned long *C) + { unsigned long T = *A; if (*A == *B) { *A = *C; } return T; -} -#define cmpxchg(a,b,c) _cmpxchg(&a,&b,&c) + } + #define cmpxchg(a,b,c) _cmpxchg(&a,&b,&c) This is really nice to have, since it allows you to only update a variable if the variable is what you expect it to be. You know if it succeeded if @@ -352,9 +362,10 @@ Then rt_mutex_setprio is called to adjust the priority of the task to the new priority. Note that rt_mutex_setprio is defined in kernel/sched/core.c to implement the actual change in priority. -(Note: For the "prio" field in task_struct, the lower the number, the +Note: + For the "prio" field in task_struct, the lower the number, the higher the priority. A "prio" of 5 is of higher priority than a - "prio" of 10.) + "prio" of 10. It is interesting to note that rt_mutex_adjust_prio can either increase or decrease the priority of the task. In the case that a higher priority @@ -439,6 +450,7 @@ wait_lock, which this code currently holds. So setting the "Has Waiters" flag forces the current owner to synchronize with this code. The lock is taken if the following are true: + 1) The lock has no owner 2) The current task is the highest priority against all other waiters of the lock @@ -546,10 +558,13 @@ Credits ------- Author: Steven Rostedt + Updated: Alex Shi - 7/6/2017 -Original Reviewers: Ingo Molnar, Thomas Gleixner, Thomas Duetsch, and +Original Reviewers: + Ingo Molnar, Thomas Gleixner, Thomas Duetsch, and Randy Dunlap + Update (7/6/2017) Reviewers: Steven Rostedt and Sebastian Siewior Updates diff --git a/Documentation/locking/rt-mutex.txt b/Documentation/locking/rt-mutex.rst similarity index 71% rename from Documentation/locking/rt-mutex.txt rename to Documentation/locking/rt-mutex.rst index 35793e003041..c365dc302081 100644 --- a/Documentation/locking/rt-mutex.txt +++ b/Documentation/locking/rt-mutex.rst @@ -1,5 +1,6 @@ +================================== RT-mutex subsystem with PI support ----------------------------------- +================================== RT-mutexes with priority inheritance are used to support PI-futexes, which enable pthread_mutex_t priority inheritance attributes @@ -46,27 +47,30 @@ The state of the rt-mutex is tracked via the owner field of the rt-mutex structure: lock->owner holds the task_struct pointer of the owner. Bit 0 is used to -keep track of the "lock has waiters" state. +keep track of the "lock has waiters" state: - owner bit0 + ============ ======= ================================================ + owner bit0 Notes + ============ ======= ================================================ NULL 0 lock is free (fast acquire possible) NULL 1 lock is free and has waiters and the top waiter - is going to take the lock* + is going to take the lock [1]_ taskpointer 0 lock is held (fast release possible) - taskpointer 1 lock is held and has waiters** + taskpointer 1 lock is held and has waiters [2]_ + ============ ======= ================================================ The fast atomic compare exchange based acquire and release is only possible when bit 0 of lock->owner is 0. -(*) It also can be a transitional state when grabbing the lock -with ->wait_lock is held. To prevent any fast path cmpxchg to the lock, -we need to set the bit0 before looking at the lock, and the owner may be -NULL in this small time, hence this can be a transitional state. +.. [1] It also can be a transitional state when grabbing the lock + with ->wait_lock is held. To prevent any fast path cmpxchg to the lock, + we need to set the bit0 before looking at the lock, and the owner may + be NULL in this small time, hence this can be a transitional state. -(**) There is a small time when bit 0 is set but there are no -waiters. This can happen when grabbing the lock in the slow path. -To prevent a cmpxchg of the owner releasing the lock, we need to -set this bit before looking at the lock. +.. [2] There is a small time when bit 0 is set but there are no + waiters. This can happen when grabbing the lock in the slow path. + To prevent a cmpxchg of the owner releasing the lock, we need to + set this bit before looking at the lock. BTW, there is still technically a "Pending Owner", it's just not called that anymore. The pending owner happens to be the top_waiter of a lock diff --git a/Documentation/locking/spinlocks.txt b/Documentation/locking/spinlocks.rst similarity index 89% rename from Documentation/locking/spinlocks.txt rename to Documentation/locking/spinlocks.rst index ff35e40bdf5b..098107fb7d86 100644 --- a/Documentation/locking/spinlocks.txt +++ b/Documentation/locking/spinlocks.rst @@ -1,8 +1,13 @@ +=============== +Locking lessons +=============== + Lesson 1: Spin locks +==================== -The most basic primitive for locking is spinlock. +The most basic primitive for locking is spinlock:: -static DEFINE_SPINLOCK(xxx_lock); + static DEFINE_SPINLOCK(xxx_lock); unsigned long flags; @@ -19,23 +24,25 @@ worry about UP vs SMP issues: the spinlocks work correctly under both. NOTE! Implications of spin_locks for memory are further described in: Documentation/memory-barriers.txt + (5) LOCK operations. + (6) UNLOCK operations. The above is usually pretty simple (you usually need and want only one spinlock for most things - using more than one spinlock can make things a lot more complex and even slower and is usually worth it only for -sequences that you _know_ need to be split up: avoid it at all cost if you +sequences that you **know** need to be split up: avoid it at all cost if you aren't sure). This is really the only really hard part about spinlocks: once you start using spinlocks they tend to expand to areas you might not have noticed before, because you have to make sure the spinlocks correctly protect the -shared data structures _everywhere_ they are used. The spinlocks are most +shared data structures **everywhere** they are used. The spinlocks are most easily added to places that are completely independent of other code (for example, internal driver data structures that nobody else ever touches). - NOTE! The spin-lock is safe only when you _also_ use the lock itself + NOTE! The spin-lock is safe only when you **also** use the lock itself to do locking across CPU's, which implies that EVERYTHING that touches a shared variable has to agree about the spinlock they want to use. @@ -43,6 +50,7 @@ example, internal driver data structures that nobody else ever touches). ---- Lesson 2: reader-writer spinlocks. +================================== If your data accesses have a very natural pattern where you usually tend to mostly read from the shared variables, the reader-writer locks @@ -54,7 +62,7 @@ to change the variables it has to get an exclusive write lock. simple spinlocks. Unless the reader critical section is long, you are better off just using spinlocks. -The routines look the same as above: +The routines look the same as above:: rwlock_t xxx_lock = __RW_LOCK_UNLOCKED(xxx_lock); @@ -71,7 +79,7 @@ The routines look the same as above: The above kind of lock may be useful for complex data structures like linked lists, especially searching for entries without changing the list itself. The read lock allows many concurrent readers. Anything that -_changes_ the list will have to get the write lock. +**changes** the list will have to get the write lock. NOTE! RCU is better for list traversal, but requires careful attention to design detail (see Documentation/RCU/listRCU.txt). @@ -87,10 +95,11 @@ to get the write-lock at the very beginning. ---- Lesson 3: spinlocks revisited. +============================== The single spin-lock primitives above are by no means the only ones. They are the most safe ones, and the ones that work under all circumstances, -but partly _because_ they are safe they are also fairly slow. They are slower +but partly **because** they are safe they are also fairly slow. They are slower than they'd need to be, because they do have to disable interrupts (which is just a single instruction on a x86, but it's an expensive one - and on other architectures it can be worse). @@ -98,7 +107,7 @@ and on other architectures it can be worse). If you have a case where you have to protect a data structure across several CPU's and you want to use spinlocks you can potentially use cheaper versions of the spinlocks. IFF you know that the spinlocks are -never used in interrupt handlers, you can use the non-irq versions: +never used in interrupt handlers, you can use the non-irq versions:: spin_lock(&lock); ... @@ -110,7 +119,7 @@ This is useful if you know that the data in question is only ever manipulated from a "process context", ie no interrupts involved. The reasons you mustn't use these versions if you have interrupts that -play with the spinlock is that you can get deadlocks: +play with the spinlock is that you can get deadlocks:: spin_lock(&lock); ... @@ -147,9 +156,10 @@ indeed), while write-locks need to protect themselves against interrupts. ---- Reference information: +====================== For dynamic initialization, use spin_lock_init() or rwlock_init() as -appropriate: +appropriate:: spinlock_t xxx_lock; rwlock_t xxx_rw_lock; diff --git a/Documentation/locking/ww-mutex-design.txt b/Documentation/locking/ww-mutex-design.rst similarity index 93% rename from Documentation/locking/ww-mutex-design.txt rename to Documentation/locking/ww-mutex-design.rst index f0ed7c30e695..1846c199da23 100644 --- a/Documentation/locking/ww-mutex-design.txt +++ b/Documentation/locking/ww-mutex-design.rst @@ -1,3 +1,4 @@ +====================================== Wound/Wait Deadlock-Proof Mutex Design ====================================== @@ -85,6 +86,7 @@ Furthermore there are three different class of w/w lock acquire functions: no deadlock potential and hence the ww_mutex_lock call will block and not prematurely return -EDEADLK. The advantage of the _slow functions is in interface safety: + - ww_mutex_lock has a __must_check int return type, whereas ww_mutex_lock_slow has a void return type. Note that since ww mutex code needs loops/retries anyway the __must_check doesn't result in spurious warnings, even though the @@ -115,36 +117,36 @@ expect the number of simultaneous competing transactions to be typically small, and you want to reduce the number of rollbacks. Three different ways to acquire locks within the same w/w class. Common -definitions for methods #1 and #2: +definitions for methods #1 and #2:: -static DEFINE_WW_CLASS(ww_class); + static DEFINE_WW_CLASS(ww_class); -struct obj { + struct obj { struct ww_mutex lock; /* obj data */ -}; + }; -struct obj_entry { + struct obj_entry { struct list_head head; struct obj *obj; -}; + }; Method 1, using a list in execbuf->buffers that's not allowed to be reordered. This is useful if a list of required objects is already tracked somewhere. Furthermore the lock helper can use propagate the -EALREADY return code back to the caller as a signal that an object is twice on the list. This is useful if the list is constructed from userspace input and the ABI requires userspace to -not have duplicate entries (e.g. for a gpu commandbuffer submission ioctl). +not have duplicate entries (e.g. for a gpu commandbuffer submission ioctl):: -int lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx) -{ + int lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx) + { struct obj *res_obj = NULL; struct obj_entry *contended_entry = NULL; struct obj_entry *entry; ww_acquire_init(ctx, &ww_class); -retry: + retry: list_for_each_entry (entry, list, head) { if (entry->obj == res_obj) { res_obj = NULL; @@ -160,7 +162,7 @@ retry: ww_acquire_done(ctx); return 0; -err: + err: list_for_each_entry_continue_reverse (entry, list, head) ww_mutex_unlock(&entry->obj->lock); @@ -176,14 +178,14 @@ err: ww_acquire_fini(ctx); return ret; -} + } Method 2, using a list in execbuf->buffers that can be reordered. Same semantics of duplicate entry detection using -EALREADY as method 1 above. But the -list-reordering allows for a bit more idiomatic code. +list-reordering allows for a bit more idiomatic code:: -int lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx) -{ + int lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx) + { struct obj_entry *entry, *entry2; ww_acquire_init(ctx, &ww_class); @@ -216,24 +218,25 @@ int lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx) ww_acquire_done(ctx); return 0; -} + } -Unlocking works the same way for both methods #1 and #2: +Unlocking works the same way for both methods #1 and #2:: -void unlock_objs(struct list_head *list, struct ww_acquire_ctx *ctx) -{ + void unlock_objs(struct list_head *list, struct ww_acquire_ctx *ctx) + { struct obj_entry *entry; list_for_each_entry (entry, list, head) ww_mutex_unlock(&entry->obj->lock); ww_acquire_fini(ctx); -} + } Method 3 is useful if the list of objects is constructed ad-hoc and not upfront, e.g. when adjusting edges in a graph where each node has its own ww_mutex lock, and edges can only be changed when holding the locks of all involved nodes. w/w mutexes are a natural fit for such a case for two reasons: + - They can handle lock-acquisition in any order which allows us to start walking a graph from a starting point and then iteratively discovering new edges and locking down the nodes those edges connect to. @@ -243,6 +246,7 @@ mutexes are a natural fit for such a case for two reasons: as a starting point). Note that this approach differs in two important ways from the above methods: + - Since the list of objects is dynamically constructed (and might very well be different when retrying due to hitting the -EDEADLK die condition) there's no need to keep any object on a persistent list when it's not locked. We can @@ -260,17 +264,17 @@ any interface misuse for these cases. Also, method 3 can't fail the lock acquisition step since it doesn't return -EALREADY. Of course this would be different when using the _interruptible -variants, but that's outside of the scope of these examples here. +variants, but that's outside of the scope of these examples here:: -struct obj { + struct obj { struct ww_mutex ww_mutex; struct list_head locked_list; -}; + }; -static DEFINE_WW_CLASS(ww_class); + static DEFINE_WW_CLASS(ww_class); -void __unlock_objs(struct list_head *list) -{ + void __unlock_objs(struct list_head *list) + { struct obj *entry, *temp; list_for_each_entry_safe (entry, temp, list, locked_list) { @@ -279,15 +283,15 @@ void __unlock_objs(struct list_head *list) list_del(&entry->locked_list); ww_mutex_unlock(entry->ww_mutex) } -} + } -void lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx) -{ + void lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx) + { struct obj *obj; ww_acquire_init(ctx, &ww_class); -retry: + retry: /* re-init loop start state */ loop { /* magic code which walks over a graph and decides which objects @@ -312,13 +316,13 @@ retry: ww_acquire_done(ctx); return 0; -} + } -void unlock_objs(struct list_head *list, struct ww_acquire_ctx *ctx) -{ + void unlock_objs(struct list_head *list, struct ww_acquire_ctx *ctx) + { __unlock_objs(list); ww_acquire_fini(ctx); -} + } Method 4: Only lock one single objects. In that case deadlock detection and prevention is obviously overkill, since with grabbing just one lock you can't @@ -329,11 +333,14 @@ Implementation Details ---------------------- Design: +^^^^^^^ + ww_mutex currently encapsulates a struct mutex, this means no extra overhead for normal mutex locks, which are far more common. As such there is only a small increase in code size if wait/wound mutexes are not used. We maintain the following invariants for the wait list: + (1) Waiters with an acquire context are sorted by stamp order; waiters without an acquire context are interspersed in FIFO order. (2) For Wait-Die, among waiters with contexts, only the first one can have @@ -355,6 +362,8 @@ Design: therefore be directed towards the uncontended cases. Lockdep: +^^^^^^^^ + Special care has been taken to warn for as many cases of api abuse as possible. Some common api abuses will be caught with CONFIG_DEBUG_MUTEXES, but CONFIG_PROVE_LOCKING is recommended. @@ -379,5 +388,6 @@ Lockdep: having called ww_acquire_fini on the first. - 'normal' deadlocks that can occur. -FIXME: Update this section once we have the TASK_DEADLOCK task state flag magic -implemented. +FIXME: + Update this section once we have the TASK_DEADLOCK task state flag magic + implemented. diff --git a/Documentation/pi-futex.txt b/Documentation/pi-futex.txt index b154f6c0c36e..c33ba2befbf8 100644 --- a/Documentation/pi-futex.txt +++ b/Documentation/pi-futex.txt @@ -119,4 +119,4 @@ properties of futexes, and all four combinations are possible: futex, robust-futex, PI-futex, robust+PI-futex. More details about priority inheritance can be found in -Documentation/locking/rt-mutex.txt. +Documentation/locking/rt-mutex.rst. diff --git a/Documentation/translations/it_IT/kernel-hacking/locking.rst b/Documentation/translations/it_IT/kernel-hacking/locking.rst index 5fd8a1abd2be..b9a6be4b8499 100644 --- a/Documentation/translations/it_IT/kernel-hacking/locking.rst +++ b/Documentation/translations/it_IT/kernel-hacking/locking.rst @@ -1404,7 +1404,7 @@ Riferimento per l'API dei Futex Approfondimenti =============== -- ``Documentation/locking/spinlocks.txt``: la guida di Linus Torvalds agli +- ``Documentation/locking/spinlocks.rst``: la guida di Linus Torvalds agli spinlock del kernel. - Unix Systems for Modern Architectures: Symmetric Multiprocessing and diff --git a/drivers/gpu/drm/drm_modeset_lock.c b/drivers/gpu/drm/drm_modeset_lock.c index 81dd11901ffd..cb5671d32ada 100644 --- a/drivers/gpu/drm/drm_modeset_lock.c +++ b/drivers/gpu/drm/drm_modeset_lock.c @@ -36,7 +36,7 @@ * of extra utility/tracking out of our acquire-ctx. This is provided * by &struct drm_modeset_lock and &struct drm_modeset_acquire_ctx. * - * For basic principles of &ww_mutex, see: Documentation/locking/ww-mutex-design.txt + * For basic principles of &ww_mutex, see: Documentation/locking/ww-mutex-design.rst * * The basic usage pattern is to:: * diff --git a/include/linux/lockdep.h b/include/linux/lockdep.h index 57baa27f238c..0b0d7259276d 100644 --- a/include/linux/lockdep.h +++ b/include/linux/lockdep.h @@ -5,7 +5,7 @@ * Copyright (C) 2006,2007 Red Hat, Inc., Ingo Molnar * Copyright (C) 2007 Red Hat, Inc., Peter Zijlstra * - * see Documentation/locking/lockdep-design.txt for more details. + * see Documentation/locking/lockdep-design.rst for more details. */ #ifndef __LINUX_LOCKDEP_H #define __LINUX_LOCKDEP_H diff --git a/include/linux/mutex.h b/include/linux/mutex.h index 3093dd162424..dcd03fee6e01 100644 --- a/include/linux/mutex.h +++ b/include/linux/mutex.h @@ -151,7 +151,7 @@ static inline bool mutex_is_locked(struct mutex *lock) /* * See kernel/locking/mutex.c for detailed documentation of these APIs. - * Also see Documentation/locking/mutex-design.txt. + * Also see Documentation/locking/mutex-design.rst. */ #ifdef CONFIG_DEBUG_LOCK_ALLOC extern void mutex_lock_nested(struct mutex *lock, unsigned int subclass); diff --git a/include/linux/rwsem.h b/include/linux/rwsem.h index e401358c4e7e..9d9c663987d8 100644 --- a/include/linux/rwsem.h +++ b/include/linux/rwsem.h @@ -160,7 +160,7 @@ extern void downgrade_write(struct rw_semaphore *sem); * static then another method for expressing nested locking is * the explicit definition of lock class keys and the use of * lockdep_set_class() at lock initialization time. - * See Documentation/locking/lockdep-design.txt for more details.) + * See Documentation/locking/lockdep-design.rst for more details.) */ extern void down_read_nested(struct rw_semaphore *sem, int subclass); extern void down_write_nested(struct rw_semaphore *sem, int subclass); diff --git a/kernel/locking/mutex.c b/kernel/locking/mutex.c index 0c601ae072b3..edd1c082dbf5 100644 --- a/kernel/locking/mutex.c +++ b/kernel/locking/mutex.c @@ -16,7 +16,7 @@ * by Steven Rostedt, based on work by Gregory Haskins, Peter Morreale * and Sven Dietrich. * - * Also see Documentation/locking/mutex-design.txt. + * Also see Documentation/locking/mutex-design.rst. */ #include #include diff --git a/kernel/locking/rtmutex.c b/kernel/locking/rtmutex.c index 38fbf9fa7f1b..fa83d36e30c6 100644 --- a/kernel/locking/rtmutex.c +++ b/kernel/locking/rtmutex.c @@ -9,7 +9,7 @@ * Copyright (C) 2005 Kihon Technologies Inc., Steven Rostedt * Copyright (C) 2006 Esben Nielsen * - * See Documentation/locking/rt-mutex-design.txt for details. + * See Documentation/locking/rt-mutex-design.rst for details. */ #include #include diff --git a/lib/Kconfig.debug b/lib/Kconfig.debug index 4ac4ca21a30a..a858b55e8ac7 100644 --- a/lib/Kconfig.debug +++ b/lib/Kconfig.debug @@ -1139,7 +1139,7 @@ config PROVE_LOCKING the proof of observed correctness is also maintained for an arbitrary combination of these separate locking variants. - For more details, see Documentation/locking/lockdep-design.txt. + For more details, see Documentation/locking/lockdep-design.rst. config LOCK_STAT bool "Lock usage statistics" @@ -1153,7 +1153,7 @@ config LOCK_STAT help This feature enables tracking lock contention points - For more details, see Documentation/locking/lockstat.txt + For more details, see Documentation/locking/lockstat.rst This also enables lock events required by "perf lock", subcommand of perf. From 720594f691e5c8fb0624f3653b20b24ba8e57742 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sat, 13 Apr 2019 22:54:53 -0300 Subject: [PATCH 02/77] docs: connector: convert to ReST and rename to connector.rst As it has some function definitions, move them to connector.h. The remaining conversion is actually: - add blank lines and identation in order to identify paragraphs; - fix tables markups; - add some lists markups; - mark literal blocks; - adjust title markups. At its new index.rst, let's add a :orphan: while this is not linked to the main index.rst file, in order to avoid build warnings. Signed-off-by: Mauro Carvalho Chehab --- .../{connector.txt => connector.rst} | 130 ++++++------------ drivers/w1/Kconfig | 2 +- include/linux/connector.h | 63 ++++++++- samples/Kconfig | 2 +- 4 files changed, 109 insertions(+), 88 deletions(-) rename Documentation/connector/{connector.txt => connector.rst} (57%) diff --git a/Documentation/connector/connector.txt b/Documentation/connector/connector.rst similarity index 57% rename from Documentation/connector/connector.txt rename to Documentation/connector/connector.rst index ab7ca897fab7..24e26dc22dbf 100644 --- a/Documentation/connector/connector.txt +++ b/Documentation/connector/connector.rst @@ -1,6 +1,8 @@ -/*****************************************/ -Kernel Connector. -/*****************************************/ +:orphan: + +================ +Kernel Connector +================ Kernel connector - new netlink based userspace <-> kernel space easy to use communication module. @@ -12,94 +14,55 @@ identifier, the appropriate callback will be called. From the userspace point of view it's quite straightforward: - socket(); - bind(); - send(); - recv(); + - socket(); + - bind(); + - send(); + - recv(); But if kernelspace wants to use the full power of such connections, the driver writer must create special sockets, must know about struct sk_buff handling, etc... The Connector driver allows any kernelspace agents to use netlink based networking for inter-process communication in a significantly -easier way: +easier way:: -int cn_add_callback(struct cb_id *id, char *name, void (*callback) (struct cn_msg *, struct netlink_skb_parms *)); -void cn_netlink_send_multi(struct cn_msg *msg, u16 len, u32 portid, u32 __group, int gfp_mask); -void cn_netlink_send(struct cn_msg *msg, u32 portid, u32 __group, int gfp_mask); + int cn_add_callback(struct cb_id *id, char *name, void (*callback) (struct cn_msg *, struct netlink_skb_parms *)); + void cn_netlink_send_multi(struct cn_msg *msg, u16 len, u32 portid, u32 __group, int gfp_mask); + void cn_netlink_send(struct cn_msg *msg, u32 portid, u32 __group, int gfp_mask); -struct cb_id -{ + struct cb_id + { __u32 idx; __u32 val; -}; + }; idx and val are unique identifiers which must be registered in the -connector.h header for in-kernel usage. void (*callback) (void *) is a +connector.h header for in-kernel usage. `void (*callback) (void *)` is a callback function which will be called when a message with above idx.val is received by the connector core. The argument for that function must -be dereferenced to struct cn_msg *. +be dereferenced to `struct cn_msg *`:: -struct cn_msg -{ + struct cn_msg + { struct cb_id id; __u32 seq; __u32 ack; - __u32 len; /* Length of the following data */ + __u32 len; /* Length of the following data */ __u8 data[0]; -}; + }; -/*****************************************/ -Connector interfaces. -/*****************************************/ +Connector interfaces +==================== -int cn_add_callback(struct cb_id *id, char *name, void (*callback) (struct cn_msg *, struct netlink_skb_parms *)); + .. kernel-doc:: include/linux/connector.h - Registers new callback with connector core. + Note: + When registering new callback user, connector core assigns + netlink group to the user which is equal to its id.idx. - struct cb_id *id - unique connector's user identifier. - It must be registered in connector.h for legal in-kernel users. - char *name - connector's callback symbolic name. - void (*callback) (struct cn..) - connector's callback. - cn_msg and the sender's credentials - - -void cn_del_callback(struct cb_id *id); - - Unregisters new callback with connector core. - - struct cb_id *id - unique connector's user identifier. - - -int cn_netlink_send_multi(struct cn_msg *msg, u16 len, u32 portid, u32 __groups, int gfp_mask); -int cn_netlink_send(struct cn_msg *msg, u32 portid, u32 __groups, int gfp_mask); - - Sends message to the specified groups. It can be safely called from - softirq context, but may silently fail under strong memory pressure. - If there are no listeners for given group -ESRCH can be returned. - - struct cn_msg * - message header(with attached data). - u16 len - for *_multi multiple cn_msg messages can be sent - u32 port - destination port. - If non-zero the message will be sent to the - given port, which should be set to the - original sender. - u32 __group - destination group. - If port and __group is zero, then appropriate group will - be searched through all registered connector users, - and message will be delivered to the group which was - created for user with the same ID as in msg. - If __group is not zero, then message will be delivered - to the specified group. - int gfp_mask - GFP mask. - - Note: When registering new callback user, connector core assigns - netlink group to the user which is equal to its id.idx. - -/*****************************************/ -Protocol description. -/*****************************************/ +Protocol description +==================== The current framework offers a transport layer with fixed headers. The recommended protocol which uses such a header is as following: @@ -132,9 +95,8 @@ driver (it also registers itself with id={-1, -1}). As example of this usage can be found in the cn_test.c module which uses the connector to request notification and to send messages. -/*****************************************/ -Reliability. -/*****************************************/ +Reliability +=========== Netlink itself is not a reliable protocol. That means that messages can be lost due to memory pressure or process' receiving queue overflowed, @@ -142,32 +104,31 @@ so caller is warned that it must be prepared. That is why the struct cn_msg [main connector's message header] contains u32 seq and u32 ack fields. -/*****************************************/ -Userspace usage. -/*****************************************/ +Userspace usage +=============== 2.6.14 has a new netlink socket implementation, which by default does not allow people to send data to netlink groups other than 1. So, if you wish to use a netlink socket (for example using connector) with a different group number, the userspace application must subscribe to -that group first. It can be achieved by the following pseudocode: +that group first. It can be achieved by the following pseudocode:: -s = socket(PF_NETLINK, SOCK_DGRAM, NETLINK_CONNECTOR); + s = socket(PF_NETLINK, SOCK_DGRAM, NETLINK_CONNECTOR); -l_local.nl_family = AF_NETLINK; -l_local.nl_groups = 12345; -l_local.nl_pid = 0; + l_local.nl_family = AF_NETLINK; + l_local.nl_groups = 12345; + l_local.nl_pid = 0; -if (bind(s, (struct sockaddr *)&l_local, sizeof(struct sockaddr_nl)) == -1) { + if (bind(s, (struct sockaddr *)&l_local, sizeof(struct sockaddr_nl)) == -1) { perror("bind"); close(s); return -1; -} + } -{ + { int on = l_local.nl_groups; setsockopt(s, 270, 1, &on, sizeof(on)); -} + } Where 270 above is SOL_NETLINK, and 1 is a NETLINK_ADD_MEMBERSHIP socket option. To drop a multicast subscription, one should call the above socket @@ -180,16 +141,15 @@ group number 12345, you must increment CN_NETLINK_USERS to that number. Additional 0xf numbers are allocated to be used by non-in-kernel users. Due to this limitation, group 0xffffffff does not work now, so one can -not use add/remove connector's group notifications, but as far as I know, +not use add/remove connector's group notifications, but as far as I know, only cn_test.c test module used it. Some work in netlink area is still being done, so things can be changed in 2.6.15 timeframe, if it will happen, documentation will be updated for that kernel. -/*****************************************/ Code samples -/*****************************************/ +============ Sample code for a connector test module and user space can be found in samples/connector/. To build this code, enable CONFIG_CONNECTOR diff --git a/drivers/w1/Kconfig b/drivers/w1/Kconfig index 03dd57581df7..160053c0baea 100644 --- a/drivers/w1/Kconfig +++ b/drivers/w1/Kconfig @@ -19,7 +19,7 @@ config W1_CON default y ---help--- This allows to communicate with userspace using connector. For more - information see . + information see . There are three types of messages between w1 core and userspace: 1. Events. They are generated each time new master or slave device found either due to automatic or requested search. diff --git a/include/linux/connector.h b/include/linux/connector.h index 1d72ef76f24f..6b6c7396a584 100644 --- a/include/linux/connector.h +++ b/include/linux/connector.h @@ -55,10 +55,71 @@ struct cn_dev { struct cn_queue_dev *cbdev; }; +/** + * cn_add_callback() - Registers new callback with connector core. + * + * @id: unique connector's user identifier. + * It must be registered in connector.h for legal + * in-kernel users. + * @name: connector's callback symbolic name. + * @callback: connector's callback. + * parameters are %cn_msg and the sender's credentials + */ int cn_add_callback(struct cb_id *id, const char *name, void (*callback)(struct cn_msg *, struct netlink_skb_parms *)); -void cn_del_callback(struct cb_id *); +/** + * cn_del_callback() - Unregisters new callback with connector core. + * + * @id: unique connector's user identifier. + */ +void cn_del_callback(struct cb_id *id); + + +/** + * cn_netlink_send_mult - Sends message to the specified groups. + * + * @msg: message header(with attached data). + * @len: Number of @msg to be sent. + * @portid: destination port. + * If non-zero the message will be sent to the given port, + * which should be set to the original sender. + * @group: destination group. + * If @portid and @group is zero, then appropriate group will + * be searched through all registered connector users, and + * message will be delivered to the group which was created + * for user with the same ID as in @msg. + * If @group is not zero, then message will be delivered + * to the specified group. + * @gfp_mask: GFP mask. + * + * It can be safely called from softirq context, but may silently + * fail under strong memory pressure. + * + * If there are no listeners for given group %-ESRCH can be returned. + */ int cn_netlink_send_mult(struct cn_msg *msg, u16 len, u32 portid, u32 group, gfp_t gfp_mask); + +/** + * cn_netlink_send_mult - Sends message to the specified groups. + * + * @msg: message header(with attached data). + * @portid: destination port. + * If non-zero the message will be sent to the given port, + * which should be set to the original sender. + * @group: destination group. + * If @portid and @group is zero, then appropriate group will + * be searched through all registered connector users, and + * message will be delivered to the group which was created + * for user with the same ID as in @msg. + * If @group is not zero, then message will be delivered + * to the specified group. + * @gfp_mask: GFP mask. + * + * It can be safely called from softirq context, but may silently + * fail under strong memory pressure. + * + * If there are no listeners for given group %-ESRCH can be returned. + */ int cn_netlink_send(struct cn_msg *msg, u32 portid, u32 group, gfp_t gfp_mask); int cn_queue_add_callback(struct cn_queue_dev *dev, const char *name, diff --git a/samples/Kconfig b/samples/Kconfig index 71b5e833dd9e..155da47dc6a4 100644 --- a/samples/Kconfig +++ b/samples/Kconfig @@ -99,7 +99,7 @@ config SAMPLE_CONNECTOR When enabled, this builds both a sample kernel module for the connector interface and a user space tool to communicate with it. - See also Documentation/connector/connector.txt + See also Documentation/connector/connector.rst config SAMPLE_HIDRAW bool "hidraw sample" From 065504d5b45bc780b8da221162145a4c9ec67ffc Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sun, 14 Apr 2019 07:59:32 -0300 Subject: [PATCH 03/77] docs: lcd-panel-cgram.txt: convert docs to ReST and rename to *.rst This small text file describes the usage of parallel port LCD displays from userspace PoV. So, a good candidate for the admin guide. While this is not part of the admin-guide book, mark it as :orphan:, in order to avoid build warnings. Signed-off-by: Mauro Carvalho Chehab --- .../{lcd-panel-cgram.txt => lcd-panel-cgram.rst} | 9 +++++++-- MAINTAINERS | 2 +- 2 files changed, 8 insertions(+), 3 deletions(-) rename Documentation/auxdisplay/{lcd-panel-cgram.txt => lcd-panel-cgram.rst} (88%) diff --git a/Documentation/auxdisplay/lcd-panel-cgram.txt b/Documentation/auxdisplay/lcd-panel-cgram.rst similarity index 88% rename from Documentation/auxdisplay/lcd-panel-cgram.txt rename to Documentation/auxdisplay/lcd-panel-cgram.rst index 7f82c905763d..dfef50286018 100644 --- a/Documentation/auxdisplay/lcd-panel-cgram.txt +++ b/Documentation/auxdisplay/lcd-panel-cgram.rst @@ -1,3 +1,9 @@ +:orphan: + +====================================== +Parallel port LCD/Keypad Panel support +====================================== + Some LCDs allow you to define up to 8 characters, mapped to ASCII characters 0 to 7. The escape code to define a new character is '\e[LG' followed by one digit from 0 to 7, representing the character @@ -7,7 +13,7 @@ illuminated pixel with LSB on the right. Lines are numbered from the top of the character to the bottom. On a 5x7 matrix, only the 5 lower bits of the 7 first bytes are used for each character. If the string is incomplete, only complete lines will be redefined. Here are some -examples : +examples:: printf "\e[LG0010101050D1F0C04;" => 0 = [enter] printf "\e[LG1040E1F0000000000;" => 1 = [up] @@ -21,4 +27,3 @@ examples : printf "\e[LG00002061E1E060200;" => small speaker Willy - diff --git a/MAINTAINERS b/MAINTAINERS index f5533d1bda2e..01c83e294f5f 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -12058,7 +12058,7 @@ PARALLEL LCD/KEYPAD PANEL DRIVER M: Willy Tarreau M: Ksenija Stanojevic S: Odd Fixes -F: Documentation/auxdisplay/lcd-panel-cgram.txt +F: Documentation/auxdisplay/lcd-panel-cgram.rst F: drivers/auxdisplay/panel.c PARALLEL PORT SUBSYSTEM From 6f2846cc2ebae4a8c875389e3aedb0cda3c4f462 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sun, 14 Apr 2019 08:03:23 -0300 Subject: [PATCH 04/77] docs: lp855x-driver.txt: convert to ReST and move to kernel-api This small file seems to be an attempt to start documenting backlight drivers. It contains descriptions of the controls for the driver with could sound as an somewhat user-faced description, but it's main focus is to describe, instead, the data that should be passed via platform data and some driver-specific stuff. While this is not part of the driver-api book, mark it as :orphan:, in order to avoid build warnings. Signed-off-by: Mauro Carvalho Chehab --- Documentation/backlight/lp855x-driver.rst | 83 +++++++++++++++++++++++ Documentation/backlight/lp855x-driver.txt | 66 ------------------ MAINTAINERS | 2 +- 3 files changed, 84 insertions(+), 67 deletions(-) create mode 100644 Documentation/backlight/lp855x-driver.rst delete mode 100644 Documentation/backlight/lp855x-driver.txt diff --git a/Documentation/backlight/lp855x-driver.rst b/Documentation/backlight/lp855x-driver.rst new file mode 100644 index 000000000000..62b7ed847a77 --- /dev/null +++ b/Documentation/backlight/lp855x-driver.rst @@ -0,0 +1,83 @@ +:orphan: + +==================== +Kernel driver lp855x +==================== + +Backlight driver for LP855x ICs + +Supported chips: + + Texas Instruments LP8550, LP8551, LP8552, LP8553, LP8555, LP8556 and + LP8557 + +Author: Milo(Woogyom) Kim + +Description +----------- + +* Brightness control + + Brightness can be controlled by the pwm input or the i2c command. + The lp855x driver supports both cases. + +* Device attributes + + 1) bl_ctl_mode + + Backlight control mode. + + Value: pwm based or register based + + 2) chip_id + + The lp855x chip id. + + Value: lp8550/lp8551/lp8552/lp8553/lp8555/lp8556/lp8557 + +Platform data for lp855x +------------------------ + +For supporting platform specific data, the lp855x platform data can be used. + +* name: + Backlight driver name. If it is not defined, default name is set. +* device_control: + Value of DEVICE CONTROL register. +* initial_brightness: + Initial value of backlight brightness. +* period_ns: + Platform specific PWM period value. unit is nano. + Only valid when brightness is pwm input mode. +* size_program: + Total size of lp855x_rom_data. +* rom_data: + List of new eeprom/eprom registers. + +Examples +======== + +1) lp8552 platform data: i2c register mode with new eeprom data:: + + #define EEPROM_A5_ADDR 0xA5 + #define EEPROM_A5_VAL 0x4f /* EN_VSYNC=0 */ + + static struct lp855x_rom_data lp8552_eeprom_arr[] = { + {EEPROM_A5_ADDR, EEPROM_A5_VAL}, + }; + + static struct lp855x_platform_data lp8552_pdata = { + .name = "lcd-bl", + .device_control = I2C_CONFIG(LP8552), + .initial_brightness = INITIAL_BRT, + .size_program = ARRAY_SIZE(lp8552_eeprom_arr), + .rom_data = lp8552_eeprom_arr, + }; + +2) lp8556 platform data: pwm input mode with default rom data:: + + static struct lp855x_platform_data lp8556_pdata = { + .device_control = PWM_CONFIG(LP8556), + .initial_brightness = INITIAL_BRT, + .period_ns = 1000000, + }; diff --git a/Documentation/backlight/lp855x-driver.txt b/Documentation/backlight/lp855x-driver.txt deleted file mode 100644 index 01bce243d3d7..000000000000 --- a/Documentation/backlight/lp855x-driver.txt +++ /dev/null @@ -1,66 +0,0 @@ -Kernel driver lp855x -==================== - -Backlight driver for LP855x ICs - -Supported chips: - Texas Instruments LP8550, LP8551, LP8552, LP8553, LP8555, LP8556 and - LP8557 - -Author: Milo(Woogyom) Kim - -Description ------------ - -* Brightness control - -Brightness can be controlled by the pwm input or the i2c command. -The lp855x driver supports both cases. - -* Device attributes - -1) bl_ctl_mode -Backlight control mode. -Value : pwm based or register based - -2) chip_id -The lp855x chip id. -Value : lp8550/lp8551/lp8552/lp8553/lp8555/lp8556/lp8557 - -Platform data for lp855x ------------------------- - -For supporting platform specific data, the lp855x platform data can be used. - -* name : Backlight driver name. If it is not defined, default name is set. -* device_control : Value of DEVICE CONTROL register. -* initial_brightness : Initial value of backlight brightness. -* period_ns : Platform specific PWM period value. unit is nano. - Only valid when brightness is pwm input mode. -* size_program : Total size of lp855x_rom_data. -* rom_data : List of new eeprom/eprom registers. - -example 1) lp8552 platform data : i2c register mode with new eeprom data - -#define EEPROM_A5_ADDR 0xA5 -#define EEPROM_A5_VAL 0x4f /* EN_VSYNC=0 */ - -static struct lp855x_rom_data lp8552_eeprom_arr[] = { - {EEPROM_A5_ADDR, EEPROM_A5_VAL}, -}; - -static struct lp855x_platform_data lp8552_pdata = { - .name = "lcd-bl", - .device_control = I2C_CONFIG(LP8552), - .initial_brightness = INITIAL_BRT, - .size_program = ARRAY_SIZE(lp8552_eeprom_arr), - .rom_data = lp8552_eeprom_arr, -}; - -example 2) lp8556 platform data : pwm input mode with default rom data - -static struct lp855x_platform_data lp8556_pdata = { - .device_control = PWM_CONFIG(LP8556), - .initial_brightness = INITIAL_BRT, - .period_ns = 1000000, -}; diff --git a/MAINTAINERS b/MAINTAINERS index 01c83e294f5f..37ba75bae7aa 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -15964,7 +15964,7 @@ F: sound/soc/codecs/isabelle* TI LP855x BACKLIGHT DRIVER M: Milo Kim S: Maintained -F: Documentation/backlight/lp855x-driver.txt +F: Documentation/backlight/lp855x-driver.rst F: drivers/video/backlight/lp855x_bl.c F: include/linux/platform_data/lp855x.h From 23e02422877b7fac868d8610a4265003da4ac0f4 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sun, 14 Apr 2019 08:27:15 -0300 Subject: [PATCH 05/77] docs: m68k: convert docs to ReST and rename to *.rst Convert the m68k kernel-options.txt file to ReST. The conversion is trivial, as the document is already on a format close enough to ReST. Just some small adjustments were needed in order to make it both good for being parsed while keeping it on a good txt shape. At its new index.rst, let's add a :orphan: while this is not linked to the main index.rst file, in order to avoid build warnings. Signed-off-by: Mauro Carvalho Chehab --- .../admin-guide/kernel-parameters.rst | 2 +- Documentation/m68k/index.rst | 17 + ...{kernel-options.txt => kernel-options.rst} | 319 ++++++++++-------- 3 files changed, 191 insertions(+), 147 deletions(-) create mode 100644 Documentation/m68k/index.rst rename Documentation/m68k/{kernel-options.txt => kernel-options.rst} (78%) diff --git a/Documentation/admin-guide/kernel-parameters.rst b/Documentation/admin-guide/kernel-parameters.rst index 5d29ba5ad88c..d05d531b4ec9 100644 --- a/Documentation/admin-guide/kernel-parameters.rst +++ b/Documentation/admin-guide/kernel-parameters.rst @@ -118,7 +118,7 @@ parameter is applicable:: LOOP Loopback device support is enabled. M68k M68k architecture is enabled. These options have more detailed description inside of - Documentation/m68k/kernel-options.txt. + Documentation/m68k/kernel-options.rst. MDA MDA console support is enabled. MIPS MIPS architecture is enabled. MOUSE Appropriate mouse support is enabled. diff --git a/Documentation/m68k/index.rst b/Documentation/m68k/index.rst new file mode 100644 index 000000000000..f3273ec075c3 --- /dev/null +++ b/Documentation/m68k/index.rst @@ -0,0 +1,17 @@ +:orphan: + +================= +m68k Architecture +================= + +.. toctree:: + :maxdepth: 2 + + kernel-options + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/m68k/kernel-options.txt b/Documentation/m68k/kernel-options.rst similarity index 78% rename from Documentation/m68k/kernel-options.txt rename to Documentation/m68k/kernel-options.rst index 79d21246c75a..cabd9419740d 100644 --- a/Documentation/m68k/kernel-options.txt +++ b/Documentation/m68k/kernel-options.rst @@ -1,22 +1,24 @@ - - - Command Line Options for Linux/m68k - =================================== +=================================== +Command Line Options for Linux/m68k +=================================== Last Update: 2 May 1999 + Linux/m68k version: 2.2.6 + Author: Roman.Hodek@informatik.uni-erlangen.de (Roman Hodek) + Update: jds@kom.auc.dk (Jes Sorensen) and faq@linux-m68k.org (Chris Lawrence) 0) Introduction =============== - Often I've been asked which command line options the Linux/m68k +Often I've been asked which command line options the Linux/m68k kernel understands, or how the exact syntax for the ... option is, or ... about the option ... . I hope, this document supplies all the answers... - Note that some options might be outdated, their descriptions being +Note that some options might be outdated, their descriptions being incomplete or missing. Please update the information and send in the patches. @@ -38,11 +40,11 @@ argument contains an '=', it is of class 2, and the definition is put into init's environment. All other arguments are passed to init as command line options. - This document describes the valid kernel options for Linux/m68k in +This document describes the valid kernel options for Linux/m68k in the version mentioned at the start of this file. Later revisions may add new such options, and some may be missing in older versions. - In general, the value (the part after the '=') of an option is a +In general, the value (the part after the '=') of an option is a list of values separated by commas. The interpretation of these values is up to the driver that "owns" the option. This association of options with drivers is also the reason that some are further @@ -55,21 +57,21 @@ subdivided. 2.1) root= ---------- -Syntax: root=/dev/ - or: root= +:Syntax: root=/dev/ +:or: root= This tells the kernel which device it should mount as the root filesystem. The device must be a block device with a valid filesystem on it. - The first syntax gives the device by name. These names are converted +The first syntax gives the device by name. These names are converted into a major/minor number internally in the kernel in an unusual way. Normally, this "conversion" is done by the device files in /dev, but this isn't possible here, because the root filesystem (with /dev) isn't mounted yet... So the kernel parses the name itself, with some hardcoded name to number mappings. The name must always be a combination of two or three letters, followed by a decimal number. -Valid names are: +Valid names are:: /dev/ram: -> 0x0100 (initial ramdisk) /dev/hda: -> 0x0300 (first IDE disk) @@ -81,7 +83,7 @@ Valid names are: /dev/sde: -> 0x0840 (fifth SCSI disk) /dev/fd : -> 0x0200 (floppy disk) - The name must be followed by a decimal number, that stands for the +The name must be followed by a decimal number, that stands for the partition number. Internally, the value of the number is just added to the device number mentioned in the table above. The exceptions are /dev/ram and /dev/fd, where /dev/ram refers to an @@ -100,12 +102,12 @@ the kernel command line. [Strange and maybe uninteresting stuff ON] - This unusual translation of device names has some strange +This unusual translation of device names has some strange consequences: If, for example, you have a symbolic link from /dev/fd to /dev/fd0D720 as an abbreviation for floppy driver #0 in DD format, you cannot use this name for specifying the root device, because the kernel cannot see this symlink before mounting the root FS and it -isn't in the table above. If you use it, the root device will not be +isn't in the table above. If you use it, the root device will not be set at all, without an error message. Another example: You cannot use a partition on e.g. the sixth SCSI disk as the root filesystem, if you want to specify it by name. This is, because only the devices up to @@ -118,7 +120,7 @@ knowledge that each disk uses 16 minors, and write "root=/dev/sde17" [Strange and maybe uninteresting stuff OFF] - If the device containing your root partition isn't in the table +If the device containing your root partition isn't in the table above, you can also specify it by major and minor numbers. These are written in hex, with no prefix and no separator between. E.g., if you have a CD with contents appropriate as a root filesystem in the first @@ -136,6 +138,7 @@ known partition UUID as the starting point. For example, if partition 5 of the device has the UUID of 00112233-4455-6677-8899-AABBCCDDEEFF then partition 3 may be found as follows: + PARTUUID=00112233-4455-6677-8899-AABBCCDDEEFF/PARTNROFF=-2 Authoritative information can be found in @@ -145,8 +148,8 @@ Authoritative information can be found in 2.2) ro, rw ----------- -Syntax: ro - or: rw +:Syntax: ro +:or: rw These two options tell the kernel whether it should mount the root filesystem read-only or read-write. The default is read-only, except @@ -156,7 +159,7 @@ for ramdisks, which default to read-write. 2.3) debug ---------- -Syntax: debug +:Syntax: debug This raises the kernel log level to 10 (the default is 7). This is the same level as set by the "dmesg" command, just that the maximum level @@ -166,7 +169,7 @@ selectable by dmesg is 8. 2.4) debug= ----------- -Syntax: debug= +:Syntax: debug= This option causes certain kernel messages be printed to the selected debugging device. This can aid debugging the kernel, since the @@ -175,7 +178,7 @@ devices are possible depends on the machine type. There are no checks for the validity of the device name. If the device isn't implemented, nothing happens. - Messages logged this way are in general stack dumps after kernel +Messages logged this way are in general stack dumps after kernel memory faults or bad kernel traps, and kernel panics. To be exact: all messages of level 0 (panic messages) and all messages printed while the log level is 8 or more (their level doesn't matter). Before stack @@ -185,19 +188,27 @@ at least 8 can also be set by the "debug" command line option (see Devices possible for Amiga: - - "ser": built-in serial port; parameters: 9600bps, 8N1 - - "mem": Save the messages to a reserved area in chip mem. After + - "ser": + built-in serial port; parameters: 9600bps, 8N1 + - "mem": + Save the messages to a reserved area in chip mem. After rebooting, they can be read under AmigaOS with the tool 'dmesg'. Devices possible for Atari: - - "ser1": ST-MFP serial port ("Modem1"); parameters: 9600bps, 8N1 - - "ser2": SCC channel B serial port ("Modem2"); parameters: 9600bps, 8N1 - - "ser" : default serial port + - "ser1": + ST-MFP serial port ("Modem1"); parameters: 9600bps, 8N1 + - "ser2": + SCC channel B serial port ("Modem2"); parameters: 9600bps, 8N1 + - "ser" : + default serial port This is "ser2" for a Falcon, and "ser1" for any other machine - - "midi": The MIDI port; parameters: 31250bps, 8N1 - - "par" : parallel port + - "midi": + The MIDI port; parameters: 31250bps, 8N1 + - "par" : + parallel port + The printing routine for this implements a timeout for the case there's no printer connected (else the kernel would lock up). The timeout is not exact, but usually a few @@ -205,26 +216,29 @@ Devices possible for Atari: 2.6) ramdisk_size= -------------- +------------------ -Syntax: ramdisk_size= +:Syntax: ramdisk_size= - This option instructs the kernel to set up a ramdisk of the given +This option instructs the kernel to set up a ramdisk of the given size in KBytes. Do not use this option if the ramdisk contents are passed by bootstrap! In this case, the size is selected automatically and should not be overwritten. - The only application is for root filesystems on floppy disks, that +The only application is for root filesystems on floppy disks, that should be loaded into memory. To do that, select the corresponding size of the disk as ramdisk size, and set the root device to the disk drive (with "root="). 2.7) swap= + + I can't find any sign of this option in 2.2.6. + 2.8) buff= ----------- - I can't find any sign of these options in 2.2.6. + I can't find any sign of this option in 2.2.6. 3) General Device Options (Amiga and Atari) @@ -233,13 +247,13 @@ drive (with "root="). 3.1) ether= ----------- -Syntax: ether=[[,[,[,]]]], +:Syntax: ether=[[,[,[,]]]], - is the name of a net driver, as specified in + is the name of a net driver, as specified in drivers/net/Space.c in the Linux source. Most prominent are eth0, ... eth3, sl0, ... sl3, ppp0, ..., ppp3, dummy, and lo. - The non-ethernet drivers (sl, ppp, dummy, lo) obviously ignore the +The non-ethernet drivers (sl, ppp, dummy, lo) obviously ignore the settings by this options. Also, the existing ethernet drivers for Linux/m68k (ariadne, a2065, hydra) don't use them because Zorro boards are really Plug-'n-Play, so the "ether=" option is useless altogether @@ -249,9 +263,9 @@ for Linux/m68k. 3.2) hd= -------- -Syntax: hd=,, +:Syntax: hd=,, - This option sets the disk geometry of an IDE disk. The first hd= +This option sets the disk geometry of an IDE disk. The first hd= option is for the first IDE disk, the second for the second one. (I.e., you can give this option twice.) In most cases, you won't have to use this option, since the kernel can obtain the geometry data @@ -262,9 +276,9 @@ disks. 3.3) max_scsi_luns= ------------------- -Syntax: max_scsi_luns= +:Syntax: max_scsi_luns= - Sets the maximum number of LUNs (logical units) of SCSI devices to +Sets the maximum number of LUNs (logical units) of SCSI devices to be scanned. Valid values for are between 1 and 8. Default is 8 if "Probe all LUNs on each SCSI device" was selected during the kernel configuration, else 1. @@ -273,9 +287,9 @@ configuration, else 1. 3.4) st= -------- -Syntax: st=,[,[]] +:Syntax: st=,[,[]] - Sets several parameters of the SCSI tape driver. is +Sets several parameters of the SCSI tape driver. is the number of 512-byte buffers reserved for tape operations for each device. sets the number of blocks which must be filled to start an actual write operation to the tape. Maximum value is the @@ -286,9 +300,9 @@ buffers allocated for all tape devices. 3.5) dmasound= -------------- -Syntax: dmasound=[,[,]] +:Syntax: dmasound=[,[,]] - This option controls some configurations of the Linux/m68k DMA sound +This option controls some configurations of the Linux/m68k DMA sound driver (Amiga and Atari): is the number of buffers you want to use (minimum 4, default 4), is the size of each buffer in kilobytes (minimum 4, default 32) and says @@ -305,20 +319,22 @@ don't need to expand the sound. 4.1) video= ----------- -Syntax: video=: +:Syntax: video=: The parameter specifies the name of the frame buffer, -eg. most atari users will want to specify `atafb' here. The +eg. most atari users will want to specify `atafb` here. The is a comma-separated list of the sub-options listed below. -NB: Please notice that this option was renamed from `atavideo' to - `video' during the development of the 1.3.x kernels, thus you +NB: + Please notice that this option was renamed from `atavideo` to + `video` during the development of the 1.3.x kernels, thus you might need to update your boot-scripts if upgrading to 2.x from an 1.2.x kernel. -NBB: The behavior of video= was changed in 2.1.57 so the recommended -option is to specify the name of the frame buffer. +NBB: + The behavior of video= was changed in 2.1.57 so the recommended + option is to specify the name of the frame buffer. 4.1.1) Video Mode ----------------- @@ -341,11 +357,11 @@ mode, if the hardware allows. Currently defined names are: - falh2 : 896x608x1, Falcon only - falh16 : 896x608x4, Falcon only - If no video mode is given on the command line, the kernel tries the +If no video mode is given on the command line, the kernel tries the modes names "default" in turn, until one is possible with the hardware in use. - A video mode setting doesn't make sense, if the external driver is +A video mode setting doesn't make sense, if the external driver is activated by a "external:" sub-option. 4.1.2) inverse @@ -358,17 +374,17 @@ option, you can make the background white. 4.1.3) font ----------- -Syntax: font: +:Syntax: font: Specify the font to use in text modes. Currently you can choose only -between `VGA8x8', `VGA8x16' and `PEARL8x8'. `VGA8x8' is default, if the +between `VGA8x8`, `VGA8x16` and `PEARL8x8`. `VGA8x8` is default, if the vertical size of the display is less than 400 pixel rows. Otherwise, the -`VGA8x16' font is the default. +`VGA8x16` font is the default. -4.1.4) hwscroll_ ----------------- +4.1.4) `hwscroll_` +------------------ -Syntax: hwscroll_ +:Syntax: `hwscroll_` The number of additional lines of video memory to reserve for speeding up the scrolling ("hardware scrolling"). Hardware scrolling @@ -378,7 +394,7 @@ possible with plain STs and graphics cards (The former because the base address must be on a 256 byte boundary there, the latter because the kernel doesn't know how to set the base address at all.) - By default, is set to the number of visible text lines on the +By default, is set to the number of visible text lines on the display. Thus, the amount of video memory is doubled, compared to no hardware scrolling. You can turn off the hardware scrolling altogether by setting to 0. @@ -386,31 +402,31 @@ by setting to 0. 4.1.5) internal: ---------------- -Syntax: internal:;[;;;] +:Syntax: internal:;[;;;] This option specifies the capabilities of some extended internal video hardware, like e.g. OverScan. and give the (extended) dimensions of the screen. - If your OverScan needs a black border, you have to write the last +If your OverScan needs a black border, you have to write the last three arguments of the "internal:". is the maximum line length the hardware allows, the maximum number of lines. is the offset of the visible part of the screen memory to its physical start, in bytes. - Often, extended interval video hardware has to be activated somehow. +Often, extended interval video hardware has to be activated somehow. For this, see the "sw_*" options below. 4.1.6) external: ---------------- -Syntax: - external:;;;;[;[;\ - [;[;[;]]]]] +:Syntax: + external:;;;;[;[; + [;[;[;]]]]] -[I had to break this line...] +.. I had to break this line... - This is probably the most complicated parameter... It specifies that +This is probably the most complicated parameter... It specifies that you have some external video hardware (a graphics board), and how to use it under Linux/m68k. The kernel cannot know more about the hardware than you tell it here! The kernel also is unable to set or change any @@ -418,38 +434,44 @@ video modes, since it doesn't know about any board internal. So, you have to switch to that video mode before you start Linux, and cannot switch to another mode once Linux has started. - The first 3 parameters of this sub-option should be obvious: , +The first 3 parameters of this sub-option should be obvious: , and give the dimensions of the screen and the number of planes (depth). The depth is the logarithm to base 2 of the number of colors possible. (Or, the other way round: The number of colors is 2^depth). - You have to tell the kernel furthermore how the video memory is +You have to tell the kernel furthermore how the video memory is organized. This is done by a letter as parameter: - 'n': "normal planes", i.e. one whole plane after another - 'i': "interleaved planes", i.e. 16 bit of the first plane, than 16 bit + 'n': + "normal planes", i.e. one whole plane after another + 'i': + "interleaved planes", i.e. 16 bit of the first plane, than 16 bit of the next, and so on... This mode is used only with the - built-in Atari video modes, I think there is no card that - supports this mode. - 'p': "packed pixels", i.e. consecutive bits stand for all - planes of one pixel; this is the most common mode for 8 planes - (256 colors) on graphic cards - 't': "true color" (more or less packed pixels, but without a color - lookup table); usually depth is 24 + built-in Atari video modes, I think there is no card that + supports this mode. + 'p': + "packed pixels", i.e. consecutive bits stand for all + planes of one pixel; this is the most common mode for 8 planes + (256 colors) on graphic cards + 't': + "true color" (more or less packed pixels, but without a color + lookup table); usually depth is 24 For monochrome modes (i.e., is 1), the letter has a different meaning: - 'n': normal colors, i.e. 0=white, 1=black - 'i': inverted colors, i.e. 0=black, 1=white + 'n': + normal colors, i.e. 0=white, 1=black + 'i': + inverted colors, i.e. 0=black, 1=white - The next important information about the video hardware is the base +The next important information about the video hardware is the base address of the video memory. That is given in the parameter, as a hexadecimal number with a "0x" prefix. You have to find out this address in the documentation of your hardware. - The next parameter, , tells the kernel about the size of the +The next parameter, , tells the kernel about the size of the video memory. If it's missing, the size is calculated from , , and . For now, it is not useful to write a value here. It would be used only for hardware scrolling (which isn't possible @@ -460,7 +482,7 @@ empty, either by ending the "external:" after the video address or by writing two consecutive semicolons, if you want to give a (it is allowed to leave this parameter empty). - The parameter is optional. If it is not given, the kernel +The parameter is optional. If it is not given, the kernel cannot read or write any color registers of the video hardware, and thus you have to set appropriate colors before you start Linux. But if your card is somehow VGA compatible, you can tell the kernel the base @@ -472,18 +494,18 @@ uses the addresses vgabase+0x3c7...vgabase+0x3c9. The parameter is written in hexadecimal with a "0x" prefix, just as . - is meaningful only if is specified. It tells the + is meaningful only if is specified. It tells the kernel how wide each of the color register is, i.e. the number of bits per single color (red/green/blue). Default is 6, another quite usual value is 8. - Also is used together with . It tells the kernel +Also is used together with . It tells the kernel about the color register model of your gfx board. Currently, the types "vga" (which is also the default) and "mv300" (SANG MV300) are implemented. - Parameter is required for ProMST or ET4000 cards where -the physical linelength differs from the visible length. With ProMST, +Parameter is required for ProMST or ET4000 cards where +the physical linelength differs from the visible length. With ProMST, xres_virtual must be set to 2048. For ET4000, xres_virtual depends on the initialisation of the video-card. If you're missing a corresponding yres_virtual: the external part is legacy, @@ -499,13 +521,13 @@ currently works only with the ScreenWonder! 4.1.8) monitorcap: ------------------- -Syntax: monitorcap:;;; +:Syntax: monitorcap:;;; This describes the capabilities of a multisync monitor. Don't use it with a fixed-frequency monitor! For now, only the Falcon frame buffer uses the settings of "monitorcap:". - and are the minimum and maximum, resp., vertical frequencies + and are the minimum and maximum, resp., vertical frequencies your monitor can work with, in Hz. and are the same for the horizontal frequency, in kHz. @@ -520,28 +542,28 @@ If this option is given, the framebuffer device doesn't do any video mode calculations and settings on its own. The only Atari fb device that does this currently is the Falcon. - What you reach with this: Settings for unknown video extensions +What you reach with this: Settings for unknown video extensions aren't overridden by the driver, so you can still use the mode found when booting, when the driver doesn't know to set this mode itself. But this also means, that you can't switch video modes anymore... - An example where you may want to use "keep" is the ScreenBlaster for +An example where you may want to use "keep" is the ScreenBlaster for the Falcon. 4.2) atamouse= -------------- -Syntax: atamouse=,[] +:Syntax: atamouse=,[] - With this option, you can set the mouse movement reporting threshold. +With this option, you can set the mouse movement reporting threshold. This is the number of pixels of mouse movement that have to accumulate before the IKBD sends a new mouse packet to the kernel. Higher values reduce the mouse interrupt load and thus reduce the chance of keyboard overruns. Lower values give a slightly faster mouse responses and slightly better mouse tracking. - You can set the threshold in x and y separately, but usually this is +You can set the threshold in x and y separately, but usually this is of little practical use. If there's just one number in the option, it is used for both dimensions. The default value is 2 for both thresholds. @@ -550,7 +572,7 @@ thresholds. 4.3) ataflop= ------------- -Syntax: ataflop=[,[,[,]]] +:Syntax: ataflop=[,[,[,]]] The drive type may be 0, 1, or 2, for DD, HD, and ED, resp. This setting affects how many buffers are reserved and which formats are @@ -563,15 +585,15 @@ Syntax: ataflop=[,[,[,]]] no for the Medusa and yes for all others. With the two following parameters, you can change the default - steprate used for drive A and B, resp. + steprate used for drive A and B, resp. 4.4) atascsi= ------------- -Syntax: atascsi=[,[,[,[,]]]] +:Syntax: atascsi=[,[,[,[,]]]] - This option sets some parameters for the Atari native SCSI driver. +This option sets some parameters for the Atari native SCSI driver. Generally, any number of arguments can be omitted from the end. And for each of the numbers, a negative value means "use default". The defaults depend on whether TT-style or Falcon-style SCSI is used. @@ -597,11 +619,14 @@ ignored (others aren't affected). 32). Default: 8/1. (Note: Values > 1 seem to cause problems on a Falcon, cause not yet known.) - The value at a great part determines the amount of + The value at a great part determines the amount of memory SCSI reserves for itself. The formula is rather complicated, but I can give you some hints: - no scatter-gather : cmd_per_lun * 232 bytes - full scatter-gather: cmd_per_lun * approx. 17 Kbytes + + no scatter-gather: + cmd_per_lun * 232 bytes + full scatter-gather: + cmd_per_lun * approx. 17 Kbytes : Size of the scatter-gather table, i.e. the number of requests @@ -634,19 +659,23 @@ ignored (others aren't affected). 4.5 switches= ------------- -Syntax: switches= +:Syntax: switches= - With this option you can switch some hardware lines that are often +With this option you can switch some hardware lines that are often used to enable/disable certain hardware extensions. Examples are OverScan, overclocking, ... - The is a comma-separated list of the following +The is a comma-separated list of the following items: - ikbd: set RTS of the keyboard ACIA high - midi: set RTS of the MIDI ACIA high - snd6: set bit 6 of the PSG port A - snd7: set bit 6 of the PSG port A + ikbd: + set RTS of the keyboard ACIA high + midi: + set RTS of the MIDI ACIA high + snd6: + set bit 6 of the PSG port A + snd7: + set bit 6 of the PSG port A It doesn't make sense to mention a switch more than once (no difference to only once), but you can give as many switches as you @@ -654,16 +683,16 @@ want to enable different features. The switch lines are set as early as possible during kernel initialization (even before determining the present hardware.) - All of the items can also be prefixed with "ov_", i.e. "ov_ikbd", -"ov_midi", ... These options are meant for switching on an OverScan +All of the items can also be prefixed with `ov_`, i.e. `ov_ikbd`, +`ov_midi`, ... These options are meant for switching on an OverScan video extension. The difference to the bare option is that the switch-on is done after video initialization, and somehow synchronized to the HBLANK. A speciality is that ov_ikbd and ov_midi are switched off before rebooting, so that OverScan is disabled and TOS boots correctly. - If you give an option both, with and without the "ov_" prefix, the -earlier initialization ("ov_"-less) takes precedence. But the +If you give an option both, with and without the `ov_` prefix, the +earlier initialization (`ov_`-less) takes precedence. But the switching-off on reset still happens in this case. 5) Options for Amiga Only: @@ -672,10 +701,10 @@ switching-off on reset still happens in this case. 5.1) video= ----------- -Syntax: video=: +:Syntax: video=: The parameter specifies the name of the frame buffer, valid -options are `amifb', `cyber', 'virge', `retz3' and `clgen', provided +options are `amifb`, `cyber`, 'virge', `retz3` and `clgen`, provided that the respective frame buffer devices have been compiled into the kernel (or compiled as loadable modules). The behavior of the option was changed in 2.1.57 so it is now recommended to specify this @@ -697,9 +726,11 @@ predefined video modes are available: NTSC modes: - ntsc : 640x200, 15 kHz, 60 Hz - ntsc-lace : 640x400, 15 kHz, 60 Hz interlaced + PAL modes: - pal : 640x256, 15 kHz, 50 Hz - pal-lace : 640x512, 15 kHz, 50 Hz interlaced + ECS modes: - multiscan : 640x480, 29 kHz, 57 Hz - multiscan-lace : 640x960, 29 kHz, 57 Hz interlaced @@ -715,6 +746,7 @@ ECS modes: - dblpal-lace : 640x1024, 27 kHz, 47 Hz interlaced - dblntsc : 640x200, 27 kHz, 57 Hz doublescan - dblpal : 640x256, 27 kHz, 47 Hz doublescan + VGA modes: - vga : 640x480, 31 kHz, 60 Hz - vga70 : 640x400, 31 kHz, 70 Hz @@ -726,7 +758,7 @@ chipset and 8-bit color for the AGA chipset. 5.1.2) depth ------------ -Syntax: depth: +:Syntax: depth: Specify the number of bit-planes for the selected video-mode. @@ -739,32 +771,32 @@ Use inverted display (black on white). Functionally the same as the 5.1.4) font ----------- -Syntax: font: +:Syntax: font: Specify the font to use in text modes. Functionally the same as the -"font" sub-option for the Atari, except that `PEARL8x8' is used instead -of `VGA8x8' if the vertical size of the display is less than 400 pixel +"font" sub-option for the Atari, except that `PEARL8x8` is used instead +of `VGA8x8` if the vertical size of the display is less than 400 pixel rows. 5.1.5) monitorcap: ------------------- -Syntax: monitorcap:;;; +:Syntax: monitorcap:;;; This describes the capabilities of a multisync monitor. For now, only the color frame buffer uses the settings of "monitorcap:". - and are the minimum and maximum, resp., vertical frequencies + and are the minimum and maximum, resp., vertical frequencies your monitor can work with, in Hz. and are the same for the horizontal frequency, in kHz. - The defaults are 50;90;15;38 (Generic Amiga multisync monitor). +The defaults are 50;90;15;38 (Generic Amiga multisync monitor). 5.2) fd_def_df0= ---------------- -Syntax: fd_def_df0= +:Syntax: fd_def_df0= Sets the df0 value for "silent" floppy drives. The value should be in hexadecimal with "0x" prefix. @@ -773,7 +805,7 @@ hexadecimal with "0x" prefix. 5.3) wd33c93= ------------- -Syntax: wd33c93= +:Syntax: wd33c93= These options affect the A590/A2091, A3000 and GVP Series II SCSI controllers. @@ -784,9 +816,9 @@ below. 5.3.1) nosync ------------- -Syntax: nosync:bitmask +:Syntax: nosync:bitmask - bitmask is a byte where the 1st 7 bits correspond with the 7 +bitmask is a byte where the 1st 7 bits correspond with the 7 possible SCSI devices. Set a bit to prevent sync negotiation on that device. To maintain backwards compatibility, a command-line such as "wd33c93=255" will be automatically translated to @@ -796,35 +828,35 @@ all devices, eg. nosync:0xff. 5.3.2) period ------------- -Syntax: period:ns +:Syntax: period:ns - `ns' is the minimum # of nanoseconds in a SCSI data transfer +`ns` is the minimum # of nanoseconds in a SCSI data transfer period. Default is 500; acceptable values are 250 - 1000. 5.3.3) disconnect ----------------- -Syntax: disconnect:x +:Syntax: disconnect:x - Specify x = 0 to never allow disconnects, 2 to always allow them. +Specify x = 0 to never allow disconnects, 2 to always allow them. x = 1 does 'adaptive' disconnects, which is the default and generally the best choice. 5.3.4) debug ------------ -Syntax: debug:x +:Syntax: debug:x - If `DEBUGGING_ON' is defined, x is a bit mask that causes various +If `DEBUGGING_ON` is defined, x is a bit mask that causes various types of debug output to printed - see the DB_xxx defines in wd33c93.h. 5.3.5) clock ------------ -Syntax: clock:x +:Syntax: clock:x - x = clock input in MHz for WD33c93 chip. Normal values would be from +x = clock input in MHz for WD33c93 chip. Normal values would be from 8 through 20. The default value depends on your hostadapter(s), default for the A3000 internal controller is 14, for the A2091 it's 8 and for the GVP hostadapters it's either 8 or 14, depending on the @@ -834,15 +866,15 @@ hostadapters. 5.3.6) next ----------- - No argument. Used to separate blocks of keywords when there's more +No argument. Used to separate blocks of keywords when there's more than one wd33c93-based host adapter in the system. 5.3.7) nodma ------------ -Syntax: nodma:x +:Syntax: nodma:x - If x is 1 (or if the option is just written as "nodma"), the WD33c93 +If x is 1 (or if the option is just written as "nodma"), the WD33c93 controller will not use DMA (= direct memory access) to access the Amiga's memory. This is useful for some systems (like A3000's and A4000's with the A3640 accelerator, revision 3.0) that have problems @@ -853,32 +885,27 @@ possible. 5.4) gvp11= ----------- -Syntax: gvp11= +:Syntax: gvp11= - The earlier versions of the GVP driver did not handle DMA +The earlier versions of the GVP driver did not handle DMA address-mask settings correctly which made it necessary for some people to use this option, in order to get their GVP controller running under Linux. These problems have hopefully been solved and the use of this option is now highly unrecommended! - Incorrect use can lead to unpredictable behavior, so please only use +Incorrect use can lead to unpredictable behavior, so please only use this option if you *know* what you are doing and have a reason to do so. In any case if you experience problems and need to use this option, please inform us about it by mailing to the Linux/68k kernel mailing list. - The address mask set by this option specifies which addresses are +The address mask set by this option specifies which addresses are valid for DMA with the GVP Series II SCSI controller. An address is valid, if no bits are set except the bits that are set in the mask, too. - Some versions of the GVP can only DMA into a 24 bit address range, +Some versions of the GVP can only DMA into a 24 bit address range, some can address a 25 bit address range while others can use the whole 32 bit address range for DMA. The correct setting depends on your controller and should be autodetected by the driver. An example is the 24 bit region which is specified by a mask of 0x00fffffe. - - -/* Local Variables: */ -/* mode: text */ -/* End: */ From 01c0aa794305ae08eb977d0719e43577e93f9ef5 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sun, 14 Apr 2019 08:37:58 -0300 Subject: [PATCH 06/77] docs: cma/debugfs.txt: convert docs to ReST and rename to *.rst The debugfs interface for CMA should be there together with other mm-related documents. Convert this small file to ReST and move it to its rightful place. The conversion is actually quite simple: just add a title for the document. In order to make it to look better for the audience, also mark the "echo" command as a literal block. While this is not part of any book, mark it as :orphan:, in order to avoid build warnings. Signed-off-by: Mauro Carvalho Chehab --- Documentation/cma/{debugfs.txt => debugfs.rst} | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) rename Documentation/cma/{debugfs.txt => debugfs.rst} (91%) diff --git a/Documentation/cma/debugfs.txt b/Documentation/cma/debugfs.rst similarity index 91% rename from Documentation/cma/debugfs.txt rename to Documentation/cma/debugfs.rst index 6cef20a8cedc..518fe401b5ee 100644 --- a/Documentation/cma/debugfs.txt +++ b/Documentation/cma/debugfs.rst @@ -1,3 +1,9 @@ +:orphan: + +===================== +CMA Debugfs Interface +===================== + The CMA debugfs interface is useful to retrieve basic information out of the different CMA areas and to test allocation/release in each of the areas. @@ -12,7 +18,7 @@ The structure of the files created under that directory is as follows: - [RO] count: Amount of memory in the CMA area. - [RO] order_per_bit: Order of pages represented by one bit. - [RO] bitmap: The bitmap of page states in the zone. - - [WO] alloc: Allocate N pages from that CMA area. For example: + - [WO] alloc: Allocate N pages from that CMA area. For example:: echo 5 > /cma/cma-2/alloc From 8db8acee4b326bfd5bc9a164a7f9ef844ec0fd2e Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sun, 14 Apr 2019 08:44:17 -0300 Subject: [PATCH 07/77] docs: console.txt: convert docs to ReST and rename to *.rst Convert this small file to ReST in preparation for adding it to the driver-api book. While this is not part of the driver-api book, mark it as :orphan:, in order to avoid build warnings. Signed-off-by: Mauro Carvalho Chehab Acked-by: Greg Kroah-Hartman Acked-by: Bartlomiej Zolnierkiewicz --- .../console/{console.txt => console.rst} | 63 ++++++++++--------- Documentation/fb/fbcon.rst | 4 +- drivers/tty/Kconfig | 2 +- 3 files changed, 38 insertions(+), 31 deletions(-) rename Documentation/console/{console.txt => console.rst} (80%) diff --git a/Documentation/console/console.txt b/Documentation/console/console.rst similarity index 80% rename from Documentation/console/console.txt rename to Documentation/console/console.rst index d73c2ab4beda..b374141b027e 100644 --- a/Documentation/console/console.txt +++ b/Documentation/console/console.rst @@ -1,3 +1,6 @@ +:orphan: + +=============== Console Drivers =============== @@ -17,25 +20,26 @@ of driver occupying the consoles.) They can only take over the console that is occupied by the system driver. In the same token, if the modular driver is released by the console, the system driver will take over. -Modular drivers, from the programmer's point of view, have to call: +Modular drivers, from the programmer's point of view, have to call:: do_take_over_console() - load and bind driver to console layer give_up_console() - unload driver; it will only work if driver is fully unbound -In newer kernels, the following are also available: +In newer kernels, the following are also available:: do_register_con_driver() do_unregister_con_driver() If sysfs is enabled, the contents of /sys/class/vtconsole can be examined. This shows the console backends currently registered by the -system which are named vtcon where is an integer from 0 to 15. Thus: +system which are named vtcon where is an integer from 0 to 15. +Thus:: ls /sys/class/vtconsole . .. vtcon0 vtcon1 -Each directory in /sys/class/vtconsole has 3 files: +Each directory in /sys/class/vtconsole has 3 files:: ls /sys/class/vtconsole/vtcon0 . .. bind name uevent @@ -46,27 +50,29 @@ What do these files signify? read, or acts to bind or unbind the driver to the virtual consoles when written to. The possible values are: - 0 - means the driver is not bound and if echo'ed, commands the driver + 0 + - means the driver is not bound and if echo'ed, commands the driver to unbind - 1 - means the driver is bound and if echo'ed, commands the driver to + 1 + - means the driver is bound and if echo'ed, commands the driver to bind - 2. name - read-only file. Shows the name of the driver in this format: + 2. name - read-only file. Shows the name of the driver in this format:: - cat /sys/class/vtconsole/vtcon0/name - (S) VGA+ + cat /sys/class/vtconsole/vtcon0/name + (S) VGA+ - '(S)' stands for a (S)ystem driver, i.e., it cannot be directly - commanded to bind or unbind + '(S)' stands for a (S)ystem driver, i.e., it cannot be directly + commanded to bind or unbind - 'VGA+' is the name of the driver + 'VGA+' is the name of the driver - cat /sys/class/vtconsole/vtcon1/name - (M) frame buffer device + cat /sys/class/vtconsole/vtcon1/name + (M) frame buffer device - In this case, '(M)' stands for a (M)odular driver, one that can be - directly commanded to bind or unbind. + In this case, '(M)' stands for a (M)odular driver, one that can be + directly commanded to bind or unbind. 3. uevent - ignore this file @@ -75,14 +81,17 @@ driver takes over the consoles vacated by the driver. Binding, on the other hand, will bind the driver to the consoles that are currently occupied by a system driver. -NOTE1: Binding and unbinding must be selected in Kconfig. It's under: +NOTE1: + Binding and unbinding must be selected in Kconfig. It's under:: -Device Drivers -> Character devices -> Support for binding and unbinding -console drivers + Device Drivers -> + Character devices -> + Support for binding and unbinding console drivers -NOTE2: If any of the virtual consoles are in KD_GRAPHICS mode, then binding or -unbinding will not succeed. An example of an application that sets the console -to KD_GRAPHICS is X. +NOTE2: + If any of the virtual consoles are in KD_GRAPHICS mode, then binding or + unbinding will not succeed. An example of an application that sets the + console to KD_GRAPHICS is X. How useful is this feature? This is very useful for console driver developers. By unbinding the driver from the console layer, one can unload the @@ -92,10 +101,10 @@ framebuffer console to VGA console and vice versa, this feature also makes this possible. (NOTE NOTE NOTE: Please read fbcon.txt under Documentation/fb for more details.) -Notes for developers: -===================== +Notes for developers +==================== -do_take_over_console() is now broken up into: +do_take_over_console() is now broken up into:: do_register_con_driver() do_bind_con_driver() - private function @@ -104,7 +113,7 @@ give_up_console() is a wrapper to do_unregister_con_driver(), and a driver must be fully unbound for this call to succeed. con_is_bound() will check if the driver is bound or not. -Guidelines for console driver writers: +Guidelines for console driver writers ===================================== In order for binding to and unbinding from the console to properly work, @@ -140,6 +149,4 @@ The current crop of console drivers should still work correctly, but binding and unbinding them may cause problems. With minimal fixes, these drivers can be made to work correctly. -========================== Antonino Daplas - diff --git a/Documentation/fb/fbcon.rst b/Documentation/fb/fbcon.rst index 1da65b9000de..26bc5cdaabab 100644 --- a/Documentation/fb/fbcon.rst +++ b/Documentation/fb/fbcon.rst @@ -187,7 +187,7 @@ the hardware. Thus, in a VGA console:: Assuming the VGA driver can be unloaded, one must first unbind the VGA driver from the console layer before unloading the driver. The VGA driver cannot be unloaded if it is still bound to the console layer. (See -Documentation/console/console.txt for more information). +Documentation/console/console.rst for more information). This is more complicated in the case of the framebuffer console (fbcon), because fbcon is an intermediate layer between the console and the drivers:: @@ -204,7 +204,7 @@ fbcon. Thus, there is no need to explicitly unbind the fbdev drivers from fbcon. So, how do we unbind fbcon from the console? Part of the answer is in -Documentation/console/console.txt. To summarize: +Documentation/console/console.rst. To summarize: Echo a value to the bind file that represents the framebuffer console driver. So assuming vtcon1 represents fbcon, then:: diff --git a/drivers/tty/Kconfig b/drivers/tty/Kconfig index 0e3e4dacbc12..1cb50f19d58c 100644 --- a/drivers/tty/Kconfig +++ b/drivers/tty/Kconfig @@ -93,7 +93,7 @@ config VT_HW_CONSOLE_BINDING select the console driver that will serve as the backend for the virtual terminals. - See for more + See for more information. For framebuffer console users, please refer to . From 93d2c159673325624ef3f2d14ededfcdf76f948b Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sun, 14 Apr 2019 08:50:59 -0300 Subject: [PATCH 08/77] docs: pti_intel_mid.txt: convert it to pti_intel_mid.rst Convert this small file to ReST format and rename it. Most of the conversion were related to adjusting whitespaces in order for each section to be properly parsed. While this is not part of any book, mark it as :orphan:, in order to avoid build warnings. Signed-off-by: Mauro Carvalho Chehab --- Documentation/pti/pti_intel_mid.rst | 106 ++++++++++++++++++++++++++++ Documentation/pti/pti_intel_mid.txt | 99 -------------------------- 2 files changed, 106 insertions(+), 99 deletions(-) create mode 100644 Documentation/pti/pti_intel_mid.rst delete mode 100644 Documentation/pti/pti_intel_mid.txt diff --git a/Documentation/pti/pti_intel_mid.rst b/Documentation/pti/pti_intel_mid.rst new file mode 100644 index 000000000000..ea05725174cb --- /dev/null +++ b/Documentation/pti/pti_intel_mid.rst @@ -0,0 +1,106 @@ +:orphan: + +============= +Intel MID PTI +============= + +The Intel MID PTI project is HW implemented in Intel Atom +system-on-a-chip designs based on the Parallel Trace +Interface for MIPI P1149.7 cJTAG standard. The kernel solution +for this platform involves the following files:: + + ./include/linux/pti.h + ./drivers/.../n_tracesink.h + ./drivers/.../n_tracerouter.c + ./drivers/.../n_tracesink.c + ./drivers/.../pti.c + +pti.c is the driver that enables various debugging features +popular on platforms from certain mobile manufacturers. +n_tracerouter.c and n_tracesink.c allow extra system information to +be collected and routed to the pti driver, such as trace +debugging data from a modem. Although n_tracerouter +and n_tracesink are a part of the complete PTI solution, +these two line disciplines can work separately from +pti.c and route any data stream from one /dev/tty node +to another /dev/tty node via kernel-space. This provides +a stable, reliable connection that will not break unless +the user-space application shuts down (plus avoids +kernel->user->kernel context switch overheads of routing +data). + +An example debugging usage for this driver system: + + * Hook /dev/ttyPTI0 to syslogd. Opening this port will also start + a console device to further capture debugging messages to PTI. + * Hook /dev/ttyPTI1 to modem debugging data to write to PTI HW. + This is where n_tracerouter and n_tracesink are used. + * Hook /dev/pti to a user-level debugging application for writing + to PTI HW. + * `Use mipi_` Kernel Driver API in other device drivers for + debugging to PTI by first requesting a PTI write address via + mipi_request_masterchannel(1). + +Below is example pseudo-code on how a 'privileged' application +can hook up n_tracerouter and n_tracesink to any tty on +a system. 'Privileged' means the application has enough +privileges to successfully manipulate the ldisc drivers +but is not just blindly executing as 'root'. Keep in mind +the use of ioctl(,TIOCSETD,) is not specific to the n_tracerouter +and n_tracesink line discpline drivers but is a generic +operation for a program to use a line discpline driver +on a tty port other than the default n_tty:: + + /////////// To hook up n_tracerouter and n_tracesink ///////// + + // Note that n_tracerouter depends on n_tracesink. + #include + #define ONE_TTY "/dev/ttyOne" + #define TWO_TTY "/dev/ttyTwo" + + // needed global to hand onto ldisc connection + static int g_fd_source = -1; + static int g_fd_sink = -1; + + // these two vars used to grab LDISC values from loaded ldisc drivers + // in OS. Look at /proc/tty/ldiscs to get the right numbers from + // the ldiscs loaded in the system. + int source_ldisc_num, sink_ldisc_num = -1; + int retval; + + g_fd_source = open(ONE_TTY, O_RDWR); // must be R/W + g_fd_sink = open(TWO_TTY, O_RDWR); // must be R/W + + if (g_fd_source <= 0) || (g_fd_sink <= 0) { + // doubt you'll want to use these exact error lines of code + printf("Error on open(). errno: %d\n",errno); + return errno; + } + + retval = ioctl(g_fd_sink, TIOCSETD, &sink_ldisc_num); + if (retval < 0) { + printf("Error on ioctl(). errno: %d\n", errno); + return errno; + } + + retval = ioctl(g_fd_source, TIOCSETD, &source_ldisc_num); + if (retval < 0) { + printf("Error on ioctl(). errno: %d\n", errno); + return errno; + } + + /////////// To disconnect n_tracerouter and n_tracesink //////// + + // First make sure data through the ldiscs has stopped. + + // Second, disconnect ldiscs. This provides a + // little cleaner shutdown on tty stack. + sink_ldisc_num = 0; + source_ldisc_num = 0; + ioctl(g_fd_uart, TIOCSETD, &sink_ldisc_num); + ioctl(g_fd_gadget, TIOCSETD, &source_ldisc_num); + + // Three, program closes connection, and cleanup: + close(g_fd_uart); + close(g_fd_gadget); + g_fd_uart = g_fd_gadget = NULL; diff --git a/Documentation/pti/pti_intel_mid.txt b/Documentation/pti/pti_intel_mid.txt deleted file mode 100644 index e7a5b6d1f7a9..000000000000 --- a/Documentation/pti/pti_intel_mid.txt +++ /dev/null @@ -1,99 +0,0 @@ -The Intel MID PTI project is HW implemented in Intel Atom -system-on-a-chip designs based on the Parallel Trace -Interface for MIPI P1149.7 cJTAG standard. The kernel solution -for this platform involves the following files: - -./include/linux/pti.h -./drivers/.../n_tracesink.h -./drivers/.../n_tracerouter.c -./drivers/.../n_tracesink.c -./drivers/.../pti.c - -pti.c is the driver that enables various debugging features -popular on platforms from certain mobile manufacturers. -n_tracerouter.c and n_tracesink.c allow extra system information to -be collected and routed to the pti driver, such as trace -debugging data from a modem. Although n_tracerouter -and n_tracesink are a part of the complete PTI solution, -these two line disciplines can work separately from -pti.c and route any data stream from one /dev/tty node -to another /dev/tty node via kernel-space. This provides -a stable, reliable connection that will not break unless -the user-space application shuts down (plus avoids -kernel->user->kernel context switch overheads of routing -data). - -An example debugging usage for this driver system: - *Hook /dev/ttyPTI0 to syslogd. Opening this port will also start - a console device to further capture debugging messages to PTI. - *Hook /dev/ttyPTI1 to modem debugging data to write to PTI HW. - This is where n_tracerouter and n_tracesink are used. - *Hook /dev/pti to a user-level debugging application for writing - to PTI HW. - *Use mipi_* Kernel Driver API in other device drivers for - debugging to PTI by first requesting a PTI write address via - mipi_request_masterchannel(1). - -Below is example pseudo-code on how a 'privileged' application -can hook up n_tracerouter and n_tracesink to any tty on -a system. 'Privileged' means the application has enough -privileges to successfully manipulate the ldisc drivers -but is not just blindly executing as 'root'. Keep in mind -the use of ioctl(,TIOCSETD,) is not specific to the n_tracerouter -and n_tracesink line discpline drivers but is a generic -operation for a program to use a line discpline driver -on a tty port other than the default n_tty. - -/////////// To hook up n_tracerouter and n_tracesink ///////// - -// Note that n_tracerouter depends on n_tracesink. -#include -#define ONE_TTY "/dev/ttyOne" -#define TWO_TTY "/dev/ttyTwo" - -// needed global to hand onto ldisc connection -static int g_fd_source = -1; -static int g_fd_sink = -1; - -// these two vars used to grab LDISC values from loaded ldisc drivers -// in OS. Look at /proc/tty/ldiscs to get the right numbers from -// the ldiscs loaded in the system. -int source_ldisc_num, sink_ldisc_num = -1; -int retval; - -g_fd_source = open(ONE_TTY, O_RDWR); // must be R/W -g_fd_sink = open(TWO_TTY, O_RDWR); // must be R/W - -if (g_fd_source <= 0) || (g_fd_sink <= 0) { - // doubt you'll want to use these exact error lines of code - printf("Error on open(). errno: %d\n",errno); - return errno; -} - -retval = ioctl(g_fd_sink, TIOCSETD, &sink_ldisc_num); -if (retval < 0) { - printf("Error on ioctl(). errno: %d\n", errno); - return errno; -} - -retval = ioctl(g_fd_source, TIOCSETD, &source_ldisc_num); -if (retval < 0) { - printf("Error on ioctl(). errno: %d\n", errno); - return errno; -} - -/////////// To disconnect n_tracerouter and n_tracesink //////// - -// First make sure data through the ldiscs has stopped. - -// Second, disconnect ldiscs. This provides a -// little cleaner shutdown on tty stack. -sink_ldisc_num = 0; -source_ldisc_num = 0; -ioctl(g_fd_uart, TIOCSETD, &sink_ldisc_num); -ioctl(g_fd_gadget, TIOCSETD, &source_ldisc_num); - -// Three, program closes connection, and cleanup: -close(g_fd_uart); -close(g_fd_gadget); -g_fd_uart = g_fd_gadget = NULL; From 0d07cf5e53a21e35289adc3ab99b6804ff0c3833 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sun, 14 Apr 2019 08:58:05 -0300 Subject: [PATCH 09/77] docs: early-userspace: convert docs to ReST and rename to *.rst The two files there describes a Kernel API feature, used to support early userspace stuff. Prepare for moving them to the kernel API book by converting to ReST format. The conversion itself was quite trivial: just add/mark a few titles as such, add a literal block markup, add a table markup and a few blank lines, in order to make Sphinx to properly parse it. At its new index.rst, let's add a :orphan: while this is not linked to the main index.rst file, in order to avoid build warnings. Signed-off-by: Mauro Carvalho Chehab --- .../{buffer-format.txt => buffer-format.rst} | 19 +++++++++++++------ .../{README => early_userspace_support.rst} | 3 +++ Documentation/early-userspace/index.rst | 18 ++++++++++++++++++ Documentation/filesystems/nfs/nfsroot.txt | 2 +- .../filesystems/ramfs-rootfs-initramfs.txt | 4 ++-- usr/Kconfig | 2 +- 6 files changed, 38 insertions(+), 10 deletions(-) rename Documentation/early-userspace/{buffer-format.txt => buffer-format.rst} (91%) rename Documentation/early-userspace/{README => early_userspace_support.rst} (99%) create mode 100644 Documentation/early-userspace/index.rst diff --git a/Documentation/early-userspace/buffer-format.txt b/Documentation/early-userspace/buffer-format.rst similarity index 91% rename from Documentation/early-userspace/buffer-format.txt rename to Documentation/early-userspace/buffer-format.rst index e1fd7f9dad16..7f74e301fdf3 100644 --- a/Documentation/early-userspace/buffer-format.txt +++ b/Documentation/early-userspace/buffer-format.rst @@ -1,8 +1,10 @@ - initramfs buffer format - ----------------------- +======================= +initramfs buffer format +======================= - Al Viro, H. Peter Anvin - Last revision: 2002-01-13 +Al Viro, H. Peter Anvin + +Last revision: 2002-01-13 Starting with kernel 2.5.x, the old "initial ramdisk" protocol is getting {replaced/complemented} with the new "initial ramfs" @@ -18,7 +20,8 @@ archive can be compressed using gzip(1). One valid version of an initramfs buffer is thus a single .cpio.gz file. The full format of the initramfs buffer is defined by the following -grammar, where: +grammar, where:: + * is used to indicate "0 or more occurrences of" (|) indicates alternatives + indicates concatenation @@ -49,7 +52,9 @@ hexadecimal ASCII numbers fully padded with '0' on the left to the full width of the field, for example, the integer 4780 is represented by the ASCII string "000012ac"): +============= ================== ============================================== Field name Field size Meaning +============= ================== ============================================== c_magic 6 bytes The string "070701" or "070702" c_ino 8 bytes File inode number c_mode 8 bytes File mode and permissions @@ -65,6 +70,7 @@ c_rmin 8 bytes Minor part of device node reference c_namesize 8 bytes Length of filename, including final \0 c_chksum 8 bytes Checksum of data field if c_magic is 070702; otherwise zero +============= ================== ============================================== The c_mode field matches the contents of st_mode returned by stat(2) on Linux, and encodes the file type and file permissions. @@ -82,7 +88,8 @@ If the filename is "TRAILER!!!" this is actually an end-of-archive marker; the c_filesize for an end-of-archive marker must be zero. -*** Handling of hard links +Handling of hard links +====================== When a nondirectory with c_nlink > 1 is seen, the (c_maj,c_min,c_ino) tuple is looked up in a tuple buffer. If not found, it is entered in diff --git a/Documentation/early-userspace/README b/Documentation/early-userspace/early_userspace_support.rst similarity index 99% rename from Documentation/early-userspace/README rename to Documentation/early-userspace/early_userspace_support.rst index 955d667dc87e..3deefb34046b 100644 --- a/Documentation/early-userspace/README +++ b/Documentation/early-userspace/early_userspace_support.rst @@ -1,3 +1,4 @@ +======================= Early userspace support ======================= @@ -26,6 +27,7 @@ archive to be used as the image or have the kernel build process build the image from specifications. CPIO ARCHIVE method +------------------- You can create a cpio archive that contains the early userspace image. Your cpio archive should be specified in CONFIG_INITRAMFS_SOURCE and it @@ -34,6 +36,7 @@ CONFIG_INITRAMFS_SOURCE and directory and file names are not allowed in combination with a cpio archive. IMAGE BUILDING method +--------------------- The kernel build process can also build an early userspace image from source parts rather than supplying a cpio archive. This method provides diff --git a/Documentation/early-userspace/index.rst b/Documentation/early-userspace/index.rst new file mode 100644 index 000000000000..2b8eb6132058 --- /dev/null +++ b/Documentation/early-userspace/index.rst @@ -0,0 +1,18 @@ +:orphan: + +=============== +Early Userspace +=============== + +.. toctree:: + :maxdepth: 1 + + early_userspace_support + buffer-format + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/filesystems/nfs/nfsroot.txt b/Documentation/filesystems/nfs/nfsroot.txt index d2963123eb1c..4862d3d77e27 100644 --- a/Documentation/filesystems/nfs/nfsroot.txt +++ b/Documentation/filesystems/nfs/nfsroot.txt @@ -239,7 +239,7 @@ rdinit= A description of the process of mounting the root file system can be found in: - Documentation/early-userspace/README + Documentation/early-userspace/early_userspace_support.rst diff --git a/Documentation/filesystems/ramfs-rootfs-initramfs.txt b/Documentation/filesystems/ramfs-rootfs-initramfs.txt index 79637d227e85..fa985909dbca 100644 --- a/Documentation/filesystems/ramfs-rootfs-initramfs.txt +++ b/Documentation/filesystems/ramfs-rootfs-initramfs.txt @@ -105,7 +105,7 @@ All this differs from the old initrd in several ways: - The old initrd file was a gzipped filesystem image (in some file format, such as ext2, that needed a driver built into the kernel), while the new initramfs archive is a gzipped cpio archive (like tar only simpler, - see cpio(1) and Documentation/early-userspace/buffer-format.txt). The + see cpio(1) and Documentation/early-userspace/buffer-format.rst). The kernel's cpio extraction code is not only extremely small, it's also __init text and data that can be discarded during the boot process. @@ -159,7 +159,7 @@ One advantage of the configuration file is that root access is not required to set permissions or create device nodes in the new archive. (Note that those two example "file" entries expect to find files named "init.sh" and "busybox" in a directory called "initramfs", under the linux-2.6.* directory. See -Documentation/early-userspace/README for more details.) +Documentation/early-userspace/early_userspace_support.rst for more details.) The kernel does not depend on external cpio tools. If you specify a directory instead of a configuration file, the kernel's build infrastructure diff --git a/usr/Kconfig b/usr/Kconfig index 43658b8a975e..86e37e297278 100644 --- a/usr/Kconfig +++ b/usr/Kconfig @@ -18,7 +18,7 @@ config INITRAMFS_SOURCE When multiple directories and files are specified then the initramfs image will be the aggregate of all of them. - See for more details. + See for more details. If you are not sure, leave it blank. From dc7a12bdfccd94c31f79e294f16f7549bd411b49 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sun, 14 Apr 2019 15:51:10 -0300 Subject: [PATCH 10/77] docs: arm: convert docs to ReST and rename to *.rst Converts ARM the text files to ReST, preparing them to be an architecture book. The conversion is actually: - add blank lines and identation in order to identify paragraphs; - fix tables markups; - add some lists markups; - mark literal blocks; - adjust title markups. At its new index.rst, let's add a :orphan: while this is not linked to the main index.rst file, in order to avoid build warnings. Signed-off-by: Mauro Carvalho Chehab Reviewed-by Corentin Labbe # For sun4i-ss --- Documentation/arm/Marvell/README | 395 -------------- Documentation/arm/Netwinder | 78 --- Documentation/arm/SA1100/FreeBird | 21 - Documentation/arm/SA1100/empeg | 2 - Documentation/arm/SA1100/serial_UART | 47 -- Documentation/arm/{README => arm.rst} | 50 +- Documentation/arm/{Booting => booting.rst} | 71 ++- ...ance.txt => cluster-pm-race-avoidance.rst} | 177 ++++--- .../arm/{firmware.txt => firmware.rst} | 14 +- Documentation/arm/index.rst | 80 +++ .../arm/{Interrupts => interrupts.rst} | 86 +-- Documentation/arm/{IXP4xx => ixp4xx.rst} | 61 +-- ...nel_mode_neon.txt => kernel_mode_neon.rst} | 3 + ...er_helpers.txt => kernel_user_helpers.rst} | 79 +-- .../keystone/{knav-qmss.txt => knav-qmss.rst} | 6 +- .../keystone/{Overview.txt => overview.rst} | 47 +- Documentation/arm/marvel.rst | 488 ++++++++++++++++++ .../arm/{mem_alignment => mem_alignment.rst} | 11 +- Documentation/arm/{memory.txt => memory.rst} | 9 +- .../arm/{Microchip/README => microchip.rst} | 63 ++- Documentation/arm/netwinder.rst | 85 +++ Documentation/arm/nwfpe/index.rst | 11 + .../nwfpe/{README.FPE => netwinder-fpe.rst} | 24 +- Documentation/arm/nwfpe/{NOTES => notes.rst} | 3 + Documentation/arm/nwfpe/{README => nwfpe.rst} | 10 +- Documentation/arm/nwfpe/{TODO => todo.rst} | 47 +- Documentation/arm/{OMAP/DSS => omap/dss.rst} | 112 ++-- Documentation/arm/omap/index.rst | 10 + .../arm/{OMAP/README => omap/omap.rst} | 7 + .../arm/{OMAP/omap_pm => omap/omap_pm.rst} | 55 +- Documentation/arm/{Porting => porting.rst} | 14 +- Documentation/arm/pxa/{mfp.txt => mfp.rst} | 106 ++-- .../{SA1100/ADSBitsy => sa1100/adsbitsy.rst} | 14 +- .../{SA1100/Assabet => sa1100/assabet.rst} | 185 +++---- .../arm/{SA1100/Brutus => sa1100/brutus.rst} | 45 +- .../arm/{SA1100/CERF => sa1100/cerf.rst} | 10 +- Documentation/arm/sa1100/freebird.rst | 25 + .../graphicsclient.rst} | 46 +- .../graphicsmaster.rst} | 13 +- .../HUW_WEBPANEL => sa1100/huw_webpanel.rst} | 8 +- Documentation/arm/sa1100/index.rst | 23 + .../arm/{SA1100/Itsy => sa1100/itsy.rst} | 14 +- .../arm/{SA1100/LART => sa1100/lart.rst} | 3 +- .../nanoEngine => sa1100/nanoengine.rst} | 6 +- .../{SA1100/Pangolin => sa1100/pangolin.rst} | 10 +- .../arm/{SA1100/PLEB => sa1100/pleb.rst} | 6 +- Documentation/arm/sa1100/serial_uart.rst | 51 ++ .../arm/{SA1100/Tifon => sa1100/tifon.rst} | 4 +- .../arm/{SA1100/Yopy => sa1100/yopy.rst} | 5 +- .../cpufreq.rst} | 5 +- .../eb2410itx.rst} | 5 +- .../GPIO.txt => samsung-s3c24xx/gpio.rst} | 23 +- .../H1940.txt => samsung-s3c24xx/h1940.rst} | 5 +- Documentation/arm/samsung-s3c24xx/index.rst | 18 + .../NAND.txt => samsung-s3c24xx/nand.rst} | 6 +- .../overview.rst} | 21 +- .../s3c2412.rst} | 5 +- .../s3c2413.rst} | 7 +- .../smdk2440.rst} | 5 +- .../suspend.rst} | 20 +- .../usb-host.rst} | 16 +- .../bootloader-interface.rst} | 27 +- .../clksrc-change-registers.awk | 0 .../{Samsung/GPIO.txt => samsung/gpio.rst} | 7 +- Documentation/arm/samsung/index.rst | 10 + .../Overview.txt => samsung/overview.rst} | 15 +- Documentation/arm/{Setup => setup.rst} | 49 +- .../arm/{SH-Mobile => sh-mobile}/.gitignore | 0 .../overview.txt => spear/overview.rst} | 20 +- .../arm/sti/{overview.txt => overview.rst} | 21 +- ...h407-overview.txt => stih407-overview.rst} | 9 +- ...h415-overview.txt => stih415-overview.rst} | 8 +- ...h416-overview.txt => stih416-overview.rst} | 5 +- ...h418-overview.txt => stih418-overview.rst} | 9 +- Documentation/arm/stm32/overview.rst | 2 - .../arm/stm32/stm32f429-overview.rst | 7 +- .../arm/stm32/stm32f746-overview.rst | 7 +- .../arm/stm32/stm32f769-overview.rst | 7 +- .../arm/stm32/stm32h743-overview.rst | 7 +- .../arm/stm32/stm32mp157-overview.rst | 3 +- Documentation/arm/{sunxi/README => sunxi.rst} | 98 +++- .../arm/sunxi/{clocks.txt => clocks.rst} | 7 +- .../arm/{swp_emulation => swp_emulation.rst} | 24 +- Documentation/arm/{tcm.txt => tcm.rst} | 54 +- Documentation/arm/{uefi.txt => uefi.rst} | 39 +- .../release-notes.rst} | 4 +- Documentation/arm/{vlocks.txt => vlocks.rst} | 9 +- Documentation/devicetree/bindings/arm/xen.txt | 2 +- .../devicetree/booting-without-of.txt | 4 +- Documentation/index.rst | 1 + Documentation/translations/zh_CN/arm/Booting | 4 +- .../zh_CN/arm/kernel_user_helpers.txt | 4 +- MAINTAINERS | 4 +- arch/arm/Kconfig | 2 +- arch/arm/common/mcpm_entry.c | 2 +- arch/arm/common/mcpm_head.S | 2 +- arch/arm/common/vlock.S | 2 +- arch/arm/include/asm/setup.h | 2 +- arch/arm/include/uapi/asm/setup.h | 2 +- arch/arm/kernel/entry-armv.S | 2 +- arch/arm/mach-exynos/common.h | 2 +- arch/arm/mach-ixp4xx/Kconfig | 14 +- arch/arm/mach-s3c24xx/pm.c | 2 +- arch/arm/mm/Kconfig | 4 +- arch/arm/plat-samsung/Kconfig | 6 +- arch/arm/tools/mach-types | 2 +- arch/arm64/Kconfig | 2 +- arch/arm64/kernel/kuser32.S | 2 +- arch/mips/bmips/setup.c | 2 +- drivers/crypto/sunxi-ss/sun4i-ss-cipher.c | 2 +- drivers/crypto/sunxi-ss/sun4i-ss-core.c | 2 +- drivers/crypto/sunxi-ss/sun4i-ss-hash.c | 2 +- drivers/crypto/sunxi-ss/sun4i-ss.h | 2 +- drivers/input/touchscreen/sun4i-ts.c | 2 +- drivers/tty/serial/Kconfig | 2 +- 115 files changed, 1985 insertions(+), 1420 deletions(-) delete mode 100644 Documentation/arm/Marvell/README delete mode 100644 Documentation/arm/Netwinder delete mode 100644 Documentation/arm/SA1100/FreeBird delete mode 100644 Documentation/arm/SA1100/empeg delete mode 100644 Documentation/arm/SA1100/serial_UART rename Documentation/arm/{README => arm.rst} (88%) rename Documentation/arm/{Booting => booting.rst} (89%) rename Documentation/arm/{cluster-pm-race-avoidance.txt => cluster-pm-race-avoidance.rst} (84%) rename Documentation/arm/{firmware.txt => firmware.rst} (86%) create mode 100644 Documentation/arm/index.rst rename Documentation/arm/{Interrupts => interrupts.rst} (81%) rename Documentation/arm/{IXP4xx => ixp4xx.rst} (84%) rename Documentation/arm/{kernel_mode_neon.txt => kernel_mode_neon.rst} (99%) rename Documentation/arm/{kernel_user_helpers.txt => kernel_user_helpers.rst} (78%) rename Documentation/arm/keystone/{knav-qmss.txt => knav-qmss.rst} (92%) rename Documentation/arm/keystone/{Overview.txt => overview.rst} (59%) create mode 100644 Documentation/arm/marvel.rst rename Documentation/arm/{mem_alignment => mem_alignment.rst} (89%) rename Documentation/arm/{memory.txt => memory.rst} (90%) rename Documentation/arm/{Microchip/README => microchip.rst} (92%) create mode 100644 Documentation/arm/netwinder.rst create mode 100644 Documentation/arm/nwfpe/index.rst rename Documentation/arm/nwfpe/{README.FPE => netwinder-fpe.rst} (94%) rename Documentation/arm/nwfpe/{NOTES => notes.rst} (99%) rename Documentation/arm/nwfpe/{README => nwfpe.rst} (98%) rename Documentation/arm/nwfpe/{TODO => todo.rst} (75%) rename Documentation/arm/{OMAP/DSS => omap/dss.rst} (86%) create mode 100644 Documentation/arm/omap/index.rst rename Documentation/arm/{OMAP/README => omap/omap.rst} (62%) rename Documentation/arm/{OMAP/omap_pm => omap/omap_pm.rst} (83%) rename Documentation/arm/{Porting => porting.rst} (94%) rename Documentation/arm/pxa/{mfp.txt => mfp.rst} (83%) rename Documentation/arm/{SA1100/ADSBitsy => sa1100/adsbitsy.rst} (90%) rename Documentation/arm/{SA1100/Assabet => sa1100/assabet.rst} (62%) rename Documentation/arm/{SA1100/Brutus => sa1100/brutus.rst} (75%) rename Documentation/arm/{SA1100/CERF => sa1100/cerf.rst} (91%) create mode 100644 Documentation/arm/sa1100/freebird.rst rename Documentation/arm/{SA1100/GraphicsClient => sa1100/graphicsclient.rst} (87%) rename Documentation/arm/{SA1100/GraphicsMaster => sa1100/graphicsmaster.rst} (92%) rename Documentation/arm/{SA1100/HUW_WEBPANEL => sa1100/huw_webpanel.rst} (78%) create mode 100644 Documentation/arm/sa1100/index.rst rename Documentation/arm/{SA1100/Itsy => sa1100/itsy.rst} (88%) rename Documentation/arm/{SA1100/LART => sa1100/lart.rst} (90%) rename Documentation/arm/{SA1100/nanoEngine => sa1100/nanoengine.rst} (74%) rename Documentation/arm/{SA1100/Pangolin => sa1100/pangolin.rst} (81%) rename Documentation/arm/{SA1100/PLEB => sa1100/pleb.rst} (95%) create mode 100644 Documentation/arm/sa1100/serial_uart.rst rename Documentation/arm/{SA1100/Tifon => sa1100/tifon.rst} (88%) rename Documentation/arm/{SA1100/Yopy => sa1100/yopy.rst} (74%) rename Documentation/arm/{Samsung-S3C24XX/CPUfreq.txt => samsung-s3c24xx/cpufreq.rst} (96%) rename Documentation/arm/{Samsung-S3C24XX/EB2410ITX.txt => samsung-s3c24xx/eb2410itx.rst} (92%) rename Documentation/arm/{Samsung-S3C24XX/GPIO.txt => samsung-s3c24xx/gpio.rst} (89%) rename Documentation/arm/{Samsung-S3C24XX/H1940.txt => samsung-s3c24xx/h1940.rst} (94%) create mode 100644 Documentation/arm/samsung-s3c24xx/index.rst rename Documentation/arm/{Samsung-S3C24XX/NAND.txt => samsung-s3c24xx/nand.rst} (92%) rename Documentation/arm/{Samsung-S3C24XX/Overview.txt => samsung-s3c24xx/overview.rst} (94%) rename Documentation/arm/{Samsung-S3C24XX/S3C2412.txt => samsung-s3c24xx/s3c2412.rst} (96%) rename Documentation/arm/{Samsung-S3C24XX/S3C2413.txt => samsung-s3c24xx/s3c2413.rst} (77%) rename Documentation/arm/{Samsung-S3C24XX/SMDK2440.txt => samsung-s3c24xx/smdk2440.rst} (94%) rename Documentation/arm/{Samsung-S3C24XX/Suspend.txt => samsung-s3c24xx/suspend.rst} (94%) rename Documentation/arm/{Samsung-S3C24XX/USB-Host.txt => samsung-s3c24xx/usb-host.rst} (94%) rename Documentation/arm/{Samsung/Bootloader-interface.txt => samsung/bootloader-interface.rst} (72%) rename Documentation/arm/{Samsung => samsung}/clksrc-change-registers.awk (100%) rename Documentation/arm/{Samsung/GPIO.txt => samsung/gpio.rst} (87%) create mode 100644 Documentation/arm/samsung/index.rst rename Documentation/arm/{Samsung/Overview.txt => samsung/overview.rst} (86%) rename Documentation/arm/{Setup => setup.rst} (87%) rename Documentation/arm/{SH-Mobile => sh-mobile}/.gitignore (100%) rename Documentation/arm/{SPEAr/overview.txt => spear/overview.rst} (91%) rename Documentation/arm/sti/{overview.txt => overview.rst} (82%) rename Documentation/arm/sti/{stih407-overview.txt => stih407-overview.rst} (82%) rename Documentation/arm/sti/{stih415-overview.txt => stih415-overview.rst} (79%) rename Documentation/arm/sti/{stih416-overview.txt => stih416-overview.rst} (83%) rename Documentation/arm/sti/{stih418-overview.txt => stih418-overview.rst} (83%) rename Documentation/arm/{sunxi/README => sunxi.rst} (83%) rename Documentation/arm/sunxi/{clocks.txt => clocks.rst} (92%) rename Documentation/arm/{swp_emulation => swp_emulation.rst} (63%) rename Documentation/arm/{tcm.txt => tcm.rst} (86%) rename Documentation/arm/{uefi.txt => uefi.rst} (63%) rename Documentation/arm/{VFP/release-notes.txt => vfp/release-notes.rst} (92%) rename Documentation/arm/{vlocks.txt => vlocks.rst} (98%) diff --git a/Documentation/arm/Marvell/README b/Documentation/arm/Marvell/README deleted file mode 100644 index 56ada27c53be..000000000000 --- a/Documentation/arm/Marvell/README +++ /dev/null @@ -1,395 +0,0 @@ -ARM Marvell SoCs -================ - -This document lists all the ARM Marvell SoCs that are currently -supported in mainline by the Linux kernel. As the Marvell families of -SoCs are large and complex, it is hard to understand where the support -for a particular SoC is available in the Linux kernel. This document -tries to help in understanding where those SoCs are supported, and to -match them with their corresponding public datasheet, when available. - -Orion family ------------- - - Flavors: - 88F5082 - 88F5181 - 88F5181L - 88F5182 - Datasheet : http://www.embeddedarm.com/documentation/third-party/MV88F5182-datasheet.pdf - Programmer's User Guide : http://www.embeddedarm.com/documentation/third-party/MV88F5182-opensource-manual.pdf - User Manual : http://www.embeddedarm.com/documentation/third-party/MV88F5182-usermanual.pdf - 88F5281 - Datasheet : http://www.ocmodshop.com/images/reviews/networking/qnap_ts409u/marvel_88f5281_data_sheet.pdf - 88F6183 - Core: Feroceon 88fr331 (88f51xx) or 88fr531-vd (88f52xx) ARMv5 compatible - Linux kernel mach directory: arch/arm/mach-orion5x - Linux kernel plat directory: arch/arm/plat-orion - -Kirkwood family ---------------- - - Flavors: - 88F6282 a.k.a Armada 300 - Product Brief : http://www.marvell.com/embedded-processors/armada-300/assets/armada_310.pdf - 88F6283 a.k.a Armada 310 - Product Brief : http://www.marvell.com/embedded-processors/armada-300/assets/armada_310.pdf - 88F6190 - Product Brief : http://www.marvell.com/embedded-processors/kirkwood/assets/88F6190-003_WEB.pdf - Hardware Spec : http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F619x_OpenSource.pdf - Functional Spec: http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf - 88F6192 - Product Brief : http://www.marvell.com/embedded-processors/kirkwood/assets/88F6192-003_ver1.pdf - Hardware Spec : http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F619x_OpenSource.pdf - Functional Spec: http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf - 88F6182 - 88F6180 - Product Brief : http://www.marvell.com/embedded-processors/kirkwood/assets/88F6180-003_ver1.pdf - Hardware Spec : http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F6180_OpenSource.pdf - Functional Spec: http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf - 88F6281 - Product Brief : http://www.marvell.com/embedded-processors/kirkwood/assets/88F6281-004_ver1.pdf - Hardware Spec : http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F6281_OpenSource.pdf - Functional Spec: http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf - Homepage: http://www.marvell.com/embedded-processors/kirkwood/ - Core: Feroceon 88fr131 ARMv5 compatible - Linux kernel mach directory: arch/arm/mach-mvebu - Linux kernel plat directory: none - -Discovery family ----------------- - - Flavors: - MV78100 - Product Brief : http://www.marvell.com/embedded-processors/discovery-innovation/assets/MV78100-003_WEB.pdf - Hardware Spec : http://www.marvell.com/embedded-processors/discovery-innovation/assets/HW_MV78100_OpenSource.pdf - Functional Spec: http://www.marvell.com/embedded-processors/discovery-innovation/assets/FS_MV76100_78100_78200_OpenSource.pdf - MV78200 - Product Brief : http://www.marvell.com/embedded-processors/discovery-innovation/assets/MV78200-002_WEB.pdf - Hardware Spec : http://www.marvell.com/embedded-processors/discovery-innovation/assets/HW_MV78200_OpenSource.pdf - Functional Spec: http://www.marvell.com/embedded-processors/discovery-innovation/assets/FS_MV76100_78100_78200_OpenSource.pdf - MV76100 - Not supported by the Linux kernel. - - Core: Feroceon 88fr571-vd ARMv5 compatible - - Linux kernel mach directory: arch/arm/mach-mv78xx0 - Linux kernel plat directory: arch/arm/plat-orion - -EBU Armada family ------------------ - - Armada 370 Flavors: - 88F6710 - 88F6707 - 88F6W11 - Product Brief: http://www.marvell.com/embedded-processors/armada-300/assets/Marvell_ARMADA_370_SoC.pdf - Hardware Spec: http://www.marvell.com/embedded-processors/armada-300/assets/ARMADA370-datasheet.pdf - Functional Spec: http://www.marvell.com/embedded-processors/armada-300/assets/ARMADA370-FunctionalSpec-datasheet.pdf - Core: Sheeva ARMv7 compatible PJ4B - - Armada 375 Flavors: - 88F6720 - Product Brief: http://www.marvell.com/embedded-processors/armada-300/assets/ARMADA_375_SoC-01_product_brief.pdf - Core: ARM Cortex-A9 - - Armada 38x Flavors: - 88F6810 Armada 380 - 88F6820 Armada 385 - 88F6828 Armada 388 - Product infos: http://www.marvell.com/embedded-processors/armada-38x/ - Functional Spec: https://marvellcorp.wufoo.com/forms/marvell-armada-38x-functional-specifications/ - Core: ARM Cortex-A9 - - Armada 39x Flavors: - 88F6920 Armada 390 - 88F6928 Armada 398 - Product infos: http://www.marvell.com/embedded-processors/armada-39x/ - Core: ARM Cortex-A9 - - Armada XP Flavors: - MV78230 - MV78260 - MV78460 - NOTE: not to be confused with the non-SMP 78xx0 SoCs - Product Brief: http://www.marvell.com/embedded-processors/armada-xp/assets/Marvell-ArmadaXP-SoC-product%20brief.pdf - Functional Spec: http://www.marvell.com/embedded-processors/armada-xp/assets/ARMADA-XP-Functional-SpecDatasheet.pdf - Hardware Specs: - http://www.marvell.com/embedded-processors/armada-xp/assets/HW_MV78230_OS.PDF - http://www.marvell.com/embedded-processors/armada-xp/assets/HW_MV78260_OS.PDF - http://www.marvell.com/embedded-processors/armada-xp/assets/HW_MV78460_OS.PDF - Core: Sheeva ARMv7 compatible Dual-core or Quad-core PJ4B-MP - - Linux kernel mach directory: arch/arm/mach-mvebu - Linux kernel plat directory: none - -EBU Armada family ARMv8 ------------------------ - - Armada 3710/3720 Flavors: - 88F3710 - 88F3720 - Core: ARM Cortex A53 (ARMv8) - - Homepage: http://www.marvell.com/embedded-processors/armada-3700/ - Product Brief: http://www.marvell.com/embedded-processors/assets/PB-88F3700-FNL.pdf - Device tree files: arch/arm64/boot/dts/marvell/armada-37* - - Armada 7K Flavors: - 88F7020 (AP806 Dual + one CP110) - 88F7040 (AP806 Quad + one CP110) - Core: ARM Cortex A72 - - Homepage: http://www.marvell.com/embedded-processors/armada-70xx/ - Product Brief: http://www.marvell.com/embedded-processors/assets/Armada7020PB-Jan2016.pdf - http://www.marvell.com/embedded-processors/assets/Armada7040PB-Jan2016.pdf - Device tree files: arch/arm64/boot/dts/marvell/armada-70* - - Armada 8K Flavors: - 88F8020 (AP806 Dual + two CP110) - 88F8040 (AP806 Quad + two CP110) - Core: ARM Cortex A72 - - Homepage: http://www.marvell.com/embedded-processors/armada-80xx/ - Product Brief: http://www.marvell.com/embedded-processors/assets/Armada8020PB-Jan2016.pdf - http://www.marvell.com/embedded-processors/assets/Armada8040PB-Jan2016.pdf - Device tree files: arch/arm64/boot/dts/marvell/armada-80* - -Avanta family -------------- - - Flavors: - 88F6510 - 88F6530P - 88F6550 - 88F6560 - Homepage : http://www.marvell.com/broadband/ - Product Brief: http://www.marvell.com/broadband/assets/Marvell_Avanta_88F6510_305_060-001_product_brief.pdf - No public datasheet available. - - Core: ARMv5 compatible - - Linux kernel mach directory: no code in mainline yet, planned for the future - Linux kernel plat directory: no code in mainline yet, planned for the future - -Storage family --------------- - - Armada SP: - 88RC1580 - Product infos: http://www.marvell.com/storage/armada-sp/ - Core: Sheeva ARMv7 comatible Quad-core PJ4C - (not supported in upstream Linux kernel) - -Dove family (application processor) ------------------------------------ - - Flavors: - 88AP510 a.k.a Armada 510 - Product Brief : http://www.marvell.com/application-processors/armada-500/assets/Marvell_Armada510_SoC.pdf - Hardware Spec : http://www.marvell.com/application-processors/armada-500/assets/Armada-510-Hardware-Spec.pdf - Functional Spec : http://www.marvell.com/application-processors/armada-500/assets/Armada-510-Functional-Spec.pdf - Homepage: http://www.marvell.com/application-processors/armada-500/ - Core: ARMv7 compatible - - Directory: arch/arm/mach-mvebu (DT enabled platforms) - arch/arm/mach-dove (non-DT enabled platforms) - -PXA 2xx/3xx/93x/95x family --------------------------- - - Flavors: - PXA21x, PXA25x, PXA26x - Application processor only - Core: ARMv5 XScale1 core - PXA270, PXA271, PXA272 - Product Brief : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_pb.pdf - Design guide : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_design_guide.pdf - Developers manual : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_dev_man.pdf - Specification : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_emts.pdf - Specification update : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_spec_update.pdf - Application processor only - Core: ARMv5 XScale2 core - PXA300, PXA310, PXA320 - PXA 300 Product Brief : http://www.marvell.com/application-processors/pxa-family/assets/PXA300_PB_R4.pdf - PXA 310 Product Brief : http://www.marvell.com/application-processors/pxa-family/assets/PXA310_PB_R4.pdf - PXA 320 Product Brief : http://www.marvell.com/application-processors/pxa-family/assets/PXA320_PB_R4.pdf - Design guide : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_Design_Guide.pdf - Developers manual : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_Developers_Manual.zip - Specifications : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_EMTS.pdf - Specification Update : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_Spec_Update.zip - Reference Manual : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_TavorP_BootROM_Ref_Manual.pdf - Application processor only - Core: ARMv5 XScale3 core - PXA930, PXA935 - Application processor with Communication processor - Core: ARMv5 XScale3 core - PXA955 - Application processor with Communication processor - Core: ARMv7 compatible Sheeva PJ4 core - - Comments: - - * This line of SoCs originates from the XScale family developed by - Intel and acquired by Marvell in ~2006. The PXA21x, PXA25x, - PXA26x, PXA27x, PXA3xx and PXA93x were developed by Intel, while - the later PXA95x were developed by Marvell. - - * Due to their XScale origin, these SoCs have virtually nothing in - common with the other (Kirkwood, Dove, etc.) families of Marvell - SoCs, except with the MMP/MMP2 family of SoCs. - - Linux kernel mach directory: arch/arm/mach-pxa - Linux kernel plat directory: arch/arm/plat-pxa - -MMP/MMP2/MMP3 family (communication processor) ------------------------------------------ - - Flavors: - PXA168, a.k.a Armada 168 - Homepage : http://www.marvell.com/application-processors/armada-100/armada-168.jsp - Product brief : http://www.marvell.com/application-processors/armada-100/assets/pxa_168_pb.pdf - Hardware manual : http://www.marvell.com/application-processors/armada-100/assets/armada_16x_datasheet.pdf - Software manual : http://www.marvell.com/application-processors/armada-100/assets/armada_16x_software_manual.pdf - Specification update : http://www.marvell.com/application-processors/armada-100/assets/ARMADA16x_Spec_update.pdf - Boot ROM manual : http://www.marvell.com/application-processors/armada-100/assets/armada_16x_ref_manual.pdf - App node package : http://www.marvell.com/application-processors/armada-100/assets/armada_16x_app_note_package.pdf - Application processor only - Core: ARMv5 compatible Marvell PJ1 88sv331 (Mohawk) - PXA910/PXA920 - Homepage : http://www.marvell.com/communication-processors/pxa910/ - Product Brief : http://www.marvell.com/communication-processors/pxa910/assets/Marvell_PXA910_Platform-001_PB_final.pdf - Application processor with Communication processor - Core: ARMv5 compatible Marvell PJ1 88sv331 (Mohawk) - PXA688, a.k.a. MMP2, a.k.a Armada 610 - Product Brief : http://www.marvell.com/application-processors/armada-600/assets/armada610_pb.pdf - Application processor only - Core: ARMv7 compatible Sheeva PJ4 88sv581x core - PXA2128, a.k.a. MMP3 (OLPC XO4, Linux support not upstream) - Product Brief : http://www.marvell.com/application-processors/armada/pxa2128/assets/Marvell-ARMADA-PXA2128-SoC-PB.pdf - Application processor only - Core: Dual-core ARMv7 compatible Sheeva PJ4C core - PXA960/PXA968/PXA978 (Linux support not upstream) - Application processor with Communication Processor - Core: ARMv7 compatible Sheeva PJ4 core - PXA986/PXA988 (Linux support not upstream) - Application processor with Communication Processor - Core: Dual-core ARMv7 compatible Sheeva PJ4B-MP core - PXA1088/PXA1920 (Linux support not upstream) - Application processor with Communication Processor - Core: quad-core ARMv7 Cortex-A7 - PXA1908/PXA1928/PXA1936 - Application processor with Communication Processor - Core: multi-core ARMv8 Cortex-A53 - - Comments: - - * This line of SoCs originates from the XScale family developed by - Intel and acquired by Marvell in ~2006. All the processors of - this MMP/MMP2 family were developed by Marvell. - - * Due to their XScale origin, these SoCs have virtually nothing in - common with the other (Kirkwood, Dove, etc.) families of Marvell - SoCs, except with the PXA family of SoCs listed above. - - Linux kernel mach directory: arch/arm/mach-mmp - Linux kernel plat directory: arch/arm/plat-pxa - -Berlin family (Multimedia Solutions) -------------------------------------- - - Flavors: - 88DE3010, Armada 1000 (no Linux support) - Core: Marvell PJ1 (ARMv5TE), Dual-core - Product Brief: http://www.marvell.com.cn/digital-entertainment/assets/armada_1000_pb.pdf - 88DE3005, Armada 1500 Mini - Design name: BG2CD - Core: ARM Cortex-A9, PL310 L2CC - 88DE3006, Armada 1500 Mini Plus - Design name: BG2CDP - Core: Dual Core ARM Cortex-A7 - 88DE3100, Armada 1500 - Design name: BG2 - Core: Marvell PJ4B-MP (ARMv7), Tauros3 L2CC - 88DE3114, Armada 1500 Pro - Design name: BG2Q - Core: Quad Core ARM Cortex-A9, PL310 L2CC - 88DE3214, Armada 1500 Pro 4K - Design name: BG3 - Core: ARM Cortex-A15, CA15 integrated L2CC - 88DE3218, ARMADA 1500 Ultra - Core: ARM Cortex-A53 - - Homepage: https://www.synaptics.com/products/multimedia-solutions - Directory: arch/arm/mach-berlin - - Comments: - - * This line of SoCs is based on Marvell Sheeva or ARM Cortex CPUs - with Synopsys DesignWare (IRQ, GPIO, Timers, ...) and PXA IP (SDHCI, USB, ETH, ...). - - * The Berlin family was acquired by Synaptics from Marvell in 2017. - -CPU Cores ---------- - -The XScale cores were designed by Intel, and shipped by Marvell in the older -PXA processors. Feroceon is a Marvell designed core that developed in-house, -and that evolved into Sheeva. The XScale and Feroceon cores were phased out -over time and replaced with Sheeva cores in later products, which subsequently -got replaced with licensed ARM Cortex-A cores. - - XScale 1 - CPUID 0x69052xxx - ARMv5, iWMMXt - XScale 2 - CPUID 0x69054xxx - ARMv5, iWMMXt - XScale 3 - CPUID 0x69056xxx or 0x69056xxx - ARMv5, iWMMXt - Feroceon-1850 88fr331 "Mohawk" - CPUID 0x5615331x or 0x41xx926x - ARMv5TE, single issue - Feroceon-2850 88fr531-vd "Jolteon" - CPUID 0x5605531x or 0x41xx926x - ARMv5TE, VFP, dual-issue - Feroceon 88fr571-vd "Jolteon" - CPUID 0x5615571x - ARMv5TE, VFP, dual-issue - Feroceon 88fr131 "Mohawk-D" - CPUID 0x5625131x - ARMv5TE, single-issue in-order - Sheeva PJ1 88sv331 "Mohawk" - CPUID 0x561584xx - ARMv5, single-issue iWMMXt v2 - Sheeva PJ4 88sv581x "Flareon" - CPUID 0x560f581x - ARMv7, idivt, optional iWMMXt v2 - Sheeva PJ4B 88sv581x - CPUID 0x561f581x - ARMv7, idivt, optional iWMMXt v2 - Sheeva PJ4B-MP / PJ4C - CPUID 0x562f584x - ARMv7, idivt/idiva, LPAE, optional iWMMXt v2 and/or NEON - -Long-term plans ---------------- - - * Unify the mach-dove/, mach-mv78xx0/, mach-orion5x/ into the - mach-mvebu/ to support all SoCs from the Marvell EBU (Engineering - Business Unit) in a single mach- directory. The plat-orion/ - would therefore disappear. - - * Unify the mach-mmp/ and mach-pxa/ into the same mach-pxa - directory. The plat-pxa/ would therefore disappear. - -Credits -------- - - Maen Suleiman - Lior Amsalem - Thomas Petazzoni - Andrew Lunn - Nicolas Pitre - Eric Miao diff --git a/Documentation/arm/Netwinder b/Documentation/arm/Netwinder deleted file mode 100644 index f1b457fbd3de..000000000000 --- a/Documentation/arm/Netwinder +++ /dev/null @@ -1,78 +0,0 @@ -NetWinder specific documentation -================================ - -The NetWinder is a small low-power computer, primarily designed -to run Linux. It is based around the StrongARM RISC processor, -DC21285 PCI bridge, with PC-type hardware glued around it. - -Port usage -========== - -Min - Max Description ---------------------------- -0x0000 - 0x000f DMA1 -0x0020 - 0x0021 PIC1 -0x0060 - 0x006f Keyboard -0x0070 - 0x007f RTC -0x0080 - 0x0087 DMA1 -0x0088 - 0x008f DMA2 -0x00a0 - 0x00a3 PIC2 -0x00c0 - 0x00df DMA2 -0x0180 - 0x0187 IRDA -0x01f0 - 0x01f6 ide0 -0x0201 Game port -0x0203 RWA010 configuration read -0x0220 - ? SoundBlaster -0x0250 - ? WaveArtist -0x0279 RWA010 configuration index -0x02f8 - 0x02ff Serial ttyS1 -0x0300 - 0x031f Ether10 -0x0338 GPIO1 -0x033a GPIO2 -0x0370 - 0x0371 W83977F configuration registers -0x0388 - ? AdLib -0x03c0 - 0x03df VGA -0x03f6 ide0 -0x03f8 - 0x03ff Serial ttyS0 -0x0400 - 0x0408 DC21143 -0x0480 - 0x0487 DMA1 -0x0488 - 0x048f DMA2 -0x0a79 RWA010 configuration write -0xe800 - 0xe80f ide0/ide1 BM DMA - - -Interrupt usage -=============== - -IRQ type Description ---------------------------- - 0 ISA 100Hz timer - 1 ISA Keyboard - 2 ISA cascade - 3 ISA Serial ttyS1 - 4 ISA Serial ttyS0 - 5 ISA PS/2 mouse - 6 ISA IRDA - 7 ISA Printer - 8 ISA RTC alarm - 9 ISA -10 ISA GP10 (Orange reset button) -11 ISA -12 ISA WaveArtist -13 ISA -14 ISA hda1 -15 ISA - -DMA usage -========= - -DMA type Description ---------------------------- - 0 ISA IRDA - 1 ISA - 2 ISA cascade - 3 ISA WaveArtist - 4 ISA - 5 ISA - 6 ISA - 7 ISA WaveArtist diff --git a/Documentation/arm/SA1100/FreeBird b/Documentation/arm/SA1100/FreeBird deleted file mode 100644 index ab9193663b2b..000000000000 --- a/Documentation/arm/SA1100/FreeBird +++ /dev/null @@ -1,21 +0,0 @@ -Freebird-1.1 is produced by Legend(C), Inc. -http://web.archive.org/web/*/http://www.legend.com.cn -and software/linux maintained by Coventive(C), Inc. -(http://www.coventive.com) - -Based on the Nicolas's strongarm kernel tree. - -=============================================================== -Maintainer: - -Chester Kuo - - -Author : -Tim wu -CIH -Eric Peng -Jeff Lee -Allen Cheng -Tony Liu - diff --git a/Documentation/arm/SA1100/empeg b/Documentation/arm/SA1100/empeg deleted file mode 100644 index 4ece4849a42c..000000000000 --- a/Documentation/arm/SA1100/empeg +++ /dev/null @@ -1,2 +0,0 @@ -See ../empeg/README - diff --git a/Documentation/arm/SA1100/serial_UART b/Documentation/arm/SA1100/serial_UART deleted file mode 100644 index a63966f1d083..000000000000 --- a/Documentation/arm/SA1100/serial_UART +++ /dev/null @@ -1,47 +0,0 @@ -The SA1100 serial port had its major/minor numbers officially assigned: - -> Date: Sun, 24 Sep 2000 21:40:27 -0700 -> From: H. Peter Anvin -> To: Nicolas Pitre -> Cc: Device List Maintainer -> Subject: Re: device -> -> Okay. Note that device numbers 204 and 205 are used for "low density -> serial devices", so you will have a range of minors on those majors (the -> tty device layer handles this just fine, so you don't have to worry about -> doing anything special.) -> -> So your assignments are: -> -> 204 char Low-density serial ports -> 5 = /dev/ttySA0 SA1100 builtin serial port 0 -> 6 = /dev/ttySA1 SA1100 builtin serial port 1 -> 7 = /dev/ttySA2 SA1100 builtin serial port 2 -> -> 205 char Low-density serial ports (alternate device) -> 5 = /dev/cusa0 Callout device for ttySA0 -> 6 = /dev/cusa1 Callout device for ttySA1 -> 7 = /dev/cusa2 Callout device for ttySA2 -> - -You must create those inodes in /dev on the root filesystem used -by your SA1100-based device: - - mknod ttySA0 c 204 5 - mknod ttySA1 c 204 6 - mknod ttySA2 c 204 7 - mknod cusa0 c 205 5 - mknod cusa1 c 205 6 - mknod cusa2 c 205 7 - -In addition to the creation of the appropriate device nodes above, you -must ensure your user space applications make use of the correct device -name. The classic example is the content of the /etc/inittab file where -you might have a getty process started on ttyS0. In this case: - -- replace occurrences of ttyS0 with ttySA0, ttyS1 with ttySA1, etc. - -- don't forget to add 'ttySA0', 'console', or the appropriate tty name - in /etc/securetty for root to be allowed to login as well. - - diff --git a/Documentation/arm/README b/Documentation/arm/arm.rst similarity index 88% rename from Documentation/arm/README rename to Documentation/arm/arm.rst index 9d1e5b2c92e6..2edc509df92a 100644 --- a/Documentation/arm/README +++ b/Documentation/arm/arm.rst @@ -1,5 +1,6 @@ - ARM Linux 2.6 - ============= +======================= +ARM Linux 2.6 and upper +======================= Please check for updates. @@ -18,22 +19,28 @@ Compilation of kernel line as detailed below. If you wish to cross-compile, then alter the following lines in the top - level make file: + level make file:: ARCH = - with + + with:: + ARCH = arm - and + and:: CROSS_COMPILE= - to + + to:: + CROSS_COMPILE= - eg. + + eg.:: + CROSS_COMPILE=arm-linux- - Do a 'make config', followed by 'make Image' to build the kernel - (arch/arm/boot/Image). A compressed image can be built by doing a + Do a 'make config', followed by 'make Image' to build the kernel + (arch/arm/boot/Image). A compressed image can be built by doing a 'make zImage' instead of 'make Image'. @@ -46,7 +53,7 @@ Bug reports etc Bug reports should be sent to linux-arm-kernel@lists.arm.linux.org.uk, or submitted through the web form at - http://www.arm.linux.org.uk/developer/ + http://www.arm.linux.org.uk/developer/ When sending bug reports, please ensure that they contain all relevant information, eg. the kernel messages that were printed before/during @@ -60,11 +67,13 @@ Include files which are there to reduce the clutter in the top-level directory. These directories, and their purpose is listed below: - arch-* machine/platform specific header files - hardware driver-internal ARM specific data structures/definitions - mach descriptions of generic ARM to specific machine interfaces - proc-* processor dependent header files (currently only two + ============= ========================================================== + `arch-*` machine/platform specific header files + `hardware` driver-internal ARM specific data structures/definitions + `mach` descriptions of generic ARM to specific machine interfaces + `proc-*` processor dependent header files (currently only two categories) + ============= ========================================================== Machine/Platform support @@ -129,7 +138,7 @@ ST506 hard drives HDC base to the source. As of 31/3/96 it works with two drives (you should get the ADFS - *configure harddrive set to 2). I've got an internal 20MB and a great + `*configure` harddrive set to 2). I've got an internal 20MB and a great big external 5.25" FH 64MB drive (who could ever want more :-) ). I've just got 240K/s off it (a dd with bs=128k); thats about half of what @@ -149,13 +158,13 @@ ST506 hard drives are welcome. -CONFIG_MACH_ and CONFIG_ARCH_ ------------------------------ +`CONFIG_MACH_` and `CONFIG_ARCH_` +--------------------------------- A change was made in 2003 to the macro names for new machines. - Historically, CONFIG_ARCH_ was used for the bonafide architecture, + Historically, `CONFIG_ARCH_` was used for the bonafide architecture, e.g. SA1100, as well as implementations of the architecture, e.g. Assabet. It was decided to change the implementation macros - to read CONFIG_MACH_ for clarity. Moreover, a retroactive fixup has + to read `CONFIG_MACH_` for clarity. Moreover, a retroactive fixup has not been made because it would complicate patching. Previous registrations may be found online. @@ -163,7 +172,7 @@ CONFIG_MACH_ and CONFIG_ARCH_ Kernel entry (head.S) --------------------------- +--------------------- The initial entry into the kernel is via head.S, which uses machine independent code. The machine is selected by the value of 'r1' on entry, which must be kept unique. @@ -201,4 +210,5 @@ Kernel entry (head.S) platform is DT-only, you do not need a registered machine type. --- + Russell King (15/03/2004) diff --git a/Documentation/arm/Booting b/Documentation/arm/booting.rst similarity index 89% rename from Documentation/arm/Booting rename to Documentation/arm/booting.rst index f1f965ce93d6..4babb6c6ae1e 100644 --- a/Documentation/arm/Booting +++ b/Documentation/arm/booting.rst @@ -1,7 +1,9 @@ - Booting ARM Linux - ================= +================= +Booting ARM Linux +================= Author: Russell King + Date : 18 May 2002 The following documentation is relevant to 2.4.18-rmk6 and beyond. @@ -25,8 +27,10 @@ following: 1. Setup and initialise RAM --------------------------- -Existing boot loaders: MANDATORY -New boot loaders: MANDATORY +Existing boot loaders: + MANDATORY +New boot loaders: + MANDATORY The boot loader is expected to find and initialise all RAM that the kernel will use for volatile data storage in the system. It performs @@ -39,8 +43,10 @@ sees fit.) 2. Initialise one serial port ----------------------------- -Existing boot loaders: OPTIONAL, RECOMMENDED -New boot loaders: OPTIONAL, RECOMMENDED +Existing boot loaders: + OPTIONAL, RECOMMENDED +New boot loaders: + OPTIONAL, RECOMMENDED The boot loader should initialise and enable one serial port on the target. This allows the kernel serial driver to automatically detect @@ -57,8 +63,10 @@ serial format options as described in 3. Detect the machine type -------------------------- -Existing boot loaders: OPTIONAL -New boot loaders: MANDATORY except for DT-only platforms +Existing boot loaders: + OPTIONAL +New boot loaders: + MANDATORY except for DT-only platforms The boot loader should detect the machine type its running on by some method. Whether this is a hard coded value or some algorithm that @@ -74,8 +82,10 @@ necessary, but assures that it will not match any existing types. 4. Setup boot data ------------------ -Existing boot loaders: OPTIONAL, HIGHLY RECOMMENDED -New boot loaders: MANDATORY +Existing boot loaders: + OPTIONAL, HIGHLY RECOMMENDED +New boot loaders: + MANDATORY The boot loader must provide either a tagged list or a dtb image for passing configuration data to the kernel. The physical address of the @@ -97,15 +107,15 @@ entirety; some tags behave as the former, others the latter. The boot loader must pass at a minimum the size and location of the system memory, and root filesystem location. Therefore, the -minimum tagged list should look: +minimum tagged list should look:: - +-----------+ -base -> | ATAG_CORE | | - +-----------+ | - | ATAG_MEM | | increasing address - +-----------+ | - | ATAG_NONE | | - +-----------+ v + +-----------+ + base -> | ATAG_CORE | | + +-----------+ | + | ATAG_MEM | | increasing address + +-----------+ | + | ATAG_NONE | | + +-----------+ v The tagged list should be stored in system RAM. @@ -134,8 +144,10 @@ A safe location is just above the 128MiB boundary from start of RAM. 5. Load initramfs. ------------------ -Existing boot loaders: OPTIONAL -New boot loaders: OPTIONAL +Existing boot loaders: + OPTIONAL +New boot loaders: + OPTIONAL If an initramfs is in use then, as with the dtb, it must be placed in a region of memory where the kernel decompressor will not overwrite it @@ -149,8 +161,10 @@ recommended above. 6. Calling the kernel image --------------------------- -Existing boot loaders: MANDATORY -New boot loaders: MANDATORY +Existing boot loaders: + MANDATORY +New boot loaders: + MANDATORY There are two options for calling the kernel zImage. If the zImage is stored in flash, and is linked correctly to be run from flash, @@ -174,12 +188,14 @@ In any case, the following conditions must be met: you many hours of debug. - CPU register settings - r0 = 0, - r1 = machine type number discovered in (3) above. - r2 = physical address of tagged list in system RAM, or - physical address of device tree block (dtb) in system RAM + + - r0 = 0, + - r1 = machine type number discovered in (3) above. + - r2 = physical address of tagged list in system RAM, or + physical address of device tree block (dtb) in system RAM - CPU mode + All forms of interrupts must be disabled (IRQs and FIQs) For CPUs which do not include the ARM virtualization extensions, the @@ -195,8 +211,11 @@ In any case, the following conditions must be met: entered in SVC mode. - Caches, MMUs + The MMU must be off. + Instruction cache may be on or off. + Data cache must be off. If the kernel is entered in HYP mode, the above requirements apply to diff --git a/Documentation/arm/cluster-pm-race-avoidance.txt b/Documentation/arm/cluster-pm-race-avoidance.rst similarity index 84% rename from Documentation/arm/cluster-pm-race-avoidance.txt rename to Documentation/arm/cluster-pm-race-avoidance.rst index 750b6fc24af9..aa58603d3f28 100644 --- a/Documentation/arm/cluster-pm-race-avoidance.txt +++ b/Documentation/arm/cluster-pm-race-avoidance.rst @@ -1,3 +1,4 @@ +========================================================= Cluster-wide Power-up/power-down race avoidance algorithm ========================================================= @@ -46,10 +47,12 @@ Basic model Each cluster and CPU is assigned a state, as follows: - DOWN - COMING_UP - UP - GOING_DOWN + - DOWN + - COMING_UP + - UP + - GOING_DOWN + +:: +---------> UP ----------+ | v @@ -60,18 +63,22 @@ Each cluster and CPU is assigned a state, as follows: +--------- DOWN <--------+ -DOWN: The CPU or cluster is not coherent, and is either powered off or +DOWN: + The CPU or cluster is not coherent, and is either powered off or suspended, or is ready to be powered off or suspended. -COMING_UP: The CPU or cluster has committed to moving to the UP state. +COMING_UP: + The CPU or cluster has committed to moving to the UP state. It may be part way through the process of initialisation and enabling coherency. -UP: The CPU or cluster is active and coherent at the hardware +UP: + The CPU or cluster is active and coherent at the hardware level. A CPU in this state is not necessarily being used actively by the kernel. -GOING_DOWN: The CPU or cluster has committed to moving to the DOWN +GOING_DOWN: + The CPU or cluster has committed to moving to the DOWN state. It may be part way through the process of teardown and coherency exit. @@ -86,8 +93,8 @@ CPUs in the cluster simultaneously modifying the state. The cluster- level states are described in the "Cluster state" section. To help distinguish the CPU states from cluster states in this -discussion, the state names are given a CPU_ prefix for the CPU states, -and a CLUSTER_ or INBOUND_ prefix for the cluster states. +discussion, the state names are given a `CPU_` prefix for the CPU states, +and a `CLUSTER_` or `INBOUND_` prefix for the cluster states. CPU state @@ -101,10 +108,12 @@ This means that CPUs fit the basic model closely. The algorithm defines the following states for each CPU in the system: - CPU_DOWN - CPU_COMING_UP - CPU_UP - CPU_GOING_DOWN + - CPU_DOWN + - CPU_COMING_UP + - CPU_UP + - CPU_GOING_DOWN + +:: cluster setup and CPU setup complete policy decision @@ -130,17 +139,17 @@ requirement for any external event to happen. CPU_DOWN: - A CPU reaches the CPU_DOWN state when it is ready for power-down. On reaching this state, the CPU will typically power itself down or suspend itself, via a WFI instruction or a firmware call. - Next state: CPU_COMING_UP - Conditions: none + Next state: + CPU_COMING_UP + Conditions: + none Trigger events: - a) an explicit hardware power-up operation, resulting from a policy decision on another CPU; @@ -148,15 +157,17 @@ CPU_DOWN: CPU_COMING_UP: - A CPU cannot start participating in hardware coherency until the cluster is set up and coherent. If the cluster is not ready, then the CPU will wait in the CPU_COMING_UP state until the cluster has been set up. - Next state: CPU_UP - Conditions: The CPU's parent cluster must be in CLUSTER_UP. - Trigger events: Transition of the parent cluster to CLUSTER_UP. + Next state: + CPU_UP + Conditions: + The CPU's parent cluster must be in CLUSTER_UP. + Trigger events: + Transition of the parent cluster to CLUSTER_UP. Refer to the "Cluster state" section for a description of the CLUSTER_UP state. @@ -178,20 +189,25 @@ CPU_UP: The CPU remains in this state until an explicit policy decision is made to shut down or suspend the CPU. - Next state: CPU_GOING_DOWN - Conditions: none - Trigger events: explicit policy decision + Next state: + CPU_GOING_DOWN + Conditions: + none + Trigger events: + explicit policy decision CPU_GOING_DOWN: - While in this state, the CPU exits coherency, including any operations required to achieve this (such as cleaning data caches). - Next state: CPU_DOWN - Conditions: local CPU teardown complete - Trigger events: (spontaneous) + Next state: + CPU_DOWN + Conditions: + local CPU teardown complete + Trigger events: + (spontaneous) Cluster state @@ -212,20 +228,20 @@ independently of the CPU which is tearing down the cluster. For this reason, the cluster state is split into two parts: "cluster" state: The global state of the cluster; or the state - on the outbound side: + on the outbound side: - CLUSTER_DOWN - CLUSTER_UP - CLUSTER_GOING_DOWN + - CLUSTER_DOWN + - CLUSTER_UP + - CLUSTER_GOING_DOWN "inbound" state: The state of the cluster on the inbound side. - INBOUND_NOT_COMING_UP - INBOUND_COMING_UP + - INBOUND_NOT_COMING_UP + - INBOUND_COMING_UP The different pairings of these states results in six possible - states for the cluster as a whole: + states for the cluster as a whole:: CLUSTER_UP +==========> INBOUND_NOT_COMING_UP -------------+ @@ -284,11 +300,12 @@ reason, the cluster state is split into two parts: CLUSTER_DOWN/INBOUND_NOT_COMING_UP: + Next state: + CLUSTER_DOWN/INBOUND_COMING_UP (inbound) + Conditions: + none - Next state: CLUSTER_DOWN/INBOUND_COMING_UP (inbound) - Conditions: none Trigger events: - a) an explicit hardware power-up operation, resulting from a policy decision on another CPU; @@ -306,9 +323,12 @@ CLUSTER_DOWN/INBOUND_COMING_UP: setup to enable other CPUs in the cluster to enter coherency safely. - Next state: CLUSTER_UP/INBOUND_COMING_UP (inbound) - Conditions: cluster-level setup and hardware coherency complete - Trigger events: (spontaneous) + Next state: + CLUSTER_UP/INBOUND_COMING_UP (inbound) + Conditions: + cluster-level setup and hardware coherency complete + Trigger events: + (spontaneous) CLUSTER_UP/INBOUND_COMING_UP: @@ -321,9 +341,12 @@ CLUSTER_UP/INBOUND_COMING_UP: CLUSTER_UP/INBOUND_NOT_COMING_UP. All other CPUs on the cluster should consider treat these two states as equivalent. - Next state: CLUSTER_UP/INBOUND_NOT_COMING_UP (inbound) - Conditions: none - Trigger events: (spontaneous) + Next state: + CLUSTER_UP/INBOUND_NOT_COMING_UP (inbound) + Conditions: + none + Trigger events: + (spontaneous) CLUSTER_UP/INBOUND_NOT_COMING_UP: @@ -335,9 +358,12 @@ CLUSTER_UP/INBOUND_NOT_COMING_UP: The cluster will remain in this state until a policy decision is made to power the cluster down. - Next state: CLUSTER_GOING_DOWN/INBOUND_NOT_COMING_UP (outbound) - Conditions: none - Trigger events: policy decision to power down the cluster + Next state: + CLUSTER_GOING_DOWN/INBOUND_NOT_COMING_UP (outbound) + Conditions: + none + Trigger events: + policy decision to power down the cluster CLUSTER_GOING_DOWN/INBOUND_NOT_COMING_UP: @@ -359,13 +385,16 @@ CLUSTER_GOING_DOWN/INBOUND_NOT_COMING_UP: Next states: CLUSTER_DOWN/INBOUND_NOT_COMING_UP (outbound) - Conditions: cluster torn down and ready to power off - Trigger events: (spontaneous) + Conditions: + cluster torn down and ready to power off + Trigger events: + (spontaneous) CLUSTER_GOING_DOWN/INBOUND_COMING_UP (inbound) - Conditions: none - Trigger events: + Conditions: + none + Trigger events: a) an explicit hardware power-up operation, resulting from a policy decision on another CPU; @@ -396,13 +425,19 @@ CLUSTER_GOING_DOWN/INBOUND_COMING_UP: Next states: CLUSTER_UP/INBOUND_COMING_UP (outbound) - Conditions: cluster-level setup and hardware + Conditions: + cluster-level setup and hardware coherency complete - Trigger events: (spontaneous) + + Trigger events: + (spontaneous) CLUSTER_DOWN/INBOUND_COMING_UP (outbound) - Conditions: cluster torn down and ready to power off - Trigger events: (spontaneous) + Conditions: + cluster torn down and ready to power off + + Trigger events: + (spontaneous) Last man and First man selection @@ -452,30 +487,30 @@ Implementation: arch/arm/common/mcpm_entry.c (everything else): __mcpm_cpu_going_down() signals the transition of a CPU to the - CPU_GOING_DOWN state. + CPU_GOING_DOWN state. __mcpm_cpu_down() signals the transition of a CPU to the CPU_DOWN - state. + state. A CPU transitions to CPU_COMING_UP and then to CPU_UP via the - low-level power-up code in mcpm_head.S. This could - involve CPU-specific setup code, but in the current - implementation it does not. + low-level power-up code in mcpm_head.S. This could + involve CPU-specific setup code, but in the current + implementation it does not. __mcpm_outbound_enter_critical() and __mcpm_outbound_leave_critical() - handle transitions from CLUSTER_UP to CLUSTER_GOING_DOWN - and from there to CLUSTER_DOWN or back to CLUSTER_UP (in - the case of an aborted cluster power-down). + handle transitions from CLUSTER_UP to CLUSTER_GOING_DOWN + and from there to CLUSTER_DOWN or back to CLUSTER_UP (in + the case of an aborted cluster power-down). - These functions are more complex than the __mcpm_cpu_*() - functions due to the extra inter-CPU coordination which - is needed for safe transitions at the cluster level. + These functions are more complex than the __mcpm_cpu_*() + functions due to the extra inter-CPU coordination which + is needed for safe transitions at the cluster level. A cluster transitions from CLUSTER_DOWN back to CLUSTER_UP via - the low-level power-up code in mcpm_head.S. This - typically involves platform-specific setup code, - provided by the platform-specific power_up_setup - function registered via mcpm_sync_init. + the low-level power-up code in mcpm_head.S. This + typically involves platform-specific setup code, + provided by the platform-specific power_up_setup + function registered via mcpm_sync_init. Deep topologies: diff --git a/Documentation/arm/firmware.txt b/Documentation/arm/firmware.rst similarity index 86% rename from Documentation/arm/firmware.txt rename to Documentation/arm/firmware.rst index 7f175dbb427e..efd844baec1d 100644 --- a/Documentation/arm/firmware.txt +++ b/Documentation/arm/firmware.rst @@ -1,5 +1,7 @@ -Interface for registering and calling firmware-specific operations for ARM. ----- +========================================================================== +Interface for registering and calling firmware-specific operations for ARM +========================================================================== + Written by Tomasz Figa Some boards are running with secure firmware running in TrustZone secure @@ -9,7 +11,7 @@ operations and call them when needed. Firmware operations can be specified by filling in a struct firmware_ops with appropriate callbacks and then registering it with register_firmware_ops() -function. +function:: void register_firmware_ops(const struct firmware_ops *ops) @@ -19,7 +21,7 @@ and its members can be found in arch/arm/include/asm/firmware.h header. There is a default, empty set of operations provided, so there is no need to set anything if platform does not require firmware operations. -To call a firmware operation, a helper macro is provided +To call a firmware operation, a helper macro is provided:: #define call_firmware_op(op, ...) \ ((firmware_ops->op) ? firmware_ops->op(__VA_ARGS__) : (-ENOSYS)) @@ -28,7 +30,7 @@ the macro checks if the operation is provided and calls it or otherwise returns -ENOSYS to signal that given operation is not available (for example, to allow fallback to legacy operation). -Example of registering firmware operations: +Example of registering firmware operations:: /* board file */ @@ -56,7 +58,7 @@ Example of registering firmware operations: register_firmware_ops(&platformX_firmware_ops); } -Example of using a firmware operation: +Example of using a firmware operation:: /* some platform code, e.g. SMP initialization */ diff --git a/Documentation/arm/index.rst b/Documentation/arm/index.rst new file mode 100644 index 000000000000..bd316d1a1802 --- /dev/null +++ b/Documentation/arm/index.rst @@ -0,0 +1,80 @@ +:orphan: + +================ +ARM Architecture +================ + +.. toctree:: + :maxdepth: 1 + + arm + booting + cluster-pm-race-avoidance + firmware + interrupts + kernel_mode_neon + kernel_user_helpers + memory + mem_alignment + tcm + setup + swp_emulation + uefi + vlocks + porting + +SoC-specific documents +====================== + +.. toctree:: + :maxdepth: 1 + + ixp4xx + + marvel + microchip + + netwinder + nwfpe/index + + keystone/overview + keystone/knav-qmss + + omap/index + + pxa/mfp + + + sa1100/index + + stm32/stm32f746-overview + stm32/overview + stm32/stm32h743-overview + stm32/stm32f769-overview + stm32/stm32f429-overview + stm32/stm32mp157-overview + + sunxi + + samsung/index + samsung-s3c24xx/index + + sunxi/clocks + + spear/overview + + sti/stih416-overview + sti/stih407-overview + sti/stih418-overview + sti/overview + sti/stih415-overview + + vfp/release-notes + + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/arm/Interrupts b/Documentation/arm/interrupts.rst similarity index 81% rename from Documentation/arm/Interrupts rename to Documentation/arm/interrupts.rst index f09ab1b90ef1..2ae70e0e9732 100644 --- a/Documentation/arm/Interrupts +++ b/Documentation/arm/interrupts.rst @@ -1,8 +1,10 @@ -2.5.2-rmk5 ----------- +========== +Interrupts +========== -This is the first kernel that contains a major shake up of some of the -major architecture-specific subsystems. +2.5.2-rmk5: + This is the first kernel that contains a major shake up of some of the + major architecture-specific subsystems. Firstly, it contains some pretty major changes to the way we handle the MMU TLB. Each MMU TLB variant is now handled completely separately - @@ -18,7 +20,7 @@ Unfortunately, this means that machine types that touch the irq_desc[] array (basically all machine types) will break, and this means every machine type that we currently have. -Lets take an example. On the Assabet with Neponset, we have: +Lets take an example. On the Assabet with Neponset, we have:: GPIO25 IRR:2 SA1100 ------------> Neponset -----------> SA1111 @@ -48,42 +50,47 @@ the irqdesc array). This doesn't have to be a real "IC"; indeed the SA11x0 IRQs are handled by two separate "chip" structures, one for GPIO0-10, and another for all the rest. It is just a container for the various operations (maybe this'll change to a better name). -This structure has the following operations: +This structure has the following operations:: -struct irqchip { - /* - * Acknowledge the IRQ. - * If this is a level-based IRQ, then it is expected to mask the IRQ - * as well. - */ - void (*ack)(unsigned int irq); - /* - * Mask the IRQ in hardware. - */ - void (*mask)(unsigned int irq); - /* - * Unmask the IRQ in hardware. - */ - void (*unmask)(unsigned int irq); - /* - * Re-run the IRQ - */ - void (*rerun)(unsigned int irq); - /* - * Set the type of the IRQ. - */ - int (*type)(unsigned int irq, unsigned int, type); -}; + struct irqchip { + /* + * Acknowledge the IRQ. + * If this is a level-based IRQ, then it is expected to mask the IRQ + * as well. + */ + void (*ack)(unsigned int irq); + /* + * Mask the IRQ in hardware. + */ + void (*mask)(unsigned int irq); + /* + * Unmask the IRQ in hardware. + */ + void (*unmask)(unsigned int irq); + /* + * Re-run the IRQ + */ + void (*rerun)(unsigned int irq); + /* + * Set the type of the IRQ. + */ + int (*type)(unsigned int irq, unsigned int, type); + }; -ack - required. May be the same function as mask for IRQs +ack + - required. May be the same function as mask for IRQs handled by do_level_IRQ. -mask - required. -unmask - required. -rerun - optional. Not required if you're using do_level_IRQ for all +mask + - required. +unmask + - required. +rerun + - optional. Not required if you're using do_level_IRQ for all IRQs that use this 'irqchip'. Generally expected to re-trigger the hardware IRQ if possible. If not, may call the handler directly. -type - optional. If you don't support changing the type of an IRQ, +type + - optional. If you don't support changing the type of an IRQ, it should be null so people can detect if they are unable to set the IRQ type. @@ -109,6 +116,7 @@ manipulation, nor state tracking. This is useful for things like the SMC9196 and USAR above. So, what's changed? +=================== 1. Machine implementations must not write to the irqdesc array. @@ -118,24 +126,19 @@ So, what's changed? absolutely necessary. set_irq_chip(irq,chip) - Set the mask/unmask methods for handling this IRQ set_irq_handler(irq,handler) - Set the handler for this IRQ (level, edge, simple) set_irq_chained_handler(irq,handler) - Set a "chained" handler for this IRQ - automatically enables this IRQ (eg, Neponset and SA1111 handlers). set_irq_flags(irq,flags) - Set the valid/probe/noautoenable flags. set_irq_type(irq,type) - Set active the IRQ edge(s)/level. This replaces the SA1111 INTPOL manipulation, and the set_GPIO_IRQ_edge() function. Type should be one of IRQ_TYPE_xxx defined in @@ -158,10 +161,9 @@ So, what's changed? be re-checked for pending events. (see the Neponset IRQ handler for details). -7. fixup_irq() is gone, as is arch/arm/mach-*/include/mach/irq.h +7. fixup_irq() is gone, as is `arch/arm/mach-*/include/mach/irq.h` Please note that this will not solve all problems - some of them are hardware based. Mixing level-based and edge-based IRQs on the same parent signal (eg neponset) is one such area where a software based solution can't provide the full answer to low IRQ latency. - diff --git a/Documentation/arm/IXP4xx b/Documentation/arm/ixp4xx.rst similarity index 84% rename from Documentation/arm/IXP4xx rename to Documentation/arm/ixp4xx.rst index e48b74de6ac0..a57235616294 100644 --- a/Documentation/arm/IXP4xx +++ b/Documentation/arm/ixp4xx.rst @@ -1,6 +1,6 @@ - -------------------------------------------------------------------------- +=========================================================== Release Notes for Linux on Intel's IXP4xx Network Processor +=========================================================== Maintained by Deepak Saxena ------------------------------------------------------------------------- @@ -8,7 +8,7 @@ Maintained by Deepak Saxena 1. Overview Intel's IXP4xx network processor is a highly integrated SOC that -is targeted for network applications, though it has become popular +is targeted for network applications, though it has become popular in industrial control and other areas due to low cost and power consumption. The IXP4xx family currently consists of several processors that support different network offload functions such as encryption, @@ -20,7 +20,7 @@ For more information on the various versions of the CPU, see: http://developer.intel.com/design/network/products/npfamily/ixp4xx.htm -Intel also made the IXCP1100 CPU for sometime which is an IXP4xx +Intel also made the IXCP1100 CPU for sometime which is an IXP4xx stripped of much of the network intelligence. 2. Linux Support @@ -31,7 +31,7 @@ Linux currently supports the following features on the IXP4xx chips: - PCI interface - Flash access (MTD/JFFS) - I2C through GPIO on IXP42x -- GPIO for input/output/interrupts +- GPIO for input/output/interrupts See arch/arm/mach-ixp4xx/include/mach/platform.h for access functions. - Timers (watchdog, OS) @@ -45,7 +45,7 @@ require the use of Intel's proprietary CSR software: If you need to use any of the above, you need to download Intel's software from: - http://developer.intel.com/design/network/products/npfamily/ixp425.htm + http://developer.intel.com/design/network/products/npfamily/ixp425.htm DO NOT POST QUESTIONS TO THE LINUX MAILING LISTS REGARDING THE PROPRIETARY SOFTWARE. @@ -53,14 +53,14 @@ SOFTWARE. There are several websites that provide directions/pointers on using Intel's software: - http://sourceforge.net/projects/ixp4xx-osdg/ - Open Source Developer's Guide for using uClinux and the Intel libraries + - http://sourceforge.net/projects/ixp4xx-osdg/ + Open Source Developer's Guide for using uClinux and the Intel libraries -http://gatewaymaker.sourceforge.net/ - Simple one page summary of building a gateway using an IXP425 and Linux + - http://gatewaymaker.sourceforge.net/ + Simple one page summary of building a gateway using an IXP425 and Linux -http://ixp425.sourceforge.net/ - ATM device driver for IXP425 that relies on Intel's libraries + - http://ixp425.sourceforge.net/ + ATM device driver for IXP425 that relies on Intel's libraries 3. Known Issues/Limitations @@ -70,7 +70,7 @@ The IXP4xx family allows for up to 256MB of memory but the PCI interface can only expose 64MB of that memory to the PCI bus. This means that if you are running with > 64MB, all PCI buffers outside of the accessible range will be bounced using the routines in arch/arm/common/dmabounce.c. - + 3b. Limited outbound PCI window IXP4xx provides two methods of accessing PCI memory space: @@ -79,15 +79,15 @@ IXP4xx provides two methods of accessing PCI memory space: To access PCI via this space, we simply ioremap() the BAR into the kernel and we can use the standard read[bwl]/write[bwl] macros. This is the preffered method due to speed but it - limits the system to just 64MB of PCI memory. This can be + limits the system to just 64MB of PCI memory. This can be problamatic if using video cards and other memory-heavy devices. - -2) If > 64MB of memory space is required, the IXP4xx can be - configured to use indirect registers to access PCI This allows - for up to 128MB (0x48000000 to 0x4fffffff) of memory on the bus. - The disadvantage of this is that every PCI access requires - three local register accesses plus a spinlock, but in some - cases the performance hit is acceptable. In addition, you cannot + +2) If > 64MB of memory space is required, the IXP4xx can be + configured to use indirect registers to access PCI This allows + for up to 128MB (0x48000000 to 0x4fffffff) of memory on the bus. + The disadvantage of this is that every PCI access requires + three local register accesses plus a spinlock, but in some + cases the performance hit is acceptable. In addition, you cannot mmap() PCI devices in this case due to the indirect nature of the PCI window. @@ -96,14 +96,14 @@ you need more PCI memory, enable the IXP4XX_INDIRECT_PCI config option. 3c. GPIO as Interrupts -Currently the code only handles level-sensitive GPIO interrupts +Currently the code only handles level-sensitive GPIO interrupts 4. Supported platforms ADI Engineering Coyote Gateway Reference Platform http://www.adiengineering.com/productsCoyote.html - The ADI Coyote platform is reference design for those building + The ADI Coyote platform is reference design for those building small residential/office gateways. One NPE is connected to a 10/100 interface, one to 4-port 10/100 switch, and the third to and ADSL interface. In addition, it also supports to POTs interfaces connected @@ -119,9 +119,9 @@ http://www.gateworks.com/support/overview.php the expansion bus. Intel IXDP425 Development Platform -http://www.intel.com/design/network/products/npfamily/ixdpg425.htm +http://www.intel.com/design/network/products/npfamily/ixdpg425.htm - This is Intel's standard reference platform for the IXDP425 and is + This is Intel's standard reference platform for the IXDP425 and is also known as the Richfield board. It contains 4 PCI slots, 16MB of flash, two 10/100 ports and one ADSL port. @@ -161,11 +161,12 @@ The IXP4xx work has been funded by Intel Corp. and MontaVista Software, Inc. The following people have contributed patches/comments/etc: -Lennerty Buytenhek -Lutz Jaenicke -Justin Mayfield -Robert E. Ranslam -[I know I've forgotten others, please email me to be added] +- Lennerty Buytenhek +- Lutz Jaenicke +- Justin Mayfield +- Robert E. Ranslam + +[I know I've forgotten others, please email me to be added] ------------------------------------------------------------------------- diff --git a/Documentation/arm/kernel_mode_neon.txt b/Documentation/arm/kernel_mode_neon.rst similarity index 99% rename from Documentation/arm/kernel_mode_neon.txt rename to Documentation/arm/kernel_mode_neon.rst index b9e060c5b61e..9bfb71a2a9b9 100644 --- a/Documentation/arm/kernel_mode_neon.txt +++ b/Documentation/arm/kernel_mode_neon.rst @@ -1,3 +1,4 @@ +================ Kernel mode NEON ================ @@ -86,6 +87,7 @@ instructions appearing in unexpected places if no special care is taken. Therefore, the recommended and only supported way of using NEON/VFP in the kernel is by adhering to the following rules: + * isolate the NEON code in a separate compilation unit and compile it with '-march=armv7-a -mfpu=neon -mfloat-abi=softfp'; * issue the calls to kernel_neon_begin(), kernel_neon_end() as well as the calls @@ -115,6 +117,7 @@ NEON intrinsics NEON intrinsics are also supported. However, as code using NEON intrinsics relies on the GCC header , (which #includes ), you should observe the following in addition to the rules above: + * Compile the unit containing the NEON intrinsics with '-ffreestanding' so GCC uses its builtin version of (this is a C99 header which the kernel does not supply); diff --git a/Documentation/arm/kernel_user_helpers.txt b/Documentation/arm/kernel_user_helpers.rst similarity index 78% rename from Documentation/arm/kernel_user_helpers.txt rename to Documentation/arm/kernel_user_helpers.rst index 5673594717cf..eb6f3d916622 100644 --- a/Documentation/arm/kernel_user_helpers.txt +++ b/Documentation/arm/kernel_user_helpers.rst @@ -1,3 +1,4 @@ +============================ Kernel-provided User Helpers ============================ @@ -43,7 +44,7 @@ kuser_helper_version Location: 0xffff0ffc -Reference declaration: +Reference declaration:: extern int32_t __kuser_helper_version; @@ -53,17 +54,17 @@ Definition: running kernel. User space may read this to determine the availability of a particular helper. -Usage example: +Usage example:: -#define __kuser_helper_version (*(int32_t *)0xffff0ffc) + #define __kuser_helper_version (*(int32_t *)0xffff0ffc) -void check_kuser_version(void) -{ + void check_kuser_version(void) + { if (__kuser_helper_version < 2) { fprintf(stderr, "can't do atomic operations, kernel too old\n"); abort(); } -} + } Notes: @@ -77,7 +78,7 @@ kuser_get_tls Location: 0xffff0fe0 -Reference prototype: +Reference prototype:: void * __kuser_get_tls(void); @@ -97,16 +98,16 @@ Definition: Get the TLS value as previously set via the __ARM_NR_set_tls syscall. -Usage example: +Usage example:: -typedef void * (__kuser_get_tls_t)(void); -#define __kuser_get_tls (*(__kuser_get_tls_t *)0xffff0fe0) + typedef void * (__kuser_get_tls_t)(void); + #define __kuser_get_tls (*(__kuser_get_tls_t *)0xffff0fe0) -void foo() -{ + void foo() + { void *tls = __kuser_get_tls(); printf("TLS = %p\n", tls); -} + } Notes: @@ -117,7 +118,7 @@ kuser_cmpxchg Location: 0xffff0fc0 -Reference prototype: +Reference prototype:: int __kuser_cmpxchg(int32_t oldval, int32_t newval, volatile int32_t *ptr); @@ -139,18 +140,18 @@ Clobbered registers: Definition: - Atomically store newval in *ptr only if *ptr is equal to oldval. - Return zero if *ptr was changed or non-zero if no exchange happened. - The C flag is also set if *ptr was changed to allow for assembly + Atomically store newval in `*ptr` only if `*ptr` is equal to oldval. + Return zero if `*ptr` was changed or non-zero if no exchange happened. + The C flag is also set if `*ptr` was changed to allow for assembly optimization in the calling code. -Usage example: +Usage example:: -typedef int (__kuser_cmpxchg_t)(int oldval, int newval, volatile int *ptr); -#define __kuser_cmpxchg (*(__kuser_cmpxchg_t *)0xffff0fc0) + typedef int (__kuser_cmpxchg_t)(int oldval, int newval, volatile int *ptr); + #define __kuser_cmpxchg (*(__kuser_cmpxchg_t *)0xffff0fc0) -int atomic_add(volatile int *ptr, int val) -{ + int atomic_add(volatile int *ptr, int val) + { int old, new; do { @@ -159,7 +160,7 @@ int atomic_add(volatile int *ptr, int val) } while(__kuser_cmpxchg(old, new, ptr)); return new; -} + } Notes: @@ -172,7 +173,7 @@ kuser_memory_barrier Location: 0xffff0fa0 -Reference prototype: +Reference prototype:: void __kuser_memory_barrier(void); @@ -193,10 +194,10 @@ Definition: Apply any needed memory barrier to preserve consistency with data modified manually and __kuser_cmpxchg usage. -Usage example: +Usage example:: -typedef void (__kuser_dmb_t)(void); -#define __kuser_dmb (*(__kuser_dmb_t *)0xffff0fa0) + typedef void (__kuser_dmb_t)(void); + #define __kuser_dmb (*(__kuser_dmb_t *)0xffff0fa0) Notes: @@ -207,7 +208,7 @@ kuser_cmpxchg64 Location: 0xffff0f60 -Reference prototype: +Reference prototype:: int __kuser_cmpxchg64(const int64_t *oldval, const int64_t *newval, @@ -231,22 +232,22 @@ Clobbered registers: Definition: - Atomically store the 64-bit value pointed by *newval in *ptr only if *ptr - is equal to the 64-bit value pointed by *oldval. Return zero if *ptr was + Atomically store the 64-bit value pointed by `*newval` in `*ptr` only if `*ptr` + is equal to the 64-bit value pointed by `*oldval`. Return zero if `*ptr` was changed or non-zero if no exchange happened. - The C flag is also set if *ptr was changed to allow for assembly + The C flag is also set if `*ptr` was changed to allow for assembly optimization in the calling code. -Usage example: +Usage example:: -typedef int (__kuser_cmpxchg64_t)(const int64_t *oldval, - const int64_t *newval, - volatile int64_t *ptr); -#define __kuser_cmpxchg64 (*(__kuser_cmpxchg64_t *)0xffff0f60) + typedef int (__kuser_cmpxchg64_t)(const int64_t *oldval, + const int64_t *newval, + volatile int64_t *ptr); + #define __kuser_cmpxchg64 (*(__kuser_cmpxchg64_t *)0xffff0f60) -int64_t atomic_add64(volatile int64_t *ptr, int64_t val) -{ + int64_t atomic_add64(volatile int64_t *ptr, int64_t val) + { int64_t old, new; do { @@ -255,7 +256,7 @@ int64_t atomic_add64(volatile int64_t *ptr, int64_t val) } while(__kuser_cmpxchg64(&old, &new, ptr)); return new; -} + } Notes: diff --git a/Documentation/arm/keystone/knav-qmss.txt b/Documentation/arm/keystone/knav-qmss.rst similarity index 92% rename from Documentation/arm/keystone/knav-qmss.txt rename to Documentation/arm/keystone/knav-qmss.rst index fcdb9fd5f53a..7f7638d80b42 100644 --- a/Documentation/arm/keystone/knav-qmss.txt +++ b/Documentation/arm/keystone/knav-qmss.rst @@ -1,4 +1,6 @@ -* Texas Instruments Keystone Navigator Queue Management SubSystem driver +====================================================================== +Texas Instruments Keystone Navigator Queue Management SubSystem driver +====================================================================== Driver source code path drivers/soc/ti/knav_qmss.c @@ -34,11 +36,13 @@ driver that interface with the accumulator PDSP. This configures accumulator channels defined in DTS (example in DT documentation) to monitor 1 or 32 queues per channel. More description on the firmware is available in CPPI/QMSS Low Level Driver document (docs/CPPI_QMSS_LLD_SDS.pdf) at + git://git.ti.com/keystone-rtos/qmss-lld.git k2_qmss_pdsp_acc48_k2_le_1_0_0_9.bin firmware supports upto 48 accumulator channels. This firmware is available under ti-keystone folder of firmware.git at + git://git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git To use copy the firmware image to lib/firmware folder of the initramfs or diff --git a/Documentation/arm/keystone/Overview.txt b/Documentation/arm/keystone/overview.rst similarity index 59% rename from Documentation/arm/keystone/Overview.txt rename to Documentation/arm/keystone/overview.rst index 400c0c270d2e..cd90298c493c 100644 --- a/Documentation/arm/keystone/Overview.txt +++ b/Documentation/arm/keystone/overview.rst @@ -1,5 +1,6 @@ - TI Keystone Linux Overview - -------------------------- +========================== +TI Keystone Linux Overview +========================== Introduction ------------ @@ -9,47 +10,65 @@ for users to run Linux on Keystone based EVMs from Texas Instruments. Following SoCs & EVMs are currently supported:- ------------- K2HK SoC and EVM -------------------------------------------------- +K2HK SoC and EVM +================= a.k.a Keystone 2 Hawking/Kepler SoC TCI6636K2H & TCI6636K2K: See documentation at + http://www.ti.com/product/tci6638k2k http://www.ti.com/product/tci6638k2h EVM: -http://www.advantech.com/Support/TI-EVM/EVMK2HX_sd.aspx + http://www.advantech.com/Support/TI-EVM/EVMK2HX_sd.aspx ------------- K2E SoC and EVM --------------------------------------------------- +K2E SoC and EVM +=============== a.k.a Keystone 2 Edison SoC -K2E - 66AK2E05: See documentation at + +K2E - 66AK2E05: + +See documentation at + http://www.ti.com/product/66AK2E05/technicaldocuments EVM: -https://www.einfochips.com/index.php/partnerships/texas-instruments/k2e-evm.html + https://www.einfochips.com/index.php/partnerships/texas-instruments/k2e-evm.html ------------- K2L SoC and EVM --------------------------------------------------- +K2L SoC and EVM +=============== a.k.a Keystone 2 Lamarr SoC -K2L - TCI6630K2L: See documentation at + +K2L - TCI6630K2L: + +See documentation at http://www.ti.com/product/TCI6630K2L/technicaldocuments + EVM: -https://www.einfochips.com/index.php/partnerships/texas-instruments/k2l-evm.html + https://www.einfochips.com/index.php/partnerships/texas-instruments/k2l-evm.html Configuration ------------- All of the K2 SoCs/EVMs share a common defconfig, keystone_defconfig and same image is used to boot on individual EVMs. The platform configuration is -specified through DTS. Following are the DTS used:- - K2HK EVM : k2hk-evm.dts - K2E EVM : k2e-evm.dts - K2L EVM : k2l-evm.dts +specified through DTS. Following are the DTS used: + + K2HK EVM: + k2hk-evm.dts + K2E EVM: + k2e-evm.dts + K2L EVM: + k2l-evm.dts The device tree documentation for the keystone machines are located at + Documentation/devicetree/bindings/arm/keystone/keystone.txt Document Author --------------- Murali Karicheri + Copyright 2015 Texas Instruments diff --git a/Documentation/arm/marvel.rst b/Documentation/arm/marvel.rst new file mode 100644 index 000000000000..16ab2eb085b8 --- /dev/null +++ b/Documentation/arm/marvel.rst @@ -0,0 +1,488 @@ +================ +ARM Marvell SoCs +================ + +This document lists all the ARM Marvell SoCs that are currently +supported in mainline by the Linux kernel. As the Marvell families of +SoCs are large and complex, it is hard to understand where the support +for a particular SoC is available in the Linux kernel. This document +tries to help in understanding where those SoCs are supported, and to +match them with their corresponding public datasheet, when available. + +Orion family +------------ + + Flavors: + - 88F5082 + - 88F5181 + - 88F5181L + - 88F5182 + + - Datasheet: http://www.embeddedarm.com/documentation/third-party/MV88F5182-datasheet.pdf + - Programmer's User Guide: http://www.embeddedarm.com/documentation/third-party/MV88F5182-opensource-manual.pdf + - User Manual: http://www.embeddedarm.com/documentation/third-party/MV88F5182-usermanual.pdf + - 88F5281 + + - Datasheet: http://www.ocmodshop.com/images/reviews/networking/qnap_ts409u/marvel_88f5281_data_sheet.pdf + - 88F6183 + Core: + Feroceon 88fr331 (88f51xx) or 88fr531-vd (88f52xx) ARMv5 compatible + Linux kernel mach directory: + arch/arm/mach-orion5x + Linux kernel plat directory: + arch/arm/plat-orion + +Kirkwood family +--------------- + + Flavors: + - 88F6282 a.k.a Armada 300 + + - Product Brief : http://www.marvell.com/embedded-processors/armada-300/assets/armada_310.pdf + - 88F6283 a.k.a Armada 310 + + - Product Brief : http://www.marvell.com/embedded-processors/armada-300/assets/armada_310.pdf + - 88F6190 + + - Product Brief : http://www.marvell.com/embedded-processors/kirkwood/assets/88F6190-003_WEB.pdf + - Hardware Spec : http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F619x_OpenSource.pdf + - Functional Spec: http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf + - 88F6192 + + - Product Brief : http://www.marvell.com/embedded-processors/kirkwood/assets/88F6192-003_ver1.pdf + - Hardware Spec : http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F619x_OpenSource.pdf + - Functional Spec: http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf + - 88F6182 + - 88F6180 + + - Product Brief : http://www.marvell.com/embedded-processors/kirkwood/assets/88F6180-003_ver1.pdf + - Hardware Spec : http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F6180_OpenSource.pdf + - Functional Spec: http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf + - 88F6281 + + - Product Brief : http://www.marvell.com/embedded-processors/kirkwood/assets/88F6281-004_ver1.pdf + - Hardware Spec : http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F6281_OpenSource.pdf + - Functional Spec: http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf + Homepage: + http://www.marvell.com/embedded-processors/kirkwood/ + Core: + Feroceon 88fr131 ARMv5 compatible + Linux kernel mach directory: + arch/arm/mach-mvebu + Linux kernel plat directory: + none + +Discovery family +---------------- + + Flavors: + - MV78100 + + - Product Brief : http://www.marvell.com/embedded-processors/discovery-innovation/assets/MV78100-003_WEB.pdf + - Hardware Spec : http://www.marvell.com/embedded-processors/discovery-innovation/assets/HW_MV78100_OpenSource.pdf + - Functional Spec: http://www.marvell.com/embedded-processors/discovery-innovation/assets/FS_MV76100_78100_78200_OpenSource.pdf + - MV78200 + + - Product Brief : http://www.marvell.com/embedded-processors/discovery-innovation/assets/MV78200-002_WEB.pdf + - Hardware Spec : http://www.marvell.com/embedded-processors/discovery-innovation/assets/HW_MV78200_OpenSource.pdf + - Functional Spec: http://www.marvell.com/embedded-processors/discovery-innovation/assets/FS_MV76100_78100_78200_OpenSource.pdf + - MV76100 + + Not supported by the Linux kernel. + + Core: + Feroceon 88fr571-vd ARMv5 compatible + + Linux kernel mach directory: + arch/arm/mach-mv78xx0 + Linux kernel plat directory: + arch/arm/plat-orion + +EBU Armada family +----------------- + + Armada 370 Flavors: + - 88F6710 + - 88F6707 + - 88F6W11 + + - Product Brief: http://www.marvell.com/embedded-processors/armada-300/assets/Marvell_ARMADA_370_SoC.pdf + - Hardware Spec: http://www.marvell.com/embedded-processors/armada-300/assets/ARMADA370-datasheet.pdf + - Functional Spec: http://www.marvell.com/embedded-processors/armada-300/assets/ARMADA370-FunctionalSpec-datasheet.pdf + + Core: + Sheeva ARMv7 compatible PJ4B + + Armada 375 Flavors: + - 88F6720 + + - Product Brief: http://www.marvell.com/embedded-processors/armada-300/assets/ARMADA_375_SoC-01_product_brief.pdf + + Core: + ARM Cortex-A9 + + Armada 38x Flavors: + - 88F6810 Armada 380 + - 88F6820 Armada 385 + - 88F6828 Armada 388 + + - Product infos: http://www.marvell.com/embedded-processors/armada-38x/ + - Functional Spec: https://marvellcorp.wufoo.com/forms/marvell-armada-38x-functional-specifications/ + + Core: + ARM Cortex-A9 + + Armada 39x Flavors: + - 88F6920 Armada 390 + - 88F6928 Armada 398 + + - Product infos: http://www.marvell.com/embedded-processors/armada-39x/ + + Core: + ARM Cortex-A9 + + Armada XP Flavors: + - MV78230 + - MV78260 + - MV78460 + + NOTE: + not to be confused with the non-SMP 78xx0 SoCs + + Product Brief: + http://www.marvell.com/embedded-processors/armada-xp/assets/Marvell-ArmadaXP-SoC-product%20brief.pdf + + Functional Spec: + http://www.marvell.com/embedded-processors/armada-xp/assets/ARMADA-XP-Functional-SpecDatasheet.pdf + + - Hardware Specs: + + - http://www.marvell.com/embedded-processors/armada-xp/assets/HW_MV78230_OS.PDF + - http://www.marvell.com/embedded-processors/armada-xp/assets/HW_MV78260_OS.PDF + - http://www.marvell.com/embedded-processors/armada-xp/assets/HW_MV78460_OS.PDF + + Core: + Sheeva ARMv7 compatible Dual-core or Quad-core PJ4B-MP + + Linux kernel mach directory: + arch/arm/mach-mvebu + Linux kernel plat directory: + none + +EBU Armada family ARMv8 +----------------------- + + Armada 3710/3720 Flavors: + - 88F3710 + - 88F3720 + + Core: + ARM Cortex A53 (ARMv8) + + Homepage: + http://www.marvell.com/embedded-processors/armada-3700/ + + Product Brief: + http://www.marvell.com/embedded-processors/assets/PB-88F3700-FNL.pdf + + Device tree files: + arch/arm64/boot/dts/marvell/armada-37* + + Armada 7K Flavors: + - 88F7020 (AP806 Dual + one CP110) + - 88F7040 (AP806 Quad + one CP110) + + Core: ARM Cortex A72 + + Homepage: + http://www.marvell.com/embedded-processors/armada-70xx/ + + Product Brief: + - http://www.marvell.com/embedded-processors/assets/Armada7020PB-Jan2016.pdf + - http://www.marvell.com/embedded-processors/assets/Armada7040PB-Jan2016.pdf + + Device tree files: + arch/arm64/boot/dts/marvell/armada-70* + + Armada 8K Flavors: + - 88F8020 (AP806 Dual + two CP110) + - 88F8040 (AP806 Quad + two CP110) + Core: + ARM Cortex A72 + + Homepage: + http://www.marvell.com/embedded-processors/armada-80xx/ + + Product Brief: + - http://www.marvell.com/embedded-processors/assets/Armada8020PB-Jan2016.pdf + - http://www.marvell.com/embedded-processors/assets/Armada8040PB-Jan2016.pdf + + Device tree files: + arch/arm64/boot/dts/marvell/armada-80* + +Avanta family +------------- + + Flavors: + - 88F6510 + - 88F6530P + - 88F6550 + - 88F6560 + + Homepage: + http://www.marvell.com/broadband/ + + Product Brief: + http://www.marvell.com/broadband/assets/Marvell_Avanta_88F6510_305_060-001_product_brief.pdf + + No public datasheet available. + + Core: + ARMv5 compatible + + Linux kernel mach directory: + no code in mainline yet, planned for the future + Linux kernel plat directory: + no code in mainline yet, planned for the future + +Storage family +-------------- + + Armada SP: + - 88RC1580 + + Product infos: + http://www.marvell.com/storage/armada-sp/ + + Core: + Sheeva ARMv7 comatible Quad-core PJ4C + + (not supported in upstream Linux kernel) + +Dove family (application processor) +----------------------------------- + + Flavors: + - 88AP510 a.k.a Armada 510 + + Product Brief: + http://www.marvell.com/application-processors/armada-500/assets/Marvell_Armada510_SoC.pdf + + Hardware Spec: + http://www.marvell.com/application-processors/armada-500/assets/Armada-510-Hardware-Spec.pdf + + Functional Spec: + http://www.marvell.com/application-processors/armada-500/assets/Armada-510-Functional-Spec.pdf + + Homepage: + http://www.marvell.com/application-processors/armada-500/ + + Core: + ARMv7 compatible + + Directory: + - arch/arm/mach-mvebu (DT enabled platforms) + - arch/arm/mach-dove (non-DT enabled platforms) + +PXA 2xx/3xx/93x/95x family +-------------------------- + + Flavors: + - PXA21x, PXA25x, PXA26x + - Application processor only + - Core: ARMv5 XScale1 core + - PXA270, PXA271, PXA272 + - Product Brief : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_pb.pdf + - Design guide : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_design_guide.pdf + - Developers manual : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_dev_man.pdf + - Specification : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_emts.pdf + - Specification update : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_spec_update.pdf + - Application processor only + - Core: ARMv5 XScale2 core + - PXA300, PXA310, PXA320 + - PXA 300 Product Brief : http://www.marvell.com/application-processors/pxa-family/assets/PXA300_PB_R4.pdf + - PXA 310 Product Brief : http://www.marvell.com/application-processors/pxa-family/assets/PXA310_PB_R4.pdf + - PXA 320 Product Brief : http://www.marvell.com/application-processors/pxa-family/assets/PXA320_PB_R4.pdf + - Design guide : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_Design_Guide.pdf + - Developers manual : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_Developers_Manual.zip + - Specifications : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_EMTS.pdf + - Specification Update : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_Spec_Update.zip + - Reference Manual : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_TavorP_BootROM_Ref_Manual.pdf + - Application processor only + - Core: ARMv5 XScale3 core + - PXA930, PXA935 + - Application processor with Communication processor + - Core: ARMv5 XScale3 core + - PXA955 + - Application processor with Communication processor + - Core: ARMv7 compatible Sheeva PJ4 core + + Comments: + + * This line of SoCs originates from the XScale family developed by + Intel and acquired by Marvell in ~2006. The PXA21x, PXA25x, + PXA26x, PXA27x, PXA3xx and PXA93x were developed by Intel, while + the later PXA95x were developed by Marvell. + + * Due to their XScale origin, these SoCs have virtually nothing in + common with the other (Kirkwood, Dove, etc.) families of Marvell + SoCs, except with the MMP/MMP2 family of SoCs. + + Linux kernel mach directory: + arch/arm/mach-pxa + Linux kernel plat directory: + arch/arm/plat-pxa + +MMP/MMP2/MMP3 family (communication processor) +---------------------------------------------- + + Flavors: + - PXA168, a.k.a Armada 168 + - Homepage : http://www.marvell.com/application-processors/armada-100/armada-168.jsp + - Product brief : http://www.marvell.com/application-processors/armada-100/assets/pxa_168_pb.pdf + - Hardware manual : http://www.marvell.com/application-processors/armada-100/assets/armada_16x_datasheet.pdf + - Software manual : http://www.marvell.com/application-processors/armada-100/assets/armada_16x_software_manual.pdf + - Specification update : http://www.marvell.com/application-processors/armada-100/assets/ARMADA16x_Spec_update.pdf + - Boot ROM manual : http://www.marvell.com/application-processors/armada-100/assets/armada_16x_ref_manual.pdf + - App node package : http://www.marvell.com/application-processors/armada-100/assets/armada_16x_app_note_package.pdf + - Application processor only + - Core: ARMv5 compatible Marvell PJ1 88sv331 (Mohawk) + - PXA910/PXA920 + - Homepage : http://www.marvell.com/communication-processors/pxa910/ + - Product Brief : http://www.marvell.com/communication-processors/pxa910/assets/Marvell_PXA910_Platform-001_PB_final.pdf + - Application processor with Communication processor + - Core: ARMv5 compatible Marvell PJ1 88sv331 (Mohawk) + - PXA688, a.k.a. MMP2, a.k.a Armada 610 + - Product Brief : http://www.marvell.com/application-processors/armada-600/assets/armada610_pb.pdf + - Application processor only + - Core: ARMv7 compatible Sheeva PJ4 88sv581x core + - PXA2128, a.k.a. MMP3 (OLPC XO4, Linux support not upstream) + - Product Brief : http://www.marvell.com/application-processors/armada/pxa2128/assets/Marvell-ARMADA-PXA2128-SoC-PB.pdf + - Application processor only + - Core: Dual-core ARMv7 compatible Sheeva PJ4C core + - PXA960/PXA968/PXA978 (Linux support not upstream) + - Application processor with Communication Processor + - Core: ARMv7 compatible Sheeva PJ4 core + - PXA986/PXA988 (Linux support not upstream) + - Application processor with Communication Processor + - Core: Dual-core ARMv7 compatible Sheeva PJ4B-MP core + - PXA1088/PXA1920 (Linux support not upstream) + - Application processor with Communication Processor + - Core: quad-core ARMv7 Cortex-A7 + - PXA1908/PXA1928/PXA1936 + - Application processor with Communication Processor + - Core: multi-core ARMv8 Cortex-A53 + + Comments: + + * This line of SoCs originates from the XScale family developed by + Intel and acquired by Marvell in ~2006. All the processors of + this MMP/MMP2 family were developed by Marvell. + + * Due to their XScale origin, these SoCs have virtually nothing in + common with the other (Kirkwood, Dove, etc.) families of Marvell + SoCs, except with the PXA family of SoCs listed above. + + Linux kernel mach directory: + arch/arm/mach-mmp + Linux kernel plat directory: + arch/arm/plat-pxa + +Berlin family (Multimedia Solutions) +------------------------------------- + + - Flavors: + - 88DE3010, Armada 1000 (no Linux support) + - Core: Marvell PJ1 (ARMv5TE), Dual-core + - Product Brief: http://www.marvell.com.cn/digital-entertainment/assets/armada_1000_pb.pdf + - 88DE3005, Armada 1500 Mini + - Design name: BG2CD + - Core: ARM Cortex-A9, PL310 L2CC + - 88DE3006, Armada 1500 Mini Plus + - Design name: BG2CDP + - Core: Dual Core ARM Cortex-A7 + - 88DE3100, Armada 1500 + - Design name: BG2 + - Core: Marvell PJ4B-MP (ARMv7), Tauros3 L2CC + - 88DE3114, Armada 1500 Pro + - Design name: BG2Q + - Core: Quad Core ARM Cortex-A9, PL310 L2CC + - 88DE3214, Armada 1500 Pro 4K + - Design name: BG3 + - Core: ARM Cortex-A15, CA15 integrated L2CC + - 88DE3218, ARMADA 1500 Ultra + - Core: ARM Cortex-A53 + + Homepage: https://www.synaptics.com/products/multimedia-solutions + Directory: arch/arm/mach-berlin + + Comments: + + * This line of SoCs is based on Marvell Sheeva or ARM Cortex CPUs + with Synopsys DesignWare (IRQ, GPIO, Timers, ...) and PXA IP (SDHCI, USB, ETH, ...). + + * The Berlin family was acquired by Synaptics from Marvell in 2017. + +CPU Cores +--------- + +The XScale cores were designed by Intel, and shipped by Marvell in the older +PXA processors. Feroceon is a Marvell designed core that developed in-house, +and that evolved into Sheeva. The XScale and Feroceon cores were phased out +over time and replaced with Sheeva cores in later products, which subsequently +got replaced with licensed ARM Cortex-A cores. + + XScale 1 + CPUID 0x69052xxx + ARMv5, iWMMXt + XScale 2 + CPUID 0x69054xxx + ARMv5, iWMMXt + XScale 3 + CPUID 0x69056xxx or 0x69056xxx + ARMv5, iWMMXt + Feroceon-1850 88fr331 "Mohawk" + CPUID 0x5615331x or 0x41xx926x + ARMv5TE, single issue + Feroceon-2850 88fr531-vd "Jolteon" + CPUID 0x5605531x or 0x41xx926x + ARMv5TE, VFP, dual-issue + Feroceon 88fr571-vd "Jolteon" + CPUID 0x5615571x + ARMv5TE, VFP, dual-issue + Feroceon 88fr131 "Mohawk-D" + CPUID 0x5625131x + ARMv5TE, single-issue in-order + Sheeva PJ1 88sv331 "Mohawk" + CPUID 0x561584xx + ARMv5, single-issue iWMMXt v2 + Sheeva PJ4 88sv581x "Flareon" + CPUID 0x560f581x + ARMv7, idivt, optional iWMMXt v2 + Sheeva PJ4B 88sv581x + CPUID 0x561f581x + ARMv7, idivt, optional iWMMXt v2 + Sheeva PJ4B-MP / PJ4C + CPUID 0x562f584x + ARMv7, idivt/idiva, LPAE, optional iWMMXt v2 and/or NEON + +Long-term plans +--------------- + + * Unify the mach-dove/, mach-mv78xx0/, mach-orion5x/ into the + mach-mvebu/ to support all SoCs from the Marvell EBU (Engineering + Business Unit) in a single mach- directory. The plat-orion/ + would therefore disappear. + + * Unify the mach-mmp/ and mach-pxa/ into the same mach-pxa + directory. The plat-pxa/ would therefore disappear. + +Credits +------- + +- Maen Suleiman +- Lior Amsalem +- Thomas Petazzoni +- Andrew Lunn +- Nicolas Pitre +- Eric Miao diff --git a/Documentation/arm/mem_alignment b/Documentation/arm/mem_alignment.rst similarity index 89% rename from Documentation/arm/mem_alignment rename to Documentation/arm/mem_alignment.rst index e110e2781039..aa22893b62bc 100644 --- a/Documentation/arm/mem_alignment +++ b/Documentation/arm/mem_alignment.rst @@ -1,3 +1,7 @@ +================ +Memory alignment +================ + Too many problems popped up because of unnoticed misaligned memory access in kernel code lately. Therefore the alignment fixup is now unconditionally configured in for SA11x0 based targets. According to Alan Cox, this is a @@ -26,9 +30,9 @@ space, and might cause programs to fail unexpectedly. To change the alignment trap behavior, simply echo a number into /proc/cpu/alignment. The number is made up from various bits: +=== ======================================================== bit behavior when set ---- ----------------- - +=== ======================================================== 0 A user process performing an unaligned memory access will cause the kernel to print a message indicating process name, pid, pc, instruction, address, and the @@ -41,12 +45,13 @@ bit behavior when set 2 The kernel will send a SIGBUS signal to the user process performing the unaligned access. +=== ======================================================== Note that not all combinations are supported - only values 0 through 5. (6 and 7 don't make sense). For example, the following will turn on the warnings, but without -fixing up or sending SIGBUS signals: +fixing up or sending SIGBUS signals:: echo 1 > /proc/cpu/alignment diff --git a/Documentation/arm/memory.txt b/Documentation/arm/memory.rst similarity index 90% rename from Documentation/arm/memory.txt rename to Documentation/arm/memory.rst index 546a39048eb0..0521b4ce5c96 100644 --- a/Documentation/arm/memory.txt +++ b/Documentation/arm/memory.rst @@ -1,6 +1,9 @@ - Kernel Memory Layout on ARM Linux +================================= +Kernel Memory Layout on ARM Linux +================================= Russell King + November 17, 2005 (2.6.15) This document describes the virtual memory layout which the Linux @@ -15,8 +18,9 @@ As the ARM architecture matures, it becomes necessary to reserve certain regions of VM space for use for new facilities; therefore this document may reserve more VM space over time. +=============== =============== =============================================== Start End Use --------------------------------------------------------------------------- +=============== =============== =============================================== ffff8000 ffffffff copy_user_page / clear_user_page use. For SA11xx and Xscale, this is used to setup a minicache mapping. @@ -77,6 +81,7 @@ MODULES_VADDR MODULES_END-1 Kernel module space place their vector page here. NULL pointer dereferences by both the kernel and user space are also caught via this mapping. +=============== =============== =============================================== Please note that mappings which collide with the above areas may result in a non-bootable kernel, or may cause the kernel to (eventually) panic diff --git a/Documentation/arm/Microchip/README b/Documentation/arm/microchip.rst similarity index 92% rename from Documentation/arm/Microchip/README rename to Documentation/arm/microchip.rst index a366f37d38f1..c9a44c98e868 100644 --- a/Documentation/arm/Microchip/README +++ b/Documentation/arm/microchip.rst @@ -1,3 +1,4 @@ +============================= ARM Microchip SoCs (aka AT91) ============================= @@ -22,32 +23,46 @@ the Microchip website: http://www.microchip.com. Flavors: * ARM 920 based SoC - at91rm9200 - + Datasheet + + * Datasheet + http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-1768-32-bit-ARM920T-Embedded-Microprocessor-AT91RM9200_Datasheet.pdf * ARM 926 based SoCs - at91sam9260 - + Datasheet + + * Datasheet + http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-6221-32-bit-ARM926EJ-S-Embedded-Microprocessor-SAM9260_Datasheet.pdf - at91sam9xe - + Datasheet + + * Datasheet + http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-6254-32-bit-ARM926EJ-S-Embedded-Microprocessor-SAM9XE_Datasheet.pdf - at91sam9261 - + Datasheet + + * Datasheet + http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-6062-ARM926EJ-S-Microprocessor-SAM9261_Datasheet.pdf - at91sam9263 - + Datasheet + + * Datasheet + http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-6249-32-bit-ARM926EJ-S-Embedded-Microprocessor-SAM9263_Datasheet.pdf - at91sam9rl - + Datasheet + + * Datasheet + http://ww1.microchip.com/downloads/en/DeviceDoc/doc6289.pdf - at91sam9g20 - + Datasheet + + * Datasheet + http://ww1.microchip.com/downloads/en/DeviceDoc/DS60001516A.pdf - at91sam9g45 family @@ -55,7 +70,9 @@ the Microchip website: http://www.microchip.com. - at91sam9g46 - at91sam9m10 - at91sam9m11 (device superset) - + Datasheet + + * Datasheet + http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-6437-32-bit-ARM926-Embedded-Microprocessor-SAM9M11_Datasheet.pdf - at91sam9x5 family (aka "The 5 series") @@ -64,33 +81,44 @@ the Microchip website: http://www.microchip.com. - at91sam9g35 - at91sam9x25 - at91sam9x35 - + Datasheet (can be considered as covering the whole family) + + * Datasheet (can be considered as covering the whole family) + http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-11055-32-bit-ARM926EJ-S-Microcontroller-SAM9X35_Datasheet.pdf - at91sam9n12 - + Datasheet + + * Datasheet + http://ww1.microchip.com/downloads/en/DeviceDoc/DS60001517A.pdf * ARM Cortex-A5 based SoCs - sama5d3 family + - sama5d31 - sama5d33 - sama5d34 - sama5d35 - sama5d36 (device superset) - + Datasheet + + * Datasheet + http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-11121-32-bit-Cortex-A5-Microcontroller-SAMA5D3_Datasheet.pdf * ARM Cortex-A5 + NEON based SoCs - sama5d4 family + - sama5d41 - sama5d42 - sama5d43 - sama5d44 (device superset) - + Datasheet + + * Datasheet + http://ww1.microchip.com/downloads/en/DeviceDoc/60001525A.pdf - sama5d2 family + - sama5d21 - sama5d22 - sama5d23 @@ -98,11 +126,14 @@ the Microchip website: http://www.microchip.com. - sama5d26 - sama5d27 (device superset) - sama5d28 (device superset + environmental monitors) - + Datasheet + + * Datasheet + http://ww1.microchip.com/downloads/en/DeviceDoc/DS60001476B.pdf * ARM Cortex-M7 MCUs - sams70 family + - sams70j19 - sams70j20 - sams70j21 @@ -114,6 +145,7 @@ the Microchip website: http://www.microchip.com. - sams70q21 - samv70 family + - samv70j19 - samv70j20 - samv70n19 @@ -122,6 +154,7 @@ the Microchip website: http://www.microchip.com. - samv70q20 - samv71 family + - samv71j19 - samv71j20 - samv71j21 @@ -132,7 +165,8 @@ the Microchip website: http://www.microchip.com. - samv71q20 - samv71q21 - + Datasheet + * Datasheet + http://ww1.microchip.com/downloads/en/DeviceDoc/60001527A.pdf @@ -157,6 +191,7 @@ definition of a "Stable" binding/ABI. This statement will be removed by AT91 MAINTAINERS when appropriate. Naming conventions and best practice: + - SoCs Device Tree Source Include files are named after the official name of the product (at91sam9g20.dtsi or sama5d33.dtsi for instance). - Device Tree Source Include files (.dtsi) are used to collect common nodes that can be diff --git a/Documentation/arm/netwinder.rst b/Documentation/arm/netwinder.rst new file mode 100644 index 000000000000..8eab66caa2ac --- /dev/null +++ b/Documentation/arm/netwinder.rst @@ -0,0 +1,85 @@ +================================ +NetWinder specific documentation +================================ + +The NetWinder is a small low-power computer, primarily designed +to run Linux. It is based around the StrongARM RISC processor, +DC21285 PCI bridge, with PC-type hardware glued around it. + +Port usage +========== + +======= ====== =============================== +Min Max Description +======= ====== =============================== +0x0000 0x000f DMA1 +0x0020 0x0021 PIC1 +0x0060 0x006f Keyboard +0x0070 0x007f RTC +0x0080 0x0087 DMA1 +0x0088 0x008f DMA2 +0x00a0 0x00a3 PIC2 +0x00c0 0x00df DMA2 +0x0180 0x0187 IRDA +0x01f0 0x01f6 ide0 +0x0201 Game port +0x0203 RWA010 configuration read +0x0220 ? SoundBlaster +0x0250 ? WaveArtist +0x0279 RWA010 configuration index +0x02f8 0x02ff Serial ttyS1 +0x0300 0x031f Ether10 +0x0338 GPIO1 +0x033a GPIO2 +0x0370 0x0371 W83977F configuration registers +0x0388 ? AdLib +0x03c0 0x03df VGA +0x03f6 ide0 +0x03f8 0x03ff Serial ttyS0 +0x0400 0x0408 DC21143 +0x0480 0x0487 DMA1 +0x0488 0x048f DMA2 +0x0a79 RWA010 configuration write +0xe800 0xe80f ide0/ide1 BM DMA +======= ====== =============================== + + +Interrupt usage +=============== + +======= ======= ======================== +IRQ type Description +======= ======= ======================== + 0 ISA 100Hz timer + 1 ISA Keyboard + 2 ISA cascade + 3 ISA Serial ttyS1 + 4 ISA Serial ttyS0 + 5 ISA PS/2 mouse + 6 ISA IRDA + 7 ISA Printer + 8 ISA RTC alarm + 9 ISA +10 ISA GP10 (Orange reset button) +11 ISA +12 ISA WaveArtist +13 ISA +14 ISA hda1 +15 ISA +======= ======= ======================== + +DMA usage +========= + +======= ======= =========== +DMA type Description +======= ======= =========== + 0 ISA IRDA + 1 ISA + 2 ISA cascade + 3 ISA WaveArtist + 4 ISA + 5 ISA + 6 ISA + 7 ISA WaveArtist +======= ======= =========== diff --git a/Documentation/arm/nwfpe/index.rst b/Documentation/arm/nwfpe/index.rst new file mode 100644 index 000000000000..21fa8ce192ae --- /dev/null +++ b/Documentation/arm/nwfpe/index.rst @@ -0,0 +1,11 @@ +=================================== +NetWinder's floating point emulator +=================================== + +.. toctree:: + :maxdepth: 1 + + nwfpe + netwinder-fpe + notes + todo diff --git a/Documentation/arm/nwfpe/README.FPE b/Documentation/arm/nwfpe/netwinder-fpe.rst similarity index 94% rename from Documentation/arm/nwfpe/README.FPE rename to Documentation/arm/nwfpe/netwinder-fpe.rst index 26f5d7bb9a41..cbb320960fc4 100644 --- a/Documentation/arm/nwfpe/README.FPE +++ b/Documentation/arm/nwfpe/netwinder-fpe.rst @@ -1,12 +1,18 @@ +============= +Current State +============= + The following describes the current state of the NetWinder's floating point emulator. In the following nomenclature is used to describe the floating point instructions. It follows the conventions in the ARM manual. - = , no default -{P|M|Z} = {round to +infinity,round to -infinity,round to zero}, - default = round to nearest +:: + + = , no default + {P|M|Z} = {round to +infinity,round to -infinity,round to zero}, + default = round to nearest Note: items enclosed in {} are optional. @@ -32,10 +38,10 @@ Form 2 syntax: {cond} Fd, , [Rn]{!} These instructions are fully implemented. They store/load three words -for each floating point register into the memory location given in the +for each floating point register into the memory location given in the instruction. The format in memory is unlikely to be compatible with other implementations, in particular the actual hardware. Specific -mention of this is made in the ARM manuals. +mention of this is made in the ARM manuals. Floating Point Coprocessor Register Transfer Instructions (CPRT) ---------------------------------------------------------------- @@ -123,7 +129,7 @@ RPW{cond}{P,M,Z} Fd, Fn, - reverse power POL{cond}{P,M,Z} Fd, Fn, - polar angle (arctan2) LOG{cond}{P,M,Z} Fd, - logarithm to base 10 -LGN{cond}{P,M,Z} Fd, - logarithm to base e +LGN{cond}{P,M,Z} Fd, - logarithm to base e EXP{cond}{P,M,Z} Fd, - exponent SIN{cond}{P,M,Z} Fd, - sine COS{cond}{P,M,Z} Fd, - cosine @@ -134,7 +140,7 @@ ATN{cond}{P,M,Z} Fd, - arctangent These are not implemented. They are not currently issued by the compiler, and are handled by routines in libc. These are not implemented by the FPA11 -hardware, but are handled by the floating point support code. They should +hardware, but are handled by the floating point support code. They should be implemented in future versions. Signalling: @@ -147,10 +153,10 @@ current_set[0] correctly. The kernel provided with this distribution (vmlinux-nwfpe-0.93) contains a fix for this problem and also incorporates the current version of the emulator directly. It is possible to run with no floating point module -loaded with this kernel. It is provided as a demonstration of the +loaded with this kernel. It is provided as a demonstration of the technology and for those who want to do floating point work that depends on signals. It is not strictly necessary to use the module. -A module (either the one provided by Russell King, or the one in this +A module (either the one provided by Russell King, or the one in this distribution) can be loaded to replace the functionality of the emulator built into the kernel. diff --git a/Documentation/arm/nwfpe/NOTES b/Documentation/arm/nwfpe/notes.rst similarity index 99% rename from Documentation/arm/nwfpe/NOTES rename to Documentation/arm/nwfpe/notes.rst index 40577b5a49d3..102e55af8439 100644 --- a/Documentation/arm/nwfpe/NOTES +++ b/Documentation/arm/nwfpe/notes.rst @@ -1,3 +1,6 @@ +Notes +===== + There seems to be a problem with exp(double) and our emulator. I haven't been able to track it down yet. This does not occur with the emulator supplied by Russell King. diff --git a/Documentation/arm/nwfpe/README b/Documentation/arm/nwfpe/nwfpe.rst similarity index 98% rename from Documentation/arm/nwfpe/README rename to Documentation/arm/nwfpe/nwfpe.rst index 771871de0c8b..35cd90dacbff 100644 --- a/Documentation/arm/nwfpe/README +++ b/Documentation/arm/nwfpe/nwfpe.rst @@ -1,4 +1,7 @@ -This directory contains the version 0.92 test release of the NetWinder +Introduction +============ + +This directory contains the version 0.92 test release of the NetWinder Floating Point Emulator. The majority of the code was written by me, Scott Bambrough It is @@ -31,7 +34,7 @@ SoftFloat to the ARM was done by Phil Blundell, based on an earlier port of SoftFloat version 1 by Neil Carson for NetBSD/arm32. The file README.FPE contains a description of what has been implemented -so far in the emulator. The file TODO contains a information on what +so far in the emulator. The file TODO contains a information on what remains to be done, and other ideas for the emulator. Bug reports, comments, suggestions should be directed to me at @@ -48,10 +51,11 @@ Legal Notices The NetWinder Floating Point Emulator is free software. Everything Rebel.com has written is provided under the GNU GPL. See the file COPYING for copying -conditions. Excluded from the above is the SoftFloat code. John Hauser's +conditions. Excluded from the above is the SoftFloat code. John Hauser's legal notice for SoftFloat is included below. ------------------------------------------------------------------------------- + SoftFloat Legal Notice SoftFloat was written by John R. Hauser. This work was made possible in diff --git a/Documentation/arm/nwfpe/TODO b/Documentation/arm/nwfpe/todo.rst similarity index 75% rename from Documentation/arm/nwfpe/TODO rename to Documentation/arm/nwfpe/todo.rst index 8027061b60eb..393f11b14540 100644 --- a/Documentation/arm/nwfpe/TODO +++ b/Documentation/arm/nwfpe/todo.rst @@ -1,39 +1,42 @@ TODO LIST ---------- +========= -POW{cond}{P,M,Z} Fd, Fn, - power -RPW{cond}{P,M,Z} Fd, Fn, - reverse power -POL{cond}{P,M,Z} Fd, Fn, - polar angle (arctan2) +:: -LOG{cond}{P,M,Z} Fd, - logarithm to base 10 -LGN{cond}{P,M,Z} Fd, - logarithm to base e -EXP{cond}{P,M,Z} Fd, - exponent -SIN{cond}{P,M,Z} Fd, - sine -COS{cond}{P,M,Z} Fd, - cosine -TAN{cond}{P,M,Z} Fd, - tangent -ASN{cond}{P,M,Z} Fd, - arcsine -ACS{cond}{P,M,Z} Fd, - arccosine -ATN{cond}{P,M,Z} Fd, - arctangent + POW{cond}{P,M,Z} Fd, Fn, - power + RPW{cond}{P,M,Z} Fd, Fn, - reverse power + POL{cond}{P,M,Z} Fd, Fn, - polar angle (arctan2) + + LOG{cond}{P,M,Z} Fd, - logarithm to base 10 + LGN{cond}{P,M,Z} Fd, - logarithm to base e + EXP{cond}{P,M,Z} Fd, - exponent + SIN{cond}{P,M,Z} Fd, - sine + COS{cond}{P,M,Z} Fd, - cosine + TAN{cond}{P,M,Z} Fd, - tangent + ASN{cond}{P,M,Z} Fd, - arcsine + ACS{cond}{P,M,Z} Fd, - arccosine + ATN{cond}{P,M,Z} Fd, - arctangent These are not implemented. They are not currently issued by the compiler, and are handled by routines in libc. These are not implemented by the FPA11 -hardware, but are handled by the floating point support code. They should +hardware, but are handled by the floating point support code. They should be implemented in future versions. There are a couple of ways to approach the implementation of these. One -method would be to use accurate table methods for these routines. I have +method would be to use accurate table methods for these routines. I have a couple of papers by S. Gal from IBM's research labs in Haifa, Israel that seem to promise extreme accuracy (in the order of 99.8%) and reasonable speed. These methods are used in GLIBC for some of the transcendental functions. Another approach, which I know little about is CORDIC. This stands for -Coordinate Rotation Digital Computer, and is a method of computing +Coordinate Rotation Digital Computer, and is a method of computing transcendental functions using mostly shifts and adds and a few multiplications and divisions. The ARM excels at shifts and adds, -so such a method could be promising, but requires more research to +so such a method could be promising, but requires more research to determine if it is feasible. Rounding Methods +---------------- The IEEE standard defines 4 rounding modes. Round to nearest is the default, but rounding to + or - infinity or round to zero are also allowed. @@ -42,8 +45,8 @@ in a control register. Not so with the ARM FPA11 architecture. To change the rounding mode one must specify it with each instruction. This has made porting some benchmarks difficult. It is possible to -introduce such a capability into the emulator. The FPCR contains -bits describing the rounding mode. The emulator could be altered to +introduce such a capability into the emulator. The FPCR contains +bits describing the rounding mode. The emulator could be altered to examine a flag, which if set forced it to ignore the rounding mode in the instruction, and use the mode specified in the bits in the FPCR. @@ -52,7 +55,8 @@ in the FPCR. This requires a kernel call in ArmLinux, as WFC/RFC are supervisor only instructions. If anyone has any ideas or comments I would like to hear them. -[NOTE: pulled out from some docs on ARM floating point, specifically +NOTE: + pulled out from some docs on ARM floating point, specifically for the Acorn FPE, but not limited to it: The floating point control register (FPCR) may only be present in some @@ -64,4 +68,5 @@ would like to hear them. Hence, the answer is yes, you could do this, but then you will run a high risk of becoming isolated if and when hardware FP emulation comes out - -- Russell]. + + -- Russell. diff --git a/Documentation/arm/OMAP/DSS b/Documentation/arm/omap/dss.rst similarity index 86% rename from Documentation/arm/OMAP/DSS rename to Documentation/arm/omap/dss.rst index 4484e021290e..a40c4d9c717a 100644 --- a/Documentation/arm/OMAP/DSS +++ b/Documentation/arm/omap/dss.rst @@ -1,5 +1,6 @@ +========================= OMAP2/3 Display Subsystem -------------------------- +========================= This is an almost total rewrite of the OMAP FB driver in drivers/video/omap (let's call it DSS1). The main differences between DSS1 and DSS2 are DSI, @@ -190,6 +191,8 @@ trans_key_value transparency color key (RGB24) default_color default background color (RGB24) /sys/devices/platform/omapdss/display? directory: + +=============== ============================================================= ctrl_name Controller name mirror 0=off, 1=on update_mode 0=off, 1=auto, 2=manual @@ -202,6 +205,7 @@ timings Display timings (pixclock,xres/hfp/hbp/hsw,yres/vfp/vbp/vsw) panel_name tear_elim Tearing elimination 0=off, 1=on output_type Output type (video encoder only): "composite" or "svideo" +=============== ============================================================= There are also some debugfs files at /omapdss/ which show information about clocks and registers. @@ -209,22 +213,22 @@ about clocks and registers. Examples -------- -The following definitions have been made for the examples below: +The following definitions have been made for the examples below:: -ovl0=/sys/devices/platform/omapdss/overlay0 -ovl1=/sys/devices/platform/omapdss/overlay1 -ovl2=/sys/devices/platform/omapdss/overlay2 + ovl0=/sys/devices/platform/omapdss/overlay0 + ovl1=/sys/devices/platform/omapdss/overlay1 + ovl2=/sys/devices/platform/omapdss/overlay2 -mgr0=/sys/devices/platform/omapdss/manager0 -mgr1=/sys/devices/platform/omapdss/manager1 + mgr0=/sys/devices/platform/omapdss/manager0 + mgr1=/sys/devices/platform/omapdss/manager1 -lcd=/sys/devices/platform/omapdss/display0 -dvi=/sys/devices/platform/omapdss/display1 -tv=/sys/devices/platform/omapdss/display2 + lcd=/sys/devices/platform/omapdss/display0 + dvi=/sys/devices/platform/omapdss/display1 + tv=/sys/devices/platform/omapdss/display2 -fb0=/sys/class/graphics/fb0 -fb1=/sys/class/graphics/fb1 -fb2=/sys/class/graphics/fb2 + fb0=/sys/class/graphics/fb0 + fb1=/sys/class/graphics/fb1 + fb2=/sys/class/graphics/fb2 Default setup on OMAP3 SDP -------------------------- @@ -232,55 +236,59 @@ Default setup on OMAP3 SDP Here's the default setup on OMAP3 SDP board. All planes go to LCD. DVI and TV-out are not in use. The columns from left to right are: framebuffers, overlays, overlay managers, displays. Framebuffers are -handled by omapfb, and the rest by the DSS. +handled by omapfb, and the rest by the DSS:: -FB0 --- GFX -\ DVI -FB1 --- VID1 --+- LCD ---- LCD -FB2 --- VID2 -/ TV ----- TV + FB0 --- GFX -\ DVI + FB1 --- VID1 --+- LCD ---- LCD + FB2 --- VID2 -/ TV ----- TV Example: Switch from LCD to DVI ----------------------- - -w=`cat $dvi/timings | cut -d "," -f 2 | cut -d "/" -f 1` -h=`cat $dvi/timings | cut -d "," -f 3 | cut -d "/" -f 1` - -echo "0" > $lcd/enabled -echo "" > $mgr0/display -fbset -fb /dev/fb0 -xres $w -yres $h -vxres $w -vyres $h -# at this point you have to switch the dvi/lcd dip-switch from the omap board -echo "dvi" > $mgr0/display -echo "1" > $dvi/enabled - -After this the configuration looks like: - -FB0 --- GFX -\ -- DVI -FB1 --- VID1 --+- LCD -/ LCD -FB2 --- VID2 -/ TV ----- TV - -Example: Clone GFX overlay to LCD and TV ------------------------------- -w=`cat $tv/timings | cut -d "," -f 2 | cut -d "/" -f 1` -h=`cat $tv/timings | cut -d "," -f 3 | cut -d "/" -f 1` +:: -echo "0" > $ovl0/enabled -echo "0" > $ovl1/enabled + w=`cat $dvi/timings | cut -d "," -f 2 | cut -d "/" -f 1` + h=`cat $dvi/timings | cut -d "," -f 3 | cut -d "/" -f 1` -echo "" > $fb1/overlays -echo "0,1" > $fb0/overlays + echo "0" > $lcd/enabled + echo "" > $mgr0/display + fbset -fb /dev/fb0 -xres $w -yres $h -vxres $w -vyres $h + # at this point you have to switch the dvi/lcd dip-switch from the omap board + echo "dvi" > $mgr0/display + echo "1" > $dvi/enabled -echo "$w,$h" > $ovl1/output_size -echo "tv" > $ovl1/manager +After this the configuration looks like::: -echo "1" > $ovl0/enabled -echo "1" > $ovl1/enabled + FB0 --- GFX -\ -- DVI + FB1 --- VID1 --+- LCD -/ LCD + FB2 --- VID2 -/ TV ----- TV -echo "1" > $tv/enabled +Example: Clone GFX overlay to LCD and TV +---------------------------------------- -After this the configuration looks like (only relevant parts shown): +:: -FB0 +-- GFX ---- LCD ---- LCD - \- VID1 ---- TV ---- TV + w=`cat $tv/timings | cut -d "," -f 2 | cut -d "/" -f 1` + h=`cat $tv/timings | cut -d "," -f 3 | cut -d "/" -f 1` + + echo "0" > $ovl0/enabled + echo "0" > $ovl1/enabled + + echo "" > $fb1/overlays + echo "0,1" > $fb0/overlays + + echo "$w,$h" > $ovl1/output_size + echo "tv" > $ovl1/manager + + echo "1" > $ovl0/enabled + echo "1" > $ovl1/enabled + + echo "1" > $tv/enabled + +After this the configuration looks like (only relevant parts shown):: + + FB0 +-- GFX ---- LCD ---- LCD + \- VID1 ---- TV ---- TV Misc notes ---------- @@ -351,12 +359,14 @@ TODO DSS locking Error checking + - Lots of checks are missing or implemented just as BUG() System DMA update for DSI + - Can be used for RGB16 and RGB24P modes. Probably not for RGB24U (how to skip the empty byte?) OMAP1 support -- Not sure if needed +- Not sure if needed diff --git a/Documentation/arm/omap/index.rst b/Documentation/arm/omap/index.rst new file mode 100644 index 000000000000..f1e9c11d9f9b --- /dev/null +++ b/Documentation/arm/omap/index.rst @@ -0,0 +1,10 @@ +======= +TI OMAP +======= + +.. toctree:: + :maxdepth: 1 + + omap + omap_pm + dss diff --git a/Documentation/arm/OMAP/README b/Documentation/arm/omap/omap.rst similarity index 62% rename from Documentation/arm/OMAP/README rename to Documentation/arm/omap/omap.rst index 90c6c57d61e8..f440c0f4613f 100644 --- a/Documentation/arm/OMAP/README +++ b/Documentation/arm/omap/omap.rst @@ -1,7 +1,13 @@ +============ +OMAP history +============ + This file contains documentation for running mainline kernel on omaps. +====== ====================================================== KERNEL NEW DEPENDENCIES +====== ====================================================== v4.3+ Update is needed for custom .config files to make sure CONFIG_REGULATOR_PBIAS is enabled for MMC1 to work properly. @@ -9,3 +15,4 @@ v4.3+ Update is needed for custom .config files to make sure v4.18+ Update is needed for custom .config files to make sure CONFIG_MMC_SDHCI_OMAP is enabled for all MMC instances to work in DRA7 and K2G based boards. +====== ====================================================== diff --git a/Documentation/arm/OMAP/omap_pm b/Documentation/arm/omap/omap_pm.rst similarity index 83% rename from Documentation/arm/OMAP/omap_pm rename to Documentation/arm/omap/omap_pm.rst index 4ae915a9f899..a335e4c8ce2c 100644 --- a/Documentation/arm/OMAP/omap_pm +++ b/Documentation/arm/omap/omap_pm.rst @@ -1,4 +1,4 @@ - +===================== The OMAP PM interface ===================== @@ -31,19 +31,24 @@ Drivers need to express PM parameters which: This document proposes the OMAP PM interface, including the following five power management functions for driver code: -1. Set the maximum MPU wakeup latency: +1. Set the maximum MPU wakeup latency:: + (*pdata->set_max_mpu_wakeup_lat)(struct device *dev, unsigned long t) -2. Set the maximum device wakeup latency: +2. Set the maximum device wakeup latency:: + (*pdata->set_max_dev_wakeup_lat)(struct device *dev, unsigned long t) -3. Set the maximum system DMA transfer start latency (CORE pwrdm): +3. Set the maximum system DMA transfer start latency (CORE pwrdm):: + (*pdata->set_max_sdma_lat)(struct device *dev, long t) -4. Set the minimum bus throughput needed by a device: +4. Set the minimum bus throughput needed by a device:: + (*pdata->set_min_bus_tput)(struct device *dev, u8 agent_id, unsigned long r) -5. Return the number of times the device has lost context +5. Return the number of times the device has lost context:: + (*pdata->get_dev_context_loss_count)(struct device *dev) @@ -65,12 +70,13 @@ Driver usage of the OMAP PM functions As the 'pdata' in the above examples indicates, these functions are exposed to drivers through function pointers in driver .platform_data -structures. The function pointers are initialized by the board-*.c +structures. The function pointers are initialized by the `board-*.c` files to point to the corresponding OMAP PM functions: -.set_max_dev_wakeup_lat will point to -omap_pm_set_max_dev_wakeup_lat(), etc. Other architectures which do -not support these functions should leave these function pointers set -to NULL. Drivers should use the following idiom: + +- set_max_dev_wakeup_lat will point to + omap_pm_set_max_dev_wakeup_lat(), etc. Other architectures which do + not support these functions should leave these function pointers set + to NULL. Drivers should use the following idiom:: if (pdata->set_max_dev_wakeup_lat) (*pdata->set_max_dev_wakeup_lat)(dev, t); @@ -81,7 +87,7 @@ becomes accessible. To accomplish this, driver writers should use the set_max_mpu_wakeup_lat() function to constrain the MPU wakeup latency, and the set_max_dev_wakeup_lat() function to constrain the device wakeup latency (from clk_enable() to accessibility). For -example, +example:: /* Limit MPU wakeup latency */ if (pdata->set_max_mpu_wakeup_lat) @@ -116,17 +122,17 @@ specialized cases to convert that input information (OPPs/MPU frequency) into the form that the underlying power management implementation needs: -6. (*pdata->dsp_get_opp_table)(void) +6. `(*pdata->dsp_get_opp_table)(void)` -7. (*pdata->dsp_set_min_opp)(u8 opp_id) +7. `(*pdata->dsp_set_min_opp)(u8 opp_id)` -8. (*pdata->dsp_get_opp)(void) +8. `(*pdata->dsp_get_opp)(void)` -9. (*pdata->cpu_get_freq_table)(void) +9. `(*pdata->cpu_get_freq_table)(void)` -10. (*pdata->cpu_set_freq)(unsigned long f) +10. `(*pdata->cpu_set_freq)(unsigned long f)` -11. (*pdata->cpu_get_freq)(void) +11. `(*pdata->cpu_get_freq)(void)` Customizing OPP for platform ============================ @@ -134,12 +140,15 @@ Defining CONFIG_PM should enable OPP layer for the silicon and the registration of OPP table should take place automatically. However, in special cases, the default OPP table may need to be tweaked, for e.g.: + * enable default OPPs which are disabled by default, but which could be enabled on a platform * Disable an unsupported OPP on the platform * Define and add a custom opp table entry -in these cases, the board file needs to do additional steps as follows: -arch/arm/mach-omapx/board-xyz.c + in these cases, the board file needs to do additional steps as follows: + +arch/arm/mach-omapx/board-xyz.c:: + #include "pm.h" .... static void __init omap_xyz_init_irq(void) @@ -150,5 +159,7 @@ arch/arm/mach-omapx/board-xyz.c /* Do customization to the defaults */ .... } -NOTE: omapx_opp_init will be omap3_opp_init or as required -based on the omap family. + +NOTE: + omapx_opp_init will be omap3_opp_init or as required + based on the omap family. diff --git a/Documentation/arm/Porting b/Documentation/arm/porting.rst similarity index 94% rename from Documentation/arm/Porting rename to Documentation/arm/porting.rst index a492233931b9..bd21958bdb2d 100644 --- a/Documentation/arm/Porting +++ b/Documentation/arm/porting.rst @@ -1,3 +1,7 @@ +======= +Porting +======= + Taken from list archive at http://lists.arm.linux.org.uk/pipermail/linux-arm-kernel/2001-July/004064.html Initial definitions @@ -89,8 +93,7 @@ DATAADDR Virtual address for the kernel data segment. Must not be defined when using the decompressor. -VMALLOC_START -VMALLOC_END +VMALLOC_START / VMALLOC_END Virtual addresses bounding the vmalloc() area. There must not be any static mappings in this area; vmalloc will overwrite them. The addresses must also be in the kernel segment (see above). @@ -107,13 +110,13 @@ Architecture Specific Macros ---------------------------- BOOT_MEM(pram,pio,vio) - `pram' specifies the physical start address of RAM. Must always + `pram` specifies the physical start address of RAM. Must always be present, and should be the same as PHYS_OFFSET. - `pio' is the physical address of an 8MB region containing IO for + `pio` is the physical address of an 8MB region containing IO for use with the debugging macros in arch/arm/kernel/debug-armv.S. - `vio' is the virtual address of the 8MB debugging region. + `vio` is the virtual address of the 8MB debugging region. It is expected that the debugging region will be re-initialised by the architecture specific code later in the code (via the @@ -132,4 +135,3 @@ MAPIO(func) INITIRQ(func) Machine specific function to initialise interrupts. - diff --git a/Documentation/arm/pxa/mfp.txt b/Documentation/arm/pxa/mfp.rst similarity index 83% rename from Documentation/arm/pxa/mfp.txt rename to Documentation/arm/pxa/mfp.rst index 0b7cab978c02..ac34e5d7ee44 100644 --- a/Documentation/arm/pxa/mfp.txt +++ b/Documentation/arm/pxa/mfp.rst @@ -1,4 +1,6 @@ - MFP Configuration for PXA2xx/PXA3xx Processors +============================================== +MFP Configuration for PXA2xx/PXA3xx Processors +============================================== Eric Miao @@ -6,15 +8,15 @@ MFP stands for Multi-Function Pin, which is the pin-mux logic on PXA3xx and later PXA series processors. This document describes the existing MFP API, and how board/platform driver authors could make use of it. - Basic Concept -=============== +Basic Concept +============= Unlike the GPIO alternate function settings on PXA25x and PXA27x, a new MFP mechanism is introduced from PXA3xx to completely move the pin-mux functions out of the GPIO controller. In addition to pin-mux configurations, the MFP also controls the low power state, driving strength, pull-up/down and event detection of each pin. Below is a diagram of internal connections between -the MFP logic and the remaining SoC peripherals: +the MFP logic and the remaining SoC peripherals:: +--------+ | |--(GPIO19)--+ @@ -69,8 +71,8 @@ NOTE: with such a clear separation of MFP and GPIO, by GPIO we normally mean it is a GPIO signal, and by MFP or pin xxx, we mean a physical pad (or ball). - MFP API Usage -=============== +MFP API Usage +============= For board code writers, here are some guidelines: @@ -94,9 +96,9 @@ For board code writers, here are some guidelines: PXA310 supporting some additional ones), thus the difference is actually covered in a single mfp-pxa300.h. -2. prepare an array for the initial pin configurations, e.g.: +2. prepare an array for the initial pin configurations, e.g.:: - static unsigned long mainstone_pin_config[] __initdata = { + static unsigned long mainstone_pin_config[] __initdata = { /* Chip Select */ GPIO15_nCS_1, @@ -116,7 +118,7 @@ For board code writers, here are some guidelines: /* GPIO */ GPIO1_GPIO | WAKEUP_ON_EDGE_BOTH, - }; + }; a) once the pin configurations are passed to pxa{2xx,3xx}_mfp_config(), and written to the actual registers, they are useless and may discard, @@ -143,17 +145,17 @@ For board code writers, here are some guidelines: d) although PXA3xx MFP supports edge detection on each pin, the internal logic will only wakeup the system when those specific bits in ADxER registers are set, which can be well mapped to the - corresponding peripheral, thus set_irq_wake() can be called with + corresponding peripheral, thus set_irq_wake() can be called with the peripheral IRQ to enable the wakeup. - MFP on PXA3xx -=============== +MFP on PXA3xx +============= Every external I/O pad on PXA3xx (excluding those for special purpose) has one MFP logic associated, and is controlled by one MFP register (MFPR). -The MFPR has the following bit definitions (for PXA300/PXA310/PXA320): +The MFPR has the following bit definitions (for PXA300/PXA310/PXA320):: 31 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 +-------------------------+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ @@ -183,8 +185,8 @@ The MFPR has the following bit definitions (for PXA300/PXA310/PXA320): 0b006 - slow 10mA 0b007 - fast 10mA - MFP Design for PXA2xx/PXA3xx -============================== +MFP Design for PXA2xx/PXA3xx +============================ Due to the difference of pin-mux handling between PXA2xx and PXA3xx, a unified MFP API is introduced to cover both series of processors. @@ -194,11 +196,11 @@ configurations, these definitions are processor and platform independent, and the actual API invoked to convert these definitions into register settings and make them effective there-after. - Files Involved - -------------- +Files Involved +-------------- - arch/arm/mach-pxa/include/mach/mfp.h - + for 1. Unified pin definitions - enum constants for all configurable pins 2. processor-neutral bit definitions for a possible MFP configuration @@ -226,42 +228,42 @@ make them effective there-after. for implementation of the pin configuration to take effect for the actual processor. - Pin Configuration - ----------------- +Pin Configuration +----------------- The following comments are copied from mfp.h (see the actual source code - for most updated info) - - /* - * a possible MFP configuration is represented by a 32-bit integer - * - * bit 0.. 9 - MFP Pin Number (1024 Pins Maximum) - * bit 10..12 - Alternate Function Selection - * bit 13..15 - Drive Strength - * bit 16..18 - Low Power Mode State - * bit 19..20 - Low Power Mode Edge Detection - * bit 21..22 - Run Mode Pull State - * - * to facilitate the definition, the following macros are provided - * - * MFP_CFG_DEFAULT - default MFP configuration value, with - * alternate function = 0, - * drive strength = fast 3mA (MFP_DS03X) - * low power mode = default - * edge detection = none - * - * MFP_CFG - default MFPR value with alternate function - * MFP_CFG_DRV - default MFPR value with alternate function and - * pin drive strength - * MFP_CFG_LPM - default MFPR value with alternate function and - * low power mode - * MFP_CFG_X - default MFPR value with alternate function, - * pin drive strength and low power mode - */ + for most updated info):: - Examples of pin configurations are: + /* + * a possible MFP configuration is represented by a 32-bit integer + * + * bit 0.. 9 - MFP Pin Number (1024 Pins Maximum) + * bit 10..12 - Alternate Function Selection + * bit 13..15 - Drive Strength + * bit 16..18 - Low Power Mode State + * bit 19..20 - Low Power Mode Edge Detection + * bit 21..22 - Run Mode Pull State + * + * to facilitate the definition, the following macros are provided + * + * MFP_CFG_DEFAULT - default MFP configuration value, with + * alternate function = 0, + * drive strength = fast 3mA (MFP_DS03X) + * low power mode = default + * edge detection = none + * + * MFP_CFG - default MFPR value with alternate function + * MFP_CFG_DRV - default MFPR value with alternate function and + * pin drive strength + * MFP_CFG_LPM - default MFPR value with alternate function and + * low power mode + * MFP_CFG_X - default MFPR value with alternate function, + * pin drive strength and low power mode + */ - #define GPIO94_SSP3_RXD MFP_CFG_X(GPIO94, AF1, DS08X, FLOAT) + Examples of pin configurations are:: + + #define GPIO94_SSP3_RXD MFP_CFG_X(GPIO94, AF1, DS08X, FLOAT) which reads GPIO94 can be configured as SSP3_RXD, with alternate function selection of 1, driving strength of 0b101, and a float state in low power @@ -272,8 +274,8 @@ make them effective there-after. do so, simply because this default setting is usually carefully encoded, and is supposed to work in most cases. - Register Settings - ----------------- +Register Settings +----------------- Register settings on PXA3xx for a pin configuration is actually very straight-forward, most bits can be converted directly into MFPR value diff --git a/Documentation/arm/SA1100/ADSBitsy b/Documentation/arm/sa1100/adsbitsy.rst similarity index 90% rename from Documentation/arm/SA1100/ADSBitsy rename to Documentation/arm/sa1100/adsbitsy.rst index f9f62e8c0719..c179cb26b682 100644 --- a/Documentation/arm/SA1100/ADSBitsy +++ b/Documentation/arm/sa1100/adsbitsy.rst @@ -1,4 +1,7 @@ +=============================== ADS Bitsy Single Board Computer +=============================== + (It is different from Bitsy(iPAQ) of Compaq) For more details, contact Applied Data Systems or see @@ -15,7 +18,9 @@ The kernel zImage is linked to be loaded and executed at 0xc0400000. Linux can be used with the ADS BootLoader that ships with the newer rev boards. See their documentation on how to load Linux. -Supported peripherals: +Supported peripherals +===================== + - SA1100 LCD frame buffer (8/16bpp...sort of) - SA1111 USB Master - SA1100 serial port @@ -25,10 +30,13 @@ Supported peripherals: - serial ports (ttyS[0-2]) - ttyS0 is default for serial console -To do: +To do +===== + - everything else! :-) -Notes: +Notes +===== - The flash on board is divided into 3 partitions. You should be careful to use flash on board. diff --git a/Documentation/arm/SA1100/Assabet b/Documentation/arm/sa1100/assabet.rst similarity index 62% rename from Documentation/arm/SA1100/Assabet rename to Documentation/arm/sa1100/assabet.rst index e08a6739e72c..3e704831c311 100644 --- a/Documentation/arm/SA1100/Assabet +++ b/Documentation/arm/sa1100/assabet.rst @@ -1,3 +1,4 @@ +============================================ The Intel Assabet (SA-1110 evaluation) board ============================================ @@ -11,7 +12,7 @@ http://www.cs.cmu.edu/~wearable/software/assabet.html Building the kernel ------------------- -To build the kernel with current defaults: +To build the kernel with current defaults:: make assabet_config make oldconfig @@ -51,9 +52,9 @@ Brief examples on how to boot Linux with RedBoot are shown below. But first you need to have RedBoot installed in your flash memory. A known to work precompiled RedBoot binary is available from the following location: -ftp://ftp.netwinder.org/users/n/nico/ -ftp://ftp.arm.linux.org.uk/pub/linux/arm/people/nico/ -ftp://ftp.handhelds.org/pub/linux/arm/sa-1100-patches/ +- ftp://ftp.netwinder.org/users/n/nico/ +- ftp://ftp.arm.linux.org.uk/pub/linux/arm/people/nico/ +- ftp://ftp.handhelds.org/pub/linux/arm/sa-1100-patches/ Look for redboot-assabet*.tgz. Some installation infos are provided in redboot-assabet*.txt. @@ -71,12 +72,12 @@ Socket Communications Inc.), you should strongly consider using it for TFTP file transfers. You must insert it before RedBoot runs since it can't detect it dynamically. -To initialize the flash directory: +To initialize the flash directory:: fis init -f To initialize the non-volatile settings, like whether you want to use BOOTP or -a static IP address, etc, use this command: +a static IP address, etc, use this command:: fconfig -i @@ -85,15 +86,15 @@ Writing a kernel image into flash --------------------------------- First, the kernel image must be loaded into RAM. If you have the zImage file -available on a TFTP server: +available on a TFTP server:: load zImage -r -b 0x100000 -If you rather want to use Y-Modem upload over the serial port: +If you rather want to use Y-Modem upload over the serial port:: load -m ymodem -r -b 0x100000 -To write it to flash: +To write it to flash:: fis create "Linux kernel" -b 0x100000 -l 0xc0000 @@ -102,18 +103,18 @@ Booting the kernel ------------------ The kernel still requires a filesystem to boot. A ramdisk image can be loaded -as follows: +as follows:: load ramdisk_image.gz -r -b 0x800000 Again, Y-Modem upload can be used instead of TFTP by replacing the file name by '-y ymodem'. -Now the kernel can be retrieved from flash like this: +Now the kernel can be retrieved from flash like this:: fis load "Linux kernel" -or loaded as described previously. To boot the kernel: +or loaded as described previously. To boot the kernel:: exec -b 0x100000 -l 0xc0000 @@ -134,35 +135,35 @@ creating JFFS/JFFS2 images is available from the same site. For instance, a sample JFFS2 image can be retrieved from the same FTP sites mentioned below for the precompiled RedBoot image. -To load this file: +To load this file:: load sample_img.jffs2 -r -b 0x100000 -The result should look like: +The result should look like:: -RedBoot> load sample_img.jffs2 -r -b 0x100000 -Raw file loaded 0x00100000-0x00377424 + RedBoot> load sample_img.jffs2 -r -b 0x100000 + Raw file loaded 0x00100000-0x00377424 -Now we must know the size of the unallocated flash: +Now we must know the size of the unallocated flash:: fis free -Result: +Result:: -RedBoot> fis free - 0x500E0000 .. 0x503C0000 + RedBoot> fis free + 0x500E0000 .. 0x503C0000 The values above may be different depending on the size of the filesystem and the type of flash. See their usage below as an example and take care of substituting yours appropriately. -We must determine some values: +We must determine some values:: -size of unallocated flash: 0x503c0000 - 0x500e0000 = 0x2e0000 -size of the filesystem image: 0x00377424 - 0x00100000 = 0x277424 + size of unallocated flash: 0x503c0000 - 0x500e0000 = 0x2e0000 + size of the filesystem image: 0x00377424 - 0x00100000 = 0x277424 We want to fit the filesystem image of course, but we also want to give it all -the remaining flash space as well. To write it: +the remaining flash space as well. To write it:: fis unlock -f 0x500E0000 -l 0x2e0000 fis erase -f 0x500E0000 -l 0x2e0000 @@ -171,32 +172,32 @@ the remaining flash space as well. To write it: Now the filesystem is associated to a MTD "partition" once Linux has discovered what they are in the boot process. From Redboot, the 'fis list' command -displays them: +displays them:: -RedBoot> fis list -Name FLASH addr Mem addr Length Entry point -RedBoot 0x50000000 0x50000000 0x00020000 0x00000000 -RedBoot config 0x503C0000 0x503C0000 0x00020000 0x00000000 -FIS directory 0x503E0000 0x503E0000 0x00020000 0x00000000 -Linux kernel 0x50020000 0x00100000 0x000C0000 0x00000000 -JFFS2 0x500E0000 0x500E0000 0x002E0000 0x00000000 + RedBoot> fis list + Name FLASH addr Mem addr Length Entry point + RedBoot 0x50000000 0x50000000 0x00020000 0x00000000 + RedBoot config 0x503C0000 0x503C0000 0x00020000 0x00000000 + FIS directory 0x503E0000 0x503E0000 0x00020000 0x00000000 + Linux kernel 0x50020000 0x00100000 0x000C0000 0x00000000 + JFFS2 0x500E0000 0x500E0000 0x002E0000 0x00000000 -However Linux should display something like: +However Linux should display something like:: -SA1100 flash: probing 32-bit flash bus -SA1100 flash: Found 2 x16 devices at 0x0 in 32-bit mode -Using RedBoot partition definition -Creating 5 MTD partitions on "SA1100 flash": -0x00000000-0x00020000 : "RedBoot" -0x00020000-0x000e0000 : "Linux kernel" -0x000e0000-0x003c0000 : "JFFS2" -0x003c0000-0x003e0000 : "RedBoot config" -0x003e0000-0x00400000 : "FIS directory" + SA1100 flash: probing 32-bit flash bus + SA1100 flash: Found 2 x16 devices at 0x0 in 32-bit mode + Using RedBoot partition definition + Creating 5 MTD partitions on "SA1100 flash": + 0x00000000-0x00020000 : "RedBoot" + 0x00020000-0x000e0000 : "Linux kernel" + 0x000e0000-0x003c0000 : "JFFS2" + 0x003c0000-0x003e0000 : "RedBoot config" + 0x003e0000-0x00400000 : "FIS directory" What's important here is the position of the partition we are interested in, which is the third one. Within Linux, this correspond to /dev/mtdblock2. Therefore to boot Linux with the kernel and its root filesystem in flash, we -need this RedBoot command: +need this RedBoot command:: fis load "Linux kernel" exec -b 0x100000 -l 0xc0000 -c "root=/dev/mtdblock2" @@ -218,21 +219,21 @@ time the Assabet is rebooted. Therefore it's possible to automate the boot process using RedBoot's scripting capability. For example, I use this to boot Linux with both the kernel and the ramdisk -images retrieved from a TFTP server on the network: +images retrieved from a TFTP server on the network:: -RedBoot> fconfig -Run script at boot: false true -Boot script: -Enter script, terminate with empty line ->> load zImage -r -b 0x100000 ->> load ramdisk_ks.gz -r -b 0x800000 ->> exec -b 0x100000 -l 0xc0000 ->> -Boot script timeout (1000ms resolution): 3 -Use BOOTP for network configuration: true -GDB connection port: 9000 -Network debug at boot time: false -Update RedBoot non-volatile configuration - are you sure (y/n)? y + RedBoot> fconfig + Run script at boot: false true + Boot script: + Enter script, terminate with empty line + >> load zImage -r -b 0x100000 + >> load ramdisk_ks.gz -r -b 0x800000 + >> exec -b 0x100000 -l 0xc0000 + >> + Boot script timeout (1000ms resolution): 3 + Use BOOTP for network configuration: true + GDB connection port: 9000 + Network debug at boot time: false + Update RedBoot non-volatile configuration - are you sure (y/n)? y Then, rebooting the Assabet is just a matter of waiting for the login prompt. @@ -240,6 +241,7 @@ Then, rebooting the Assabet is just a matter of waiting for the login prompt. Nicolas Pitre nico@fluxnic.net + June 12, 2001 @@ -249,52 +251,51 @@ Status of peripherals in -rmk tree (updated 14/10/2001) Assabet: Serial ports: Radio: TX, RX, CTS, DSR, DCD, RI - PM: Not tested. - COM: TX, RX, CTS, DSR, DCD, RTS, DTR, PM - PM: Not tested. - I2C: Implemented, not fully tested. - L3: Fully tested, pass. - PM: Not tested. + - PM: Not tested. + - COM: TX, RX, CTS, DSR, DCD, RTS, DTR, PM + - PM: Not tested. + - I2C: Implemented, not fully tested. + - L3: Fully tested, pass. + - PM: Not tested. Video: - LCD: Fully tested. PM - (LCD doesn't like being blanked with - neponset connected) - Video out: Not fully + - LCD: Fully tested. PM + + (LCD doesn't like being blanked with neponset connected) + + - Video out: Not fully Audio: UDA1341: - Playback: Fully tested, pass. - Record: Implemented, not tested. - PM: Not tested. + - Playback: Fully tested, pass. + - Record: Implemented, not tested. + - PM: Not tested. UCB1200: - Audio play: Implemented, not heavily tested. - Audio rec: Implemented, not heavily tested. - Telco audio play: Implemented, not heavily tested. - Telco audio rec: Implemented, not heavily tested. - POTS control: No - Touchscreen: Yes - PM: Not tested. + - Audio play: Implemented, not heavily tested. + - Audio rec: Implemented, not heavily tested. + - Telco audio play: Implemented, not heavily tested. + - Telco audio rec: Implemented, not heavily tested. + - POTS control: No + - Touchscreen: Yes + - PM: Not tested. Other: - PCMCIA: - LPE: Fully tested, pass. - USB: No - IRDA: - SIR: Fully tested, pass. - FIR: Fully tested, pass. - PM: Not tested. + - PCMCIA: + - LPE: Fully tested, pass. + - USB: No + - IRDA: + - SIR: Fully tested, pass. + - FIR: Fully tested, pass. + - PM: Not tested. Neponset: Serial ports: - COM1,2: TX, RX, CTS, DSR, DCD, RTS, DTR - PM: Not tested. - USB: Implemented, not heavily tested. - PCMCIA: Implemented, not heavily tested. - PM: Not tested. - CF: Implemented, not heavily tested. - PM: Not tested. + - COM1,2: TX, RX, CTS, DSR, DCD, RTS, DTR + - PM: Not tested. + - USB: Implemented, not heavily tested. + - PCMCIA: Implemented, not heavily tested. + - CF: Implemented, not heavily tested. + - PM: Not tested. More stuff can be found in the -np (Nicolas Pitre's) tree. - diff --git a/Documentation/arm/SA1100/Brutus b/Documentation/arm/sa1100/brutus.rst similarity index 75% rename from Documentation/arm/SA1100/Brutus rename to Documentation/arm/sa1100/brutus.rst index 6a3aa95e9bfd..e1a23bee6d44 100644 --- a/Documentation/arm/SA1100/Brutus +++ b/Documentation/arm/sa1100/brutus.rst @@ -1,9 +1,13 @@ -Brutus is an evaluation platform for the SA1100 manufactured by Intel. +====== +Brutus +====== + +Brutus is an evaluation platform for the SA1100 manufactured by Intel. For more details, see: http://developer.intel.com -To compile for Brutus, you must issue the following commands: +To compile for Brutus, you must issue the following commands:: make brutus_config make config @@ -16,25 +20,23 @@ must be loaded at 0xc0008000 in Brutus's memory and execution started at entry. But prior to execute the kernel, a ramdisk image must also be loaded in -memory. Use memory address 0xd8000000 for this. Note that the file +memory. Use memory address 0xd8000000 for this. Note that the file containing the (compressed) ramdisk image must not exceed 4 MB. Typically, you'll need angelboot to load the kernel. -The following angelboot.opt file should be used: +The following angelboot.opt file should be used:: ------ begin angelboot.opt ----- -base 0xc0008000 -entry 0xc0008000 -r0 0x00000000 -r1 0x00000010 -device /dev/ttyS0 -options "9600 8N1" -baud 115200 -otherfile ramdisk_img.gz -otherbase 0xd8000000 ------ end angelboot.opt ----- + base 0xc0008000 + entry 0xc0008000 + r0 0x00000000 + r1 0x00000010 + device /dev/ttyS0 + options "9600 8N1" + baud 115200 + otherfile ramdisk_img.gz + otherbase 0xd8000000 -Then load the kernel and ramdisk with: +Then load the kernel and ramdisk with:: angelboot -f angelboot.opt zImage @@ -44,14 +46,16 @@ console is provided through the second Brutus serial port. To access it, you may use minicom configured with /dev/ttyS1, 9600 baud, 8N1, no flow control. -Currently supported: +Currently supported +=================== + - RS232 serial ports - audio output - LCD screen - keyboard - -The actual Brutus support may not be complete without extra patches. -If such patches exist, they should be found from + +The actual Brutus support may not be complete without extra patches. +If such patches exist, they should be found from ftp.netwinder.org/users/n/nico. A full PCMCIA support is still missing, although it's possible to hack @@ -63,4 +67,3 @@ Any contribution is welcome. Please send patches to nico@fluxnic.net Have Fun ! - diff --git a/Documentation/arm/SA1100/CERF b/Documentation/arm/sa1100/cerf.rst similarity index 91% rename from Documentation/arm/SA1100/CERF rename to Documentation/arm/sa1100/cerf.rst index b3d845301ef1..7fa71b609bf9 100644 --- a/Documentation/arm/SA1100/CERF +++ b/Documentation/arm/sa1100/cerf.rst @@ -1,3 +1,7 @@ +============== +CerfBoard/Cube +============== + *** The StrongARM version of the CerfBoard/Cube has been discontinued *** The Intrinsyc CerfBoard is a StrongARM 1110-based computer on a board @@ -9,7 +13,9 @@ Intrinsyc website, http://www.intrinsyc.com. This document describes the support in the Linux kernel for the Intrinsyc CerfBoard. -Supported in this version: +Supported in this version +========================= + - CompactFlash+ slot (select PCMCIA in General Setup and any options that may be required) - Onboard Crystal CS8900 Ethernet controller (Cerf CS8900A support in @@ -19,7 +25,7 @@ Supported in this version: In order to get this kernel onto your Cerf, you need a server that runs both BOOTP and TFTP. Detailed instructions should have come with your evaluation kit on how to use the bootloader. This series of commands -will suffice: +will suffice:: make ARCH=arm CROSS_COMPILE=arm-linux- cerfcube_defconfig make ARCH=arm CROSS_COMPILE=arm-linux- zImage diff --git a/Documentation/arm/sa1100/freebird.rst b/Documentation/arm/sa1100/freebird.rst new file mode 100644 index 000000000000..81043d0c6d64 --- /dev/null +++ b/Documentation/arm/sa1100/freebird.rst @@ -0,0 +1,25 @@ +======== +Freebird +======== + +Freebird-1.1 is produced by Legend(C), Inc. +`http://web.archive.org/web/*/http://www.legend.com.cn` +and software/linux maintained by Coventive(C), Inc. +(http://www.coventive.com) + +Based on the Nicolas's strongarm kernel tree. + +Maintainer: + +Chester Kuo + - + - + +Author: + +- Tim wu +- CIH +- Eric Peng +- Jeff Lee +- Allen Cheng +- Tony Liu diff --git a/Documentation/arm/SA1100/GraphicsClient b/Documentation/arm/sa1100/graphicsclient.rst similarity index 87% rename from Documentation/arm/SA1100/GraphicsClient rename to Documentation/arm/sa1100/graphicsclient.rst index 867bb35943af..a73d61c3ce91 100644 --- a/Documentation/arm/SA1100/GraphicsClient +++ b/Documentation/arm/sa1100/graphicsclient.rst @@ -1,9 +1,11 @@ +============================================= ADS GraphicsClient Plus Single Board Computer +============================================= For more details, contact Applied Data Systems or see http://www.applieddata.net/products.html -The original Linux support for this product has been provided by +The original Linux support for this product has been provided by Nicolas Pitre . Continued development work by Woojung Huh @@ -14,8 +16,8 @@ board supports MTD/JFFS, so you could also mount something on there. Use 'make graphicsclient_config' before any 'make config'. This will set up defaults for GraphicsClient Plus support. -The kernel zImage is linked to be loaded and executed at 0xc0200000. -Also the following registers should have the specified values upon entry: +The kernel zImage is linked to be loaded and executed at 0xc0200000. +Also the following registers should have the specified values upon entry:: r0 = 0 r1 = 29 (this is the GraphicsClient architecture number) @@ -31,23 +33,21 @@ as outlined below. In any case, if you're planning on deploying something en masse, you should probably get the newer board. If using Angel on the older boards, here is a typical angel.opt option file -if the kernel is loaded through the Angel Debug Monitor: +if the kernel is loaded through the Angel Debug Monitor:: ------ begin angelboot.opt ----- -base 0xc0200000 -entry 0xc0200000 -r0 0x00000000 -r1 0x0000001d -device /dev/ttyS1 -options "38400 8N1" -baud 115200 -#otherfile ramdisk.gz -#otherbase 0xc0800000 -exec minicom ------ end angelboot.opt ----- + base 0xc0200000 + entry 0xc0200000 + r0 0x00000000 + r1 0x0000001d + device /dev/ttyS1 + options "38400 8N1" + baud 115200 + #otherfile ramdisk.gz + #otherbase 0xc0800000 + exec minicom Then the kernel (and ramdisk if otherfile/otherbase lines above are -uncommented) would be loaded with: +uncommented) would be loaded with:: angelboot -f angelboot.opt zImage @@ -59,7 +59,9 @@ If any other bootloader is used, ensure it accomplish the same, especially for r0/r1 register values before jumping into the kernel. -Supported peripherals: +Supported peripherals +===================== + - SA1100 LCD frame buffer (8/16bpp...sort of) - on-board SMC 92C96 ethernet NIC - SA1100 serial port @@ -74,11 +76,14 @@ Supported peripherals: See http://www.eurotech-inc.com/linux-sbc.asp for IOCTL documentation and example user space code. ps/2 keybd is multiplexed through this driver -To do: +To do +===== + - UCB1200 audio with new ucb_generic layer - everything else! :-) -Notes: +Notes +===== - The flash on board is divided into 3 partitions. mtd0 is where the ADS boot ROM and zImage is stored. It's been marked as @@ -95,4 +100,3 @@ Notes: fixed soon. Any contribution can be sent to nico@fluxnic.net and will be greatly welcome! - diff --git a/Documentation/arm/SA1100/GraphicsMaster b/Documentation/arm/sa1100/graphicsmaster.rst similarity index 92% rename from Documentation/arm/SA1100/GraphicsMaster rename to Documentation/arm/sa1100/graphicsmaster.rst index 9145088a0ba2..e39892514f0c 100644 --- a/Documentation/arm/SA1100/GraphicsMaster +++ b/Documentation/arm/sa1100/graphicsmaster.rst @@ -1,4 +1,6 @@ +======================================== ADS GraphicsMaster Single Board Computer +======================================== For more details, contact Applied Data Systems or see http://www.applieddata.net/products.html @@ -15,7 +17,9 @@ The kernel zImage is linked to be loaded and executed at 0xc0400000. Linux can be used with the ADS BootLoader that ships with the newer rev boards. See their documentation on how to load Linux. -Supported peripherals: +Supported peripherals +===================== + - SA1100 LCD frame buffer (8/16bpp...sort of) - SA1111 USB Master - on-board SMC 92C96 ethernet NIC @@ -31,10 +35,13 @@ Supported peripherals: See http://www.eurotech-inc.com/linux-sbc.asp for IOCTL documentation and example user space code. ps/2 keybd is multiplexed through this driver -To do: +To do +===== + - everything else! :-) -Notes: +Notes +===== - The flash on board is divided into 3 partitions. mtd0 is where the zImage is stored. It's been marked as read-only to keep you diff --git a/Documentation/arm/SA1100/HUW_WEBPANEL b/Documentation/arm/sa1100/huw_webpanel.rst similarity index 78% rename from Documentation/arm/SA1100/HUW_WEBPANEL rename to Documentation/arm/sa1100/huw_webpanel.rst index fd56b48d4833..1dc7ccb165f0 100644 --- a/Documentation/arm/SA1100/HUW_WEBPANEL +++ b/Documentation/arm/sa1100/huw_webpanel.rst @@ -1,9 +1,14 @@ +======================= +Hoeft & Wessel Webpanel +======================= + The HUW_WEBPANEL is a product of the german company Hoeft & Wessel AG If you want more information, please visit http://www.hoeft-wessel.de -To build the kernel: +To build the kernel:: + make huw_webpanel_config make oldconfig [accept all defaults] @@ -14,4 +19,3 @@ Roman Jordan jor@hoeft-wessel.de Christoph Schulz schu@hoeft-wessel.de 2000/12/18/ - diff --git a/Documentation/arm/sa1100/index.rst b/Documentation/arm/sa1100/index.rst new file mode 100644 index 000000000000..fb2385b3accf --- /dev/null +++ b/Documentation/arm/sa1100/index.rst @@ -0,0 +1,23 @@ +==================== +Intel StrongARM 1100 +==================== + +.. toctree:: + :maxdepth: 1 + + adsbitsy + assabet + brutus + cerf + freebird + graphicsclient + graphicsmaster + huw_webpanel + itsy + lart + nanoengine + pangolin + pleb + serial_uart + tifon + yopy diff --git a/Documentation/arm/SA1100/Itsy b/Documentation/arm/sa1100/itsy.rst similarity index 88% rename from Documentation/arm/SA1100/Itsy rename to Documentation/arm/sa1100/itsy.rst index 44b94997fa0d..f49896ba3ef1 100644 --- a/Documentation/arm/SA1100/Itsy +++ b/Documentation/arm/sa1100/itsy.rst @@ -1,3 +1,7 @@ +==== +Itsy +==== + Itsy is a research project done by the Western Research Lab, and Systems Research Center in Palo Alto, CA. The Itsy project is one of several research projects at Compaq that are related to pocket computing. @@ -7,6 +11,7 @@ For more information, see: http://www.hpl.hp.com/downloads/crl/itsy/ Notes on initial 2.4 Itsy support (8/27/2000) : + The port was done on an Itsy version 1.5 machine with a daughtercard with 64 Meg of DRAM and 32 Meg of Flash. The initial work includes support for serial console (to see what you're doing). No other devices have been @@ -18,8 +23,10 @@ Finally, you will need to cd to arch/arm/boot/tools and execute a make there to build the params-itsy program used to boot the kernel. In order to install the port of 2.4 to the itsy, You will need to set the -configuration parameters in the monitor as follows: -Arg 1:0x08340000, Arg2: 0xC0000000, Arg3:18 (0x12), Arg4:0 +configuration parameters in the monitor as follows:: + + Arg 1:0x08340000, Arg2: 0xC0000000, Arg3:18 (0x12), Arg4:0 + Make sure the start-routine address is set to 0x00060000. Next, flash the params-itsy program to 0x00060000 ("p 1 0x00060000" in the @@ -29,7 +36,8 @@ flash menu) Flash the kernel in arch/arm/boot/zImage into 0x08340000 handhelds.org. The serial connection we established was at: - 8-bit data, no parity, 1 stop bit(s), 115200.00 b/s. in the monitor, in the + +8-bit data, no parity, 1 stop bit(s), 115200.00 b/s. in the monitor, in the params-itsy program, and in the kernel itself. This can be changed, but not easily. The monitor parameters are easily changed, the params program setup is assembly outl's, and the kernel is a configuration item specific to diff --git a/Documentation/arm/SA1100/LART b/Documentation/arm/sa1100/lart.rst similarity index 90% rename from Documentation/arm/SA1100/LART rename to Documentation/arm/sa1100/lart.rst index 6d412b685598..94c0568d1095 100644 --- a/Documentation/arm/SA1100/LART +++ b/Documentation/arm/sa1100/lart.rst @@ -1,5 +1,6 @@ +==================================== Linux Advanced Radio Terminal (LART) ------------------------------------- +==================================== The LART is a small (7.5 x 10cm) SA-1100 board, designed for embedded applications. It has 32 MB DRAM, 4MB Flash ROM, double RS232 and all diff --git a/Documentation/arm/SA1100/nanoEngine b/Documentation/arm/sa1100/nanoengine.rst similarity index 74% rename from Documentation/arm/SA1100/nanoEngine rename to Documentation/arm/sa1100/nanoengine.rst index 48a7934f95f6..47f1a14cf98a 100644 --- a/Documentation/arm/SA1100/nanoEngine +++ b/Documentation/arm/sa1100/nanoengine.rst @@ -1,11 +1,11 @@ +========== nanoEngine ----------- +========== -"nanoEngine" is a SA1110 based single board computer from +"nanoEngine" is a SA1110 based single board computer from Bright Star Engineering Inc. See www.brightstareng.com/arm for more info. (Ref: Stuart Adams ) Also visit Larry Doolittle's "Linux for the nanoEngine" site: http://www.brightstareng.com/arm/nanoeng.htm - diff --git a/Documentation/arm/SA1100/Pangolin b/Documentation/arm/sa1100/pangolin.rst similarity index 81% rename from Documentation/arm/SA1100/Pangolin rename to Documentation/arm/sa1100/pangolin.rst index 077a6120e129..f0c5c1618553 100644 --- a/Documentation/arm/SA1100/Pangolin +++ b/Documentation/arm/sa1100/pangolin.rst @@ -1,16 +1,22 @@ +======== +Pangolin +======== + Pangolin is a StrongARM 1110-based evaluation platform produced by Dialogue Technology (http://www.dialogue.com.tw/). It has EISA slots for ease of configuration with SDRAM/Flash memory card, USB/Serial/Audio card, Compact Flash card, PCMCIA/IDE card and TFT-LCD card. -To compile for Pangolin, you must issue the following commands: +To compile for Pangolin, you must issue the following commands:: make pangolin_config make oldconfig make zImage -Supported peripherals: +Supported peripherals +===================== + - SA1110 serial port (UART1/UART2/UART3) - flash memory access - compact flash driver diff --git a/Documentation/arm/SA1100/PLEB b/Documentation/arm/sa1100/pleb.rst similarity index 95% rename from Documentation/arm/SA1100/PLEB rename to Documentation/arm/sa1100/pleb.rst index b9c8a631a351..d5b732967aa3 100644 --- a/Documentation/arm/SA1100/PLEB +++ b/Documentation/arm/sa1100/pleb.rst @@ -1,3 +1,7 @@ +==== +PLEB +==== + The PLEB project was started as a student initiative at the School of Computer Science and Engineering, University of New South Wales to make a pocket computer capable of running the Linux Kernel. @@ -7,5 +11,3 @@ PLEB support has yet to be fully integrated. For more information, see: http://www.cse.unsw.edu.au - - diff --git a/Documentation/arm/sa1100/serial_uart.rst b/Documentation/arm/sa1100/serial_uart.rst new file mode 100644 index 000000000000..ea983642b9be --- /dev/null +++ b/Documentation/arm/sa1100/serial_uart.rst @@ -0,0 +1,51 @@ +================== +SA1100 serial port +================== + +The SA1100 serial port had its major/minor numbers officially assigned:: + + > Date: Sun, 24 Sep 2000 21:40:27 -0700 + > From: H. Peter Anvin + > To: Nicolas Pitre + > Cc: Device List Maintainer + > Subject: Re: device + > + > Okay. Note that device numbers 204 and 205 are used for "low density + > serial devices", so you will have a range of minors on those majors (the + > tty device layer handles this just fine, so you don't have to worry about + > doing anything special.) + > + > So your assignments are: + > + > 204 char Low-density serial ports + > 5 = /dev/ttySA0 SA1100 builtin serial port 0 + > 6 = /dev/ttySA1 SA1100 builtin serial port 1 + > 7 = /dev/ttySA2 SA1100 builtin serial port 2 + > + > 205 char Low-density serial ports (alternate device) + > 5 = /dev/cusa0 Callout device for ttySA0 + > 6 = /dev/cusa1 Callout device for ttySA1 + > 7 = /dev/cusa2 Callout device for ttySA2 + > + +You must create those inodes in /dev on the root filesystem used +by your SA1100-based device:: + + mknod ttySA0 c 204 5 + mknod ttySA1 c 204 6 + mknod ttySA2 c 204 7 + mknod cusa0 c 205 5 + mknod cusa1 c 205 6 + mknod cusa2 c 205 7 + +In addition to the creation of the appropriate device nodes above, you +must ensure your user space applications make use of the correct device +name. The classic example is the content of the /etc/inittab file where +you might have a getty process started on ttyS0. + +In this case: + +- replace occurrences of ttyS0 with ttySA0, ttyS1 with ttySA1, etc. + +- don't forget to add 'ttySA0', 'console', or the appropriate tty name + in /etc/securetty for root to be allowed to login as well. diff --git a/Documentation/arm/SA1100/Tifon b/Documentation/arm/sa1100/tifon.rst similarity index 88% rename from Documentation/arm/SA1100/Tifon rename to Documentation/arm/sa1100/tifon.rst index dd1934d9c851..c26e910b9ea7 100644 --- a/Documentation/arm/SA1100/Tifon +++ b/Documentation/arm/sa1100/tifon.rst @@ -1,7 +1,7 @@ +===== Tifon ------ +===== More info has to come... Contact: Peter Danielsson - diff --git a/Documentation/arm/SA1100/Yopy b/Documentation/arm/sa1100/yopy.rst similarity index 74% rename from Documentation/arm/SA1100/Yopy rename to Documentation/arm/sa1100/yopy.rst index e14f16d836ac..5b35a5f61a44 100644 --- a/Documentation/arm/SA1100/Yopy +++ b/Documentation/arm/sa1100/yopy.rst @@ -1,2 +1,5 @@ -See http://www.yopydeveloper.org for more. +==== +Yopy +==== +See http://www.yopydeveloper.org for more. diff --git a/Documentation/arm/Samsung-S3C24XX/CPUfreq.txt b/Documentation/arm/samsung-s3c24xx/cpufreq.rst similarity index 96% rename from Documentation/arm/Samsung-S3C24XX/CPUfreq.txt rename to Documentation/arm/samsung-s3c24xx/cpufreq.rst index fa968aa99d67..2ddc26c03b1f 100644 --- a/Documentation/arm/Samsung-S3C24XX/CPUfreq.txt +++ b/Documentation/arm/samsung-s3c24xx/cpufreq.rst @@ -1,5 +1,6 @@ - S3C24XX CPUfreq support - ======================= +======================= +S3C24XX CPUfreq support +======================= Introduction ------------ diff --git a/Documentation/arm/Samsung-S3C24XX/EB2410ITX.txt b/Documentation/arm/samsung-s3c24xx/eb2410itx.rst similarity index 92% rename from Documentation/arm/Samsung-S3C24XX/EB2410ITX.txt rename to Documentation/arm/samsung-s3c24xx/eb2410itx.rst index b87292e05f2f..7863c93652f8 100644 --- a/Documentation/arm/Samsung-S3C24XX/EB2410ITX.txt +++ b/Documentation/arm/samsung-s3c24xx/eb2410itx.rst @@ -1,5 +1,6 @@ - Simtec Electronics EB2410ITX (BAST) - =================================== +=================================== +Simtec Electronics EB2410ITX (BAST) +=================================== http://www.simtec.co.uk/products/EB2410ITX/ diff --git a/Documentation/arm/Samsung-S3C24XX/GPIO.txt b/Documentation/arm/samsung-s3c24xx/gpio.rst similarity index 89% rename from Documentation/arm/Samsung-S3C24XX/GPIO.txt rename to Documentation/arm/samsung-s3c24xx/gpio.rst index e8f918b96123..f7c3d7d011a2 100644 --- a/Documentation/arm/Samsung-S3C24XX/GPIO.txt +++ b/Documentation/arm/samsung-s3c24xx/gpio.rst @@ -1,5 +1,6 @@ - S3C24XX GPIO Control - ==================== +==================== +S3C24XX GPIO Control +==================== Introduction ------------ @@ -12,7 +13,7 @@ Introduction of the s3c2410 GPIO system, please read the Samsung provided data-sheet/users manual to find out the complete list. - See Documentation/arm/Samsung/GPIO.txt for the core implementation. + See Documentation/arm/samsung/gpio.rst for the core implementation. GPIOLIB @@ -26,16 +27,16 @@ GPIOLIB listed below will be removed (they may be marked as __deprecated in the near future). - The following functions now either have a s3c_ specific variant + The following functions now either have a `s3c_` specific variant or are merged into gpiolib. See the definitions in arch/arm/plat-samsung/include/plat/gpio-cfg.h: - s3c2410_gpio_setpin() gpio_set_value() or gpio_direction_output() - s3c2410_gpio_getpin() gpio_get_value() or gpio_direction_input() - s3c2410_gpio_getirq() gpio_to_irq() - s3c2410_gpio_cfgpin() s3c_gpio_cfgpin() - s3c2410_gpio_getcfg() s3c_gpio_getcfg() - s3c2410_gpio_pullup() s3c_gpio_setpull() + - s3c2410_gpio_setpin() gpio_set_value() or gpio_direction_output() + - s3c2410_gpio_getpin() gpio_get_value() or gpio_direction_input() + - s3c2410_gpio_getirq() gpio_to_irq() + - s3c2410_gpio_cfgpin() s3c_gpio_cfgpin() + - s3c2410_gpio_getcfg() s3c_gpio_getcfg() + - s3c2410_gpio_pullup() s3c_gpio_setpull() GPIOLIB conversion @@ -77,7 +78,7 @@ out s3c2410 API, then here are some notes on the process. 6) s3c2410_gpio_getirq() should be directly replaceable with the gpio_to_irq() call. -The s3c2410_gpio and gpio_ calls have always operated on the same gpio +The s3c2410_gpio and `gpio_` calls have always operated on the same gpio numberspace, so there is no problem with converting the gpio numbering between the calls. diff --git a/Documentation/arm/Samsung-S3C24XX/H1940.txt b/Documentation/arm/samsung-s3c24xx/h1940.rst similarity index 94% rename from Documentation/arm/Samsung-S3C24XX/H1940.txt rename to Documentation/arm/samsung-s3c24xx/h1940.rst index b738859b1fc0..62a562c178e3 100644 --- a/Documentation/arm/Samsung-S3C24XX/H1940.txt +++ b/Documentation/arm/samsung-s3c24xx/h1940.rst @@ -1,5 +1,6 @@ - HP IPAQ H1940 - ============= +============= +HP IPAQ H1940 +============= http://www.handhelds.org/projects/h1940.html diff --git a/Documentation/arm/samsung-s3c24xx/index.rst b/Documentation/arm/samsung-s3c24xx/index.rst new file mode 100644 index 000000000000..6c7b241cbf37 --- /dev/null +++ b/Documentation/arm/samsung-s3c24xx/index.rst @@ -0,0 +1,18 @@ +========================== +Samsung S3C24XX SoC Family +========================== + +.. toctree:: + :maxdepth: 1 + + h1940 + gpio + cpufreq + suspend + usb-host + s3c2412 + eb2410itx + nand + smdk2440 + s3c2413 + overview diff --git a/Documentation/arm/Samsung-S3C24XX/NAND.txt b/Documentation/arm/samsung-s3c24xx/nand.rst similarity index 92% rename from Documentation/arm/Samsung-S3C24XX/NAND.txt rename to Documentation/arm/samsung-s3c24xx/nand.rst index bc478a3409b8..938995694ee7 100644 --- a/Documentation/arm/Samsung-S3C24XX/NAND.txt +++ b/Documentation/arm/samsung-s3c24xx/nand.rst @@ -1,5 +1,6 @@ - S3C24XX NAND Support - ==================== +==================== +S3C24XX NAND Support +==================== Introduction ------------ @@ -27,4 +28,3 @@ Document Author --------------- Ben Dooks, Copyright 2007 Simtec Electronics - diff --git a/Documentation/arm/Samsung-S3C24XX/Overview.txt b/Documentation/arm/samsung-s3c24xx/overview.rst similarity index 94% rename from Documentation/arm/Samsung-S3C24XX/Overview.txt rename to Documentation/arm/samsung-s3c24xx/overview.rst index 00d3c3141e21..e9a1dc7276b5 100644 --- a/Documentation/arm/Samsung-S3C24XX/Overview.txt +++ b/Documentation/arm/samsung-s3c24xx/overview.rst @@ -1,5 +1,6 @@ - S3C24XX ARM Linux Overview - ========================== +========================== +S3C24XX ARM Linux Overview +========================== @@ -182,7 +183,7 @@ NAND controller. If there are any problems the latest linux-mtd code can be found from http://www.linux-mtd.infradead.org/ - For more information see Documentation/arm/Samsung-S3C24XX/NAND.txt + For more information see Documentation/arm/samsung-s3c24xx/nand.rst SD/MMC @@ -221,8 +222,8 @@ GPIO As of v2.6.34, the move towards using gpiolib support is almost complete, and very little of the old calls are left. - See Documentation/arm/Samsung-S3C24XX/GPIO.txt for the S3C24XX specific - support and Documentation/arm/Samsung/GPIO.txt for the core Samsung + See Documentation/arm/samsung-s3c24xx/gpio.rst for the S3C24XX specific + support and Documentation/arm/samsung/gpio.rst for the core Samsung implementation. @@ -276,18 +277,18 @@ Platform Data kmalloc()s an area of memory, and copies the __initdata and then sets the relevant device's platform data. Making the function `__init` takes care of ensuring it is discarded - with the rest of the initialisation code + with the rest of the initialisation code:: - static __init void s3c24xx_xxx_set_platdata(struct xxx_data *pd) - { - struct s3c2410_xxx_mach_info *npd; + static __init void s3c24xx_xxx_set_platdata(struct xxx_data *pd) + { + struct s3c2410_xxx_mach_info *npd; npd = kmalloc(sizeof(struct s3c2410_xxx_mach_info), GFP_KERNEL); if (npd) { memcpy(npd, pd, sizeof(struct s3c2410_xxx_mach_info)); s3c_device_xxx.dev.platform_data = npd; } else { - printk(KERN_ERR "no memory for xxx platform data\n"); + printk(KERN_ERR "no memory for xxx platform data\n"); } } diff --git a/Documentation/arm/Samsung-S3C24XX/S3C2412.txt b/Documentation/arm/samsung-s3c24xx/s3c2412.rst similarity index 96% rename from Documentation/arm/Samsung-S3C24XX/S3C2412.txt rename to Documentation/arm/samsung-s3c24xx/s3c2412.rst index dc1fd362d3c1..68b985fc6bf4 100644 --- a/Documentation/arm/Samsung-S3C24XX/S3C2412.txt +++ b/Documentation/arm/samsung-s3c24xx/s3c2412.rst @@ -1,5 +1,6 @@ - S3C2412 ARM Linux Overview - ========================== +========================== +S3C2412 ARM Linux Overview +========================== Introduction ------------ diff --git a/Documentation/arm/Samsung-S3C24XX/S3C2413.txt b/Documentation/arm/samsung-s3c24xx/s3c2413.rst similarity index 77% rename from Documentation/arm/Samsung-S3C24XX/S3C2413.txt rename to Documentation/arm/samsung-s3c24xx/s3c2413.rst index 909bdc7dd7b5..1f51e207fc46 100644 --- a/Documentation/arm/Samsung-S3C24XX/S3C2413.txt +++ b/Documentation/arm/samsung-s3c24xx/s3c2413.rst @@ -1,5 +1,6 @@ - S3C2413 ARM Linux Overview - ========================== +========================== +S3C2413 ARM Linux Overview +========================== Introduction ------------ @@ -10,7 +11,7 @@ Introduction Camera Interface ---------------- +---------------- This block is currently not supported. diff --git a/Documentation/arm/Samsung-S3C24XX/SMDK2440.txt b/Documentation/arm/samsung-s3c24xx/smdk2440.rst similarity index 94% rename from Documentation/arm/Samsung-S3C24XX/SMDK2440.txt rename to Documentation/arm/samsung-s3c24xx/smdk2440.rst index 429390bd4684..524fd0b4afaf 100644 --- a/Documentation/arm/Samsung-S3C24XX/SMDK2440.txt +++ b/Documentation/arm/samsung-s3c24xx/smdk2440.rst @@ -1,5 +1,6 @@ - Samsung/Meritech SMDK2440 - ========================= +========================= +Samsung/Meritech SMDK2440 +========================= Introduction ------------ diff --git a/Documentation/arm/Samsung-S3C24XX/Suspend.txt b/Documentation/arm/samsung-s3c24xx/suspend.rst similarity index 94% rename from Documentation/arm/Samsung-S3C24XX/Suspend.txt rename to Documentation/arm/samsung-s3c24xx/suspend.rst index cb4f0c0cdf9d..b4f3ae9fe76e 100644 --- a/Documentation/arm/Samsung-S3C24XX/Suspend.txt +++ b/Documentation/arm/samsung-s3c24xx/suspend.rst @@ -1,5 +1,6 @@ - S3C24XX Suspend Support - ======================= +======================= +S3C24XX Suspend Support +======================= Introduction @@ -57,16 +58,16 @@ Machine Support and will end up initialising all compiled machines' pm init! The following is an example of code used for testing wakeup from - an falling edge on IRQ_EINT0: + an falling edge on IRQ_EINT0:: -static irqreturn_t button_irq(int irq, void *pw) -{ + static irqreturn_t button_irq(int irq, void *pw) + { return IRQ_HANDLED; -} + } -statuc void __init machine_init(void) -{ + statuc void __init machine_init(void) + { ... request_irq(IRQ_EINT0, button_irq, IRQF_TRIGGER_FALLING, @@ -75,7 +76,7 @@ statuc void __init machine_init(void) enable_irq_wake(IRQ_EINT0); s3c_pm_init(); -} + } Debugging @@ -134,4 +135,3 @@ Document Author --------------- Ben Dooks, Copyright 2004 Simtec Electronics - diff --git a/Documentation/arm/Samsung-S3C24XX/USB-Host.txt b/Documentation/arm/samsung-s3c24xx/usb-host.rst similarity index 94% rename from Documentation/arm/Samsung-S3C24XX/USB-Host.txt rename to Documentation/arm/samsung-s3c24xx/usb-host.rst index f82b1faefad5..c84268bd1884 100644 --- a/Documentation/arm/Samsung-S3C24XX/USB-Host.txt +++ b/Documentation/arm/samsung-s3c24xx/usb-host.rst @@ -1,5 +1,6 @@ - S3C24XX USB Host support - ======================== +======================== +S3C24XX USB Host support +======================== @@ -13,7 +14,7 @@ Configuration Enable at least the following kernel options: - menuconfig: + menuconfig:: Device Drivers ---> USB support ---> @@ -22,8 +23,9 @@ Configuration .config: - CONFIG_USB - CONFIG_USB_OHCI_HCD + + - CONFIG_USB + - CONFIG_USB_OHCI_HCD Once these options are configured, the standard set of USB device @@ -60,17 +62,14 @@ Platform Data The ports are numbered 0 and 1. power_control: - Called to enable or disable the power on the port. enable_oc: - Called to enable or disable the over-current monitoring. This should claim or release the resources being used to check the power condition on the port, such as an IRQ. report_oc: - The OHCI driver fills this field in for the over-current code to call when there is a change to the over-current state on an port. The ports argument is a bitmask of 1 bit per port, @@ -80,7 +79,6 @@ Platform Data ensure this is called correctly. port[x]: - This is struct describes each port, 0 or 1. The platform driver should set the flags field of each port to S3C_HCDFLG_USED if the port is enabled. diff --git a/Documentation/arm/Samsung/Bootloader-interface.txt b/Documentation/arm/samsung/bootloader-interface.rst similarity index 72% rename from Documentation/arm/Samsung/Bootloader-interface.txt rename to Documentation/arm/samsung/bootloader-interface.rst index d17ed518a7ea..a56f325dae78 100644 --- a/Documentation/arm/Samsung/Bootloader-interface.txt +++ b/Documentation/arm/samsung/bootloader-interface.rst @@ -1,7 +1,9 @@ - Interface between kernel and boot loaders on Exynos boards - ========================================================== +========================================================== +Interface between kernel and boot loaders on Exynos boards +========================================================== Author: Krzysztof Kozlowski + Date : 6 June 2015 The document tries to describe currently used interface between Linux kernel @@ -17,8 +19,10 @@ executing kernel. 1. Non-Secure mode Address: sysram_ns_base_addr + +============= ============================================ ================== Offset Value Purpose -============================================================================= +============= ============================================ ================== 0x08 exynos_cpu_resume_ns, mcpm_entry_point System suspend 0x0c 0x00000bad (Magic cookie) System suspend 0x1c exynos4_secondary_startup Secondary CPU boot @@ -27,22 +31,28 @@ Offset Value Purpose 0x24 exynos_cpu_resume_ns AFTR 0x28 + 4*cpu 0x8 (Magic cookie, Exynos3250) AFTR 0x28 0x0 or last value during resume (Exynos542x) System suspend +============= ============================================ ================== 2. Secure mode Address: sysram_base_addr + +============= ============================================ ================== Offset Value Purpose -============================================================================= +============= ============================================ ================== 0x00 exynos4_secondary_startup Secondary CPU boot 0x04 exynos4_secondary_startup (Exynos542x) Secondary CPU boot 4*cpu exynos4_secondary_startup (Exynos4412) Secondary CPU boot 0x20 exynos_cpu_resume (Exynos4210 r1.0) AFTR 0x24 0xfcba0d10 (Magic cookie, Exynos4210 r1.0) AFTR +============= ============================================ ================== Address: pmu_base_addr + +============= ============================================ ================== Offset Value Purpose -============================================================================= +============= ============================================ ================== 0x0800 exynos_cpu_resume AFTR, suspend 0x0800 mcpm_entry_point (Exynos542x with MCPM) AFTR, suspend 0x0804 0xfcba0d10 (Magic cookie) AFTR @@ -50,15 +60,18 @@ Offset Value Purpose 0x0814 exynos4_secondary_startup (Exynos4210 r1.1) Secondary CPU boot 0x0818 0xfcba0d10 (Magic cookie, Exynos4210 r1.1) AFTR 0x081C exynos_cpu_resume (Exynos4210 r1.1) AFTR - +============= ============================================ ================== 3. Other (regardless of secure/non-secure mode) Address: pmu_base_addr + +============= =============================== =============================== Offset Value Purpose -============================================================================= +============= =============================== =============================== 0x0908 Non-zero Secondary CPU boot up indicator on Exynos3250 and Exynos542x +============= =============================== =============================== 4. Glossary diff --git a/Documentation/arm/Samsung/clksrc-change-registers.awk b/Documentation/arm/samsung/clksrc-change-registers.awk similarity index 100% rename from Documentation/arm/Samsung/clksrc-change-registers.awk rename to Documentation/arm/samsung/clksrc-change-registers.awk diff --git a/Documentation/arm/Samsung/GPIO.txt b/Documentation/arm/samsung/gpio.rst similarity index 87% rename from Documentation/arm/Samsung/GPIO.txt rename to Documentation/arm/samsung/gpio.rst index 795adfd88081..5f7cadd7159e 100644 --- a/Documentation/arm/Samsung/GPIO.txt +++ b/Documentation/arm/samsung/gpio.rst @@ -1,5 +1,6 @@ - Samsung GPIO implementation - =========================== +=========================== +Samsung GPIO implementation +=========================== Introduction ------------ @@ -11,7 +12,7 @@ specific calls provided alongside the drivers/gpio core. S3C24XX (Legacy) ---------------- -See Documentation/arm/Samsung-S3C24XX/GPIO.txt for more information +See Documentation/arm/samsung-s3c24xx/gpio.rst for more information about these devices. Their implementation has been brought into line with the core samsung implementation described in this document. diff --git a/Documentation/arm/samsung/index.rst b/Documentation/arm/samsung/index.rst new file mode 100644 index 000000000000..f54d95734362 --- /dev/null +++ b/Documentation/arm/samsung/index.rst @@ -0,0 +1,10 @@ +=========== +Samsung SoC +=========== + +.. toctree:: + :maxdepth: 1 + + gpio + bootloader-interface + overview diff --git a/Documentation/arm/Samsung/Overview.txt b/Documentation/arm/samsung/overview.rst similarity index 86% rename from Documentation/arm/Samsung/Overview.txt rename to Documentation/arm/samsung/overview.rst index 8f7309bad460..e74307897416 100644 --- a/Documentation/arm/Samsung/Overview.txt +++ b/Documentation/arm/samsung/overview.rst @@ -1,5 +1,6 @@ - Samsung ARM Linux Overview - ========================== +========================== +Samsung ARM Linux Overview +========================== Introduction ------------ @@ -11,7 +12,7 @@ Introduction The currently supported SoCs are: - - S3C24XX: See Documentation/arm/Samsung-S3C24XX/Overview.txt for full list + - S3C24XX: See Documentation/arm/samsung-s3c24xx/overview.rst for full list - S3C64XX: S3C6400 and S3C6410 - S5PC110 / S5PV210 @@ -22,7 +23,7 @@ S3C24XX Systems There is still documentation in Documnetation/arm/Samsung-S3C24XX/ which deals with the architecture and drivers specific to these devices. - See Documentation/arm/Samsung-S3C24XX/Overview.txt for more information + See Documentation/arm/samsung-s3c24xx/overview.rst for more information on the implementation details and specific support. @@ -32,8 +33,10 @@ Configuration A number of configurations are supplied, as there is no current way of unifying all the SoCs into one kernel. - s5pc110_defconfig - S5PC110 specific default configuration - s5pv210_defconfig - S5PV210 specific default configuration + s5pc110_defconfig + - S5PC110 specific default configuration + s5pv210_defconfig + - S5PV210 specific default configuration Layout diff --git a/Documentation/arm/Setup b/Documentation/arm/setup.rst similarity index 87% rename from Documentation/arm/Setup rename to Documentation/arm/setup.rst index 0cb1e64bde80..8e12ef3fb9a7 100644 --- a/Documentation/arm/Setup +++ b/Documentation/arm/setup.rst @@ -1,5 +1,6 @@ +============================================= Kernel initialisation parameters on ARM Linux ---------------------------------------------- +============================================= The following document describes the kernel initialisation parameter structure, otherwise known as 'struct param_struct' which is used @@ -14,12 +15,10 @@ There are a lot of parameters listed in there, and they are described below: page_size - This parameter must be set to the page size of the machine, and will be checked by the kernel. nr_pages - This is the total number of pages of memory in the system. If the memory is banked, then this should contain the total number of pages in the system. @@ -28,24 +27,22 @@ below: include this information. ramdisk_size - This is now obsolete, and should not be used. flags - Various kernel flags, including: - bit 0 - 1 = mount root read only - bit 1 - unused - bit 2 - 0 = load ramdisk - bit 3 - 0 = prompt for ramdisk + + ===== ======================== + bit 0 1 = mount root read only + bit 1 unused + bit 2 0 = load ramdisk + bit 3 0 = prompt for ramdisk + ===== ======================== rootdev - major/minor number pair of device to mount as the root filesystem. - video_num_cols - video_num_rows - + video_num_cols / video_num_rows These two together describe the character size of the dummy console, or VGA console character size. They should not be used for any other purpose. @@ -54,66 +51,50 @@ below: the equivalent character size of your fbcon display. This then allows all the bootup messages to be displayed correctly. - video_x - video_y - + video_x / video_y This describes the character position of cursor on VGA console, and is otherwise unused. (should not be used for other console types, and should not be used for other purposes). memc_control_reg - MEMC chip control register for Acorn Archimedes and Acorn A5000 based machines. May be used differently by different architectures. sounddefault - Default sound setting on Acorn machines. May be used differently by different architectures. adfsdrives - Number of ADFS/MFM disks. May be used differently by different architectures. - bytes_per_char_h - bytes_per_char_v - + bytes_per_char_h / bytes_per_char_v These are now obsolete, and should not be used. pages_in_bank[4] - Number of pages in each bank of the systems memory (used for RiscPC). This is intended to be used on systems where the physical memory is non-contiguous from the processors point of view. pages_in_vram - Number of pages in VRAM (used on Acorn RiscPC). This value may also be used by loaders if the size of the video RAM can't be obtained from the hardware. - initrd_start - initrd_size - + initrd_start / initrd_size This describes the kernel virtual start address and size of the initial ramdisk. rd_start - Start address in sectors of the ramdisk image on a floppy disk. system_rev - system revision number. - system_serial_low - system_serial_high - + system_serial_low / system_serial_high system 64-bit serial number mem_fclk_21285 - The speed of the external oscillator to the 21285 (footbridge), which control's the speed of the memory bus, timer & serial port. Depending upon the speed of the cpu its value can be between @@ -121,9 +102,7 @@ below: then a value of 50 Mhz is the default on 21285 architectures. paths[8][128] - These are now obsolete, and should not be used. commandline - Kernel command line parameters. Details can be found elsewhere. diff --git a/Documentation/arm/SH-Mobile/.gitignore b/Documentation/arm/sh-mobile/.gitignore similarity index 100% rename from Documentation/arm/SH-Mobile/.gitignore rename to Documentation/arm/sh-mobile/.gitignore diff --git a/Documentation/arm/SPEAr/overview.txt b/Documentation/arm/spear/overview.rst similarity index 91% rename from Documentation/arm/SPEAr/overview.txt rename to Documentation/arm/spear/overview.rst index 1b049be6c84f..8a1a87aca427 100644 --- a/Documentation/arm/SPEAr/overview.txt +++ b/Documentation/arm/spear/overview.rst @@ -1,5 +1,6 @@ - SPEAr ARM Linux Overview - ========================== +======================== +SPEAr ARM Linux Overview +======================== Introduction ------------ @@ -30,17 +31,18 @@ Introduction - SPEAr1340 (SOC) - SPEAr1340 Evaluation Board - Configuration - ------------- +Configuration +------------- A generic configuration is provided for each machine, and can be used as the - default by + default by:: + make spear13xx_defconfig make spear3xx_defconfig make spear6xx_defconfig - Layout - ------ +Layout +------ The common files for multiple machine families (SPEAr3xx, SPEAr6xx and SPEAr13xx) are located in the platform code contained in arch/arm/plat-spear @@ -57,7 +59,7 @@ Introduction support Flattened Device Tree. - Document Author - --------------- +Document Author +--------------- Viresh Kumar , (c) 2010-2012 ST Microelectronics diff --git a/Documentation/arm/sti/overview.txt b/Documentation/arm/sti/overview.rst similarity index 82% rename from Documentation/arm/sti/overview.txt rename to Documentation/arm/sti/overview.rst index 1a4e93d6027f..70743617a74f 100644 --- a/Documentation/arm/sti/overview.txt +++ b/Documentation/arm/sti/overview.rst @@ -1,5 +1,6 @@ - STi ARM Linux Overview - ========================== +====================== +STi ARM Linux Overview +====================== Introduction ------------ @@ -10,15 +11,17 @@ Introduction B2000 and B2020 Reference boards. - configuration - ------------- +configuration +------------- A generic configuration is provided for both STiH415/416, and can be used as the - default by + default by:: + make stih41x_defconfig - Layout - ------ +Layout +------ + All the files for multiple machine families (STiH415, STiH416, and STiG125) are located in the platform code contained in arch/arm/mach-sti @@ -27,7 +30,7 @@ Introduction Device Trees. - Document Author - --------------- +Document Author +--------------- Srinivas Kandagatla , (c) 2013 ST Microelectronics diff --git a/Documentation/arm/sti/stih407-overview.txt b/Documentation/arm/sti/stih407-overview.rst similarity index 82% rename from Documentation/arm/sti/stih407-overview.txt rename to Documentation/arm/sti/stih407-overview.rst index 3343f32f58bc..027e75bc7b7c 100644 --- a/Documentation/arm/sti/stih407-overview.txt +++ b/Documentation/arm/sti/stih407-overview.rst @@ -1,5 +1,6 @@ - STiH407 Overview - ================ +================ +STiH407 Overview +================ Introduction ------------ @@ -12,7 +13,7 @@ Introduction - ARM Cortex-A9 1.5 GHz dual core CPU (28nm) - SATA2, USB 3.0, PCIe, Gbit Ethernet - Document Author - --------------- +Document Author +--------------- Maxime Coquelin , (c) 2014 ST Microelectronics diff --git a/Documentation/arm/sti/stih415-overview.txt b/Documentation/arm/sti/stih415-overview.rst similarity index 79% rename from Documentation/arm/sti/stih415-overview.txt rename to Documentation/arm/sti/stih415-overview.rst index 1383e33f265d..b67452d610c4 100644 --- a/Documentation/arm/sti/stih415-overview.txt +++ b/Documentation/arm/sti/stih415-overview.rst @@ -1,5 +1,6 @@ - STiH415 Overview - ================ +================ +STiH415 Overview +================ Introduction ------------ @@ -7,6 +8,7 @@ Introduction The STiH415 is the next generation of HD, AVC set-top box processors for satellite, cable, terrestrial and IP-STB markets. - Features + Features: + - ARM Cortex-A9 1.0 GHz, dual-core CPU - SATA2x2,USB 2.0x3, PCIe, Gbit Ethernet MACx2 diff --git a/Documentation/arm/sti/stih416-overview.txt b/Documentation/arm/sti/stih416-overview.rst similarity index 83% rename from Documentation/arm/sti/stih416-overview.txt rename to Documentation/arm/sti/stih416-overview.rst index 558444c201c6..93f17d74d8db 100644 --- a/Documentation/arm/sti/stih416-overview.txt +++ b/Documentation/arm/sti/stih416-overview.rst @@ -1,5 +1,6 @@ - STiH416 Overview - ================ +================ +STiH416 Overview +================ Introduction ------------ diff --git a/Documentation/arm/sti/stih418-overview.txt b/Documentation/arm/sti/stih418-overview.rst similarity index 83% rename from Documentation/arm/sti/stih418-overview.txt rename to Documentation/arm/sti/stih418-overview.rst index 1cd8fc80646d..b563c1f4fe5a 100644 --- a/Documentation/arm/sti/stih418-overview.txt +++ b/Documentation/arm/sti/stih418-overview.rst @@ -1,5 +1,6 @@ - STiH418 Overview - ================ +================ +STiH418 Overview +================ Introduction ------------ @@ -14,7 +15,7 @@ Introduction - HEVC L5.1 Main 10 - VP9 - Document Author - --------------- +Document Author +--------------- Maxime Coquelin , (c) 2015 ST Microelectronics diff --git a/Documentation/arm/stm32/overview.rst b/Documentation/arm/stm32/overview.rst index f7e734153860..85cfc8410798 100644 --- a/Documentation/arm/stm32/overview.rst +++ b/Documentation/arm/stm32/overview.rst @@ -1,5 +1,3 @@ -:orphan: - ======================== STM32 ARM Linux Overview ======================== diff --git a/Documentation/arm/stm32/stm32f429-overview.rst b/Documentation/arm/stm32/stm32f429-overview.rst index 65bbb1c3b423..a7ebe8ea6697 100644 --- a/Documentation/arm/stm32/stm32f429-overview.rst +++ b/Documentation/arm/stm32/stm32f429-overview.rst @@ -1,5 +1,4 @@ -:orphan: - +================== STM32F429 Overview ================== @@ -23,6 +22,4 @@ Datasheet and reference manual are publicly available on ST website (STM32F429_) .. _STM32F429: http://www.st.com/web/en/catalog/mmc/FM141/SC1169/SS1577/LN1806?ecmp=stm32f429-439_pron_pr-ces2014_nov2013 -:Authors: - -Maxime Coquelin +:Authors: Maxime Coquelin diff --git a/Documentation/arm/stm32/stm32f746-overview.rst b/Documentation/arm/stm32/stm32f746-overview.rst index 42d593085015..78befddc7740 100644 --- a/Documentation/arm/stm32/stm32f746-overview.rst +++ b/Documentation/arm/stm32/stm32f746-overview.rst @@ -1,5 +1,4 @@ -:orphan: - +================== STM32F746 Overview ================== @@ -30,6 +29,4 @@ Datasheet and reference manual are publicly available on ST website (STM32F746_) .. _STM32F746: http://www.st.com/content/st_com/en/products/microcontrollers/stm32-32-bit-arm-cortex-mcus/stm32f7-series/stm32f7x6/stm32f746ng.html -:Authors: - -Alexandre Torgue +:Authors: Alexandre Torgue diff --git a/Documentation/arm/stm32/stm32f769-overview.rst b/Documentation/arm/stm32/stm32f769-overview.rst index f6adac862b17..e482980ddf21 100644 --- a/Documentation/arm/stm32/stm32f769-overview.rst +++ b/Documentation/arm/stm32/stm32f769-overview.rst @@ -1,5 +1,4 @@ -:orphan: - +================== STM32F769 Overview ================== @@ -32,6 +31,4 @@ Datasheet and reference manual are publicly available on ST website (STM32F769_) .. _STM32F769: http://www.st.com/content/st_com/en/products/microcontrollers/stm32-32-bit-arm-cortex-mcus/stm32-high-performance-mcus/stm32f7-series/stm32f7x9/stm32f769ni.html -:Authors: - -Alexandre Torgue +:Authors: Alexandre Torgue diff --git a/Documentation/arm/stm32/stm32h743-overview.rst b/Documentation/arm/stm32/stm32h743-overview.rst index c525835e7473..4e15f1a42730 100644 --- a/Documentation/arm/stm32/stm32h743-overview.rst +++ b/Documentation/arm/stm32/stm32h743-overview.rst @@ -1,5 +1,4 @@ -:orphan: - +================== STM32H743 Overview ================== @@ -31,6 +30,4 @@ Datasheet and reference manual are publicly available on ST website (STM32H743_) .. _STM32H743: http://www.st.com/en/microcontrollers/stm32h7x3.html?querycriteria=productId=LN2033 -:Authors: - -Alexandre Torgue +:Authors: Alexandre Torgue diff --git a/Documentation/arm/stm32/stm32mp157-overview.rst b/Documentation/arm/stm32/stm32mp157-overview.rst index 2c52cd020601..f62fdc8e7d8d 100644 --- a/Documentation/arm/stm32/stm32mp157-overview.rst +++ b/Documentation/arm/stm32/stm32mp157-overview.rst @@ -1,5 +1,4 @@ -:orphan: - +=================== STM32MP157 Overview =================== diff --git a/Documentation/arm/sunxi/README b/Documentation/arm/sunxi.rst similarity index 83% rename from Documentation/arm/sunxi/README rename to Documentation/arm/sunxi.rst index f8efc21998bf..b037428aee98 100644 --- a/Documentation/arm/sunxi/README +++ b/Documentation/arm/sunxi.rst @@ -1,3 +1,4 @@ +================== ARM Allwinner SoCs ================== @@ -10,93 +11,140 @@ SunXi family Linux kernel mach directory: arch/arm/mach-sunxi Flavors: + * ARM926 based SoCs - Allwinner F20 (sun3i) - + Not Supported + + * Not Supported * ARM Cortex-A8 based SoCs - Allwinner A10 (sun4i) - + Datasheet + + * Datasheet + http://dl.linux-sunxi.org/A10/A10%20Datasheet%20-%20v1.21%20%282012-04-06%29.pdf - + User Manual + * User Manual + http://dl.linux-sunxi.org/A10/A10%20User%20Manual%20-%20v1.20%20%282012-04-09%2c%20DECRYPTED%29.pdf - Allwinner A10s (sun5i) - + Datasheet + + * Datasheet + http://dl.linux-sunxi.org/A10s/A10s%20Datasheet%20-%20v1.20%20%282012-03-27%29.pdf - Allwinner A13 / R8 (sun5i) - + Datasheet + + * Datasheet + http://dl.linux-sunxi.org/A13/A13%20Datasheet%20-%20v1.12%20%282012-03-29%29.pdf - + User Manual + * User Manual + http://dl.linux-sunxi.org/A13/A13%20User%20Manual%20-%20v1.2%20%282013-01-08%29.pdf - Next Thing Co GR8 (sun5i) * Single ARM Cortex-A7 based SoCs - Allwinner V3s (sun8i) - + Datasheet + + * Datasheet + http://linux-sunxi.org/File:Allwinner_V3s_Datasheet_V1.0.pdf * Dual ARM Cortex-A7 based SoCs - Allwinner A20 (sun7i) - + User Manual + + * User Manual + http://dl.linux-sunxi.org/A20/A20%20User%20Manual%202013-03-22.pdf - Allwinner A23 (sun8i) - + Datasheet + + * Datasheet + http://dl.linux-sunxi.org/A23/A23%20Datasheet%20V1.0%2020130830.pdf - + User Manual + + * User Manual + http://dl.linux-sunxi.org/A23/A23%20User%20Manual%20V1.0%2020130830.pdf * Quad ARM Cortex-A7 based SoCs - Allwinner A31 (sun6i) - + Datasheet + + * Datasheet + http://dl.linux-sunxi.org/A31/A3x_release_document/A31/IC/A31%20datasheet%20V1.3%2020131106.pdf - + User Manual + + * User Manual + http://dl.linux-sunxi.org/A31/A3x_release_document/A31/IC/A31%20user%20manual%20V1.1%2020130630.pdf - Allwinner A31s (sun6i) - + Datasheet + + * Datasheet + http://dl.linux-sunxi.org/A31/A3x_release_document/A31s/IC/A31s%20datasheet%20V1.3%2020131106.pdf - + User Manual + + * User Manual + http://dl.linux-sunxi.org/A31/A3x_release_document/A31s/IC/A31s%20User%20Manual%20%20V1.0%2020130322.pdf - Allwinner A33 (sun8i) - + Datasheet + + * Datasheet + http://dl.linux-sunxi.org/A33/A33%20Datasheet%20release%201.1.pdf - + User Manual + + * User Manual + http://dl.linux-sunxi.org/A33/A33%20user%20manual%20release%201.1.pdf - Allwinner H2+ (sun8i) - + No document available now, but is known to be working properly with + + * No document available now, but is known to be working properly with H3 drivers and memory map. - Allwinner H3 (sun8i) - + Datasheet + + * Datasheet + http://dl.linux-sunxi.org/H3/Allwinner_H3_Datasheet_V1.0.pdf - Allwinner R40 (sun8i) - + Datasheet + + * Datasheet + https://github.com/tinalinux/docs/raw/r40-v1.y/R40_Datasheet_V1.0.pdf - + User Manual + + * User Manual + https://github.com/tinalinux/docs/raw/r40-v1.y/Allwinner_R40_User_Manual_V1.0.pdf * Quad ARM Cortex-A15, Quad ARM Cortex-A7 based SoCs - Allwinner A80 - + Datasheet + + * Datasheet + http://dl.linux-sunxi.org/A80/A80_Datasheet_Revision_1.0_0404.pdf * Octa ARM Cortex-A7 based SoCs - Allwinner A83T - + Datasheet + + * Datasheet + https://github.com/allwinner-zh/documents/raw/master/A83T/A83T_Datasheet_v1.3_20150510.pdf - + User Manual + + * User Manual + https://github.com/allwinner-zh/documents/raw/master/A83T/A83T_User_Manual_v1.5.1_20150513.pdf * Quad ARM Cortex-A53 based SoCs - Allwinner A64 - + Datasheet + + * Datasheet + http://dl.linux-sunxi.org/A64/A64_Datasheet_V1.1.pdf - + User Manual + + * User Manual + http://dl.linux-sunxi.org/A64/Allwinner%20A64%20User%20Manual%20v1.0.pdf diff --git a/Documentation/arm/sunxi/clocks.txt b/Documentation/arm/sunxi/clocks.rst similarity index 92% rename from Documentation/arm/sunxi/clocks.txt rename to Documentation/arm/sunxi/clocks.rst index e09a88aa3136..23bd03f3e21f 100644 --- a/Documentation/arm/sunxi/clocks.txt +++ b/Documentation/arm/sunxi/clocks.rst @@ -1,3 +1,4 @@ +======================================================= Frequently asked questions about the sunxi clock system ======================================================= @@ -12,7 +13,7 @@ A: The 24MHz oscillator allows gating to save power. Indeed, if gated steps, one can gate it and keep the system running. Consider this simplified suspend example: - While the system is operational, you would see something like + While the system is operational, you would see something like:: 24MHz 32kHz | @@ -23,7 +24,7 @@ A: The 24MHz oscillator allows gating to save power. Indeed, if gated [CPU] When you are about to suspend, you switch the CPU Mux to the 32kHz - oscillator: + oscillator:: 24Mhz 32kHz | | @@ -33,7 +34,7 @@ A: The 24MHz oscillator allows gating to save power. Indeed, if gated | [CPU] - Finally you can gate the main oscillator + Finally you can gate the main oscillator:: 32kHz | diff --git a/Documentation/arm/swp_emulation b/Documentation/arm/swp_emulation.rst similarity index 63% rename from Documentation/arm/swp_emulation rename to Documentation/arm/swp_emulation.rst index af903d22fd93..6a608a9c3715 100644 --- a/Documentation/arm/swp_emulation +++ b/Documentation/arm/swp_emulation.rst @@ -11,17 +11,17 @@ sequence. If a memory access fault (an abort) occurs, a segmentation fault is signalled to the triggering process. /proc/cpu/swp_emulation holds some statistics/information, including the PID of -the last process to trigger the emulation to be invocated. For example: ---- -Emulated SWP: 12 -Emulated SWPB: 0 -Aborted SWP{B}: 1 -Last process: 314 ---- +the last process to trigger the emulation to be invocated. For example:: -NOTE: when accessing uncached shared regions, LDREX/STREX rely on an external -transaction monitoring block called a global monitor to maintain update -atomicity. If your system does not implement a global monitor, this option can -cause programs that perform SWP operations to uncached memory to deadlock, as -the STREX operation will always fail. + Emulated SWP: 12 + Emulated SWPB: 0 + Aborted SWP{B}: 1 + Last process: 314 + +NOTE: + when accessing uncached shared regions, LDREX/STREX rely on an external + transaction monitoring block called a global monitor to maintain update + atomicity. If your system does not implement a global monitor, this option can + cause programs that perform SWP operations to uncached memory to deadlock, as + the STREX operation will always fail. diff --git a/Documentation/arm/tcm.txt b/Documentation/arm/tcm.rst similarity index 86% rename from Documentation/arm/tcm.txt rename to Documentation/arm/tcm.rst index 7c15871c1885..effd9c7bc968 100644 --- a/Documentation/arm/tcm.txt +++ b/Documentation/arm/tcm.rst @@ -1,5 +1,7 @@ +================================================== ARM TCM (Tightly-Coupled Memory) handling in Linux ----- +================================================== + Written by Linus Walleij Some ARM SoC:s have a so-called TCM (Tightly-Coupled Memory). @@ -85,46 +87,50 @@ to have functions called locally inside the TCM without wasting space, there is also the __tcmlocalfunc prefix that will make the call relative. -Variables to go into dtcm can be tagged like this: -int __tcmdata foo; +Variables to go into dtcm can be tagged like this:: -Constants can be tagged like this: -int __tcmconst foo; + int __tcmdata foo; + +Constants can be tagged like this:: + + int __tcmconst foo; + +To put assembler into TCM just use:: + + .section ".tcm.text" or .section ".tcm.data" -To put assembler into TCM just use -.section ".tcm.text" or .section ".tcm.data" respectively. -Example code: +Example code:: -#include + #include -/* Uninitialized data */ -static u32 __tcmdata tcmvar; -/* Initialized data */ -static u32 __tcmdata tcmassigned = 0x2BADBABEU; -/* Constant */ -static const u32 __tcmconst tcmconst = 0xCAFEBABEU; + /* Uninitialized data */ + static u32 __tcmdata tcmvar; + /* Initialized data */ + static u32 __tcmdata tcmassigned = 0x2BADBABEU; + /* Constant */ + static const u32 __tcmconst tcmconst = 0xCAFEBABEU; -static void __tcmlocalfunc tcm_to_tcm(void) -{ + static void __tcmlocalfunc tcm_to_tcm(void) + { int i; for (i = 0; i < 100; i++) tcmvar ++; -} + } -static void __tcmfunc hello_tcm(void) -{ + static void __tcmfunc hello_tcm(void) + { /* Some abstract code that runs in ITCM */ int i; for (i = 0; i < 100; i++) { tcmvar ++; } tcm_to_tcm(); -} + } -static void __init test_tcm(void) -{ + static void __init test_tcm(void) + { u32 *tcmem; int i; @@ -152,4 +158,4 @@ static void __init test_tcm(void) printk("TCM tcmem[%d] = %08x\n", i, tcmem[i]); tcm_free(tcmem, 20); } -} + } diff --git a/Documentation/arm/uefi.txt b/Documentation/arm/uefi.rst similarity index 63% rename from Documentation/arm/uefi.txt rename to Documentation/arm/uefi.rst index 6543a0adea8a..f868330df6be 100644 --- a/Documentation/arm/uefi.txt +++ b/Documentation/arm/uefi.rst @@ -1,3 +1,7 @@ +================================================ +The Unified Extensible Firmware Interface (UEFI) +================================================ + UEFI, the Unified Extensible Firmware Interface, is a specification governing the behaviours of compatible firmware interfaces. It is maintained by the UEFI Forum - http://www.uefi.org/. @@ -11,11 +15,13 @@ UEFI support in Linux ===================== Booting on a platform with firmware compliant with the UEFI specification makes it possible for the kernel to support additional features: + - UEFI Runtime Services - Retrieving various configuration information through the standardised interface of UEFI configuration tables. (ACPI, SMBIOS, ...) For actually enabling [U]EFI support, enable: + - CONFIG_EFI=y - CONFIG_EFI_VARS=y or m @@ -42,19 +48,20 @@ Instead, the kernel reads the UEFI memory map. The stub populates the FDT /chosen node with (and the kernel scans for) the following parameters: -________________________________________________________________________________ -Name | Size | Description -================================================================================ -linux,uefi-system-table | 64-bit | Physical address of the UEFI System Table. --------------------------------------------------------------------------------- -linux,uefi-mmap-start | 64-bit | Physical address of the UEFI memory map, - | | populated by the UEFI GetMemoryMap() call. --------------------------------------------------------------------------------- -linux,uefi-mmap-size | 32-bit | Size in bytes of the UEFI memory map - | | pointed to in previous entry. --------------------------------------------------------------------------------- -linux,uefi-mmap-desc-size | 32-bit | Size in bytes of each entry in the UEFI - | | memory map. --------------------------------------------------------------------------------- -linux,uefi-mmap-desc-ver | 32-bit | Version of the mmap descriptor format. --------------------------------------------------------------------------------- + +========================== ====== =========================================== +Name Size Description +========================== ====== =========================================== +linux,uefi-system-table 64-bit Physical address of the UEFI System Table. + +linux,uefi-mmap-start 64-bit Physical address of the UEFI memory map, + populated by the UEFI GetMemoryMap() call. + +linux,uefi-mmap-size 32-bit Size in bytes of the UEFI memory map + pointed to in previous entry. + +linux,uefi-mmap-desc-size 32-bit Size in bytes of each entry in the UEFI + memory map. + +linux,uefi-mmap-desc-ver 32-bit Version of the mmap descriptor format. +========================== ====== =========================================== diff --git a/Documentation/arm/VFP/release-notes.txt b/Documentation/arm/vfp/release-notes.rst similarity index 92% rename from Documentation/arm/VFP/release-notes.txt rename to Documentation/arm/vfp/release-notes.rst index 28a2795705ca..c6b04937cee3 100644 --- a/Documentation/arm/VFP/release-notes.txt +++ b/Documentation/arm/vfp/release-notes.rst @@ -1,7 +1,9 @@ +=============================================== Release notes for Linux Kernel VFP support code ------------------------------------------------ +=============================================== Date: 20 May 2004 + Author: Russell King This is the first release of the Linux Kernel VFP support code. It diff --git a/Documentation/arm/vlocks.txt b/Documentation/arm/vlocks.rst similarity index 98% rename from Documentation/arm/vlocks.txt rename to Documentation/arm/vlocks.rst index 45731672c564..a40a1742110b 100644 --- a/Documentation/arm/vlocks.txt +++ b/Documentation/arm/vlocks.rst @@ -1,3 +1,4 @@ +====================================== vlocks for Bare-Metal Mutual Exclusion ====================================== @@ -26,7 +27,7 @@ started yet. Algorithm --------- -The easiest way to explain the vlocks algorithm is with some pseudo-code: +The easiest way to explain the vlocks algorithm is with some pseudo-code:: int currently_voting[NR_CPUS] = { 0, }; @@ -93,7 +94,7 @@ Features and limitations number of CPUs. vlocks can be cascaded in a voting hierarchy to permit better scaling - if necessary, as in the following hypothetical example for 4096 CPUs: + if necessary, as in the following hypothetical example for 4096 CPUs:: /* first level: local election */ my_town = towns[(this_cpu >> 4) & 0xf]; @@ -127,12 +128,12 @@ the basic algorithm: reduces the number of round-trips required to external memory. In the ARM implementation, this means that we can use a single load - and comparison: + and comparison:: LDR Rt, [Rn] CMP Rt, #0 - ...in place of code equivalent to: + ...in place of code equivalent to:: LDRB Rt, [Rn] CMP Rt, #0 diff --git a/Documentation/devicetree/bindings/arm/xen.txt b/Documentation/devicetree/bindings/arm/xen.txt index c9b9321434ea..db5c56db30ec 100644 --- a/Documentation/devicetree/bindings/arm/xen.txt +++ b/Documentation/devicetree/bindings/arm/xen.txt @@ -54,7 +54,7 @@ hypervisor { }; The format and meaning of the "xen,uefi-*" parameters are similar to those in -Documentation/arm/uefi.txt, which are provided by the regular UEFI stub. However +Documentation/arm/uefi.rst, which are provided by the regular UEFI stub. However they differ because they are provided by the Xen hypervisor, together with a set of UEFI runtime services implemented via hypercalls, see http://xenbits.xen.org/docs/unstable/hypercall/x86_64/include,public,platform.h.html. diff --git a/Documentation/devicetree/booting-without-of.txt b/Documentation/devicetree/booting-without-of.txt index 60f8640f2b2f..4660ccee35a3 100644 --- a/Documentation/devicetree/booting-without-of.txt +++ b/Documentation/devicetree/booting-without-of.txt @@ -160,7 +160,7 @@ it with special cases. of the kernel image. That entry point supports two calling conventions. A summary of the interface is described here. A full description of the boot requirements is documented in - Documentation/arm/Booting + Documentation/arm/booting.rst a) ATAGS interface. Minimal information is passed from firmware to the kernel with a tagged list of predefined parameters. @@ -174,7 +174,7 @@ it with special cases. b) Entry with a flattened device-tree block. Firmware loads the physical address of the flattened device tree block (dtb) into r2, r1 is not used, but it is considered good practice to use a valid - machine number as described in Documentation/arm/Booting. + machine number as described in Documentation/arm/booting.rst. r0 : 0 diff --git a/Documentation/index.rst b/Documentation/index.rst index 216dc0e1e6f2..c6934d90363c 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -1,3 +1,4 @@ + .. The Linux Kernel documentation master file, created by sphinx-quickstart on Fri Feb 12 13:51:46 2016. You can adapt this file completely to your liking, but it should at least diff --git a/Documentation/translations/zh_CN/arm/Booting b/Documentation/translations/zh_CN/arm/Booting index 1fe866f8218f..562e9a2957e6 100644 --- a/Documentation/translations/zh_CN/arm/Booting +++ b/Documentation/translations/zh_CN/arm/Booting @@ -1,4 +1,4 @@ -Chinese translated version of Documentation/arm/Booting +Chinese translated version of Documentation/arm/booting.rst If you have any comment or update to the content, please contact the original document maintainer directly. However, if you have a problem @@ -9,7 +9,7 @@ or if there is a problem with the translation. Maintainer: Russell King Chinese maintainer: Fu Wei --------------------------------------------------------------------- -Documentation/arm/Booting 的中文翻译 +Documentation/arm/booting.rst 的中文翻译 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 diff --git a/Documentation/translations/zh_CN/arm/kernel_user_helpers.txt b/Documentation/translations/zh_CN/arm/kernel_user_helpers.txt index cd7fc8f34cf9..99af4363984d 100644 --- a/Documentation/translations/zh_CN/arm/kernel_user_helpers.txt +++ b/Documentation/translations/zh_CN/arm/kernel_user_helpers.txt @@ -1,4 +1,4 @@ -Chinese translated version of Documentation/arm/kernel_user_helpers.txt +Chinese translated version of Documentation/arm/kernel_user_helpers.rst If you have any comment or update to the content, please contact the original document maintainer directly. However, if you have a problem @@ -10,7 +10,7 @@ Maintainer: Nicolas Pitre Dave Martin Chinese maintainer: Fu Wei --------------------------------------------------------------------- -Documentation/arm/kernel_user_helpers.txt 的中文翻译 +Documentation/arm/kernel_user_helpers.rst 的中文翻译 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 diff --git a/MAINTAINERS b/MAINTAINERS index 37ba75bae7aa..96c85695b3d4 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -2218,7 +2218,7 @@ F: drivers/*/*s3c64xx* F: drivers/*/*s5pv210* F: drivers/memory/samsung/* F: drivers/soc/samsung/* -F: Documentation/arm/Samsung/ +F: Documentation/arm/samsung/ F: Documentation/devicetree/bindings/arm/samsung/ F: Documentation/devicetree/bindings/sram/samsung-sram.txt F: Documentation/devicetree/bindings/power/pd-samsung.txt @@ -11571,7 +11571,7 @@ L: linux-omap@vger.kernel.org L: linux-fbdev@vger.kernel.org S: Orphan F: drivers/video/fbdev/omap2/ -F: Documentation/arm/OMAP/DSS +F: Documentation/arm/omap/dss.rst OMAP FRAMEBUFFER SUPPORT L: linux-fbdev@vger.kernel.org diff --git a/arch/arm/Kconfig b/arch/arm/Kconfig index 2bf1ce39a96d..6425871e9903 100644 --- a/arch/arm/Kconfig +++ b/arch/arm/Kconfig @@ -2142,7 +2142,7 @@ config VFP Say Y to include VFP support code in the kernel. This is needed if your hardware includes a VFP unit. - Please see for + Please see for release notes and additional status information. Say N if your target does not have VFP hardware. diff --git a/arch/arm/common/mcpm_entry.c b/arch/arm/common/mcpm_entry.c index e24ad60891b2..8a9aeeb504dd 100644 --- a/arch/arm/common/mcpm_entry.c +++ b/arch/arm/common/mcpm_entry.c @@ -21,7 +21,7 @@ /* * The public API for this code is documented in arch/arm/include/asm/mcpm.h. * For a comprehensive description of the main algorithm used here, please - * see Documentation/arm/cluster-pm-race-avoidance.txt. + * see Documentation/arm/cluster-pm-race-avoidance.rst. */ struct sync_struct mcpm_sync; diff --git a/arch/arm/common/mcpm_head.S b/arch/arm/common/mcpm_head.S index d5bd75dd576d..291d969bc719 100644 --- a/arch/arm/common/mcpm_head.S +++ b/arch/arm/common/mcpm_head.S @@ -5,7 +5,7 @@ * Created by: Nicolas Pitre, March 2012 * Copyright: (C) 2012-2013 Linaro Limited * - * Refer to Documentation/arm/cluster-pm-race-avoidance.txt + * Refer to Documentation/arm/cluster-pm-race-avoidance.rst * for details of the synchronisation algorithms used here. */ diff --git a/arch/arm/common/vlock.S b/arch/arm/common/vlock.S index 9675cc15d0c4..f1c7fd44f1b1 100644 --- a/arch/arm/common/vlock.S +++ b/arch/arm/common/vlock.S @@ -6,7 +6,7 @@ * Copyright: (C) 2012-2013 Linaro Limited * * This algorithm is described in more detail in - * Documentation/arm/vlocks.txt. + * Documentation/arm/vlocks.rst. */ #include diff --git a/arch/arm/include/asm/setup.h b/arch/arm/include/asm/setup.h index 77e5582c2259..67d20712cb48 100644 --- a/arch/arm/include/asm/setup.h +++ b/arch/arm/include/asm/setup.h @@ -5,7 +5,7 @@ * Copyright (C) 1997-1999 Russell King * * Structure passed to kernel to tell it about the - * hardware it's running on. See Documentation/arm/Setup + * hardware it's running on. See Documentation/arm/setup.rst * for more info. */ #ifndef __ASMARM_SETUP_H diff --git a/arch/arm/include/uapi/asm/setup.h b/arch/arm/include/uapi/asm/setup.h index 6b335a9ff8c8..25ceda63b284 100644 --- a/arch/arm/include/uapi/asm/setup.h +++ b/arch/arm/include/uapi/asm/setup.h @@ -9,7 +9,7 @@ * published by the Free Software Foundation. * * Structure passed to kernel to tell it about the - * hardware it's running on. See Documentation/arm/Setup + * hardware it's running on. See Documentation/arm/setup.rst * for more info. */ #ifndef _UAPI__ASMARM_SETUP_H diff --git a/arch/arm/kernel/entry-armv.S b/arch/arm/kernel/entry-armv.S index 0b8cfdd60b90..858d4e541532 100644 --- a/arch/arm/kernel/entry-armv.S +++ b/arch/arm/kernel/entry-armv.S @@ -826,7 +826,7 @@ ENDPROC(__switch_to) * existing ones. This mechanism should be used only for things that are * really small and justified, and not be abused freely. * - * See Documentation/arm/kernel_user_helpers.txt for formal definitions. + * See Documentation/arm/kernel_user_helpers.rst for formal definitions. */ THUMB( .arm ) diff --git a/arch/arm/mach-exynos/common.h b/arch/arm/mach-exynos/common.h index c93356a8d662..56411bb63d45 100644 --- a/arch/arm/mach-exynos/common.h +++ b/arch/arm/mach-exynos/common.h @@ -106,7 +106,7 @@ void exynos_firmware_init(void); #define C2_STATE (1 << 3) /* * Magic values for bootloader indicating chosen low power mode. - * See also Documentation/arm/Samsung/Bootloader-interface.txt + * See also Documentation/arm/samsung/bootloader-interface.rst */ #define EXYNOS_SLEEP_MAGIC 0x00000bad #define EXYNOS_AFTR_MAGIC 0xfcba0d10 diff --git a/arch/arm/mach-ixp4xx/Kconfig b/arch/arm/mach-ixp4xx/Kconfig index fc5378b00f3d..f7211b57b1e7 100644 --- a/arch/arm/mach-ixp4xx/Kconfig +++ b/arch/arm/mach-ixp4xx/Kconfig @@ -33,7 +33,7 @@ config MACH_AVILA help Say 'Y' here if you want your kernel to support the Gateworks Avila Network Platform. For more information on this platform, - see . + see . config MACH_LOFT bool "Loft" @@ -49,7 +49,7 @@ config ARCH_ADI_COYOTE help Say 'Y' here if you want your kernel to support the ADI Engineering Coyote Gateway Reference Platform. For more - information on this platform, see . + information on this platform, see . config MACH_GATEWAY7001 bool "Gateway 7001" @@ -72,21 +72,21 @@ config ARCH_IXDP425 help Say 'Y' here if you want your kernel to support Intel's IXDP425 Development Platform (Also known as Richfield). - For more information on this platform, see . + For more information on this platform, see . config MACH_IXDPG425 bool "IXDPG425" help Say 'Y' here if you want your kernel to support Intel's IXDPG425 Development Platform (Also known as Montajade). - For more information on this platform, see . + For more information on this platform, see . config MACH_IXDP465 bool "IXDP465" help Say 'Y' here if you want your kernel to support Intel's IXDP465 Development Platform (Also known as BMP). - For more information on this platform, see . + For more information on this platform, see . config MACH_GORAMO_MLR bool "GORAMO Multi Link Router" @@ -99,7 +99,7 @@ config MACH_KIXRP435 help Say 'Y' here if you want your kernel to support Intel's KIXRP435 Reference Platform. - For more information on this platform, see . + For more information on this platform, see . # # IXCDP1100 is the exact same HW as IXDP425, but with a different machine @@ -116,7 +116,7 @@ config ARCH_PRPMC1100 help Say 'Y' here if you want your kernel to support the Motorola PrPCM1100 Processor Mezanine Module. For more information on - this platform, see . + this platform, see . config MACH_NAS100D bool diff --git a/arch/arm/mach-s3c24xx/pm.c b/arch/arm/mach-s3c24xx/pm.c index adcb90645460..c64988c609ad 100644 --- a/arch/arm/mach-s3c24xx/pm.c +++ b/arch/arm/mach-s3c24xx/pm.c @@ -5,7 +5,7 @@ // // S3C24XX Power Manager (Suspend-To-RAM) support // -// See Documentation/arm/Samsung-S3C24XX/Suspend.txt for more information +// See Documentation/arm/samsung-s3c24xx/suspend.rst for more information // // Parts based on arch/arm/mach-pxa/pm.c // diff --git a/arch/arm/mm/Kconfig b/arch/arm/mm/Kconfig index cc798115aa9b..820b60a50125 100644 --- a/arch/arm/mm/Kconfig +++ b/arch/arm/mm/Kconfig @@ -709,7 +709,7 @@ config ARM_VIRT_EXT assistance. A compliant bootloader is required in order to make maximum - use of this feature. Refer to Documentation/arm/Booting for + use of this feature. Refer to Documentation/arm/booting.rst for details. config SWP_EMULATE @@ -875,7 +875,7 @@ config KUSER_HELPERS the CPU type fitted to the system. This permits binaries to be run on ARMv4 through to ARMv7 without modification. - See Documentation/arm/kernel_user_helpers.txt for details. + See Documentation/arm/kernel_user_helpers.rst for details. However, the fixed address nature of these helpers can be used by ROP (return orientated programming) authors when creating diff --git a/arch/arm/plat-samsung/Kconfig b/arch/arm/plat-samsung/Kconfig index 53da57fba39c..301e572651c0 100644 --- a/arch/arm/plat-samsung/Kconfig +++ b/arch/arm/plat-samsung/Kconfig @@ -243,7 +243,7 @@ config SAMSUNG_PM_DEBUG depends on DEBUG_EXYNOS_UART || DEBUG_S3C24XX_UART || DEBUG_S3C2410_UART help Say Y here if you want verbose debugging from the PM Suspend and - Resume code. See + Resume code. See for more information. config S3C_PM_DEBUG_LED_SMDK @@ -268,7 +268,7 @@ config SAMSUNG_PM_CHECK Note, this can take several seconds depending on memory size and CPU speed. - See + See config SAMSUNG_PM_CHECK_CHUNKSIZE int "S3C2410 PM Suspend CRC Chunksize (KiB)" @@ -280,7 +280,7 @@ config SAMSUNG_PM_CHECK_CHUNKSIZE the CRC data block will take more memory, but will identify any faults with better precision. - See + See config SAMSUNG_WAKEMASK bool diff --git a/arch/arm/tools/mach-types b/arch/arm/tools/mach-types index 4eac94c1eb6f..9e74c7ff6b04 100644 --- a/arch/arm/tools/mach-types +++ b/arch/arm/tools/mach-types @@ -7,7 +7,7 @@ # http://www.arm.linux.org.uk/developer/machines/download.php # # Please do not send patches to this file; it is automatically generated! -# To add an entry into this database, please see Documentation/arm/README, +# To add an entry into this database, please see Documentation/arm/arm.rst, # or visit: # # http://www.arm.linux.org.uk/developer/machines/?action=new diff --git a/arch/arm64/Kconfig b/arch/arm64/Kconfig index a36ff61321ce..a4b22bbf0590 100644 --- a/arch/arm64/Kconfig +++ b/arch/arm64/Kconfig @@ -1142,7 +1142,7 @@ config KUSER_HELPERS the system. This permits binaries to be run on ARMv4 through to ARMv8 without modification. - See Documentation/arm/kernel_user_helpers.txt for details. + See Documentation/arm/kernel_user_helpers.rst for details. However, the fixed address nature of these helpers can be used by ROP (return orientated programming) authors when creating diff --git a/arch/arm64/kernel/kuser32.S b/arch/arm64/kernel/kuser32.S index 49825e9e421e..42bd8c0c60e0 100644 --- a/arch/arm64/kernel/kuser32.S +++ b/arch/arm64/kernel/kuser32.S @@ -10,7 +10,7 @@ * aarch32_setup_additional_pages() and are provided for compatibility * reasons with 32 bit (aarch32) applications that need them. * - * See Documentation/arm/kernel_user_helpers.txt for formal definitions. + * See Documentation/arm/kernel_user_helpers.rst for formal definitions. */ #include diff --git a/arch/mips/bmips/setup.c b/arch/mips/bmips/setup.c index 1738a06396f9..2f81a94c71a6 100644 --- a/arch/mips/bmips/setup.c +++ b/arch/mips/bmips/setup.c @@ -162,7 +162,7 @@ void __init plat_mem_setup(void) ioport_resource.start = 0; ioport_resource.end = ~0; - /* intended to somewhat resemble ARM; see Documentation/arm/Booting */ + /* intended to somewhat resemble ARM; see Documentation/arm/booting.rst */ if (fw_arg0 == 0 && fw_arg1 == 0xffffffff) dtb = phys_to_virt(fw_arg2); else if (fw_passed_dtb) /* UHI interface or appended dtb */ diff --git a/drivers/crypto/sunxi-ss/sun4i-ss-cipher.c b/drivers/crypto/sunxi-ss/sun4i-ss-cipher.c index 4ab14d58e85b..6f7cbf6c2b55 100644 --- a/drivers/crypto/sunxi-ss/sun4i-ss-cipher.c +++ b/drivers/crypto/sunxi-ss/sun4i-ss-cipher.c @@ -8,7 +8,7 @@ * keysize in CBC and ECB mode. * Add support also for DES and 3DES in CBC and ECB mode. * - * You could find the datasheet in Documentation/arm/sunxi/README + * You could find the datasheet in Documentation/arm/sunxi.rst */ #include "sun4i-ss.h" diff --git a/drivers/crypto/sunxi-ss/sun4i-ss-core.c b/drivers/crypto/sunxi-ss/sun4i-ss-core.c index cdcda7f059c8..2e8704271f45 100644 --- a/drivers/crypto/sunxi-ss/sun4i-ss-core.c +++ b/drivers/crypto/sunxi-ss/sun4i-ss-core.c @@ -6,7 +6,7 @@ * * Core file which registers crypto algorithms supported by the SS. * - * You could find a link for the datasheet in Documentation/arm/sunxi/README + * You could find a link for the datasheet in Documentation/arm/sunxi.rst */ #include #include diff --git a/drivers/crypto/sunxi-ss/sun4i-ss-hash.c b/drivers/crypto/sunxi-ss/sun4i-ss-hash.c index d2b6d89aad28..fcffba5ef927 100644 --- a/drivers/crypto/sunxi-ss/sun4i-ss-hash.c +++ b/drivers/crypto/sunxi-ss/sun4i-ss-hash.c @@ -6,7 +6,7 @@ * * This file add support for MD5 and SHA1. * - * You could find the datasheet in Documentation/arm/sunxi/README + * You could find the datasheet in Documentation/arm/sunxi.rst */ #include "sun4i-ss.h" #include diff --git a/drivers/crypto/sunxi-ss/sun4i-ss.h b/drivers/crypto/sunxi-ss/sun4i-ss.h index 68b82d1a6303..8654d48aedc0 100644 --- a/drivers/crypto/sunxi-ss/sun4i-ss.h +++ b/drivers/crypto/sunxi-ss/sun4i-ss.h @@ -8,7 +8,7 @@ * Support MD5 and SHA1 hash algorithms. * Support DES and 3DES * - * You could find the datasheet in Documentation/arm/sunxi/README + * You could find the datasheet in Documentation/arm/sunxi.rst */ #include diff --git a/drivers/input/touchscreen/sun4i-ts.c b/drivers/input/touchscreen/sun4i-ts.c index 92f6e1ae23a2..f11ba7f2dca7 100644 --- a/drivers/input/touchscreen/sun4i-ts.c +++ b/drivers/input/touchscreen/sun4i-ts.c @@ -22,7 +22,7 @@ * in the kernel). So this driver offers straight forward, reliable single * touch functionality only. * - * s.a. A20 User Manual "1.15 TP" (Documentation/arm/sunxi/README) + * s.a. A20 User Manual "1.15 TP" (Documentation/arm/sunxi.rst) * (looks like the description in the A20 User Manual v1.3 is better * than the one in the A10 User Manual v.1.5) */ diff --git a/drivers/tty/serial/Kconfig b/drivers/tty/serial/Kconfig index b416c7b33f49..04c23951b831 100644 --- a/drivers/tty/serial/Kconfig +++ b/drivers/tty/serial/Kconfig @@ -500,7 +500,7 @@ config SERIAL_SA1100 help If you have a machine based on a SA1100/SA1110 StrongARM(R) CPU you can enable its onboard serial port by enabling this option. - Please read for further + Please read for further info. config SERIAL_SA1100_CONSOLE From 2bbbf827d339032dbeda62f0a5f20d2fde07b0f5 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 15 Apr 2019 18:39:27 -0300 Subject: [PATCH 11/77] docs: memory-devices: convert ti-emif.txt to ReST Prepare this file to be moved to a kernel book by converting it to ReST format and renaming it to ti-emif.rst. While this is not part of any book, mark it as :orphan:, in order to avoid build warnings. Signed-off-by: Mauro Carvalho Chehab --- .../{ti-emif.txt => ti-emif.rst} | 27 ++++++++++++------- 1 file changed, 17 insertions(+), 10 deletions(-) rename Documentation/memory-devices/{ti-emif.txt => ti-emif.rst} (81%) diff --git a/Documentation/memory-devices/ti-emif.txt b/Documentation/memory-devices/ti-emif.rst similarity index 81% rename from Documentation/memory-devices/ti-emif.txt rename to Documentation/memory-devices/ti-emif.rst index f4ad9a7d0f4b..c9242294e63c 100644 --- a/Documentation/memory-devices/ti-emif.txt +++ b/Documentation/memory-devices/ti-emif.rst @@ -1,20 +1,24 @@ -TI EMIF SDRAM Controller Driver: +:orphan: + +=============================== +TI EMIF SDRAM Controller Driver +=============================== Author -======== +====== Aneesh V Location -============ +======== driver/memory/emif.c Supported SoCs: -=================== +=============== TI OMAP44xx TI OMAP54xx Menuconfig option: -========================== +================== Device Drivers Memory devices Texas Instruments EMIF driver @@ -29,10 +33,11 @@ functions of the driver includes re-configuring AC timing parameters and other settings during frequency, voltage and temperature changes -Platform Data (see include/linux/platform_data/emif_plat.h): -===================================================================== +Platform Data (see include/linux/platform_data/emif_plat.h) +=========================================================== DDR device details and other board dependent and SoC dependent information can be passed through platform data (struct emif_platform_data) + - DDR device details: 'struct ddr_device_info' - Device AC timings: 'struct lpddr2_timings' and 'struct lpddr2_min_tck' - Custom configurations: customizable policy options through @@ -40,17 +45,19 @@ information can be passed through platform data (struct emif_platform_data) - IP revision - PHY type -Interface to the external world: -================================ +Interface to the external world +=============================== EMIF driver registers notifiers for voltage and frequency changes affecting EMIF and takes appropriate actions when these are invoked. + - freq_pre_notify_handling() - freq_post_notify_handling() - volt_notify_handling() Debugfs -======== +======= The driver creates two debugfs entries per device. + - regcache_dump : dump of register values calculated and saved for all frequencies used so far. - mr4 : last polled value of MR4 register in the LPDDR2 device. MR4 From 675aaf05d8982d3d304d4652d1555714be8b4af2 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 15 Apr 2019 18:46:48 -0300 Subject: [PATCH 12/77] docs: xen-tpmfront.txt: convert it to .rst In order to be able to add this file to the security book, we need first to convert it to reST. While this is not part of any book, mark it as :orphan:, in order to avoid build warnings. Signed-off-by: Mauro Carvalho Chehab --- .../{xen-tpmfront.txt => xen-tpmfront.rst} | 103 ++++++++++-------- 1 file changed, 58 insertions(+), 45 deletions(-) rename Documentation/security/tpm/{xen-tpmfront.txt => xen-tpmfront.rst} (66%) diff --git a/Documentation/security/tpm/xen-tpmfront.txt b/Documentation/security/tpm/xen-tpmfront.rst similarity index 66% rename from Documentation/security/tpm/xen-tpmfront.txt rename to Documentation/security/tpm/xen-tpmfront.rst index 69346de87ff3..98a16ab87360 100644 --- a/Documentation/security/tpm/xen-tpmfront.txt +++ b/Documentation/security/tpm/xen-tpmfront.rst @@ -1,4 +1,8 @@ +:orphan: + +============================= Virtual TPM interface for Xen +============================= Authors: Matthew Fioravante (JHUAPL), Daniel De Graaf (NSA) @@ -6,7 +10,8 @@ This document describes the virtual Trusted Platform Module (vTPM) subsystem for Xen. The reader is assumed to have familiarity with building and installing Xen, Linux, and a basic understanding of the TPM and vTPM concepts. -INTRODUCTION +Introduction +------------ The goal of this work is to provide a TPM functionality to a virtual guest operating system (in Xen terms, a DomU). This allows programs to interact with @@ -24,81 +29,89 @@ This mini-os vTPM subsystem was built on top of the previous vTPM work done by IBM and Intel corporation. -DESIGN OVERVIEW +Design Overview --------------- -The architecture of vTPM is described below: +The architecture of vTPM is described below:: -+------------------+ -| Linux DomU | ... -| | ^ | -| v | | -| xen-tpmfront | -+------------------+ - | ^ - v | -+------------------+ -| mini-os/tpmback | -| | ^ | -| v | | -| vtpm-stubdom | ... -| | ^ | -| v | | -| mini-os/tpmfront | -+------------------+ - | ^ - v | -+------------------+ -| mini-os/tpmback | -| | ^ | -| v | | -| vtpmmgr-stubdom | -| | ^ | -| v | | -| mini-os/tpm_tis | -+------------------+ - | ^ - v | -+------------------+ -| Hardware TPM | -+------------------+ + +------------------+ + | Linux DomU | ... + | | ^ | + | v | | + | xen-tpmfront | + +------------------+ + | ^ + v | + +------------------+ + | mini-os/tpmback | + | | ^ | + | v | | + | vtpm-stubdom | ... + | | ^ | + | v | | + | mini-os/tpmfront | + +------------------+ + | ^ + v | + +------------------+ + | mini-os/tpmback | + | | ^ | + | v | | + | vtpmmgr-stubdom | + | | ^ | + | v | | + | mini-os/tpm_tis | + +------------------+ + | ^ + v | + +------------------+ + | Hardware TPM | + +------------------+ - * Linux DomU: The Linux based guest that wants to use a vTPM. There may be +* Linux DomU: + The Linux based guest that wants to use a vTPM. There may be more than one of these. - * xen-tpmfront.ko: Linux kernel virtual TPM frontend driver. This driver +* xen-tpmfront.ko: + Linux kernel virtual TPM frontend driver. This driver provides vTPM access to a Linux-based DomU. - * mini-os/tpmback: Mini-os TPM backend driver. The Linux frontend driver +* mini-os/tpmback: + Mini-os TPM backend driver. The Linux frontend driver connects to this backend driver to facilitate communications between the Linux DomU and its vTPM. This driver is also used by vtpmmgr-stubdom to communicate with vtpm-stubdom. - * vtpm-stubdom: A mini-os stub domain that implements a vTPM. There is a +* vtpm-stubdom: + A mini-os stub domain that implements a vTPM. There is a one to one mapping between running vtpm-stubdom instances and logical vtpms on the system. The vTPM Platform Configuration Registers (PCRs) are normally all initialized to zero. - * mini-os/tpmfront: Mini-os TPM frontend driver. The vTPM mini-os domain +* mini-os/tpmfront: + Mini-os TPM frontend driver. The vTPM mini-os domain vtpm-stubdom uses this driver to communicate with vtpmmgr-stubdom. This driver is also used in mini-os domains such as pv-grub that talk to the vTPM domain. - * vtpmmgr-stubdom: A mini-os domain that implements the vTPM manager. There is +* vtpmmgr-stubdom: + A mini-os domain that implements the vTPM manager. There is only one vTPM manager and it should be running during the entire lifetime of the machine. This domain regulates access to the physical TPM on the system and secures the persistent state of each vTPM. - * mini-os/tpm_tis: Mini-os TPM version 1.2 TPM Interface Specification (TIS) +* mini-os/tpm_tis: + Mini-os TPM version 1.2 TPM Interface Specification (TIS) driver. This driver used by vtpmmgr-stubdom to talk directly to the hardware TPM. Communication is facilitated by mapping hardware memory pages into vtpmmgr-stubdom. - * Hardware TPM: The physical TPM that is soldered onto the motherboard. +* Hardware TPM: + The physical TPM that is soldered onto the motherboard. -INTEGRATION WITH XEN +Integration With Xen -------------------- Support for the vTPM driver was added in Xen using the libxl toolstack in Xen From 619ba4516771bdfb96658e7a5f57e6551232549a Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 19 Apr 2019 18:49:49 -0300 Subject: [PATCH 13/77] docs: bus-devices: ti-gpmc.rst: convert it to ReST In order to be able to add this file to a book, it needs first to be converted to ReST and renamed. While this is not part of any book, mark it as :orphan:, in order to avoid build warnings. Signed-off-by: Mauro Carvalho Chehab --- .../bus-devices/{ti-gpmc.txt => ti-gpmc.rst} | 159 ++++++++++++------ 1 file changed, 108 insertions(+), 51 deletions(-) rename Documentation/bus-devices/{ti-gpmc.txt => ti-gpmc.rst} (58%) diff --git a/Documentation/bus-devices/ti-gpmc.txt b/Documentation/bus-devices/ti-gpmc.rst similarity index 58% rename from Documentation/bus-devices/ti-gpmc.txt rename to Documentation/bus-devices/ti-gpmc.rst index cc9ce57e0a26..87c366e418be 100644 --- a/Documentation/bus-devices/ti-gpmc.txt +++ b/Documentation/bus-devices/ti-gpmc.rst @@ -1,8 +1,12 @@ -GPMC (General Purpose Memory Controller): -========================================= +:orphan: + +======================================== +GPMC (General Purpose Memory Controller) +======================================== GPMC is an unified memory controller dedicated to interfacing external memory devices like + * Asynchronous SRAM like memories and application specific integrated circuit devices. * Asynchronous, synchronous, and page mode burst NOR flash devices @@ -48,75 +52,128 @@ most of the datasheets & hardware (to be exact none of those supported in mainline having custom timing routine) and by simulation. gpmc timing dependency on peripheral timings: + [: , ...] 1. common -cs_on: t_ceasu -adv_on: t_avdasu, t_ceavd + +cs_on: + t_ceasu +adv_on: + t_avdasu, t_ceavd 2. sync common -sync_clk: clk -page_burst_access: t_bacc -clk_activation: t_ces, t_avds + +sync_clk: + clk +page_burst_access: + t_bacc +clk_activation: + t_ces, t_avds 3. read async muxed -adv_rd_off: t_avdp_r -oe_on: t_oeasu, t_aavdh -access: t_iaa, t_oe, t_ce, t_aa -rd_cycle: t_rd_cycle, t_cez_r, t_oez + +adv_rd_off: + t_avdp_r +oe_on: + t_oeasu, t_aavdh +access: + t_iaa, t_oe, t_ce, t_aa +rd_cycle: + t_rd_cycle, t_cez_r, t_oez 4. read async non-muxed -adv_rd_off: t_avdp_r -oe_on: t_oeasu -access: t_iaa, t_oe, t_ce, t_aa -rd_cycle: t_rd_cycle, t_cez_r, t_oez + +adv_rd_off: + t_avdp_r +oe_on: + t_oeasu +access: + t_iaa, t_oe, t_ce, t_aa +rd_cycle: + t_rd_cycle, t_cez_r, t_oez 5. read sync muxed -adv_rd_off: t_avdp_r, t_avdh -oe_on: t_oeasu, t_ach, cyc_aavdh_oe -access: t_iaa, cyc_iaa, cyc_oe -rd_cycle: t_cez_r, t_oez, t_ce_rdyz + +adv_rd_off: + t_avdp_r, t_avdh +oe_on: + t_oeasu, t_ach, cyc_aavdh_oe +access: + t_iaa, cyc_iaa, cyc_oe +rd_cycle: + t_cez_r, t_oez, t_ce_rdyz 6. read sync non-muxed -adv_rd_off: t_avdp_r -oe_on: t_oeasu -access: t_iaa, cyc_iaa, cyc_oe -rd_cycle: t_cez_r, t_oez, t_ce_rdyz + +adv_rd_off: + t_avdp_r +oe_on: + t_oeasu +access: + t_iaa, cyc_iaa, cyc_oe +rd_cycle: + t_cez_r, t_oez, t_ce_rdyz 7. write async muxed -adv_wr_off: t_avdp_w -we_on, wr_data_mux_bus: t_weasu, t_aavdh, cyc_aavhd_we -we_off: t_wpl -cs_wr_off: t_wph -wr_cycle: t_cez_w, t_wr_cycle + +adv_wr_off: + t_avdp_w +we_on, wr_data_mux_bus: + t_weasu, t_aavdh, cyc_aavhd_we +we_off: + t_wpl +cs_wr_off: + t_wph +wr_cycle: + t_cez_w, t_wr_cycle 8. write async non-muxed -adv_wr_off: t_avdp_w -we_on, wr_data_mux_bus: t_weasu -we_off: t_wpl -cs_wr_off: t_wph -wr_cycle: t_cez_w, t_wr_cycle + +adv_wr_off: + t_avdp_w +we_on, wr_data_mux_bus: + t_weasu +we_off: + t_wpl +cs_wr_off: + t_wph +wr_cycle: + t_cez_w, t_wr_cycle 9. write sync muxed -adv_wr_off: t_avdp_w, t_avdh -we_on, wr_data_mux_bus: t_weasu, t_rdyo, t_aavdh, cyc_aavhd_we -we_off: t_wpl, cyc_wpl -cs_wr_off: t_wph -wr_cycle: t_cez_w, t_ce_rdyz + +adv_wr_off: + t_avdp_w, t_avdh +we_on, wr_data_mux_bus: + t_weasu, t_rdyo, t_aavdh, cyc_aavhd_we +we_off: + t_wpl, cyc_wpl +cs_wr_off: + t_wph +wr_cycle: + t_cez_w, t_ce_rdyz 10. write sync non-muxed -adv_wr_off: t_avdp_w -we_on, wr_data_mux_bus: t_weasu, t_rdyo -we_off: t_wpl, cyc_wpl -cs_wr_off: t_wph -wr_cycle: t_cez_w, t_ce_rdyz + +adv_wr_off: + t_avdp_w +we_on, wr_data_mux_bus: + t_weasu, t_rdyo +we_off: + t_wpl, cyc_wpl +cs_wr_off: + t_wph +wr_cycle: + t_cez_w, t_ce_rdyz -Note: Many of gpmc timings are dependent on other gpmc timings (a few -gpmc timings purely dependent on other gpmc timings, a reason that -some of the gpmc timings are missing above), and it will result in -indirect dependency of peripheral timings to gpmc timings other than -mentioned above, refer timing routine for more details. To know what -these peripheral timings correspond to, please see explanations in -struct gpmc_device_timings definition. And for gpmc timings refer -IP details (link above). +Note: + Many of gpmc timings are dependent on other gpmc timings (a few + gpmc timings purely dependent on other gpmc timings, a reason that + some of the gpmc timings are missing above), and it will result in + indirect dependency of peripheral timings to gpmc timings other than + mentioned above, refer timing routine for more details. To know what + these peripheral timings correspond to, please see explanations in + struct gpmc_device_timings definition. And for gpmc timings refer + IP details (link above). From a278295ccc2ddd1dc0ac8423a12ff6dd74f0d502 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 15 Apr 2019 19:25:27 -0300 Subject: [PATCH 14/77] docs: nvmem: convert docs to ReST and rename to *.rst In order to be able to add it into a doc book, we need first convert it to ReST. The conversion is actually: - add blank lines and identation in order to identify paragraphs; - mark literal blocks; - adjust title markups. While this is not part of any book, mark it as :orphan:, in order to avoid build warnings. Signed-off-by: Mauro Carvalho Chehab --- Documentation/nvmem/{nvmem.txt => nvmem.rst} | 112 ++++++++++--------- 1 file changed, 59 insertions(+), 53 deletions(-) rename Documentation/nvmem/{nvmem.txt => nvmem.rst} (62%) diff --git a/Documentation/nvmem/nvmem.txt b/Documentation/nvmem/nvmem.rst similarity index 62% rename from Documentation/nvmem/nvmem.txt rename to Documentation/nvmem/nvmem.rst index fc2fe4b18655..3866b6e066d5 100644 --- a/Documentation/nvmem/nvmem.txt +++ b/Documentation/nvmem/nvmem.rst @@ -1,5 +1,10 @@ - NVMEM SUBSYSTEM - Srinivas Kandagatla +:orphan: + +=============== +NVMEM Subsystem +=============== + + Srinivas Kandagatla This document explains the NVMEM Framework along with the APIs provided, and how to use it. @@ -40,54 +45,54 @@ nvmem_device pointer. nvmem_unregister(nvmem) is used to unregister a previously registered provider. -For example, a simple qfprom case: +For example, a simple qfprom case:: -static struct nvmem_config econfig = { + static struct nvmem_config econfig = { .name = "qfprom", .owner = THIS_MODULE, -}; + }; -static int qfprom_probe(struct platform_device *pdev) -{ + static int qfprom_probe(struct platform_device *pdev) + { ... econfig.dev = &pdev->dev; nvmem = nvmem_register(&econfig); ... -} + } It is mandatory that the NVMEM provider has a regmap associated with its struct device. Failure to do would return error code from nvmem_register(). Users of board files can define and register nvmem cells using the -nvmem_cell_table struct: +nvmem_cell_table struct:: -static struct nvmem_cell_info foo_nvmem_cells[] = { + static struct nvmem_cell_info foo_nvmem_cells[] = { { .name = "macaddr", .offset = 0x7f00, .bytes = ETH_ALEN, } -}; + }; -static struct nvmem_cell_table foo_nvmem_cell_table = { + static struct nvmem_cell_table foo_nvmem_cell_table = { .nvmem_name = "i2c-eeprom", .cells = foo_nvmem_cells, .ncells = ARRAY_SIZE(foo_nvmem_cells), -}; + }; -nvmem_add_cell_table(&foo_nvmem_cell_table); + nvmem_add_cell_table(&foo_nvmem_cell_table); Additionally it is possible to create nvmem cell lookup entries and register -them with the nvmem framework from machine code as shown in the example below: +them with the nvmem framework from machine code as shown in the example below:: -static struct nvmem_cell_lookup foo_nvmem_lookup = { + static struct nvmem_cell_lookup foo_nvmem_lookup = { .nvmem_name = "i2c-eeprom", .cell_name = "macaddr", .dev_id = "foo_mac.0", .con_id = "mac-address", -}; + }; -nvmem_add_cell_lookups(&foo_nvmem_lookup, 1); + nvmem_add_cell_lookups(&foo_nvmem_lookup, 1); NVMEM Consumers +++++++++++++++ @@ -99,43 +104,43 @@ read from and to NVMEM. ================================= NVMEM cells are the data entries/fields in the NVMEM. -The NVMEM framework provides 3 APIs to read/write NVMEM cells. +The NVMEM framework provides 3 APIs to read/write NVMEM cells:: -struct nvmem_cell *nvmem_cell_get(struct device *dev, const char *name); -struct nvmem_cell *devm_nvmem_cell_get(struct device *dev, const char *name); + struct nvmem_cell *nvmem_cell_get(struct device *dev, const char *name); + struct nvmem_cell *devm_nvmem_cell_get(struct device *dev, const char *name); -void nvmem_cell_put(struct nvmem_cell *cell); -void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell); + void nvmem_cell_put(struct nvmem_cell *cell); + void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell); -void *nvmem_cell_read(struct nvmem_cell *cell, ssize_t *len); -int nvmem_cell_write(struct nvmem_cell *cell, void *buf, ssize_t len); + void *nvmem_cell_read(struct nvmem_cell *cell, ssize_t *len); + int nvmem_cell_write(struct nvmem_cell *cell, void *buf, ssize_t len); -*nvmem_cell_get() apis will get a reference to nvmem cell for a given id, +`*nvmem_cell_get()` apis will get a reference to nvmem cell for a given id, and nvmem_cell_read/write() can then read or write to the cell. -Once the usage of the cell is finished the consumer should call *nvmem_cell_put() -to free all the allocation memory for the cell. +Once the usage of the cell is finished the consumer should call +`*nvmem_cell_put()` to free all the allocation memory for the cell. 4. Direct NVMEM device based consumer APIs ========================================== In some instances it is necessary to directly read/write the NVMEM. -To facilitate such consumers NVMEM framework provides below apis. +To facilitate such consumers NVMEM framework provides below apis:: -struct nvmem_device *nvmem_device_get(struct device *dev, const char *name); -struct nvmem_device *devm_nvmem_device_get(struct device *dev, + struct nvmem_device *nvmem_device_get(struct device *dev, const char *name); + struct nvmem_device *devm_nvmem_device_get(struct device *dev, const char *name); -void nvmem_device_put(struct nvmem_device *nvmem); -int nvmem_device_read(struct nvmem_device *nvmem, unsigned int offset, + void nvmem_device_put(struct nvmem_device *nvmem); + int nvmem_device_read(struct nvmem_device *nvmem, unsigned int offset, size_t bytes, void *buf); -int nvmem_device_write(struct nvmem_device *nvmem, unsigned int offset, + int nvmem_device_write(struct nvmem_device *nvmem, unsigned int offset, size_t bytes, void *buf); -int nvmem_device_cell_read(struct nvmem_device *nvmem, + int nvmem_device_cell_read(struct nvmem_device *nvmem, struct nvmem_cell_info *info, void *buf); -int nvmem_device_cell_write(struct nvmem_device *nvmem, + int nvmem_device_cell_write(struct nvmem_device *nvmem, struct nvmem_cell_info *info, void *buf); Before the consumers can read/write NVMEM directly, it should get hold -of nvmem_controller from one of the *nvmem_device_get() api. +of nvmem_controller from one of the `*nvmem_device_get()` api. The difference between these apis and cell based apis is that these apis always take nvmem_device as parameter. @@ -145,12 +150,12 @@ take nvmem_device as parameter. When a consumer no longer needs the NVMEM, it has to release the reference to the NVMEM it has obtained using the APIs mentioned in the above section. -The NVMEM framework provides 2 APIs to release a reference to the NVMEM. +The NVMEM framework provides 2 APIs to release a reference to the NVMEM:: -void nvmem_cell_put(struct nvmem_cell *cell); -void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell); -void nvmem_device_put(struct nvmem_device *nvmem); -void devm_nvmem_device_put(struct device *dev, struct nvmem_device *nvmem); + void nvmem_cell_put(struct nvmem_cell *cell); + void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell); + void nvmem_device_put(struct nvmem_device *nvmem); + void devm_nvmem_device_put(struct device *dev, struct nvmem_device *nvmem); Both these APIs are used to release a reference to the NVMEM and devm_nvmem_cell_put and devm_nvmem_device_put destroys the devres associated @@ -162,20 +167,21 @@ Userspace 6. Userspace binary interface ============================== -Userspace can read/write the raw NVMEM file located at -/sys/bus/nvmem/devices/*/nvmem +Userspace can read/write the raw NVMEM file located at:: -ex: + /sys/bus/nvmem/devices/*/nvmem -hexdump /sys/bus/nvmem/devices/qfprom0/nvmem +ex:: -0000000 0000 0000 0000 0000 0000 0000 0000 0000 -* -00000a0 db10 2240 0000 e000 0c00 0c00 0000 0c00 -0000000 0000 0000 0000 0000 0000 0000 0000 0000 -... -* -0001000 + hexdump /sys/bus/nvmem/devices/qfprom0/nvmem + + 0000000 0000 0000 0000 0000 0000 0000 0000 0000 + * + 00000a0 db10 2240 0000 e000 0c00 0c00 0000 0c00 + 0000000 0000 0000 0000 0000 0000 0000 0000 0000 + ... + * + 0001000 7. DeviceTree Binding ===================== From 1945a035540e2cef0362a2e7e828f8cf547e86b8 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 15 Apr 2019 19:27:55 -0300 Subject: [PATCH 15/77] docs: phy: convert samsung-usb2.txt to ReST format In order to merge it into a Sphinx book, we need first to convert to ReST. While this is not part of any book, mark it as :orphan:, in order to avoid build warnings. Signed-off-by: Mauro Carvalho Chehab --- .../{samsung-usb2.txt => samsung-usb2.rst} | 62 ++++++++++--------- MAINTAINERS | 2 +- 2 files changed, 34 insertions(+), 30 deletions(-) rename Documentation/phy/{samsung-usb2.txt => samsung-usb2.rst} (77%) diff --git a/Documentation/phy/samsung-usb2.txt b/Documentation/phy/samsung-usb2.rst similarity index 77% rename from Documentation/phy/samsung-usb2.txt rename to Documentation/phy/samsung-usb2.rst index ed12d437189d..98b5952fcb97 100644 --- a/Documentation/phy/samsung-usb2.txt +++ b/Documentation/phy/samsung-usb2.rst @@ -1,9 +1,11 @@ -.------------------------------------------------------------------------------+ -| Samsung USB 2.0 PHY adaptation layer | -+-----------------------------------------------------------------------------+' +:orphan: -| 1. Description -+---------------- +==================================== +Samsung USB 2.0 PHY adaptation layer +==================================== + +1. Description +-------------- The architecture of the USB 2.0 PHY module in Samsung SoCs is similar among many SoCs. In spite of the similarities it proved difficult to @@ -14,8 +16,8 @@ the PHY powering up process had to be altered. This adaptation layer is a compromise between having separate drivers and having a single driver with added support for many special cases. -| 2. Files description -+---------------------- +2. Files description +-------------------- - phy-samsung-usb2.c This is the main file of the adaptation layer. This file contains @@ -32,44 +34,45 @@ with added support for many special cases. driver. In addition it should contain extern declarations for structures that describe particular SoCs. -| 3. Supporting SoCs -+-------------------- +3. Supporting SoCs +------------------ To support a new SoC a new file should be added to the drivers/phy directory. Each SoC's configuration is stored in an instance of the -struct samsung_usb2_phy_config. +struct samsung_usb2_phy_config:: -struct samsung_usb2_phy_config { + struct samsung_usb2_phy_config { const struct samsung_usb2_common_phy *phys; int (*rate_to_clk)(unsigned long, u32 *); unsigned int num_phys; bool has_mode_switch; -}; + }; -The num_phys is the number of phys handled by the driver. *phys is an +The num_phys is the number of phys handled by the driver. `*phys` is an array that contains the configuration for each phy. The has_mode_switch property is a boolean flag that determines whether the SoC has USB host and device on a single pair of pins. If so, a special register has to be modified to change the internal routing of these pins between a USB device or host module. -For example the configuration for Exynos 4210 is following: +For example the configuration for Exynos 4210 is following:: -const struct samsung_usb2_phy_config exynos4210_usb2_phy_config = { + const struct samsung_usb2_phy_config exynos4210_usb2_phy_config = { .has_mode_switch = 0, .num_phys = EXYNOS4210_NUM_PHYS, .phys = exynos4210_phys, .rate_to_clk = exynos4210_rate_to_clk, -} + } + +- `int (*rate_to_clk)(unsigned long, u32 *)` -- int (*rate_to_clk)(unsigned long, u32 *) The rate_to_clk callback is to convert the rate of the clock used as the reference clock for the PHY module to the value that should be written in the hardware register. -The exynos4210_phys configuration array is as follows: +The exynos4210_phys configuration array is as follows:: -static const struct samsung_usb2_common_phy exynos4210_phys[] = { + static const struct samsung_usb2_common_phy exynos4210_phys[] = { { .label = "device", .id = EXYNOS4210_DEVICE, @@ -95,29 +98,30 @@ static const struct samsung_usb2_common_phy exynos4210_phys[] = { .power_off = exynos4210_power_off, }, {}, -}; + }; + +- `int (*power_on)(struct samsung_usb2_phy_instance *);` + `int (*power_off)(struct samsung_usb2_phy_instance *);` -- int (*power_on)(struct samsung_usb2_phy_instance *); -- int (*power_off)(struct samsung_usb2_phy_instance *); These two callbacks are used to power on and power off the phy by modifying appropriate registers. Final change to the driver is adding appropriate compatible value to the phy-samsung-usb2.c file. In case of Exynos 4210 the following lines were -added to the struct of_device_id samsung_usb2_phy_of_match[] array: +added to the struct of_device_id samsung_usb2_phy_of_match[] array:: -#ifdef CONFIG_PHY_EXYNOS4210_USB2 + #ifdef CONFIG_PHY_EXYNOS4210_USB2 { .compatible = "samsung,exynos4210-usb2-phy", .data = &exynos4210_usb2_phy_config, }, -#endif + #endif To add further flexibility to the driver the Kconfig file enables to include support for selected SoCs in the compiled driver. The Kconfig -entry for Exynos 4210 is following: +entry for Exynos 4210 is following:: -config PHY_EXYNOS4210_USB2 + config PHY_EXYNOS4210_USB2 bool "Support for Exynos 4210" depends on PHY_SAMSUNG_USB2 depends on CPU_EXYNOS4210 @@ -128,8 +132,8 @@ config PHY_EXYNOS4210_USB2 phys are available - device, host, HSCI0 and HSCI1. The newly created file that supports the new SoC has to be also added to the -Makefile. In case of Exynos 4210 the added line is following: +Makefile. In case of Exynos 4210 the added line is following:: -obj-$(CONFIG_PHY_EXYNOS4210_USB2) += phy-exynos4210-usb2.o + obj-$(CONFIG_PHY_EXYNOS4210_USB2) += phy-exynos4210-usb2.o After completing these steps the support for the new SoC should be ready. diff --git a/MAINTAINERS b/MAINTAINERS index 96c85695b3d4..2a2d74e5d670 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -14083,7 +14083,7 @@ M: Sylwester Nawrocki L: linux-kernel@vger.kernel.org S: Supported F: Documentation/devicetree/bindings/phy/samsung-phy.txt -F: Documentation/phy/samsung-usb2.txt +F: Documentation/phy/samsung-usb2.rst F: drivers/phy/samsung/phy-exynos4210-usb2.c F: drivers/phy/samsung/phy-exynos4x12-usb2.c F: drivers/phy/samsung/phy-exynos5250-usb2.c From eaf5211d8c00060a3b41a031a762c906d3603098 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 15 Apr 2019 23:00:35 -0300 Subject: [PATCH 16/77] docs: rbtree.txt: fix Sphinx build warnings Ths file is already at ReST format. Yet, some recent changes made it to produce a few warnings when building it with Sphinx. Those are trivially fixed by marking some literal blocks. Fix them before adding it to the docs building system. Signed-off-by: Mauro Carvalho Chehab --- Documentation/rbtree.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Documentation/rbtree.txt b/Documentation/rbtree.txt index c42a21b99046..523d54b60087 100644 --- a/Documentation/rbtree.txt +++ b/Documentation/rbtree.txt @@ -204,21 +204,21 @@ potentially expensive tree iterations. This is done at negligible runtime overhead for maintanence; albeit larger memory footprint. Similar to the rb_root structure, cached rbtrees are initialized to be -empty via: +empty via:: struct rb_root_cached mytree = RB_ROOT_CACHED; Cached rbtree is simply a regular rb_root with an extra pointer to cache the leftmost node. This allows rb_root_cached to exist wherever rb_root does, which permits augmented trees to be supported as well as only a few extra -interfaces: +interfaces:: struct rb_node *rb_first_cached(struct rb_root_cached *tree); void rb_insert_color_cached(struct rb_node *, struct rb_root_cached *, bool); void rb_erase_cached(struct rb_node *node, struct rb_root_cached *); Both insert and erase calls have their respective counterpart of augmented -trees: +trees:: void rb_insert_augmented_cached(struct rb_node *node, struct rb_root_cached *, bool, struct rb_augment_callbacks *); From a36d053863a1b6cd6e79a632af01be014517f9ac Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 27 May 2019 15:59:13 -0300 Subject: [PATCH 17/77] docs: DMA-API-HOWTO.txt: fix an unmarked code block When building with Sphinx, it would produce this warning: docs/Documentation/DMA-API-HOWTO.rst:222: WARNING: Definition list ends without a blank line; unexpected unindent. Signed-off-by: Mauro Carvalho Chehab --- Documentation/DMA-API-HOWTO.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/DMA-API-HOWTO.txt b/Documentation/DMA-API-HOWTO.txt index cb712a02f59f..358d495456d1 100644 --- a/Documentation/DMA-API-HOWTO.txt +++ b/Documentation/DMA-API-HOWTO.txt @@ -212,7 +212,7 @@ The standard 64-bit addressing device would do something like this:: If the device only supports 32-bit addressing for descriptors in the coherent allocations, but supports full 64-bits for streaming mappings -it would look like this: +it would look like this:: if (dma_set_mask(dev, DMA_BIT_MASK(64))) { dev_warn(dev, "mydev: No suitable DMA available\n"); From c3123552aad3ffd7a35e16d4402231225165e343 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 17 Apr 2019 05:46:08 -0300 Subject: [PATCH 18/77] docs: accounting: convert to ReST Rename the accounting documentation files to ReST, add an index for them and adjust in order to produce a nice html output via the Sphinx build system. At its new index.rst, let's add a :orphan: while this is not linked to the main index.rst file, in order to avoid build warnings. Signed-off-by: Mauro Carvalho Chehab --- .../{cgroupstats.txt => cgroupstats.rst} | 14 ++-- ...ay-accounting.txt => delay-accounting.rst} | 61 ++++++++------ Documentation/accounting/index.rst | 14 ++++ Documentation/accounting/{psi.txt => psi.rst} | 40 +++++----- ...kstats-struct.txt => taskstats-struct.rst} | 79 ++++++++++++------- .../{taskstats.txt => taskstats.rst} | 15 ++-- Documentation/admin-guide/cgroup-v2.rst | 6 +- init/Kconfig | 2 +- 8 files changed, 139 insertions(+), 92 deletions(-) rename Documentation/accounting/{cgroupstats.txt => cgroupstats.rst} (77%) rename Documentation/accounting/{delay-accounting.txt => delay-accounting.rst} (77%) create mode 100644 Documentation/accounting/index.rst rename Documentation/accounting/{psi.txt => psi.rst} (91%) rename Documentation/accounting/{taskstats-struct.txt => taskstats-struct.rst} (78%) rename Documentation/accounting/{taskstats.txt => taskstats.rst} (95%) diff --git a/Documentation/accounting/cgroupstats.txt b/Documentation/accounting/cgroupstats.rst similarity index 77% rename from Documentation/accounting/cgroupstats.txt rename to Documentation/accounting/cgroupstats.rst index d16a9849e60e..b9afc48f4ea2 100644 --- a/Documentation/accounting/cgroupstats.txt +++ b/Documentation/accounting/cgroupstats.rst @@ -1,3 +1,7 @@ +================== +Control Groupstats +================== + Control Groupstats is inspired by the discussion at http://lkml.org/lkml/2007/4/11/187 and implements per cgroup statistics as suggested by Andrew Morton in http://lkml.org/lkml/2007/4/11/263. @@ -19,9 +23,9 @@ about tasks blocked on I/O. If CONFIG_TASK_DELAY_ACCT is disabled, this information will not be available. To extract cgroup statistics a utility very similar to getdelays.c -has been developed, the sample output of the utility is shown below +has been developed, the sample output of the utility is shown below:: -~/balbir/cgroupstats # ./getdelays -C "/sys/fs/cgroup/a" -sleeping 1, blocked 0, running 1, stopped 0, uninterruptible 0 -~/balbir/cgroupstats # ./getdelays -C "/sys/fs/cgroup" -sleeping 155, blocked 0, running 1, stopped 0, uninterruptible 2 + ~/balbir/cgroupstats # ./getdelays -C "/sys/fs/cgroup/a" + sleeping 1, blocked 0, running 1, stopped 0, uninterruptible 0 + ~/balbir/cgroupstats # ./getdelays -C "/sys/fs/cgroup" + sleeping 155, blocked 0, running 1, stopped 0, uninterruptible 2 diff --git a/Documentation/accounting/delay-accounting.txt b/Documentation/accounting/delay-accounting.rst similarity index 77% rename from Documentation/accounting/delay-accounting.txt rename to Documentation/accounting/delay-accounting.rst index 042ea59b5853..7cc7f5852da0 100644 --- a/Documentation/accounting/delay-accounting.txt +++ b/Documentation/accounting/delay-accounting.rst @@ -1,5 +1,6 @@ +================ Delay accounting ----------------- +================ Tasks encounter delays in execution when they wait for some kernel resource to become available e.g. a @@ -39,7 +40,9 @@ in detail in a separate document in this directory. Taskstats returns a generic data structure to userspace corresponding to per-pid and per-tgid statistics. The delay accounting functionality populates specific fields of this structure. See + include/linux/taskstats.h + for a description of the fields pertaining to delay accounting. It will generally be in the form of counters returning the cumulative delay seen for cpu, sync block I/O, swapin, memory reclaim etc. @@ -61,13 +64,16 @@ also serves as an example of using the taskstats interface. Usage ----- -Compile the kernel with +Compile the kernel with:: + CONFIG_TASK_DELAY_ACCT=y CONFIG_TASKSTATS=y Delay accounting is enabled by default at boot up. -To disable, add +To disable, add:: + nodelayacct + to the kernel boot options. The rest of the instructions below assume this has not been done. @@ -78,40 +84,43 @@ The utility also allows a given command to be executed and the corresponding delays to be seen. -General format of the getdelays command +General format of the getdelays command:: -getdelays [-t tgid] [-p pid] [-c cmd...] + getdelays [-t tgid] [-p pid] [-c cmd...] -Get delays, since system boot, for pid 10 -# ./getdelays -p 10 -(output similar to next case) +Get delays, since system boot, for pid 10:: -Get sum of delays, since system boot, for all pids with tgid 5 -# ./getdelays -t 5 + # ./getdelays -p 10 + (output similar to next case) + +Get sum of delays, since system boot, for all pids with tgid 5:: + + # ./getdelays -t 5 -CPU count real total virtual total delay total - 7876 92005750 100000000 24001500 -IO count delay total - 0 0 -SWAP count delay total - 0 0 -RECLAIM count delay total - 0 0 + CPU count real total virtual total delay total + 7876 92005750 100000000 24001500 + IO count delay total + 0 0 + SWAP count delay total + 0 0 + RECLAIM count delay total + 0 0 -Get delays seen in executing a given simple command -# ./getdelays -c ls / +Get delays seen in executing a given simple command:: -bin data1 data3 data5 dev home media opt root srv sys usr -boot data2 data4 data6 etc lib mnt proc sbin subdomain tmp var + # ./getdelays -c ls / + + bin data1 data3 data5 dev home media opt root srv sys usr + boot data2 data4 data6 etc lib mnt proc sbin subdomain tmp var -CPU count real total virtual total delay total + CPU count real total virtual total delay total 6 4000250 4000000 0 -IO count delay total + IO count delay total 0 0 -SWAP count delay total + SWAP count delay total 0 0 -RECLAIM count delay total + RECLAIM count delay total 0 0 diff --git a/Documentation/accounting/index.rst b/Documentation/accounting/index.rst new file mode 100644 index 000000000000..e1f6284b5ff3 --- /dev/null +++ b/Documentation/accounting/index.rst @@ -0,0 +1,14 @@ +:orphan: + +========== +Accounting +========== + +.. toctree:: + :maxdepth: 1 + + cgroupstats + delay-accounting + psi + taskstats + taskstats-struct diff --git a/Documentation/accounting/psi.txt b/Documentation/accounting/psi.rst similarity index 91% rename from Documentation/accounting/psi.txt rename to Documentation/accounting/psi.rst index 5cbe5659e3b7..621111ce5740 100644 --- a/Documentation/accounting/psi.txt +++ b/Documentation/accounting/psi.rst @@ -35,14 +35,14 @@ Pressure interface Pressure information for each resource is exported through the respective file in /proc/pressure/ -- cpu, memory, and io. -The format for CPU is as such: +The format for CPU is as such:: -some avg10=0.00 avg60=0.00 avg300=0.00 total=0 + some avg10=0.00 avg60=0.00 avg300=0.00 total=0 -and for memory and IO: +and for memory and IO:: -some avg10=0.00 avg60=0.00 avg300=0.00 total=0 -full avg10=0.00 avg60=0.00 avg300=0.00 total=0 + some avg10=0.00 avg60=0.00 avg300=0.00 total=0 + full avg10=0.00 avg60=0.00 avg300=0.00 total=0 The "some" line indicates the share of time in which at least some tasks are stalled on a given resource. @@ -77,9 +77,9 @@ To register a trigger user has to open psi interface file under /proc/pressure/ representing the resource to be monitored and write the desired threshold and time window. The open file descriptor should be used to wait for trigger events using select(), poll() or epoll(). -The following format is used: +The following format is used:: -