From 387b14684f94483cbbb72843db406ec9a8d0d6d2 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 10 Apr 2019 08:32:41 -0300 Subject: 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 + Documentation/locking/lockdep-design.rst | 394 ++++++++++++++ Documentation/locking/lockdep-design.txt | 389 -------------- Documentation/locking/lockstat.rst | 204 ++++++++ Documentation/locking/lockstat.txt | 183 ------- Documentation/locking/locktorture.rst | 170 ++++++ Documentation/locking/locktorture.txt | 145 ------ Documentation/locking/mutex-design.rst | 152 ++++++ Documentation/locking/mutex-design.txt | 142 ----- Documentation/locking/rt-mutex-design.rst | 574 +++++++++++++++++++++ Documentation/locking/rt-mutex-design.txt | 559 -------------------- Documentation/locking/rt-mutex.rst | 77 +++ Documentation/locking/rt-mutex.txt | 73 --- Documentation/locking/spinlocks.rst | 177 +++++++ Documentation/locking/spinlocks.txt | 167 ------ Documentation/locking/ww-mutex-design.rst | 393 ++++++++++++++ Documentation/locking/ww-mutex-design.txt | 383 -------------- Documentation/pi-futex.txt | 2 +- .../translations/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 +- 27 files changed, 2176 insertions(+), 2052 deletions(-) create mode 100644 Documentation/locking/index.rst create mode 100644 Documentation/locking/lockdep-design.rst delete mode 100644 Documentation/locking/lockdep-design.txt create mode 100644 Documentation/locking/lockstat.rst delete mode 100644 Documentation/locking/lockstat.txt create mode 100644 Documentation/locking/locktorture.rst delete mode 100644 Documentation/locking/locktorture.txt create mode 100644 Documentation/locking/mutex-design.rst delete mode 100644 Documentation/locking/mutex-design.txt create mode 100644 Documentation/locking/rt-mutex-design.rst delete mode 100644 Documentation/locking/rt-mutex-design.txt create mode 100644 Documentation/locking/rt-mutex.rst delete mode 100644 Documentation/locking/rt-mutex.txt create mode 100644 Documentation/locking/spinlocks.rst delete mode 100644 Documentation/locking/spinlocks.txt create mode 100644 Documentation/locking/ww-mutex-design.rst delete mode 100644 Documentation/locking/ww-mutex-design.txt 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.rst b/Documentation/locking/lockdep-design.rst new file mode 100644 index 000000000000..23fcbc4d3fc0 --- /dev/null +++ b/Documentation/locking/lockdep-design.rst @@ -0,0 +1,394 @@ +Runtime locking correctness validator +===================================== + +started by Ingo Molnar + +additions by Arjan van de Ven + +Lock-class +---------- + +The basic object the validator operates upon is a 'class' of locks. + +A class of locks is a group of locks that are logically the same with +respect to locking rules, even if the locks may have multiple (possibly +tens of thousands of) instantiations. For example a lock in the inode +struct is one class, while each inode has its own instantiation of that +lock class. + +The validator tracks the 'usage state' of lock-classes, and it tracks +the dependencies between different lock-classes. Lock usage indicates +how a lock is used with regard to its IRQ contexts, while lock +dependency can be understood as lock order, where L1 -> L2 suggests that +a task is attempting to acquire L2 while holding L1. From lockdep's +perspective, the two locks (L1 and L2) are not necessarily related; that +dependency just means the order ever happened. The validator maintains a +continuing effort to prove lock usages and dependencies are correct or +the validator will shoot a splat if incorrect. + +A lock-class's behavior is constructed by its instances collectively: +when the first instance of a lock-class is used after bootup the class +gets registered, then all (subsequent) instances will be mapped to the +class and hence their usages and dependecies will contribute to those of +the class. A lock-class does not go away when a lock instance does, but +it can be removed if the memory space of the lock class (static or +dynamic) is reclaimed, this happens for example when a module is +unloaded or a workqueue is destroyed. + +State +----- + +The validator tracks lock-class usage history and divides the usage into +(4 usages * n STATEs + 1) categories: + +where the 4 usages can be: +- 'ever held in STATE context' +- 'ever held as readlock in STATE context' +- 'ever held with STATE enabled' +- 'ever held as readlock with STATE enabled' + +where the n STATEs are coded in kernel/locking/lockdep_states.h and as of +now they include: +- hardirq +- softirq + +where the last 1 category is: +- 'ever used' [ == !unused ] + +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:: + + modprobe/2287 is trying to acquire lock: + (&sio_locks[i].lock){-.-.}, at: [] mutex_lock+0x21/0x24 + + but task is already holding lock: + (&sio_locks[i].lock){-.-.}, at: [] mutex_lock+0x21/0x24 + + +For a given lock, the bit positions from left to right indicate the usage +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:: + + (&sio_locks[i].lock){-.-.}, at: [] mutex_lock+0x21/0x24 + |||| + ||| \-> softirq disabled and not in softirq context + || \--> acquired in softirq context + | \---> hardirq disabled and not in hardirq context + \----> acquired in hardirq context + + +For a given STATE, whether the lock is ever acquired in that STATE +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 +applied for '+' too. + +Unused locks (e.g., mutexes) cannot be part of the cause of an error. + + +Single-lock state rules: +------------------------ + +A lock is irq-safe means it was ever used in an irq context, while a lock +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:: + + or + or + +This is because if a lock can be used in irq context (irq-safe) then it +cannot be ever acquired with irq enabled (irq-unsafe). Otherwise, a +deadlock may happen. For example, in the scenario that after this lock +was acquired but before released, if the context is interrupted this +lock will be attempted to acquire twice, which creates a deadlock, +referred to as lock recursion deadlock. + +The validator detects and reports lock usage that violates these +single-lock state rules. + +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:: + + -> + -> + +because this could lead to a deadlock - referred to as lock inversion +deadlock - as attempts to acquire the two locks form a circle which +could lead to the two contexts waiting for each other permanently. The +validator will find such dependency circle in arbitrary complexity, +i.e., there can be any other locking sequence between the acquire-lock +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:: + + -> + -> + +The first rule comes from the fact that a hardirq-safe lock could be +taken by a hardirq context, interrupting a hardirq-unsafe lock - and +thus could result in a lock inversion deadlock. Likewise, a softirq-safe +lock could be taken by an softirq context, interrupting a softirq-unsafe +lock. + +The above rules are enforced for any locking sequence that occurs in the +kernel: when acquiring a new lock, the validator checks whether there is +any rule violation between the new lock and any of the held locks. + +When a lock-class changes its state, the following aspects of the above +dependency rules are enforced: + +- if a new hardirq-safe lock is discovered, we check whether it + took any hardirq-unsafe lock in the past. + +- if a new softirq-safe lock is discovered, we check whether it took + any softirq-unsafe lock in the past. + +- if a new hardirq-unsafe lock is discovered, we check whether any + hardirq-safe lock took it in the past. + +- if a new softirq-unsafe lock is discovered, we check whether any + softirq-safe lock took it in the past. + +(Again, we do these checks too on the basis that an interrupt context +could interrupt _any_ of the irq-unsafe or hardirq-unsafe locks, which +could lead to a lock inversion deadlock - even if that lock scenario did +not trigger in practice yet.) + +Exception: Nested data dependencies leading to nested locking +------------------------------------------------------------- + +There are a few cases where the Linux kernel acquires more than one +instance of the same lock-class. Such cases typically happen when there +is some sort of hierarchy within objects of the same type. In these +cases there is an inherent "natural" ordering between the two objects +(defined by the properties of the hierarchy), and the kernel grabs the +locks in this fixed order on each of the objects. + +An example of such an object hierarchy that results in "nested locking" +is that of a "whole disk" block-dev object and a "partition" block-dev +object; the partition is "part of" the whole device and as long as one +always takes the whole disk lock as a higher lock than the partition +lock, the lock ordering is fully correct. The validator does not +automatically detect this natural ordering, as the locking rule behind +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:: + + 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); + +In this case the locking is done on a bdev object that is known to be a +partition. + +The validator treats a lock that is taken in such a nested fashion as a +separate (sub)class for the purposes of validation. + +Note: When changing code to use the _nested() primitives, be careful and +check really thoroughly that the hierarchy is correctly mapped; otherwise +you can get false positives or false negatives. + +Annotations +----------- + +Two constructs can be used to annotate and check where and if certain locks +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:: + + void update_rq_clock(struct rq *rq) + { + s64 delta; + + lockdep_assert_held(&rq->lock); + [...] + } + +where holding rq->lock is required to safely update a rq's clock. + +The other family of macros is lockdep_*pin_lock(), which is admittedly only +used for rq->lock ATM. Despite their limited adoption these annotations +generate a WARN() if the lock of interest is "accidentally" unlocked. This turns +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:: + + static inline void rq_pin_lock(struct rq *rq, struct rq_flags *rf) + { + rf->cookie = lockdep_pin_lock(&rq->lock); + [...] + } + + static inline void rq_unpin_lock(struct rq *rq, struct rq_flags *rf) + { + [...] + lockdep_unpin_lock(&rq->lock, rf->cookie); + } + +While comments about locking requirements might provide useful information, +the runtime checks performed by annotations are invaluable when debugging +locking problems and they carry the same level of details when inspecting +code. Always prefer annotations when in doubt! + +Proof of 100% correctness: +-------------------------- + +The validator achieves perfect, mathematical 'closure' (proof of locking +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. [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' +locking chains have to occur at least once (anytime, in any +task/context) for the validator to be able to prove correctness. (For +example, complex deadlocks that would normally need more than 3 CPUs and +a very unlikely constellation of tasks, irq-contexts and timings to +occur, can be detected on a plain, lightly loaded single-CPU system as +well!) + +This radically decreases the complexity of locking related QA of the +kernel: what has to be done during QA is to trigger as many "simple" +single-task locking dependencies in the kernel as possible, at least +once, to prove locking correctness - instead of having to trigger every +possible combination of locking interaction between CPUs, combined with +every possible hardirq and softirq nesting scenario (which is impossible +to do in practice). + +.. [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 + with the validator. We also assume that the 64-bit 'chain hash' + value is unique for every lock-chain in the system. Also, lock + recursion must not be higher than 20. + +Performance: +------------ + +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 +tens of thousands of checks for every event. + +This problem is solved by checking any given 'locking scenario' (unique +sequence of locks taken after each other) only once. A simple stack of +held locks is maintained, and a lightweight 64-bit hash value is +calculated, which hash is unique for every lock chain. The hash value, +when the chain is validated for the first time, is then put into a hash +table, which hash-table can be checked in a lockfree manner. If the +locking chain occurs again later on, the hash table tells us that we +don't have to validate the chain again. + +Troubleshooting: +---------------- + +The validator tracks a maximum of MAX_LOCKDEP_KEYS number of lock classes. +Exceeding this number will trigger the following lockdep warning: + + (DEBUG_LOCKS_WARN_ON(id >= MAX_LOCKDEP_KEYS)) + +By default, MAX_LOCKDEP_KEYS is currently set to 8191, and typical +desktop systems have less than 1,000 lock classes, so this warning +normally results from lock-class leakage or failure to properly +initialize locks. These two problems are illustrated below: + +1. Repeated module loading and unloading while running the validator + will result in lock-class leakage. The issue here is that each + load of the module will create a new set of lock classes for + that module's locks, but module unloading does not remove old + classes (see below discussion of reuse of lock classes for why). + Therefore, if that module is loaded and unloaded repeatedly, + the number of lock classes will eventually reach the maximum. + +2. Using structures such as arrays that have large numbers of + locks that are not explicitly initialized. For example, + a hash table with 8192 buckets where each bucket has its own + spinlock_t will consume 8192 lock classes -unless- each spinlock + is explicitly initialized at runtime, for example, using the + run-time spin_lock_init() as opposed to compile-time initializers + such as __SPIN_LOCK_UNLOCKED(). Failure to properly initialize + the per-bucket spinlocks would guarantee lock-class overflow. + In contrast, a loop that called spin_lock_init() on each lock + would place all 8192 locks into a single lock class. + + The moral of this story is that you should always explicitly + initialize your locks. + +One might argue that the validator should be modified to allow +lock classes to be reused. However, if you are tempted to make this +argument, first review the code and think through the changes that would +be required, keeping in mind that the lock classes to be removed are +likely to be linked into the lock-dependency graph. This turns out to +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:: + + grep "lock-classes" /proc/lockdep_stats + +This command produces the following output on a modest system:: + + 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:: + + grep "BD" /proc/lockdep + +Run the command and save the output, then compare against the output from +a later run of this command to identify the leakers. This same output +can also help you find situations where runtime lock initialization has +been omitted. diff --git a/Documentation/locking/lockdep-design.txt b/Documentation/locking/lockdep-design.txt deleted file mode 100644 index f189d130e543..000000000000 --- a/Documentation/locking/lockdep-design.txt +++ /dev/null @@ -1,389 +0,0 @@ -Runtime locking correctness validator -===================================== - -started by Ingo Molnar -additions by Arjan van de Ven - -Lock-class ----------- - -The basic object the validator operates upon is a 'class' of locks. - -A class of locks is a group of locks that are logically the same with -respect to locking rules, even if the locks may have multiple (possibly -tens of thousands of) instantiations. For example a lock in the inode -struct is one class, while each inode has its own instantiation of that -lock class. - -The validator tracks the 'usage state' of lock-classes, and it tracks -the dependencies between different lock-classes. Lock usage indicates -how a lock is used with regard to its IRQ contexts, while lock -dependency can be understood as lock order, where L1 -> L2 suggests that -a task is attempting to acquire L2 while holding L1. From lockdep's -perspective, the two locks (L1 and L2) are not necessarily related; that -dependency just means the order ever happened. The validator maintains a -continuing effort to prove lock usages and dependencies are correct or -the validator will shoot a splat if incorrect. - -A lock-class's behavior is constructed by its instances collectively: -when the first instance of a lock-class is used after bootup the class -gets registered, then all (subsequent) instances will be mapped to the -class and hence their usages and dependecies will contribute to those of -the class. A lock-class does not go away when a lock instance does, but -it can be removed if the memory space of the lock class (static or -dynamic) is reclaimed, this happens for example when a module is -unloaded or a workqueue is destroyed. - -State ------ - -The validator tracks lock-class usage history and divides the usage into -(4 usages * n STATEs + 1) categories: - -where the 4 usages can be: -- 'ever held in STATE context' -- 'ever held as readlock in STATE context' -- 'ever held with STATE enabled' -- 'ever held as readlock with STATE enabled' - -where the n STATEs are coded in kernel/locking/lockdep_states.h and as of -now they include: -- hardirq -- softirq - -where the last 1 category is: -- 'ever used' [ == !unused ] - -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: - - modprobe/2287 is trying to acquire lock: - (&sio_locks[i].lock){-.-.}, at: [] mutex_lock+0x21/0x24 - - but task is already holding lock: - (&sio_locks[i].lock){-.-.}, at: [] mutex_lock+0x21/0x24 - - -For a given lock, the bit positions from left to right indicate the usage -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: - - (&sio_locks[i].lock){-.-.}, at: [] mutex_lock+0x21/0x24 - |||| - ||| \-> softirq disabled and not in softirq context - || \--> acquired in softirq context - | \---> hardirq disabled and not in hardirq context - \----> acquired in hardirq context - - -For a given STATE, whether the lock is ever acquired in that STATE -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 -applied for '+' too. - -Unused locks (e.g., mutexes) cannot be part of the cause of an error. - - -Single-lock state rules: ------------------------- - -A lock is irq-safe means it was ever used in an irq context, while a lock -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: - - or - or - -This is because if a lock can be used in irq context (irq-safe) then it -cannot be ever acquired with irq enabled (irq-unsafe). Otherwise, a -deadlock may happen. For example, in the scenario that after this lock -was acquired but before released, if the context is interrupted this -lock will be attempted to acquire twice, which creates a deadlock, -referred to as lock recursion deadlock. - -The validator detects and reports lock usage that violates these -single-lock state rules. - -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: - - -> - -> - -because this could lead to a deadlock - referred to as lock inversion -deadlock - as attempts to acquire the two locks form a circle which -could lead to the two contexts waiting for each other permanently. The -validator will find such dependency circle in arbitrary complexity, -i.e., there can be any other locking sequence between the acquire-lock -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: - - -> - -> - -The first rule comes from the fact that a hardirq-safe lock could be -taken by a hardirq context, interrupting a hardirq-unsafe lock - and -thus could result in a lock inversion deadlock. Likewise, a softirq-safe -lock could be taken by an softirq context, interrupting a softirq-unsafe -lock. - -The above rules are enforced for any locking sequence that occurs in the -kernel: when acquiring a new lock, the validator checks whether there is -any rule violation between the new lock and any of the held locks. - -When a lock-class changes its state, the following aspects of the above -dependency rules are enforced: - -- if a new hardirq-safe lock is discovered, we check whether it - took any hardirq-unsafe lock in the past. - -- if a new softirq-safe lock is discovered, we check whether it took - any softirq-unsafe lock in the past. - -- if a new hardirq-unsafe lock is discovered, we check whether any - hardirq-safe lock took it in the past. - -- if a new softirq-unsafe lock is discovered, we check whether any - softirq-safe lock took it in the past. - -(Again, we do these checks too on the basis that an interrupt context -could interrupt _any_ of the irq-unsafe or hardirq-unsafe locks, which -could lead to a lock inversion deadlock - even if that lock scenario did -not trigger in practice yet.) - -Exception: Nested data dependencies leading to nested locking -------------------------------------------------------------- - -There are a few cases where the Linux kernel acquires more than one -instance of the same lock-class. Such cases typically happen when there -is some sort of hierarchy within objects of the same type. In these -cases there is an inherent "natural" ordering between the two objects -(defined by the properties of the hierarchy), and the kernel grabs the -locks in this fixed order on each of the objects. - -An example of such an object hierarchy that results in "nested locking" -is that of a "whole disk" block-dev object and a "partition" block-dev -object; the partition is "part of" the whole device and as long as one -always takes the whole disk lock as a higher lock than the partition -lock, the lock ordering is fully correct. The validator does not -automatically detect this natural ordering, as the locking rule behind -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: - -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); - -In this case the locking is done on a bdev object that is known to be a -partition. - -The validator treats a lock that is taken in such a nested fashion as a -separate (sub)class for the purposes of validation. - -Note: When changing code to use the _nested() primitives, be careful and -check really thoroughly that the hierarchy is correctly mapped; otherwise -you can get false positives or false negatives. - -Annotations ------------ - -Two constructs can be used to annotate and check where and if certain locks -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 - - void update_rq_clock(struct rq *rq) - { - s64 delta; - - lockdep_assert_held(&rq->lock); - [...] - } - -where holding rq->lock is required to safely update a rq's clock. - -The other family of macros is lockdep_*pin_lock(), which is admittedly only -used for rq->lock ATM. Despite their limited adoption these annotations -generate a WARN() if the lock of interest is "accidentally" unlocked. This turns -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 - - static inline void rq_pin_lock(struct rq *rq, struct rq_flags *rf) - { - rf->cookie = lockdep_pin_lock(&rq->lock); - [...] - } - - static inline void rq_unpin_lock(struct rq *rq, struct rq_flags *rf) - { - [...] - lockdep_unpin_lock(&rq->lock, rf->cookie); - } - -While comments about locking requirements might provide useful information, -the runtime checks performed by annotations are invaluable when debugging -locking problems and they carry the same level of details when inspecting -code. Always prefer annotations when in doubt! - -Proof of 100% correctness: --------------------------- - -The validator achieves perfect, mathematical 'closure' (proof of locking -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. [*] - -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' -locking chains have to occur at least once (anytime, in any -task/context) for the validator to be able to prove correctness. (For -example, complex deadlocks that would normally need more than 3 CPUs and -a very unlikely constellation of tasks, irq-contexts and timings to -occur, can be detected on a plain, lightly loaded single-CPU system as -well!) - -This radically decreases the complexity of locking related QA of the -kernel: what has to be done during QA is to trigger as many "simple" -single-task locking dependencies in the kernel as possible, at least -once, to prove locking correctness - instead of having to trigger every -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 - 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 - with the validator. We also assume that the 64-bit 'chain hash' - value is unique for every lock-chain in the system. Also, lock - recursion must not be higher than 20. - -Performance: ------------- - -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 -tens of thousands of checks for every event. - -This problem is solved by checking any given 'locking scenario' (unique -sequence of locks taken after each other) only once. A simple stack of -held locks is maintained, and a lightweight 64-bit hash value is -calculated, which hash is unique for every lock chain. The hash value, -when the chain is validated for the first time, is then put into a hash -table, which hash-table can be checked in a lockfree manner. If the -locking chain occurs again later on, the hash table tells us that we -don't have to validate the chain again. - -Troubleshooting: ----------------- - -The validator tracks a maximum of MAX_LOCKDEP_KEYS number of lock classes. -Exceeding this number will trigger the following lockdep warning: - - (DEBUG_LOCKS_WARN_ON(id >= MAX_LOCKDEP_KEYS)) - -By default, MAX_LOCKDEP_KEYS is currently set to 8191, and typical -desktop systems have less than 1,000 lock classes, so this warning -normally results from lock-class leakage or failure to properly -initialize locks. These two problems are illustrated below: - -1. Repeated module loading and unloading while running the validator - will result in lock-class leakage. The issue here is that each - load of the module will create a new set of lock classes for - that module's locks, but module unloading does not remove old - classes (see below discussion of reuse of lock classes for why). - Therefore, if that module is loaded and unloaded repeatedly, - the number of lock classes will eventually reach the maximum. - -2. Using structures such as arrays that have large numbers of - locks that are not explicitly initialized. For example, - a hash table with 8192 buckets where each bucket has its own - spinlock_t will consume 8192 lock classes -unless- each spinlock - is explicitly initialized at runtime, for example, using the - run-time spin_lock_init() as opposed to compile-time initializers - such as __SPIN_LOCK_UNLOCKED(). Failure to properly initialize - the per-bucket spinlocks would guarantee lock-class overflow. - In contrast, a loop that called spin_lock_init() on each lock - would place all 8192 locks into a single lock class. - - The moral of this story is that you should always explicitly - initialize your locks. - -One might argue that the validator should be modified to allow -lock classes to be reused. However, if you are tempted to make this -argument, first review the code and think through the changes that would -be required, keeping in mind that the lock classes to be removed are -likely to be linked into the lock-dependency graph. This turns out to -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: - - grep "lock-classes" /proc/lockdep_stats - -This command produces the following output on a modest system: - - 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: - - grep "BD" /proc/lockdep - -Run the command and save the output, then compare against the output from -a later run of this command to identify the leakers. This same output -can also help you find situations where runtime lock initialization has -been omitted. 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.rst b/Documentation/locking/locktorture.rst new file mode 100644 index 000000000000..e79eeeca3ac6 --- /dev/null +++ b/Documentation/locking/locktorture.rst @@ -0,0 +1,170 @@ +================================== +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 +module, 'locktorture', may be built after the fact on the running +kernel to be tested, if desired. The tests periodically output status +messages via printk(), which can be examined via the dmesg (perhaps +grepping for "torture"). The test is started when the module is loaded, +and stops when the module is unloaded. This program is based on how RCU +is tortured, via rcutorture. + +This torture test consists of creating a number of kernel threads which +acquire the lock and hold it for specific amount of time, thus simulating +different critical region behaviors. The amount of contention on the lock +can be simulated by either enlarging this critical region hold time and/or +creating more kthreads. + + +Module Parameters +================= + +This module has the following parameters: + + +Locktorture-specific +-------------------- + +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 + 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 + be tortured. This module can torture the following locks, + with string values as follows: + + - "lock_busted": + Simulates a buggy lock implementation. + + - "spin_lock": + spin_lock() and spin_unlock() pairs. + + - "spin_lock_irq": + spin_lock_irq() and spin_unlock_irq() pairs. + + - "rw_lock": + read/write lock() and unlock() rwlock pairs. + + - "rw_lock_irq": + read/write lock_irq() and unlock_irq() + rwlock pairs. + + - "mutex_lock": + mutex_lock() and mutex_unlock() pairs. + + - "rtmutex_lock": + rtmutex_lock() and rtmutex_unlock() pairs. + Kernel must have CONFIG_RT_MUTEX=y. + + - "rwsem_lock": + read/write down() and up() semaphore pairs. + + +Torture-framework (RCU + locking) +--------------------------------- + +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 + 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 + 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 + in order to avoid confusing boot-time code with CPUs + coming and going. This parameter is only useful if + CONFIG_HOTPLUG_CPU is enabled. + +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 + 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 + 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 + by default. This extra information is mostly related to + high-level errors and reports from the main 'torture' + framework. + + +Statistics +========== + +Statistics are printed in the following format:: + + 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. + + (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. + + (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. + +Usage +===== + +The following script may be used to torture locks:: + + #!/bin/sh + + modprobe locktorture + sleep 3600 + rmmod locktorture + dmesg | grep torture: + +The output can be manually inspected for the error flag of "!!!". +One could of course create a more elaborate script that automatically +checked for such errors. The "rmmod" command forces a "SUCCESS", +"FAILURE", or "RCU_HOTPLUG" indication to be printk()ed. The first +two are self-explanatory, while the last indicates that while there +were no locking failures, CPU-hotplug problems were detected. + +Also see: Documentation/RCU/torture.txt diff --git a/Documentation/locking/locktorture.txt b/Documentation/locking/locktorture.txt deleted file mode 100644 index 6a8df4cd19bf..000000000000 --- a/Documentation/locking/locktorture.txt +++ /dev/null @@ -1,145 +0,0 @@ -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 -module, 'locktorture', may be built after the fact on the running -kernel to be tested, if desired. The tests periodically output status -messages via printk(), which can be examined via the dmesg (perhaps -grepping for "torture"). The test is started when the module is loaded, -and stops when the module is unloaded. This program is based on how RCU -is tortured, via rcutorture. - -This torture test consists of creating a number of kernel threads which -acquire the lock and hold it for specific amount of time, thus simulating -different critical region behaviors. The amount of contention on the lock -can be simulated by either enlarging this critical region hold time and/or -creating more kthreads. - - -MODULE PARAMETERS - -This module has the following parameters: - - - ** Locktorture-specific ** - -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 - 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 - be tortured. This module can torture the following locks, - with string values as follows: - - o "lock_busted": Simulates a buggy lock implementation. - - o "spin_lock": spin_lock() and spin_unlock() pairs. - - o "spin_lock_irq": spin_lock_irq() and spin_unlock_irq() - pairs. - - o "rw_lock": read/write lock() and unlock() rwlock pairs. - - o "rw_lock_irq": read/write lock_irq() and unlock_irq() - rwlock pairs. - - o "mutex_lock": mutex_lock() and mutex_unlock() pairs. - - o "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. - - - ** Torture-framework (RCU + locking) ** - -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 - 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 - 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 - in order to avoid confusing boot-time code with CPUs - coming and going. This parameter is only useful if - CONFIG_HOTPLUG_CPU is enabled. - -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 - 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 - 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 - by default. This extra information is mostly related to - high-level errors and reports from the main 'torture' - framework. - - -STATISTICS - -Statistics are printed in the following format: - -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. - -(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. - -(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. - -USAGE - -The following script may be used to torture locks: - - #!/bin/sh - - modprobe locktorture - sleep 3600 - rmmod locktorture - dmesg | grep torture: - -The output can be manually inspected for the error flag of "!!!". -One could of course create a more elaborate script that automatically -checked for such errors. The "rmmod" command forces a "SUCCESS", -"FAILURE", or "RCU_HOTPLUG" indication to be printk()ed. The first -two are self-explanatory, while the last indicates that while there -were no locking failures, CPU-hotplug problems were detected. - -Also see: Documentation/RCU/torture.txt diff --git a/Documentation/locking/mutex-design.rst b/Documentation/locking/mutex-design.rst new file mode 100644 index 000000000000..4d8236b81fa5 --- /dev/null +++ b/Documentation/locking/mutex-design.rst @@ -0,0 +1,152 @@ +======================= +Generic Mutex Subsystem +======================= + +started by Ingo Molnar + +updated by Davidlohr Bueso + +What are mutexes? +----------------- + +In the Linux kernel, mutexes refer to a particular locking primitive +that enforces serialization on shared memory systems, and not only to +the generic term referring to 'mutual exclusion' found in academia +or similar theoretical text books. Mutexes are sleeping locks which +behave similarly to binary semaphores, and were introduced in 2006[1] +as an alternative to these. This new data structure provided a number +of advantages, including simpler interfaces, and at that time smaller +code (see Disadvantages). + +[1] http://lwn.net/Articles/164802/ + +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 +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 +wait-queue and a spinlock that serializes access to it. Furthermore, +CONFIG_MUTEX_SPIN_ON_OWNER=y systems use a spinner MCS lock (->osq), described +below in (ii). + +When acquiring a mutex, there are three possible paths that can be +taken, depending on the state of the lock: + +(i) fastpath: tries to atomically acquire the lock by cmpxchg()ing the owner with + the current task. This only works in the uncontended case (cmpxchg() checks + against 0UL, so all 3 state bits above have to be 0). If the lock is + contended it goes to the next possible path. + +(ii) midpath: aka optimistic spinning, tries to spin for acquisition + while the lock owner is running and there are no other tasks ready + to run that have higher priority (need_resched). The rationale is + that if the lock owner is running, it is likely to release the lock + soon. The mutex spinners are queued up using MCS lock so that only + one spinner can compete for the mutex. + + The MCS lock (proposed by Mellor-Crummey and Scott) is a simple spinlock + with the desirable properties of being fair and with each cpu trying + to acquire the lock spinning on a local variable. It avoids expensive + cacheline bouncing that common test-and-set spinlock implementations + incur. An MCS-like lock is specially tailored for optimistic spinning + for sleeping lock implementation. An important feature of the customized + MCS lock is that it has the extra property that spinners are able to exit + the MCS spinlock queue when they need to reschedule. This further helps + avoid situations where MCS spinners that need to reschedule would continue + waiting to spin on mutex owner, only to go directly to slowpath upon + obtaining the MCS lock. + + +(iii) slowpath: last resort, if the lock is still unable to be acquired, + the task is added to the wait-queue and sleeps until woken up by the + unlock path. Under normal circumstances it blocks as TASK_UNINTERRUPTIBLE. + +While formally kernel mutexes are sleepable locks, it is path (ii) that +makes them more practically a hybrid type. By simply not interrupting a +task and busy-waiting for a few cycles instead of immediately sleeping, +the performance of this lock has been seen to significantly improve a +number of workloads. Note that this technique is also used for rw-semaphores. + +Semantics +--------- + +The mutex subsystem checks and enforces the following rules: + + - Only one task can hold the mutex at a time. + - Only the owner can unlock the mutex. + - Multiple unlocks are not permitted. + - Recursive locking/unlocking is not permitted. + - A mutex must only be initialized via the API (see below). + - A task may not exit with a mutex held. + - Memory areas where held locks reside must not be freed. + - Held mutexes must not be reinitialized. + - Mutexes may not be used in hardware or software interrupt + contexts such as tasklets and timers. + +These semantics are fully enforced when CONFIG DEBUG_MUTEXES is enabled. +In addition, the mutex debugging code also implements a number of other +features that make lock debugging easier and faster: + + - Uses symbolic names of mutexes, whenever they are printed + in debug output. + - Point-of-acquire tracking, symbolic lookup of function names, + list of all locks held in the system, printout of them. + - Owner tracking. + - Detects self-recursing locks and prints out all relevant info. + - Detects multi-task circular deadlocks and prints out all affected + locks and tasks (and only those tasks). + + +Interfaces +---------- +Statically define the mutex:: + + DEFINE_MUTEX(name); + +Dynamically initialize the mutex:: + + mutex_init(mutex); + +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:: + + 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:: + + int atomic_dec_and_mutex_lock(atomic_t *cnt, struct mutex *lock); + +Unlock the mutex:: + + void mutex_unlock(struct mutex *lock); + +Test if the mutex is taken:: + + int mutex_is_locked(struct mutex *lock); + +Disadvantages +------------- + +Unlike its original design and purpose, 'struct mutex' is among the largest +locks in the kernel. E.g: on x86-64 it is 32 bytes, where 'struct semaphore' +is 24 bytes and rw_semaphore is 40 bytes. Larger structure sizes mean more CPU +cache and memory footprint. + +When to use mutexes +------------------- + +Unless the strict semantics of mutexes are unsuitable and/or the critical +region prevents the lock from being shared, always prefer them to any other +locking primitive. diff --git a/Documentation/locking/mutex-design.txt b/Documentation/locking/mutex-design.txt deleted file mode 100644 index 818aca19612f..000000000000 --- a/Documentation/locking/mutex-design.txt +++ /dev/null @@ -1,142 +0,0 @@ -Generic Mutex Subsystem - -started by Ingo Molnar -updated by Davidlohr Bueso - -What are mutexes? ------------------ - -In the Linux kernel, mutexes refer to a particular locking primitive -that enforces serialization on shared memory systems, and not only to -the generic term referring to 'mutual exclusion' found in academia -or similar theoretical text books. Mutexes are sleeping locks which -behave similarly to binary semaphores, and were introduced in 2006[1] -as an alternative to these. This new data structure provided a number -of advantages, including simpler interfaces, and at that time smaller -code (see Disadvantages). - -[1] http://lwn.net/Articles/164802/ - -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 -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 -wait-queue and a spinlock that serializes access to it. Furthermore, -CONFIG_MUTEX_SPIN_ON_OWNER=y systems use a spinner MCS lock (->osq), described -below in (ii). - -When acquiring a mutex, there are three possible paths that can be -taken, depending on the state of the lock: - -(i) fastpath: tries to atomically acquire the lock by cmpxchg()ing the owner with - the current task. This only works in the uncontended case (cmpxchg() checks - against 0UL, so all 3 state bits above have to be 0). If the lock is - contended it goes to the next possible path. - -(ii) midpath: aka optimistic spinning, tries to spin for acquisition - while the lock owner is running and there are no other tasks ready - to run that have higher priority (need_resched). The rationale is - that if the lock owner is running, it is likely to release the lock - soon. The mutex spinners are queued up using MCS lock so that only - one spinner can compete for the mutex. - - The MCS lock (proposed by Mellor-Crummey and Scott) is a simple spinlock - with the desirable properties of being fair and with each cpu trying - to acquire the lock spinning on a local variable. It avoids expensive - cacheline bouncing that common test-and-set spinlock implementations - incur. An MCS-like lock is specially tailored for optimistic spinning - for sleeping lock implementation. An important feature of the customized - MCS lock is that it has the extra property that spinners are able to exit - the MCS spinlock queue when they need to reschedule. This further helps - avoid situations where MCS spinners that need to reschedule would continue - waiting to spin on mutex owner, only to go directly to slowpath upon - obtaining the MCS lock. - - -(iii) slowpath: last resort, if the lock is still unable to be acquired, - the task is added to the wait-queue and sleeps until woken up by the - unlock path. Under normal circumstances it blocks as TASK_UNINTERRUPTIBLE. - -While formally kernel mutexes are sleepable locks, it is path (ii) that -makes them more practically a hybrid type. By simply not interrupting a -task and busy-waiting for a few cycles instead of immediately sleeping, -the performance of this lock has been seen to significantly improve a -number of workloads. Note that this technique is also used for rw-semaphores. - -Semantics ---------- - -The mutex subsystem checks and enforces the following rules: - - - Only one task can hold the mutex at a time. - - Only the owner can unlock the mutex. - - Multiple unlocks are not permitted. - - Recursive locking/unlocking is not permitted. - - A mutex must only be initialized via the API (see below). - - A task may not exit with a mutex held. - - Memory areas where held locks reside must not be freed. - - Held mutexes must not be reinitialized. - - Mutexes may not be used in hardware or software interrupt - contexts such as tasklets and timers. - -These semantics are fully enforced when CONFIG DEBUG_MUTEXES is enabled. -In addition, the mutex debugging code also implements a number of other -features that make lock debugging easier and faster: - - - Uses symbolic names of mutexes, whenever they are printed - in debug output. - - Point-of-acquire tracking, symbolic lookup of function names, - list of all locks held in the system, printout of them. - - Owner tracking. - - Detects self-recursing locks and prints out all relevant info. - - Detects multi-task circular deadlocks and prints out all affected - locks and tasks (and only those tasks). - - -Interfaces ----------- -Statically define the mutex: - DEFINE_MUTEX(name); - -Dynamically initialize the mutex: - mutex_init(mutex); - -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: - 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: - int atomic_dec_and_mutex_lock(atomic_t *cnt, struct mutex *lock); - -Unlock the mutex: - void mutex_unlock(struct mutex *lock); - -Test if the mutex is taken: - int mutex_is_locked(struct mutex *lock); - -Disadvantages -------------- - -Unlike its original design and purpose, 'struct mutex' is among the largest -locks in the kernel. E.g: on x86-64 it is 32 bytes, where 'struct semaphore' -is 24 bytes and rw_semaphore is 40 bytes. Larger structure sizes mean more CPU -cache and memory footprint. - -When to use mutexes -------------------- - -Unless the strict semantics of mutexes are unsuitable and/or the critical -region prevents the lock from being shared, always prefer them to any other -locking primitive. diff --git a/Documentation/locking/rt-mutex-design.rst b/Documentation/locking/rt-mutex-design.rst new file mode 100644 index 000000000000..59c2a64efb21 --- /dev/null +++ b/Documentation/locking/rt-mutex-design.rst @@ -0,0 +1,574 @@ +============================== +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.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. + +The goal of this document is to help others understand the priority +inheritance (PI) algorithm that is used, as well as reasons for the +decisions that were made to implement PI in the manner that was done. + + +Unbounded Priority Inversion +---------------------------- + +Priority inversion is when a lower priority process executes while a higher +priority process wants to run. This happens for several reasons, and +most of the time it can't be helped. Anytime a high priority process wants +to use a resource that a lower priority process has (a mutex for example), +the high priority process must wait until the lower priority process is done +with the resource. This is a priority inversion. What we want to prevent +is something called unbounded priority inversion. That is when the high +priority process is prevented from running by a lower priority process for +an undetermined amount of time. + +The classic example of unbounded priority inversion is where you have three +processes, let's call them processes A, B, and C, where A is the highest +priority process, C is the lowest, and B is in between. A tries to grab a lock +that C owns and must wait and lets C run to release the lock. But in the +meantime, B executes, and since B is of a higher priority than C, it preempts C, +but by doing so, it is in fact preempting A which is a higher priority process. +Now there's no way of knowing how long A will be sleeping waiting for C +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:: + + grab lock L1 (owned by C) + | + A ---+ + C preempted by B + | + C +----+ + + B +--------> + B now keeps A from running. + + +Priority Inheritance (PI) +------------------------- + +There are several ways to solve this issue, but other ways are out of scope +for this document. Here we only discuss PI. + +PI is where a process inherits the priority of another process if the other +process blocks on a lock owned by the current process. To make this easier +to understand, let's use the previous example, with processes A, B, and C again. + +This time, when A blocks on the lock owned by C, C would inherit the priority +of A. So now if B becomes runnable, it would not preempt C, since C now has +the high priority of A. As soon as C releases the lock, it loses its +inherited priority, and A then can continue with the resource that C had. + +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 + 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 + 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 + 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. + +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 + structure holds a pointer to the task, as well as the mutex that + the task is blocked on. It also has rbtree node structures to + place the task in the waiters rbtree of a mutex as well as the + pi_waiters rbtree of a mutex owner task (described below). + + 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. + +top waiter + - The highest priority process waiting on a specific mutex. + +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 + differentiate between two processes that are being described together. + + +PI chain +-------- + +The PI chain is a list of processes and mutexes that may cause priority +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:: + + Process: A, B, C, D, E + Mutexes: L1, L2, L3, L4 + + A owns: L1 + B blocked on L1 + B owns L2 + C blocked on L2 + C owns L3 + D blocked on L3 + D owns L4 + E blocked on L4 + +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:: + + 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:: + + E->L4->D->L3->C->L2-+ + | + +->B->L1->A + | + F->L5-+ + +For PI to work, the processes at the right end of these chains (or we may +also call it the Top of the chain) must be equal to or higher in priority +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:: + + G->L2->B->L1->A + +And once again, to show how this can grow I will show the merging chains +again:: + + E->L4->D->L3->C-+ + +->L2-+ + | | + G-+ +->B->L1->A + | + F->L5-+ + +If process G has the highest priority in the chain, then all the tasks up +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 +by a spin lock that is located in the struct of the mutex. This lock is called +wait_lock. + + +Task PI Tree +------------ + +To keep track of the PI chains, each process has its own PI rbtree. This is +a tree of all top waiters of the mutexes that are owned by the process. +Note that this tree only holds the top waiters and not all waiters that are +blocked on mutexes owned by the process. + +The top of the task's PI tree is always the highest priority task that +is waiting on a mutex that is owned by the task. So if the task has +inherited a priority, it will always be the priority of the task that is +at the top of this tree. + +This tree is stored in the task structure of a process as a rbtree called +pi_waiters. It is protected by a spin lock also in the task structure, +called pi_lock. This lock may also be taken in interrupt context, so when +locking the pi_lock, interrupts must be disabled. + + +Depth of the PI Chain +--------------------- + +The maximum depth of the PI chain is not dynamic, and could actually be +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:: + + void func1(void) + { + mutex_lock(L1); + + /* do anything */ + + mutex_unlock(L1); + } + + void func2(void) + { + mutex_lock(L1); + mutex_lock(L2); + + /* do something */ + + mutex_unlock(L2); + mutex_unlock(L1); + } + + void func3(void) + { + mutex_lock(L2); + mutex_lock(L3); + + /* do something else */ + + mutex_unlock(L3); + mutex_unlock(L2); + } + + 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:: + + 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. + +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 +depth of two. So, although the locking depth is defined at compile time, +it still is very difficult to find the possibilities of that depth. + +Now since mutexes can be defined by user-land applications, we don't want a DOS +type of application that nests large amounts of mutexes to create a large +PI chain, and have the code holding spin locks while looking at a large +amount of data. So to prevent this, the implementation not only implements +a maximum lock depth, but also only holds at most two different locks at a +time, as it walks the PI chain. More about this below. + + +Mutex owner and flags +--------------------- + +The mutex structure contains a pointer to the owner of the mutex. If the +mutex is not owned, this owner is set to NULL. Since all architectures +have the task structure on at least a two byte alignment (and if this is +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.rst for further details. + +cmpxchg Tricks +-------------- + +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:: + + 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) + +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 +the return value (the old value of A) is equal to B. + +The macro rt_mutex_cmpxchg is used to try to lock and unlock mutexes. If +the architecture does not support CMPXCHG, then this macro is simply set +to fail every time. But if CMPXCHG is supported, then this will +help out extremely to keep the fast path short. + +The use of rt_mutex_cmpxchg with the flags in the owner field help optimize +the system for architectures that support it. This will also be explained +later in this document. + + +Priority adjustments +-------------------- + +The implementation of the PI code in rtmutex.c has several places that a +process must adjust its priority. With the help of the pi_waiters of a +process this is rather easy to know what needs to be adjusted. + +The functions implementing the task adjustments are rt_mutex_adjust_prio +and rt_mutex_setprio. rt_mutex_setprio is only used in rt_mutex_adjust_prio. + +rt_mutex_adjust_prio examines the priority of the task, and the highest +priority process that is waiting any of mutexes owned by the task. Since +the pi_waiters of a task holds an order by priority of all the top waiters +of all the mutexes that the task owns, we simply need to compare the top +pi waiter to its own normal/deadline priority and take the higher one. +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 + higher the priority. A "prio" of 5 is of higher priority than a + "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 +process has just blocked on a mutex owned by the task, rt_mutex_adjust_prio +would increase/boost the task's priority. But if a higher priority task +were for some reason to leave the mutex (timeout or signal), this same function +would decrease/unboost the priority of the task. That is because the pi_waiters +always contains the highest priority task that is waiting on a mutex owned +by the task, so we only need to compare the priority of that top pi waiter +to the normal priority of the given task. + + +High level overview of the PI chain walk +---------------------------------------- + +The PI chain walk is implemented by the function rt_mutex_adjust_prio_chain. + +The implementation has gone through several iterations, and has ended up +with what we believe is the best. It walks the PI chain by only grabbing +at most two locks at a time, and is very efficient. + +The rt_mutex_adjust_prio_chain can be used either to boost or lower process +priorities. + +rt_mutex_adjust_prio_chain is called with a task to be checked for PI +(de)boosting (the owner of a mutex that a process is blocking on), a flag to +check for deadlocking, the mutex that the task owns, a pointer to a waiter +that is the process's waiter struct that is blocked on the mutex (although this +parameter may be NULL for deboosting), a pointer to the mutex on which the task +is blocked, and a top_task as the top waiter of the mutex. + +For this explanation, I will not mention deadlock detection. This explanation +will try to stay at a high level. + +When this function is called, there are no locks held. That also means +that the state of the owner and lock can change when entered into this function. + +Before this function is called, the task has already had rt_mutex_adjust_prio +performed on it. This means that the task is set to the priority that it +should be at, but the rbtree nodes of the task's waiter have not been updated +with the new priorities, and this task may not be in the proper locations +in the pi_waiters and waiters trees that the task is blocked on. This function +solves all that. + +The main operation of this function is summarized by Thomas Gleixner in +rtmutex.c. See the 'Chain walk basics and protection scope' comment for further +details. + +Taking of a mutex (The walk through) +------------------------------------ + +OK, now let's take a look at the detailed walk through of what happens when +taking a mutex. + +The first thing that is tried is the fast taking of the mutex. This is +done when we have CMPXCHG enabled (otherwise the fast taking automatically +fails). Only when the owner field of the mutex is NULL can the lock be +taken with the CMPXCHG and nothing else needs to be done. + +If there is contention on the lock, we go about the slow path +(rt_mutex_slowlock). + +The slow path function is where the task's waiter structure is created on +the stack. This is because the waiter structure is only needed for the +scope of this function. The waiter structure holds the nodes to store +the task on the waiters tree of the mutex, and if need be, the pi_waiters +tree of the owner. + +The wait_lock of the mutex is taken since the slow path of unlocking the +mutex also takes this lock. + +We then call try_to_take_rt_mutex. This is where the architecture that +does not implement CMPXCHG would always grab the lock (if there's no +contention). + +try_to_take_rt_mutex is used every time the task tries to grab a mutex in the +slow path. The first thing that is done here is an atomic setting of +the "Has Waiters" flag of the mutex's owner field. By setting this flag +now, the current owner of the mutex being contended for can't release the mutex +without going into the slow unlock path, and it would then need to grab the +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 + +If the task succeeds to acquire the lock, then the task is set as the +owner of the lock, and if the lock still has waiters, the top_waiter +(highest priority task waiting on the lock) is added to this task's +pi_waiters tree. + +If the lock is not taken by try_to_take_rt_mutex(), then the +task_blocks_on_rt_mutex() function is called. This will add the task to +the lock's waiter tree and propagate the pi chain of the lock as well +as the lock's owner's pi_waiters tree. This is described in the next +section. + +Task blocks on mutex +-------------------- + +The accounting of a mutex and process is done with the waiter structure of +the process. The "task" field is set to the process, and the "lock" field +to the mutex. The rbtree node of waiter are initialized to the processes +current priority. + +Since the wait_lock was taken at the entry of the slow lock, we can safely +add the waiter to the task waiter tree. If the current process is the +highest priority process currently waiting on this mutex, then we remove the +previous top waiter process (if it exists) from the pi_waiters of the owner, +and add the current process to that tree. Since the pi_waiter of the owner +has changed, we call rt_mutex_adjust_prio on the owner to see if the owner +should adjust its priority accordingly. + +If the owner is also blocked on a lock, and had its pi_waiters changed +(or deadlock checking is on), we unlock the wait_lock of the mutex and go ahead +and run rt_mutex_adjust_prio_chain on the owner, as described earlier. + +Now all locks are released, and if the current process is still blocked on a +mutex (waiter "task" field is not NULL), then we go to sleep (call schedule). + +Waking up in the loop +--------------------- + +The task can then wake up for a couple of reasons: + 1) The previous lock owner released the lock, and the task now is top_waiter + 2) we received a signal or timeout + +In both cases, the task will try again to acquire the lock. If it +does, then it will take itself off the waiters tree and set itself back +to the TASK_RUNNING state. + +In first case, if the lock was acquired by another task before this task +could get the lock, then it will go back to sleep and wait to be woken again. + +The second case is only applicable for tasks that are grabbing a mutex +that can wake up before getting the lock, either due to a signal or +a timeout (i.e. rt_mutex_timed_futex_lock()). When woken, it will try to +take the lock again, if it succeeds, then the task will return with the +lock held, otherwise it will return with -EINTR if the task was woken +by a signal, or -ETIMEDOUT if it timed out. + + +Unlocking the Mutex +------------------- + +The unlocking of a mutex also has a fast path for those architectures with +CMPXCHG. Since the taking of a mutex on contention always sets the +"Has Waiters" flag of the mutex's owner, we use this to know if we need to +take the slow path when unlocking the mutex. If the mutex doesn't have any +waiters, the owner field of the mutex would equal the current process and +the mutex can be unlocked by just replacing the owner field with NULL. + +If the owner field has the "Has Waiters" bit set (or CMPXCHG is not available), +the slow unlock path is taken. + +The first thing done in the slow unlock path is to take the wait_lock of the +mutex. This synchronizes the locking and unlocking of the mutex. + +A check is made to see if the mutex has waiters or not. On architectures that +do not have CMPXCHG, this is the location that the owner of the mutex will +determine if a waiter needs to be awoken or not. On architectures that +do have CMPXCHG, that check is done in the fast path, but it is still needed +in the slow path too. If a waiter of a mutex woke up because of a signal +or timeout between the time the owner failed the fast path CMPXCHG check and +the grabbing of the wait_lock, the mutex may not have any waiters, thus the +owner still needs to make this check. If there are no waiters then the mutex +owner field is set to NULL, the wait_lock is released and nothing more is +needed. + +If there are waiters, then we need to wake one up. + +On the wake up code, the pi_lock of the current owner is taken. The top +waiter of the lock is found and removed from the waiters tree of the mutex +as well as the pi_waiters tree of the current owner. The "Has Waiters" bit is +marked to prevent lower priority tasks from stealing the lock. + +Finally we unlock the pi_lock of the pending owner and wake it up. + + +Contact +------- + +For updates on this document, please email Steven Rostedt + + +Credits +------- + +Author: Steven Rostedt + +Updated: Alex Shi - 7/6/2017 + +Original Reviewers: + Ingo Molnar, Thomas Gleixner, Thomas Duetsch, and + Randy Dunlap + +Update (7/6/2017) Reviewers: Steven Rostedt and Sebastian Siewior + +Updates +------- + +This document was originally written for 2.6.17-rc3-mm1 +was updated on 4.12 diff --git a/Documentation/locking/rt-mutex-design.txt b/Documentation/locking/rt-mutex-design.txt deleted file mode 100644 index 3d7b865539cc..000000000000 --- a/Documentation/locking/rt-mutex-design.txt +++ /dev/null @@ -1,559 +0,0 @@ -# -# Copyright (c) 2006 Steven Rostedt -# Licensed under the GNU Free Documentation License, Version 1.2 -# - -RT-mutex implementation design ------------------------------- - -This document tries to describe the design of the rtmutex.c implementation. -It doesn't describe the reasons why rtmutex.c exists. For that please see -Documentation/locking/rt-mutex.txt. Although this document does explain problems -that happen without this code, but that is in the concept to understand -what the code actually is doing. - -The goal of this document is to help others understand the priority -inheritance (PI) algorithm that is used, as well as reasons for the -decisions that were made to implement PI in the manner that was done. - - -Unbounded Priority Inversion ----------------------------- - -Priority inversion is when a lower priority process executes while a higher -priority process wants to run. This happens for several reasons, and -most of the time it can't be helped. Anytime a high priority process wants -to use a resource that a lower priority process has (a mutex for example), -the high priority process must wait until the lower priority process is done -with the resource. This is a priority inversion. What we want to prevent -is something called unbounded priority inversion. That is when the high -priority process is prevented from running by a lower priority process for -an undetermined amount of time. - -The classic example of unbounded priority inversion is where you have three -processes, let's call them processes A, B, and C, where A is the highest -priority process, C is the lowest, and B is in between. A tries to grab a lock -that C owns and must wait and lets C run to release the lock. But in the -meantime, B executes, and since B is of a higher priority than C, it preempts C, -but by doing so, it is in fact preempting A which is a higher priority process. -Now there's no way of knowing how long A will be sleeping waiting for C -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. - - grab lock L1 (owned by C) - | -A ---+ - C preempted by B - | -C +----+ - -B +--------> - B now keeps A from running. - - -Priority Inheritance (PI) -------------------------- - -There are several ways to solve this issue, but other ways are out of scope -for this document. Here we only discuss PI. - -PI is where a process inherits the priority of another process if the other -process blocks on a lock owned by the current process. To make this easier -to understand, let's use the previous example, with processes A, B, and C again. - -This time, when A blocks on the lock owned by C, C would inherit the priority -of A. So now if B becomes runnable, it would not preempt C, since C now has -the high priority of A. As soon as C releases the lock, it loses its -inherited priority, and A then can continue with the resource that C had. - -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 - 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 - 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 - 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. - -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 - structure holds a pointer to the task, as well as the mutex that - the task is blocked on. It also has rbtree node structures to - place the task in the waiters rbtree of a mutex as well as the - pi_waiters rbtree of a mutex owner task (described below). - - 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. - -top waiter - The highest priority process waiting on a specific mutex. - -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 - differentiate between two processes that are being described together. - - -PI chain --------- - -The PI chain is a list of processes and mutexes that may cause priority -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: - - Process: A, B, C, D, E - Mutexes: L1, L2, L3, L4 - - A owns: L1 - B blocked on L1 - B owns L2 - C blocked on L2 - C owns L3 - D blocked on L3 - D owns L4 - E blocked on L4 - -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: - - 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: - - E->L4->D->L3->C->L2-+ - | - +->B->L1->A - | - F->L5-+ - -For PI to work, the processes at the right end of these chains (or we may -also call it the Top of the chain) must be equal to or higher in priority -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: - - G->L2->B->L1->A - -And once again, to show how this can grow I will show the merging chains -again. - - E->L4->D->L3->C-+ - +->L2-+ - | | - G-+ +->B->L1->A - | - F->L5-+ - -If process G has the highest priority in the chain, then all the tasks up -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 -by a spin lock that is located in the struct of the mutex. This lock is called -wait_lock. - - -Task PI Tree ------------- - -To keep track of the PI chains, each process has its own PI rbtree. This is -a tree of all top waiters of the mutexes that are owned by the process. -Note that this tree only holds the top waiters and not all waiters that are -blocked on mutexes owned by the process. - -The top of the task's PI tree is always the highest priority task that -is waiting on a mutex that is owned by the task. So if the task has -inherited a priority, it will always be the priority of the task that is -at the top of this tree. - -This tree is stored in the task structure of a process as a rbtree called -pi_waiters. It is protected by a spin lock also in the task structure, -called pi_lock. This lock may also be taken in interrupt context, so when -locking the pi_lock, interrupts must be disabled. - - -Depth of the PI Chain ---------------------- - -The maximum depth of the PI chain is not dynamic, and could actually be -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. - -void func1(void) -{ - mutex_lock(L1); - - /* do anything */ - - mutex_unlock(L1); -} - -void func2(void) -{ - mutex_lock(L1); - mutex_lock(L2); - - /* do something */ - - mutex_unlock(L2); - mutex_unlock(L1); -} - -void func3(void) -{ - mutex_lock(L2); - mutex_lock(L3); - - /* do something else */ - - mutex_unlock(L3); - mutex_unlock(L2); -} - -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: - -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. - -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 -depth of two. So, although the locking depth is defined at compile time, -it still is very difficult to find the possibilities of that depth. - -Now since mutexes can be defined by user-land applications, we don't want a DOS -type of application that nests large amounts of mutexes to create a large -PI chain, and have the code holding spin locks while looking at a large -amount of data. So to prevent this, the implementation not only implements -a maximum lock depth, but also only holds at most two different locks at a -time, as it walks the PI chain. More about this below. - - -Mutex owner and flags ---------------------- - -The mutex structure contains a pointer to the owner of the mutex. If the -mutex is not owned, this owner is set to NULL. Since all architectures -have the task structure on at least a two byte alignment (and if this is -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. - -cmpxchg Tricks --------------- - -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: - -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) - -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 -the return value (the old value of A) is equal to B. - -The macro rt_mutex_cmpxchg is used to try to lock and unlock mutexes. If -the architecture does not support CMPXCHG, then this macro is simply set -to fail every time. But if CMPXCHG is supported, then this will -help out extremely to keep the fast path short. - -The use of rt_mutex_cmpxchg with the flags in the owner field help optimize -the system for architectures that support it. This will also be explained -later in this document. - - -Priority adjustments --------------------- - -The implementation of the PI code in rtmutex.c has several places that a -process must adjust its priority. With the help of the pi_waiters of a -process this is rather easy to know what needs to be adjusted. - -The functions implementing the task adjustments are rt_mutex_adjust_prio -and rt_mutex_setprio. rt_mutex_setprio is only used in rt_mutex_adjust_prio. - -rt_mutex_adjust_prio examines the priority of the task, and the highest -priority process that is waiting any of mutexes owned by the task. Since -the pi_waiters of a task holds an order by priority of all the top waiters -of all the mutexes that the task owns, we simply need to compare the top -pi waiter to its own normal/deadline priority and take the higher one. -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 - higher the priority. A "prio" of 5 is of higher priority than a - "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 -process has just blocked on a mutex owned by the task, rt_mutex_adjust_prio -would increase/boost the task's priority. But if a higher priority task -were for some reason to leave the mutex (timeout or signal), this same function -would decrease/unboost the priority of the task. That is because the pi_waiters -always contains the highest priority task that is waiting on a mutex owned -by the task, so we only need to compare the priority of that top pi waiter -to the normal priority of the given task. - - -High level overview of the PI chain walk ----------------------------------------- - -The PI chain walk is implemented by the function rt_mutex_adjust_prio_chain. - -The implementation has gone through several iterations, and has ended up -with what we believe is the best. It walks the PI chain by only grabbing -at most two locks at a time, and is very efficient. - -The rt_mutex_adjust_prio_chain can be used either to boost or lower process -priorities. - -rt_mutex_adjust_prio_chain is called with a task to be checked for PI -(de)boosting (the owner of a mutex that a process is blocking on), a flag to -check for deadlocking, the mutex that the task owns, a pointer to a waiter -that is the process's waiter struct that is blocked on the mutex (although this -parameter may be NULL for deboosting), a pointer to the mutex on which the task -is blocked, and a top_task as the top waiter of the mutex. - -For this explanation, I will not mention deadlock detection. This explanation -will try to stay at a high level. - -When this function is called, there are no locks held. That also means -that the state of the owner and lock can change when entered into this function. - -Before this function is called, the task has already had rt_mutex_adjust_prio -performed on it. This means that the task is set to the priority that it -should be at, but the rbtree nodes of the task's waiter have not been updated -with the new priorities, and this task may not be in the proper locations -in the pi_waiters and waiters trees that the task is blocked on. This function -solves all that. - -The main operation of this function is summarized by Thomas Gleixner in -rtmutex.c. See the 'Chain walk basics and protection scope' comment for further -details. - -Taking of a mutex (The walk through) ------------------------------------- - -OK, now let's take a look at the detailed walk through of what happens when -taking a mutex. - -The first thing that is tried is the fast taking of the mutex. This is -done when we have CMPXCHG enabled (otherwise the fast taking automatically -fails). Only when the owner field of the mutex is NULL can the lock be -taken with the CMPXCHG and nothing else needs to be done. - -If there is contention on the lock, we go about the slow path -(rt_mutex_slowlock). - -The slow path function is where the task's waiter structure is created on -the stack. This is because the waiter structure is only needed for the -scope of this function. The waiter structure holds the nodes to store -the task on the waiters tree of the mutex, and if need be, the pi_waiters -tree of the owner. - -The wait_lock of the mutex is taken since the slow path of unlocking the -mutex also takes this lock. - -We then call try_to_take_rt_mutex. This is where the architecture that -does not implement CMPXCHG would always grab the lock (if there's no -contention). - -try_to_take_rt_mutex is used every time the task tries to grab a mutex in the -slow path. The first thing that is done here is an atomic setting of -the "Has Waiters" flag of the mutex's owner field. By setting this flag -now, the current owner of the mutex being contended for can't release the mutex -without going into the slow unlock path, and it would then need to grab the -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 - -If the task succeeds to acquire the lock, then the task is set as the -owner of the lock, and if the lock still has waiters, the top_waiter -(highest priority task waiting on the lock) is added to this task's -pi_waiters tree. - -If the lock is not taken by try_to_take_rt_mutex(), then the -task_blocks_on_rt_mutex() function is called. This will add the task to -the lock's waiter tree and propagate the pi chain of the lock as well -as the lock's owner's pi_waiters tree. This is described in the next -section. - -Task blocks on mutex --------------------- - -The accounting of a mutex and process is done with the waiter structure of -the process. The "task" field is set to the process, and the "lock" field -to the mutex. The rbtree node of waiter are initialized to the processes -current priority. - -Since the wait_lock was taken at the entry of the slow lock, we can safely -add the waiter to the task waiter tree. If the current process is the -highest priority process currently waiting on this mutex, then we remove the -previous top waiter process (if it exists) from the pi_waiters of the owner, -and add the current process to that tree. Since the pi_waiter of the owner -has changed, we call rt_mutex_adjust_prio on the owner to see if the owner -should adjust its priority accordingly. - -If the owner is also blocked on a lock, and had its pi_waiters changed -(or deadlock checking is on), we unlock the wait_lock of the mutex and go ahead -and run rt_mutex_adjust_prio_chain on the owner, as described earlier. - -Now all locks are released, and if the current process is still blocked on a -mutex (waiter "task" field is not NULL), then we go to sleep (call schedule). - -Waking up in the loop ---------------------- - -The task can then wake up for a couple of reasons: - 1) The previous lock owner released the lock, and the task now is top_waiter - 2) we received a signal or timeout - -In both cases, the task will try again to acquire the lock. If it -does, then it will take itself off the waiters tree and set itself back -to the TASK_RUNNING state. - -In first case, if the lock was acquired by another task before this task -could get the lock, then it will go back to sleep and wait to be woken again. - -The second case is only applicable for tasks that are grabbing a mutex -that can wake up before getting the lock, either due to a signal or -a timeout (i.e. rt_mutex_timed_futex_lock()). When woken, it will try to -take the lock again, if it succeeds, then the task will return with the -lock held, otherwise it will return with -EINTR if the task was woken -by a signal, or -ETIMEDOUT if it timed out. - - -Unlocking the Mutex -------------------- - -The unlocking of a mutex also has a fast path for those architectures with -CMPXCHG. Since the taking of a mutex on contention always sets the -"Has Waiters" flag of the mutex's owner, we use this to know if we need to -take the slow path when unlocking the mutex. If the mutex doesn't have any -waiters, the owner field of the mutex would equal the current process and -the mutex can be unlocked by just replacing the owner field with NULL. - -If the owner field has the "Has Waiters" bit set (or CMPXCHG is not available), -the slow unlock path is taken. - -The first thing done in the slow unlock path is to take the wait_lock of the -mutex. This synchronizes the locking and unlocking of the mutex. - -A check is made to see if the mutex has waiters or not. On architectures that -do not have CMPXCHG, this is the location that the owner of the mutex will -determine if a waiter needs to be awoken or not. On architectures that -do have CMPXCHG, that check is done in the fast path, but it is still needed -in the slow path too. If a waiter of a mutex woke up because of a signal -or timeout between the time the owner failed the fast path CMPXCHG check and -the grabbing of the wait_lock, the mutex may not have any waiters, thus the -owner still needs to make this check. If there are no waiters then the mutex -owner field is set to NULL, the wait_lock is released and nothing more is -needed. - -If there are waiters, then we need to wake one up. - -On the wake up code, the pi_lock of the current owner is taken. The top -waiter of the lock is found and removed from the waiters tree of the mutex -as well as the pi_waiters tree of the current owner. The "Has Waiters" bit is -marked to prevent lower priority tasks from stealing the lock. - -Finally we unlock the pi_lock of the pending owner and wake it up. - - -Contact -------- - -For updates on this document, please email Steven Rostedt - - -Credits -------- - -Author: Steven Rostedt -Updated: Alex Shi - 7/6/2017 - -Original Reviewers: Ingo Molnar, Thomas Gleixner, Thomas Duetsch, and - Randy Dunlap -Update (7/6/2017) Reviewers: Steven Rostedt and Sebastian Siewior - -Updates -------- - -This document was originally written for 2.6.17-rc3-mm1 -was updated on 4.12 diff --git a/Documentation/locking/rt-mutex.rst b/Documentation/locking/rt-mutex.rst new file mode 100644 index 000000000000..c365dc302081 --- /dev/null +++ b/Documentation/locking/rt-mutex.rst @@ -0,0 +1,77 @@ +================================== +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 +(PTHREAD_PRIO_INHERIT). [See Documentation/pi-futex.txt for more details +about PI-futexes.] + +This technology was developed in the -rt tree and streamlined for +pthread_mutex support. + +Basic principles: +----------------- + +RT-mutexes extend the semantics of simple mutexes by the priority +inheritance protocol. + +A low priority owner of a rt-mutex inherits the priority of a higher +priority waiter until the rt-mutex is released. If the temporarily +boosted owner blocks on a rt-mutex itself it propagates the priority +boosting to the owner of the other rt_mutex it gets blocked on. The +priority boosting is immediately removed once the rt_mutex has been +unlocked. + +This approach allows us to shorten the block of high-prio tasks on +mutexes which protect shared resources. Priority inheritance is not a +magic bullet for poorly designed applications, but it allows +well-designed applications to use userspace locks in critical parts of +an high priority thread, without losing determinism. + +The enqueueing of the waiters into the rtmutex waiter tree is done in +priority order. For same priorities FIFO order is chosen. For each +rtmutex, only the top priority waiter is enqueued into the owner's +priority waiters tree. This tree too queues in priority order. Whenever +the top priority waiter of a task changes (for example it timed out or +got a signal), the priority of the owner task is readjusted. The +priority enqueueing is handled by "pi_waiters". + +RT-mutexes are optimized for fastpath operations and have no internal +locking overhead when locking an uncontended mutex or unlocking a mutex +without waiters. The optimized fastpath operations require cmpxchg +support. [If that is not available then the rt-mutex internal spinlock +is used] + +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: + + ============ ======= ================================================ + 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 [1]_ + taskpointer 0 lock is held (fast release possible) + 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. + +.. [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. + +.. [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 +that has no owner and has been woken up to grab the lock. diff --git a/Documentation/locking/rt-mutex.txt b/Documentation/locking/rt-mutex.txt deleted file mode 100644 index 35793e003041..000000000000 --- a/Documentation/locking/rt-mutex.txt +++ /dev/null @@ -1,73 +0,0 @@ -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 -(PTHREAD_PRIO_INHERIT). [See Documentation/pi-futex.txt for more details -about PI-futexes.] - -This technology was developed in the -rt tree and streamlined for -pthread_mutex support. - -Basic principles: ------------------ - -RT-mutexes extend the semantics of simple mutexes by the priority -inheritance protocol. - -A low priority owner of a rt-mutex inherits the priority of a higher -priority waiter until the rt-mutex is released. If the temporarily -boosted owner blocks on a rt-mutex itself it propagates the priority -boosting to the owner of the other rt_mutex it gets blocked on. The -priority boosting is immediately removed once the rt_mutex has been -unlocked. - -This approach allows us to shorten the block of high-prio tasks on -mutexes which protect shared resources. Priority inheritance is not a -magic bullet for poorly designed applications, but it allows -well-designed applications to use userspace locks in critical parts of -an high priority thread, without losing determinism. - -The enqueueing of the waiters into the rtmutex waiter tree is done in -priority order. For same priorities FIFO order is chosen. For each -rtmutex, only the top priority waiter is enqueued into the owner's -priority waiters tree. This tree too queues in priority order. Whenever -the top priority waiter of a task changes (for example it timed out or -got a signal), the priority of the owner task is readjusted. The -priority enqueueing is handled by "pi_waiters". - -RT-mutexes are optimized for fastpath operations and have no internal -locking overhead when locking an uncontended mutex or unlocking a mutex -without waiters. The optimized fastpath operations require cmpxchg -support. [If that is not available then the rt-mutex internal spinlock -is used] - -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. - - owner bit0 - 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* - taskpointer 0 lock is held (fast release possible) - taskpointer 1 lock is held and has waiters** - -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. - -(**) 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 -that has no owner and has been woken up to grab the lock. diff --git a/Documentation/locking/spinlocks.rst b/Documentation/locking/spinlocks.rst new file mode 100644 index 000000000000..098107fb7d86 --- /dev/null +++ b/Documentation/locking/spinlocks.rst @@ -0,0 +1,177 @@ +=============== +Locking lessons +=============== + +Lesson 1: Spin locks +==================== + +The most basic primitive for locking is spinlock:: + + static DEFINE_SPINLOCK(xxx_lock); + + unsigned long flags; + + spin_lock_irqsave(&xxx_lock, flags); + ... critical section here .. + spin_unlock_irqrestore(&xxx_lock, flags); + +The above is always safe. It will disable interrupts _locally_, but the +spinlock itself will guarantee the global lock, so it will guarantee that +there is only one thread-of-control within the region(s) protected by that +lock. This works well even under UP also, so the code does _not_ need to +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 +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 +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 + 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. + +---- + +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 +(rw_lock) versions of the spinlocks are sometimes useful. They allow multiple +readers to be in the same critical region at once, but if somebody wants +to change the variables it has to get an exclusive write lock. + + NOTE! reader-writer locks require more atomic memory operations than + simple spinlocks. Unless the reader critical section is long, you + are better off just using spinlocks. + +The routines look the same as above:: + + rwlock_t xxx_lock = __RW_LOCK_UNLOCKED(xxx_lock); + + unsigned long flags; + + read_lock_irqsave(&xxx_lock, flags); + .. critical section that only reads the info ... + read_unlock_irqrestore(&xxx_lock, flags); + + write_lock_irqsave(&xxx_lock, flags); + .. read and write exclusive access to the info ... + write_unlock_irqrestore(&xxx_lock, flags); + +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. + + NOTE! RCU is better for list traversal, but requires careful + attention to design detail (see Documentation/RCU/listRCU.txt). + +Also, you cannot "upgrade" a read-lock to a write-lock, so if you at _any_ +time need to do any changes (even if you don't do it every time), you have +to get the write-lock at the very beginning. + + NOTE! We are working hard to remove reader-writer spinlocks in most + cases, so please don't add a new one without consensus. (Instead, see + Documentation/RCU/rcu.txt for complete information.) + +---- + +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 +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). + +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:: + + spin_lock(&lock); + ... + spin_unlock(&lock); + +(and the equivalent read-write versions too, of course). The spinlock will +guarantee the same kind of exclusive access, and it will be much faster. +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:: + + spin_lock(&lock); + ... + <- interrupt comes in: + spin_lock(&lock); + +where an interrupt tries to lock an already locked variable. This is ok if +the other interrupt happens on another CPU, but it is _not_ ok if the +interrupt happens on the same CPU that already holds the lock, because the +lock will obviously never be released (because the interrupt is waiting +for the lock, and the lock-holder is interrupted by the interrupt and will +not continue until the interrupt has been processed). + +(This is also the reason why the irq-versions of the spinlocks only need +to disable the _local_ interrupts - it's ok to use spinlocks in interrupts +on other CPU's, because an interrupt on another CPU doesn't interrupt the +CPU that holds the lock, so the lock-holder can continue and eventually +releases the lock). + +Note that you can be clever with read-write locks and interrupts. For +example, if you know that the interrupt only ever gets a read-lock, then +you can use a non-irq version of read locks everywhere - because they +don't block on each other (and thus there is no dead-lock wrt interrupts. +But when you do the write-lock, you have to use the irq-safe version. + +For an example of being clever with rw-locks, see the "waitqueue_lock" +handling in kernel/sched/core.c - nothing ever _changes_ a wait-queue from +within an interrupt, they only read the queue in order to know whom to +wake up. So read-locks are safe (which is good: they are very common +indeed), while write-locks need to protect themselves against interrupts. + + Linus + +---- + +Reference information: +====================== + +For dynamic initialization, use spin_lock_init() or rwlock_init() as +appropriate:: + + spinlock_t xxx_lock; + rwlock_t xxx_rw_lock; + + static int __init xxx_init(void) + { + spin_lock_init(&xxx_lock); + rwlock_init(&xxx_rw_lock); + ... + } + + module_init(xxx_init); + +For static initialization, use DEFINE_SPINLOCK() / DEFINE_RWLOCK() or +__SPIN_LOCK_UNLOCKED() / __RW_LOCK_UNLOCKED() as appropriate. diff --git a/Documentation/locking/spinlocks.txt b/Documentation/locking/spinlocks.txt deleted file mode 100644 index ff35e40bdf5b..000000000000 --- a/Documentation/locking/spinlocks.txt +++ /dev/null @@ -1,167 +0,0 @@ -Lesson 1: Spin locks - -The most basic primitive for locking is spinlock. - -static DEFINE_SPINLOCK(xxx_lock); - - unsigned long flags; - - spin_lock_irqsave(&xxx_lock, flags); - ... critical section here .. - spin_unlock_irqrestore(&xxx_lock, flags); - -The above is always safe. It will disable interrupts _locally_, but the -spinlock itself will guarantee the global lock, so it will guarantee that -there is only one thread-of-control within the region(s) protected by that -lock. This works well even under UP also, so the code does _not_ need to -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 -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 -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 - 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. - ----- - -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 -(rw_lock) versions of the spinlocks are sometimes useful. They allow multiple -readers to be in the same critical region at once, but if somebody wants -to change the variables it has to get an exclusive write lock. - - NOTE! reader-writer locks require more atomic memory operations than - simple spinlocks. Unless the reader critical section is long, you - are better off just using spinlocks. - -The routines look the same as above: - - rwlock_t xxx_lock = __RW_LOCK_UNLOCKED(xxx_lock); - - unsigned long flags; - - read_lock_irqsave(&xxx_lock, flags); - .. critical section that only reads the info ... - read_unlock_irqrestore(&xxx_lock, flags); - - write_lock_irqsave(&xxx_lock, flags); - .. read and write exclusive access to the info ... - write_unlock_irqrestore(&xxx_lock, flags); - -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. - - NOTE! RCU is better for list traversal, but requires careful - attention to design detail (see Documentation/RCU/listRCU.txt). - -Also, you cannot "upgrade" a read-lock to a write-lock, so if you at _any_ -time need to do any changes (even if you don't do it every time), you have -to get the write-lock at the very beginning. - - NOTE! We are working hard to remove reader-writer spinlocks in most - cases, so please don't add a new one without consensus. (Instead, see - Documentation/RCU/rcu.txt for complete information.) - ----- - -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 -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). - -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: - - spin_lock(&lock); - ... - spin_unlock(&lock); - -(and the equivalent read-write versions too, of course). The spinlock will -guarantee the same kind of exclusive access, and it will be much faster. -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: - - spin_lock(&lock); - ... - <- interrupt comes in: - spin_lock(&lock); - -where an interrupt tries to lock an already locked variable. This is ok if -the other interrupt happens on another CPU, but it is _not_ ok if the -interrupt happens on the same CPU that already holds the lock, because the -lock will obviously never be released (because the interrupt is waiting -for the lock, and the lock-holder is interrupted by the interrupt and will -not continue until the interrupt has been processed). - -(This is also the reason why the irq-versions of the spinlocks only need -to disable the _local_ interrupts - it's ok to use spinlocks in interrupts -on other CPU's, because an interrupt on another CPU doesn't interrupt the -CPU that holds the lock, so the lock-holder can continue and eventually -releases the lock). - -Note that you can be clever with read-write locks and interrupts. For -example, if you know that the interrupt only ever gets a read-lock, then -you can use a non-irq version of read locks everywhere - because they -don't block on each other (and thus there is no dead-lock wrt interrupts. -But when you do the write-lock, you have to use the irq-safe version. - -For an example of being clever with rw-locks, see the "waitqueue_lock" -handling in kernel/sched/core.c - nothing ever _changes_ a wait-queue from -within an interrupt, they only read the queue in order to know whom to -wake up. So read-locks are safe (which is good: they are very common -indeed), while write-locks need to protect themselves against interrupts. - - Linus - ----- - -Reference information: - -For dynamic initialization, use spin_lock_init() or rwlock_init() as -appropriate: - - spinlock_t xxx_lock; - rwlock_t xxx_rw_lock; - - static int __init xxx_init(void) - { - spin_lock_init(&xxx_lock); - rwlock_init(&xxx_rw_lock); - ... - } - - module_init(xxx_init); - -For static initialization, use DEFINE_SPINLOCK() / DEFINE_RWLOCK() or -__SPIN_LOCK_UNLOCKED() / __RW_LOCK_UNLOCKED() as appropriate. diff --git a/Documentation/locking/ww-mutex-design.rst b/Documentation/locking/ww-mutex-design.rst new file mode 100644 index 000000000000..1846c199da23 --- /dev/null +++ b/Documentation/locking/ww-mutex-design.rst @@ -0,0 +1,393 @@ +====================================== +Wound/Wait Deadlock-Proof Mutex Design +====================================== + +Please read mutex-design.txt first, as it applies to wait/wound mutexes too. + +Motivation for WW-Mutexes +------------------------- + +GPU's do operations that commonly involve many buffers. Those buffers +can be shared across contexts/processes, exist in different memory +domains (for example VRAM vs system memory), and so on. And with +PRIME / dmabuf, they can even be shared across devices. So there are +a handful of situations where the driver needs to wait for buffers to +become ready. If you think about this in terms of waiting on a buffer +mutex for it to become available, this presents a problem because +there is no way to guarantee that buffers appear in a execbuf/batch in +the same order in all contexts. That is directly under control of +userspace, and a result of the sequence of GL calls that an application +makes. Which results in the potential for deadlock. The problem gets +more complex when you consider that the kernel may need to migrate the +buffer(s) into VRAM before the GPU operates on the buffer(s), which +may in turn require evicting some other buffers (and you don't want to +evict other buffers which are already queued up to the GPU), but for a +simplified understanding of the problem you can ignore this. + +The algorithm that the TTM graphics subsystem came up with for dealing with +this problem is quite simple. For each group of buffers (execbuf) that need +to be locked, the caller would be assigned a unique reservation id/ticket, +from a global counter. In case of deadlock while locking all the buffers +associated with a execbuf, the one with the lowest reservation ticket (i.e. +the oldest task) wins, and the one with the higher reservation id (i.e. the +younger task) unlocks all of the buffers that it has already locked, and then +tries again. + +In the RDBMS literature, a reservation ticket is associated with a transaction. +and the deadlock handling approach is called Wait-Die. The name is based on +the actions of a locking thread when it encounters an already locked mutex. +If the transaction holding the lock is younger, the locking transaction waits. +If the transaction holding the lock is older, the locking transaction backs off +and dies. Hence Wait-Die. +There is also another algorithm called Wound-Wait: +If the transaction holding the lock is younger, the locking transaction +wounds the transaction holding the lock, requesting it to die. +If the transaction holding the lock is older, it waits for the other +transaction. Hence Wound-Wait. +The two algorithms are both fair in that a transaction will eventually succeed. +However, the Wound-Wait algorithm is typically stated to generate fewer backoffs +compared to Wait-Die, but is, on the other hand, associated with more work than +Wait-Die when recovering from a backoff. Wound-Wait is also a preemptive +algorithm in that transactions are wounded by other transactions, and that +requires a reliable way to pick up up the wounded condition and preempt the +running transaction. Note that this is not the same as process preemption. A +Wound-Wait transaction is considered preempted when it dies (returning +-EDEADLK) following a wound. + +Concepts +-------- + +Compared to normal mutexes two additional concepts/objects show up in the lock +interface for w/w mutexes: + +Acquire context: To ensure eventual forward progress it is important the a task +trying to acquire locks doesn't grab a new reservation id, but keeps the one it +acquired when starting the lock acquisition. This ticket is stored in the +acquire context. Furthermore the acquire context keeps track of debugging state +to catch w/w mutex interface abuse. An acquire context is representing a +transaction. + +W/w class: In contrast to normal mutexes the lock class needs to be explicit for +w/w mutexes, since it is required to initialize the acquire context. The lock +class also specifies what algorithm to use, Wound-Wait or Wait-Die. + +Furthermore there are three different class of w/w lock acquire functions: + +* Normal lock acquisition with a context, using ww_mutex_lock. + +* Slowpath lock acquisition on the contending lock, used by the task that just + killed its transaction after having dropped all already acquired locks. + These functions have the _slow postfix. + + From a simple semantics point-of-view the _slow functions are not strictly + required, since simply calling the normal ww_mutex_lock functions on the + contending lock (after having dropped all other already acquired locks) will + work correctly. After all if no other ww mutex has been acquired yet there's + 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 + very first lock operation can never fail. + - When full debugging is enabled ww_mutex_lock_slow checks that all acquired + ww mutex have been released (preventing deadlocks) and makes sure that we + block on the contending lock (preventing spinning through the -EDEADLK + slowpath until the contended lock can be acquired). + +* Functions to only acquire a single w/w mutex, which results in the exact same + semantics as a normal mutex. This is done by calling ww_mutex_lock with a NULL + context. + + Again this is not strictly required. But often you only want to acquire a + single lock in which case it's pointless to set up an acquire context (and so + better to avoid grabbing a deadlock avoidance ticket). + +Of course, all the usual variants for handling wake-ups due to signals are also +provided. + +Usage +----- + +The algorithm (Wait-Die vs Wound-Wait) is chosen by using either +DEFINE_WW_CLASS() (Wound-Wait) or DEFINE_WD_CLASS() (Wait-Die) +As a rough rule of thumb, use Wound-Wait iff you +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:: + + static DEFINE_WW_CLASS(ww_class); + + struct obj { + struct ww_mutex lock; + /* obj data */ + }; + + 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):: + + 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: + list_for_each_entry (entry, list, head) { + if (entry->obj == res_obj) { + res_obj = NULL; + continue; + } + ret = ww_mutex_lock(&entry->obj->lock, ctx); + if (ret < 0) { + contended_entry = entry; + goto err; + } + } + + ww_acquire_done(ctx); + return 0; + + err: + list_for_each_entry_continue_reverse (entry, list, head) + ww_mutex_unlock(&entry->obj->lock); + + if (res_obj) + ww_mutex_unlock(&res_obj->lock); + + if (ret == -EDEADLK) { + /* we lost out in a seqno race, lock and retry.. */ + ww_mutex_lock_slow(&contended_entry->obj->lock, ctx); + res_obj = contended_entry->obj; + goto retry; + } + 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:: + + int lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx) + { + struct obj_entry *entry, *entry2; + + ww_acquire_init(ctx, &ww_class); + + list_for_each_entry (entry, list, head) { + ret = ww_mutex_lock(&entry->obj->lock, ctx); + if (ret < 0) { + entry2 = entry; + + list_for_each_entry_continue_reverse (entry2, list, head) + ww_mutex_unlock(&entry2->obj->lock); + + if (ret != -EDEADLK) { + ww_acquire_fini(ctx); + return ret; + } + + /* we lost out in a seqno race, lock and retry.. */ + ww_mutex_lock_slow(&entry->obj->lock, ctx); + + /* + * Move buf to head of the list, this will point + * buf->next to the first unlocked entry, + * restarting the for loop. + */ + list_del(&entry->head); + list_add(&entry->head, list); + } + } + + ww_acquire_done(ctx); + return 0; + } + +Unlocking works the same way for both methods #1 and #2:: + + 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. +- Due to the -EALREADY return code signalling that a given objects is already + held there's no need for additional book-keeping to break cycles in the graph + or keep track off which looks are already held (when using more than one node + 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 + therefore move the list_head into the object itself. +- On the other hand the dynamic object list construction also means that the -EALREADY return + code can't be propagated. + +Note also that methods #1 and #2 and method #3 can be combined, e.g. to first lock a +list of starting nodes (passed in from userspace) using one of the above +methods. And then lock any additional objects affected by the operations using +method #3 below. The backoff/retry procedure will be a bit more involved, since +when the dynamic locking step hits -EDEADLK we also need to unlock all the +objects acquired with the fixed list. But the w/w mutex debug checks will catch +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:: + + struct obj { + struct ww_mutex ww_mutex; + struct list_head locked_list; + }; + + static DEFINE_WW_CLASS(ww_class); + + void __unlock_objs(struct list_head *list) + { + struct obj *entry, *temp; + + list_for_each_entry_safe (entry, temp, list, locked_list) { + /* need to do that before unlocking, since only the current lock holder is + allowed to use object */ + list_del(&entry->locked_list); + ww_mutex_unlock(entry->ww_mutex) + } + } + + void lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx) + { + struct obj *obj; + + ww_acquire_init(ctx, &ww_class); + + retry: + /* re-init loop start state */ + loop { + /* magic code which walks over a graph and decides which objects + * to lock */ + + ret = ww_mutex_lock(obj->ww_mutex, ctx); + if (ret == -EALREADY) { + /* we have that one already, get to the next object */ + continue; + } + if (ret == -EDEADLK) { + __unlock_objs(list); + + ww_mutex_lock_slow(obj, ctx); + list_add(&entry->locked_list, list); + goto retry; + } + + /* locked a new object, add it to the list */ + list_add_tail(&entry->locked_list, list); + } + + ww_acquire_done(ctx); + return 0; + } + + 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 +produce a deadlock within just one class. To simplify this case the w/w mutex +api can be used with a NULL context. + +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 + other locks acquired already (ctx->acquired > 0). Note that this waiter + may come after other waiters without contexts in the list. + + The Wound-Wait preemption is implemented with a lazy-preemption scheme: + The wounded status of the transaction is checked only when there is + contention for a new lock and hence a true chance of deadlock. In that + situation, if the transaction is wounded, it backs off, clears the + wounded status and retries. A great benefit of implementing preemption in + this way is that the wounded transaction can identify a contending lock to + wait for before restarting the transaction. Just blindly restarting the + transaction would likely make the transaction end up in a situation where + it would have to back off again. + + In general, not much contention is expected. The locks are typically used to + serialize access to resources for devices, and optimization focus should + 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. + + Some of the errors which will be warned about: + - Forgetting to call ww_acquire_fini or ww_acquire_init. + - Attempting to lock more mutexes after ww_acquire_done. + - Attempting to lock the wrong mutex after -EDEADLK and + unlocking all mutexes. + - Attempting to lock the right mutex after -EDEADLK, + before unlocking all mutexes. + + - Calling ww_mutex_lock_slow before -EDEADLK was returned. + + - Unlocking mutexes with the wrong unlock function. + - Calling one of the ww_acquire_* twice on the same context. + - Using a different ww_class for the mutex than for the ww_acquire_ctx. + - Normal lockdep errors that can result in deadlocks. + + Some of the lockdep errors that can result in deadlocks: + - Calling ww_acquire_init to initialize a second ww_acquire_ctx before + 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. diff --git a/Documentation/locking/ww-mutex-design.txt b/Documentation/locking/ww-mutex-design.txt deleted file mode 100644 index f0ed7c30e695..000000000000 --- a/Documentation/locking/ww-mutex-design.txt +++ /dev/null @@ -1,383 +0,0 @@ -Wound/Wait Deadlock-Proof Mutex Design -====================================== - -Please read mutex-design.txt first, as it applies to wait/wound mutexes too. - -Motivation for WW-Mutexes -------------------------- - -GPU's do operations that commonly involve many buffers. Those buffers -can be shared across contexts/processes, exist in different memory -domains (for example VRAM vs system memory), and so on. And with -PRIME / dmabuf, they can even be shared across devices. So there are -a handful of situations where the driver needs to wait for buffers to -become ready. If you think about this in terms of waiting on a buffer -mutex for it to become available, this presents a problem because -there is no way to guarantee that buffers appear in a execbuf/batch in -the same order in all contexts. That is directly under control of -userspace, and a result of the sequence of GL calls that an application -makes. Which results in the potential for deadlock. The problem gets -more complex when you consider that the kernel may need to migrate the -buffer(s) into VRAM before the GPU operates on the buffer(s), which -may in turn require evicting some other buffers (and you don't want to -evict other buffers which are already queued up to the GPU), but for a -simplified understanding of the problem you can ignore this. - -The algorithm that the TTM graphics subsystem came up with for dealing with -this problem is quite simple. For each group of buffers (execbuf) that need -to be locked, the caller would be assigned a unique reservation id/ticket, -from a global counter. In case of deadlock while locking all the buffers -associated with a execbuf, the one with the lowest reservation ticket (i.e. -the oldest task) wins, and the one with the higher reservation id (i.e. the -younger task) unlocks all of the buffers that it has already locked, and then -tries again. - -In the RDBMS literature, a reservation ticket is associated with a transaction. -and the deadlock handling approach is called Wait-Die. The name is based on -the actions of a locking thread when it encounters an already locked mutex. -If the transaction holding the lock is younger, the locking transaction waits. -If the transaction holding the lock is older, the locking transaction backs off -and dies. Hence Wait-Die. -There is also another algorithm called Wound-Wait: -If the transaction holding the lock is younger, the locking transaction -wounds the transaction holding the lock, requesting it to die. -If the transaction holding the lock is older, it waits for the other -transaction. Hence Wound-Wait. -The two algorithms are both fair in that a transaction will eventually succeed. -However, the Wound-Wait algorithm is typically stated to generate fewer backoffs -compared to Wait-Die, but is, on the other hand, associated with more work than -Wait-Die when recovering from a backoff. Wound-Wait is also a preemptive -algorithm in that transactions are wounded by other transactions, and that -requires a reliable way to pick up up the wounded condition and preempt the -running transaction. Note that this is not the same as process preemption. A -Wound-Wait transaction is considered preempted when it dies (returning --EDEADLK) following a wound. - -Concepts --------- - -Compared to normal mutexes two additional concepts/objects show up in the lock -interface for w/w mutexes: - -Acquire context: To ensure eventual forward progress it is important the a task -trying to acquire locks doesn't grab a new reservation id, but keeps the one it -acquired when starting the lock acquisition. This ticket is stored in the -acquire context. Furthermore the acquire context keeps track of debugging state -to catch w/w mutex interface abuse. An acquire context is representing a -transaction. - -W/w class: In contrast to normal mutexes the lock class needs to be explicit for -w/w mutexes, since it is required to initialize the acquire context. The lock -class also specifies what algorithm to use, Wound-Wait or Wait-Die. - -Furthermore there are three different class of w/w lock acquire functions: - -* Normal lock acquisition with a context, using ww_mutex_lock. - -* Slowpath lock acquisition on the contending lock, used by the task that just - killed its transaction after having dropped all already acquired locks. - These functions have the _slow postfix. - - From a simple semantics point-of-view the _slow functions are not strictly - required, since simply calling the normal ww_mutex_lock functions on the - contending lock (after having dropped all other already acquired locks) will - work correctly. After all if no other ww mutex has been acquired yet there's - 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 - very first lock operation can never fail. - - When full debugging is enabled ww_mutex_lock_slow checks that all acquired - ww mutex have been released (preventing deadlocks) and makes sure that we - block on the contending lock (preventing spinning through the -EDEADLK - slowpath until the contended lock can be acquired). - -* Functions to only acquire a single w/w mutex, which results in the exact same - semantics as a normal mutex. This is done by calling ww_mutex_lock with a NULL - context. - - Again this is not strictly required. But often you only want to acquire a - single lock in which case it's pointless to set up an acquire context (and so - better to avoid grabbing a deadlock avoidance ticket). - -Of course, all the usual variants for handling wake-ups due to signals are also -provided. - -Usage ------ - -The algorithm (Wait-Die vs Wound-Wait) is chosen by using either -DEFINE_WW_CLASS() (Wound-Wait) or DEFINE_WD_CLASS() (Wait-Die) -As a rough rule of thumb, use Wound-Wait iff you -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: - -static DEFINE_WW_CLASS(ww_class); - -struct obj { - struct ww_mutex lock; - /* obj data */ -}; - -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). - -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: - list_for_each_entry (entry, list, head) { - if (entry->obj == res_obj) { - res_obj = NULL; - continue; - } - ret = ww_mutex_lock(&entry->obj->lock, ctx); - if (ret < 0) { - contended_entry = entry; - goto err; - } - } - - ww_acquire_done(ctx); - return 0; - -err: - list_for_each_entry_continue_reverse (entry, list, head) - ww_mutex_unlock(&entry->obj->lock); - - if (res_obj) - ww_mutex_unlock(&res_obj->lock); - - if (ret == -EDEADLK) { - /* we lost out in a seqno race, lock and retry.. */ - ww_mutex_lock_slow(&contended_entry->obj->lock, ctx); - res_obj = contended_entry->obj; - goto retry; - } - 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. - -int lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx) -{ - struct obj_entry *entry, *entry2; - - ww_acquire_init(ctx, &ww_class); - - list_for_each_entry (entry, list, head) { - ret = ww_mutex_lock(&entry->obj->lock, ctx); - if (ret < 0) { - entry2 = entry; - - list_for_each_entry_continue_reverse (entry2, list, head) - ww_mutex_unlock(&entry2->obj->lock); - - if (ret != -EDEADLK) { - ww_acquire_fini(ctx); - return ret; - } - - /* we lost out in a seqno race, lock and retry.. */ - ww_mutex_lock_slow(&entry->obj->lock, ctx); - - /* - * Move buf to head of the list, this will point - * buf->next to the first unlocked entry, - * restarting the for loop. - */ - list_del(&entry->head); - list_add(&entry->head, list); - } - } - - ww_acquire_done(ctx); - return 0; -} - -Unlocking works the same way for both methods #1 and #2: - -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. -- Due to the -EALREADY return code signalling that a given objects is already - held there's no need for additional book-keeping to break cycles in the graph - or keep track off which looks are already held (when using more than one node - 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 - therefore move the list_head into the object itself. -- On the other hand the dynamic object list construction also means that the -EALREADY return - code can't be propagated. - -Note also that methods #1 and #2 and method #3 can be combined, e.g. to first lock a -list of starting nodes (passed in from userspace) using one of the above -methods. And then lock any additional objects affected by the operations using -method #3 below. The backoff/retry procedure will be a bit more involved, since -when the dynamic locking step hits -EDEADLK we also need to unlock all the -objects acquired with the fixed list. But the w/w mutex debug checks will catch -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. - -struct obj { - struct ww_mutex ww_mutex; - struct list_head locked_list; -}; - -static DEFINE_WW_CLASS(ww_class); - -void __unlock_objs(struct list_head *list) -{ - struct obj *entry, *temp; - - list_for_each_entry_safe (entry, temp, list, locked_list) { - /* need to do that before unlocking, since only the current lock holder is - allowed to use object */ - list_del(&entry->locked_list); - ww_mutex_unlock(entry->ww_mutex) - } -} - -void lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx) -{ - struct obj *obj; - - ww_acquire_init(ctx, &ww_class); - -retry: - /* re-init loop start state */ - loop { - /* magic code which walks over a graph and decides which objects - * to lock */ - - ret = ww_mutex_lock(obj->ww_mutex, ctx); - if (ret == -EALREADY) { - /* we have that one already, get to the next object */ - continue; - } - if (ret == -EDEADLK) { - __unlock_objs(list); - - ww_mutex_lock_slow(obj, ctx); - list_add(&entry->locked_list, list); - goto retry; - } - - /* locked a new object, add it to the list */ - list_add_tail(&entry->locked_list, list); - } - - ww_acquire_done(ctx); - return 0; -} - -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 -produce a deadlock within just one class. To simplify this case the w/w mutex -api can be used with a NULL context. - -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 - other locks acquired already (ctx->acquired > 0). Note that this waiter - may come after other waiters without contexts in the list. - - The Wound-Wait preemption is implemented with a lazy-preemption scheme: - The wounded status of the transaction is checked only when there is - contention for a new lock and hence a true chance of deadlock. In that - situation, if the transaction is wounded, it backs off, clears the - wounded status and retries. A great benefit of implementing preemption in - this way is that the wounded transaction can identify a contending lock to - wait for before restarting the transaction. Just blindly restarting the - transaction would likely make the transaction end up in a situation where - it would have to back off again. - - In general, not much contention is expected. The locks are typically used to - serialize access to resources for devices, and optimization focus should - 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. - - Some of the errors which will be warned about: - - Forgetting to call ww_acquire_fini or ww_acquire_init. - - Attempting to lock more mutexes after ww_acquire_done. - - Attempting to lock the wrong mutex after -EDEADLK and - unlocking all mutexes. - - Attempting to lock the right mutex after -EDEADLK, - before unlocking all mutexes. - - - Calling ww_mutex_lock_slow before -EDEADLK was returned. - - - Unlocking mutexes with the wrong unlock function. - - Calling one of the ww_acquire_* twice on the same context. - - Using a different ww_class for the mutex than for the ww_acquire_ctx. - - Normal lockdep errors that can result in deadlocks. - - Some of the lockdep errors that can result in deadlocks: - - Calling ww_acquire_init to initialize a second ww_acquire_ctx before - 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. 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. -- cgit v1.2.3-55-g7522 From 720594f691e5c8fb0624f3653b20b24ba8e57742 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sat, 13 Apr 2019 22:54:53 -0300 Subject: 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 --- Documentation/connector/connector.rst | 156 +++++++++++++++++++++++++++ Documentation/connector/connector.txt | 196 ---------------------------------- drivers/w1/Kconfig | 2 +- include/linux/connector.h | 63 ++++++++++- samples/Kconfig | 2 +- 5 files changed, 220 insertions(+), 199 deletions(-) create mode 100644 Documentation/connector/connector.rst delete mode 100644 Documentation/connector/connector.txt diff --git a/Documentation/connector/connector.rst b/Documentation/connector/connector.rst new file mode 100644 index 000000000000..24e26dc22dbf --- /dev/null +++ b/Documentation/connector/connector.rst @@ -0,0 +1,156 @@ +:orphan: + +================ +Kernel Connector +================ + +Kernel connector - new netlink based userspace <-> kernel space easy +to use communication module. + +The Connector driver makes it easy to connect various agents using a +netlink based network. One must register a callback and an identifier. +When the driver receives a special netlink message with the appropriate +identifier, the appropriate callback will be called. + +From the userspace point of view it's quite straightforward: + + - 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:: + + 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 + { + __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 +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 *`:: + + struct cn_msg + { + struct cb_id id; + + __u32 seq; + __u32 ack; + + __u32 len; /* Length of the following data */ + __u8 data[0]; + }; + +Connector interfaces +==================== + + .. kernel-doc:: include/linux/connector.h + + Note: + When registering new callback user, connector core assigns + netlink group to the user which is equal to its id.idx. + +Protocol description +==================== + +The current framework offers a transport layer with fixed headers. The +recommended protocol which uses such a header is as following: + +msg->seq and msg->ack are used to determine message genealogy. When +someone sends a message, they use a locally unique sequence and random +acknowledge number. The sequence number may be copied into +nlmsghdr->nlmsg_seq too. + +The sequence number is incremented with each message sent. + +If you expect a reply to the message, then the sequence number in the +received message MUST be the same as in the original message, and the +acknowledge number MUST be the same + 1. + +If we receive a message and its sequence number is not equal to one we +are expecting, then it is a new message. If we receive a message and +its sequence number is the same as one we are expecting, but its +acknowledge is not equal to the sequence number in the original +message + 1, then it is a new message. + +Obviously, the protocol header contains the above id. + +The connector allows event notification in the following form: kernel +driver or userspace process can ask connector to notify it when +selected ids will be turned on or off (registered or unregistered its +callback). It is done by sending a special command to the connector +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 +=========== + +Netlink itself is not a reliable protocol. That means that messages can +be lost due to memory pressure or process' receiving queue overflowed, +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 +=============== + +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:: + + s = socket(PF_NETLINK, SOCK_DGRAM, NETLINK_CONNECTOR); + + 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) { + 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 +option with the NETLINK_DROP_MEMBERSHIP parameter which is defined as 0. + +2.6.14 netlink code only allows to select a group which is less or equal to +the maximum group number, which is used at netlink_kernel_create() time. +In case of connector it is CN_NETLINK_USERS + 0xf, so if you want to use +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, +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 +and CONFIG_SAMPLES. diff --git a/Documentation/connector/connector.txt b/Documentation/connector/connector.txt deleted file mode 100644 index ab7ca897fab7..000000000000 --- a/Documentation/connector/connector.txt +++ /dev/null @@ -1,196 +0,0 @@ -/*****************************************/ -Kernel Connector. -/*****************************************/ - -Kernel connector - new netlink based userspace <-> kernel space easy -to use communication module. - -The Connector driver makes it easy to connect various agents using a -netlink based network. One must register a callback and an identifier. -When the driver receives a special netlink message with the appropriate -identifier, the appropriate callback will be called. - -From the userspace point of view it's quite straightforward: - - 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: - -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 -{ - __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 -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 *. - -struct cn_msg -{ - struct cb_id id; - - __u32 seq; - __u32 ack; - - __u32 len; /* Length of the following data */ - __u8 data[0]; -}; - -/*****************************************/ -Connector interfaces. -/*****************************************/ - -int cn_add_callback(struct cb_id *id, char *name, void (*callback) (struct cn_msg *, struct netlink_skb_parms *)); - - Registers new callback with connector core. - - 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. -/*****************************************/ - -The current framework offers a transport layer with fixed headers. The -recommended protocol which uses such a header is as following: - -msg->seq and msg->ack are used to determine message genealogy. When -someone sends a message, they use a locally unique sequence and random -acknowledge number. The sequence number may be copied into -nlmsghdr->nlmsg_seq too. - -The sequence number is incremented with each message sent. - -If you expect a reply to the message, then the sequence number in the -received message MUST be the same as in the original message, and the -acknowledge number MUST be the same + 1. - -If we receive a message and its sequence number is not equal to one we -are expecting, then it is a new message. If we receive a message and -its sequence number is the same as one we are expecting, but its -acknowledge is not equal to the sequence number in the original -message + 1, then it is a new message. - -Obviously, the protocol header contains the above id. - -The connector allows event notification in the following form: kernel -driver or userspace process can ask connector to notify it when -selected ids will be turned on or off (registered or unregistered its -callback). It is done by sending a special command to the connector -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. -/*****************************************/ - -Netlink itself is not a reliable protocol. That means that messages can -be lost due to memory pressure or process' receiving queue overflowed, -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. -/*****************************************/ - -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: - -s = socket(PF_NETLINK, SOCK_DGRAM, NETLINK_CONNECTOR); - -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) { - 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 -option with the NETLINK_DROP_MEMBERSHIP parameter which is defined as 0. - -2.6.14 netlink code only allows to select a group which is less or equal to -the maximum group number, which is used at netlink_kernel_create() time. -In case of connector it is CN_NETLINK_USERS + 0xf, so if you want to use -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, -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 -and CONFIG_SAMPLES. 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" -- cgit v1.2.3-55-g7522 From 065504d5b45bc780b8da221162145a4c9ec67ffc Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sun, 14 Apr 2019 07:59:32 -0300 Subject: 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 --- Documentation/auxdisplay/lcd-panel-cgram.rst | 29 ++++++++++++++++++++++++++++ Documentation/auxdisplay/lcd-panel-cgram.txt | 24 ----------------------- MAINTAINERS | 2 +- 3 files changed, 30 insertions(+), 25 deletions(-) create mode 100644 Documentation/auxdisplay/lcd-panel-cgram.rst delete mode 100644 Documentation/auxdisplay/lcd-panel-cgram.txt diff --git a/Documentation/auxdisplay/lcd-panel-cgram.rst b/Documentation/auxdisplay/lcd-panel-cgram.rst new file mode 100644 index 000000000000..dfef50286018 --- /dev/null +++ b/Documentation/auxdisplay/lcd-panel-cgram.rst @@ -0,0 +1,29 @@ +: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 +number, and up to 8 couples of hex digits terminated by a semi-colon +(';'). Each couple of digits represents a line, with 1-bits for each +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:: + + printf "\e[LG0010101050D1F0C04;" => 0 = [enter] + printf "\e[LG1040E1F0000000000;" => 1 = [up] + printf "\e[LG2000000001F0E0400;" => 2 = [down] + printf "\e[LG3040E1F001F0E0400;" => 3 = [up-down] + printf "\e[LG40002060E1E0E0602;" => 4 = [left] + printf "\e[LG500080C0E0F0E0C08;" => 5 = [right] + printf "\e[LG60016051516141400;" => 6 = "IP" + + printf "\e[LG00103071F1F070301;" => big speaker + printf "\e[LG00002061E1E060200;" => small speaker + +Willy diff --git a/Documentation/auxdisplay/lcd-panel-cgram.txt b/Documentation/auxdisplay/lcd-panel-cgram.txt deleted file mode 100644 index 7f82c905763d..000000000000 --- a/Documentation/auxdisplay/lcd-panel-cgram.txt +++ /dev/null @@ -1,24 +0,0 @@ -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 -number, and up to 8 couples of hex digits terminated by a semi-colon -(';'). Each couple of digits represents a line, with 1-bits for each -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 : - - printf "\e[LG0010101050D1F0C04;" => 0 = [enter] - printf "\e[LG1040E1F0000000000;" => 1 = [up] - printf "\e[LG2000000001F0E0400;" => 2 = [down] - printf "\e[LG3040E1F001F0E0400;" => 3 = [up-down] - printf "\e[LG40002060E1E0E0602;" => 4 = [left] - printf "\e[LG500080C0E0F0E0C08;" => 5 = [right] - printf "\e[LG60016051516141400;" => 6 = "IP" - - printf "\e[LG00103071F1F070301;" => big speaker - 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 -- cgit v1.2.3-55-g7522 From 6f2846cc2ebae4a8c875389e3aedb0cda3c4f462 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sun, 14 Apr 2019 08:03:23 -0300 Subject: 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 -- cgit v1.2.3-55-g7522 From 23e02422877b7fac868d8610a4265003da4ac0f4 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sun, 14 Apr 2019 08:27:15 -0300 Subject: 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 --- Documentation/admin-guide/kernel-parameters.rst | 2 +- Documentation/m68k/index.rst | 17 + Documentation/m68k/kernel-options.rst | 911 ++++++++++++++++++++++++ Documentation/m68k/kernel-options.txt | 884 ----------------------- 4 files changed, 929 insertions(+), 885 deletions(-) create mode 100644 Documentation/m68k/index.rst create mode 100644 Documentation/m68k/kernel-options.rst delete mode 100644 Documentation/m68k/kernel-options.txt 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.rst b/Documentation/m68k/kernel-options.rst new file mode 100644 index 000000000000..cabd9419740d --- /dev/null +++ b/Documentation/m68k/kernel-options.rst @@ -0,0 +1,911 @@ +=================================== +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 +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 +incomplete or missing. Please update the information and send in the +patches. + + +1) Overview of the Kernel's Option Processing +============================================= + +The kernel knows three kinds of options on its command line: + + 1) kernel options + 2) environment settings + 3) arguments for init + +To which of these classes an argument belongs is determined as +follows: If the option is known to the kernel itself, i.e. if the name +(the part before the '=') or, in some cases, the whole argument string +is known to the kernel, it belongs to class 1. Otherwise, if the +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 +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 +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 +subdivided. + + +2) General Kernel Options +========================= + +2.1) 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 +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:: + + /dev/ram: -> 0x0100 (initial ramdisk) + /dev/hda: -> 0x0300 (first IDE disk) + /dev/hdb: -> 0x0340 (second IDE disk) + /dev/sda: -> 0x0800 (first SCSI disk) + /dev/sdb: -> 0x0810 (second SCSI disk) + /dev/sdc: -> 0x0820 (third SCSI disk) + /dev/sdd: -> 0x0830 (forth SCSI disk) + /dev/sde: -> 0x0840 (fifth SCSI disk) + /dev/fd : -> 0x0200 (floppy disk) + +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 +initial ramdisk loaded by your bootstrap program (please consult the +instructions for your bootstrap program to find out how to load an +initial ramdisk). As of kernel version 2.0.18 you must specify +/dev/ram as the root device if you want to boot from an initial +ramdisk. For the floppy devices, /dev/fd, the number stands for the +floppy drive number (there are no partitions on floppy disks). I.e., +/dev/fd0 stands for the first drive, /dev/fd1 for the second, and so +on. Since the number is just added, you can also force the disk format +by adding a number greater than 3. If you look into your /dev +directory, use can see the /dev/fd0D720 has major 2 and minor 16. You +can specify this device for the root FS by writing "root=/dev/fd16" on +the kernel command line. + +[Strange and maybe uninteresting stuff ON] + +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 +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 +/dev/sde are in the table above, but not /dev/sdf. Although, you can +use the sixth SCSI disk for the root FS, but you have to specify the +device by number... (see below). Or, even more strange, you can use the +fact that there is no range checking of the partition number, and your +knowledge that each disk uses 16 minors, and write "root=/dev/sde17" +(for /dev/sdf1). + +[Strange and maybe uninteresting stuff OFF] + +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 +SCSI CD-ROM drive, you boot from it by "root=0b00". Here, hex "0b" = +decimal 11 is the major of SCSI CD-ROMs, and the minor 0 stands for +the first of these. You can find out all valid major numbers by +looking into include/linux/major.h. + +In addition to major and minor numbers, if the device containing your +root partition uses a partition table format with unique partition +identifiers, then you may use them. For instance, +"root=PARTUUID=00112233-4455-6677-8899-AABBCCDDEEFF". It is also +possible to reference another partition on the same device using a +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 +"Documentation/admin-guide/kernel-parameters.rst". + + +2.2) ro, 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 +for ramdisks, which default to read-write. + + +2.3) 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 +selectable by dmesg is 8. + + +2.4) debug= +----------- + +:Syntax: debug= + +This option causes certain kernel messages be printed to the selected +debugging device. This can aid debugging the kernel, since the +messages can be captured and analyzed on some other machine. Which +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 +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 +dumps, the kernel sets the log level to 10 automatically. A level of +at least 8 can also be set by the "debug" command line option (see +2.3) and at run time with "dmesg -n 8". + +Devices possible for Amiga: + + - "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 + This is "ser2" for a Falcon, and "ser1" for any other machine + - "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 + seconds. + + +2.6) ramdisk_size= +------------------ + +:Syntax: ramdisk_size= + +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 +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 this option in 2.2.6. + + +3) General Device Options (Amiga and Atari) +=========================================== + +3.1) ether= +----------- + +:Syntax: ether=[[,[,[,]]]], + + 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 +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 +for Linux/m68k. + + +3.2) hd= +-------- + +:Syntax: 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 +itself. It exists just for the case that this fails for one of your +disks. + + +3.3) max_scsi_luns= +------------------- + +:Syntax: max_scsi_luns= + +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. + + +3.4) st= +-------- + +:Syntax: st=,[,[]] + +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 +total number of buffers. limits the total number of +buffers allocated for all tape devices. + + +3.5) dmasound= +-------------- + +:Syntax: dmasound=[,[,]] + +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 +how much percent of error will be tolerated when setting a frequency +(maximum 10, default 0). For example with 3% you can play 8000Hz +AU-Files on the Falcon with its hardware frequency of 8195Hz and thus +don't need to expand the sound. + + + +4) Options for Atari Only +========================= + +4.1) video= +----------- + +:Syntax: video=: + +The parameter specifies the name of the frame buffer, +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 + 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. + +4.1.1) Video Mode +----------------- + +This sub-option may be any of the predefined video modes, as listed +in atari/atafb.c in the Linux/m68k source tree. The kernel will +activate the given video mode at boot time and make it the default +mode, if the hardware allows. Currently defined names are: + + - stlow : 320x200x4 + - stmid, default5 : 640x200x2 + - sthigh, default4: 640x400x1 + - ttlow : 320x480x8, TT only + - ttmid, default1 : 640x480x4, TT only + - tthigh, default2: 1280x960x1, TT only + - vga2 : 640x480x1, Falcon only + - vga4 : 640x480x2, Falcon only + - vga16, default3 : 640x480x4, Falcon only + - vga256 : 640x480x8, Falcon only + - falh2 : 896x608x1, Falcon only + - falh16 : 896x608x4, Falcon only + +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 +activated by a "external:" sub-option. + +4.1.2) inverse +-------------- + +Invert the display. This affects both, text (consoles) and graphics +(X) display. Usually, the background is chosen to be black. With this +option, you can make the background white. + +4.1.3) 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 +vertical size of the display is less than 400 pixel rows. Otherwise, the +`VGA8x16` font is the default. + +4.1.4) `hwscroll_` +------------------ + +:Syntax: `hwscroll_` + +The number of additional lines of video memory to reserve for +speeding up the scrolling ("hardware scrolling"). Hardware scrolling +is possible only if the kernel can set the video base address in steps +fine enough. This is true for STE, MegaSTE, TT, and Falcon. It is not +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 +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. + +4.1.5) 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 +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. +For this, see the "sw_*" options below. + +4.1.6) external: +---------------- + +:Syntax: + external:;;;;[;[; + [;[;[;]]]]] + +.. I had to break this line... + +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 +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: , + 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 +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 + 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 + +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 + +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 +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 +with the external driver, because the kernel cannot set the video base +address), or for virtual resolutions under X (which the X server +doesn't support yet). So, it's currently best to leave this field +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 +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 +address of the VGA register set, so it can change the color lookup +table. You have to look up this address in your board's documentation. +To avoid misunderstandings: is the _base_ address, i.e. a 4k +aligned address. For read/writing the color registers, the kernel +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 +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 +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, +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, +therefore we don't support hardware-dependent functions like hardware-scroll, +panning or blanking. + +4.1.7) eclock: +-------------- + +The external pixel clock attached to the Falcon VIDEL shifter. This +currently works only with the ScreenWonder! + +4.1.8) 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 +your monitor can work with, in Hz. and are the same for +the horizontal frequency, in kHz. + + The defaults are 58;62;31;32 (VGA compatible). + + The defaults for TV/SC1224/SC1435 cover both PAL and NTSC standards. + +4.1.9) keep +------------ + +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 +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 +the Falcon. + + +4.2) atamouse= +-------------- + +:Syntax: atamouse=,[] + +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 +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. + + +4.3) 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 + probed (see also below). The default is 1 (HD). Only one drive type + can be selected. If you have two disk drives, select the "better" + type. + + The second parameter tells the kernel whether to use + track buffering (1) or not (0). The default is machine-dependent: + 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. + + +4.4) atascsi= +------------- + +:Syntax: atascsi=[,[,[,[,]]]] + +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. +Below, defaults are noted as n/m, where the first value refers to +TT-SCSI and the latter to Falcon-SCSI. If an illegal value is given +for one parameter, an error message is printed and that one setting is +ignored (others aren't affected). + + : + This is the maximum number of SCSI commands queued internally to the + Atari SCSI driver. A value of 1 effectively turns off the driver + internal multitasking (if it causes problems). Legal values are >= + 1. can be as high as you like, but values greater than + times the number of SCSI targets (LUNs) you have + don't make sense. Default: 16/8. + + : + Maximum number of SCSI commands issued to the driver for one + logical unit (LUN, usually one SCSI target). Legal values start + from 1. If tagged queuing (see below) is not used, values greater + than 2 don't make sense, but waste memory. Otherwise, the maximum + is the number of command tags available to the driver (currently + 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 + 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 + + : + Size of the scatter-gather table, i.e. the number of requests + consecutive on the disk that can be merged into one SCSI command. + Legal values are between 0 and 255. Default: 255/0. Note: This + value is forced to 0 on a Falcon, since scatter-gather isn't + possible with the ST-DMA. Not using scatter-gather hurts + performance significantly. + + : + The SCSI ID to be used by the initiator (your Atari). This is + usually 7, the highest possible ID. Every ID on the SCSI bus must + be unique. Default: determined at run time: If the NV-RAM checksum + is valid, and bit 7 in byte 30 of the NV-RAM is set, the lower 3 + bits of this byte are used as the host ID. (This method is defined + by Atari and also used by some TOS HD drivers.) If the above + isn't given, the default ID is 7. (both, TT and Falcon). + + : + 0 means turn off tagged queuing support, all other values > 0 mean + use tagged queuing for targets that support it. Default: currently + off, but this may change when tagged queuing handling has been + proved to be reliable. + + Tagged queuing means that more than one command can be issued to + one LUN, and the SCSI device itself orders the requests so they + can be performed in optimal order. Not all SCSI devices support + tagged queuing (:-(). + +4.5 switches= +------------- + +:Syntax: switches= + +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 +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 + +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 +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 +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 +switching-off on reset still happens in this case. + +5) Options for Amiga Only: +========================== + +5.1) video= +----------- + +:Syntax: video=: + +The parameter specifies the name of the frame buffer, valid +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 +option. + +The is a comma-separated list of the sub-options listed +below. This option is organized similar to the Atari version of the +"video"-option (4.1), but knows fewer sub-options. + +5.1.1) video mode +----------------- + +Again, similar to the video mode for the Atari (see 4.1.1). Predefined +modes depend on the used frame buffer device. + +OCS, ECS and AGA machines all use the color frame buffer. The following +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 + - euro36 : 640x200, 15 kHz, 72 Hz + - euro36-lace : 640x400, 15 kHz, 72 Hz interlaced + - euro72 : 640x400, 29 kHz, 68 Hz + - euro72-lace : 640x800, 29 kHz, 68 Hz interlaced + - super72 : 800x300, 23 kHz, 70 Hz + - super72-lace : 800x600, 23 kHz, 70 Hz interlaced + - dblntsc-ff : 640x400, 27 kHz, 57 Hz + - dblntsc-lace : 640x800, 27 kHz, 57 Hz interlaced + - dblpal-ff : 640x512, 27 kHz, 47 Hz + - 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 + +Please notice that the ECS and VGA modes require either an ECS or AGA +chipset, and that these modes are limited to 2-bit color for the ECS +chipset and 8-bit color for the AGA chipset. + +5.1.2) depth +------------ + +:Syntax: depth: + +Specify the number of bit-planes for the selected video-mode. + +5.1.3) inverse +-------------- + +Use inverted display (black on white). Functionally the same as the +"inverse" sub-option for the Atari. + +5.1.4) 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 +rows. + +5.1.5) 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 +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). + + +5.2) fd_def_df0= +---------------- + +:Syntax: fd_def_df0= + +Sets the df0 value for "silent" floppy drives. The value should be in +hexadecimal with "0x" prefix. + + +5.3) wd33c93= +------------- + +:Syntax: wd33c93= + +These options affect the A590/A2091, A3000 and GVP Series II SCSI +controllers. + +The is a comma-separated list of the sub-options listed +below. + +5.3.1) nosync +------------- + +:Syntax: nosync:bitmask + +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 +"wd33c93=nosync:0xff". The default is to disable sync negotiation for +all devices, eg. nosync:0xff. + +5.3.2) period +------------- + +:Syntax: period:ns + +`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 + +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 + +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 + +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 +hostadapter and the SCSI-clock jumper present on some GVP +hostadapters. + +5.3.6) next +----------- + +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 + +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 +using DMA to chip memory. The default is 0, i.e. to use DMA if +possible. + + +5.4) gvp11= +----------- + +:Syntax: gvp11= + +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 +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 +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 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. diff --git a/Documentation/m68k/kernel-options.txt b/Documentation/m68k/kernel-options.txt deleted file mode 100644 index 79d21246c75a..000000000000 --- a/Documentation/m68k/kernel-options.txt +++ /dev/null @@ -1,884 +0,0 @@ - - - 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 -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 -incomplete or missing. Please update the information and send in the -patches. - - -1) Overview of the Kernel's Option Processing -============================================= - -The kernel knows three kinds of options on its command line: - - 1) kernel options - 2) environment settings - 3) arguments for init - -To which of these classes an argument belongs is determined as -follows: If the option is known to the kernel itself, i.e. if the name -(the part before the '=') or, in some cases, the whole argument string -is known to the kernel, it belongs to class 1. Otherwise, if the -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 -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 -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 -subdivided. - - -2) General Kernel Options -========================= - -2.1) 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 -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: - - /dev/ram: -> 0x0100 (initial ramdisk) - /dev/hda: -> 0x0300 (first IDE disk) - /dev/hdb: -> 0x0340 (second IDE disk) - /dev/sda: -> 0x0800 (first SCSI disk) - /dev/sdb: -> 0x0810 (second SCSI disk) - /dev/sdc: -> 0x0820 (third SCSI disk) - /dev/sdd: -> 0x0830 (forth SCSI disk) - /dev/sde: -> 0x0840 (fifth SCSI disk) - /dev/fd : -> 0x0200 (floppy disk) - - 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 -initial ramdisk loaded by your bootstrap program (please consult the -instructions for your bootstrap program to find out how to load an -initial ramdisk). As of kernel version 2.0.18 you must specify -/dev/ram as the root device if you want to boot from an initial -ramdisk. For the floppy devices, /dev/fd, the number stands for the -floppy drive number (there are no partitions on floppy disks). I.e., -/dev/fd0 stands for the first drive, /dev/fd1 for the second, and so -on. Since the number is just added, you can also force the disk format -by adding a number greater than 3. If you look into your /dev -directory, use can see the /dev/fd0D720 has major 2 and minor 16. You -can specify this device for the root FS by writing "root=/dev/fd16" on -the kernel command line. - -[Strange and maybe uninteresting stuff ON] - - 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 -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 -/dev/sde are in the table above, but not /dev/sdf. Although, you can -use the sixth SCSI disk for the root FS, but you have to specify the -device by number... (see below). Or, even more strange, you can use the -fact that there is no range checking of the partition number, and your -knowledge that each disk uses 16 minors, and write "root=/dev/sde17" -(for /dev/sdf1). - -[Strange and maybe uninteresting stuff OFF] - - 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 -SCSI CD-ROM drive, you boot from it by "root=0b00". Here, hex "0b" = -decimal 11 is the major of SCSI CD-ROMs, and the minor 0 stands for -the first of these. You can find out all valid major numbers by -looking into include/linux/major.h. - -In addition to major and minor numbers, if the device containing your -root partition uses a partition table format with unique partition -identifiers, then you may use them. For instance, -"root=PARTUUID=00112233-4455-6677-8899-AABBCCDDEEFF". It is also -possible to reference another partition on the same device using a -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 -"Documentation/admin-guide/kernel-parameters.rst". - - -2.2) ro, 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 -for ramdisks, which default to read-write. - - -2.3) 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 -selectable by dmesg is 8. - - -2.4) debug= ------------ - -Syntax: debug= - -This option causes certain kernel messages be printed to the selected -debugging device. This can aid debugging the kernel, since the -messages can be captured and analyzed on some other machine. Which -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 -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 -dumps, the kernel sets the log level to 10 automatically. A level of -at least 8 can also be set by the "debug" command line option (see -2.3) and at run time with "dmesg -n 8". - -Devices possible for Amiga: - - - "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 - This is "ser2" for a Falcon, and "ser1" for any other machine - - "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 - seconds. - - -2.6) ramdisk_size= -------------- - -Syntax: ramdisk_size= - - 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 -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= -2.8) buff= ------------ - - I can't find any sign of these options in 2.2.6. - - -3) General Device Options (Amiga and Atari) -=========================================== - -3.1) ether= ------------ - -Syntax: ether=[[,[,[,]]]], - - 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 -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 -for Linux/m68k. - - -3.2) hd= --------- - -Syntax: 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 -itself. It exists just for the case that this fails for one of your -disks. - - -3.3) max_scsi_luns= -------------------- - -Syntax: max_scsi_luns= - - 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. - - -3.4) st= --------- - -Syntax: st=,[,[]] - - 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 -total number of buffers. limits the total number of -buffers allocated for all tape devices. - - -3.5) dmasound= --------------- - -Syntax: dmasound=[,[,]] - - 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 -how much percent of error will be tolerated when setting a frequency -(maximum 10, default 0). For example with 3% you can play 8000Hz -AU-Files on the Falcon with its hardware frequency of 8195Hz and thus -don't need to expand the sound. - - - -4) Options for Atari Only -========================= - -4.1) video= ------------ - -Syntax: video=: - -The parameter specifies the name of the frame buffer, -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 - 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. - -4.1.1) Video Mode ------------------ - -This sub-option may be any of the predefined video modes, as listed -in atari/atafb.c in the Linux/m68k source tree. The kernel will -activate the given video mode at boot time and make it the default -mode, if the hardware allows. Currently defined names are: - - - stlow : 320x200x4 - - stmid, default5 : 640x200x2 - - sthigh, default4: 640x400x1 - - ttlow : 320x480x8, TT only - - ttmid, default1 : 640x480x4, TT only - - tthigh, default2: 1280x960x1, TT only - - vga2 : 640x480x1, Falcon only - - vga4 : 640x480x2, Falcon only - - vga16, default3 : 640x480x4, Falcon only - - vga256 : 640x480x8, Falcon only - - falh2 : 896x608x1, Falcon only - - falh16 : 896x608x4, Falcon only - - 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 -activated by a "external:" sub-option. - -4.1.2) inverse --------------- - -Invert the display. This affects both, text (consoles) and graphics -(X) display. Usually, the background is chosen to be black. With this -option, you can make the background white. - -4.1.3) 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 -vertical size of the display is less than 400 pixel rows. Otherwise, the -`VGA8x16' font is the default. - -4.1.4) hwscroll_ ----------------- - -Syntax: hwscroll_ - -The number of additional lines of video memory to reserve for -speeding up the scrolling ("hardware scrolling"). Hardware scrolling -is possible only if the kernel can set the video base address in steps -fine enough. This is true for STE, MegaSTE, TT, and Falcon. It is not -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 -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. - -4.1.5) 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 -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. -For this, see the "sw_*" options below. - -4.1.6) external: ----------------- - -Syntax: - external:;;;;[;[;\ - [;[;[;]]]]] - -[I had to break this line...] - - 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 -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: , - 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 -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 - 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 - -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 - - 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 -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 -with the external driver, because the kernel cannot set the video base -address), or for virtual resolutions under X (which the X server -doesn't support yet). So, it's currently best to leave this field -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 -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 -address of the VGA register set, so it can change the color lookup -table. You have to look up this address in your board's documentation. -To avoid misunderstandings: is the _base_ address, i.e. a 4k -aligned address. For read/writing the color registers, the kernel -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 -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 -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, -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, -therefore we don't support hardware-dependent functions like hardware-scroll, -panning or blanking. - -4.1.7) eclock: --------------- - -The external pixel clock attached to the Falcon VIDEL shifter. This -currently works only with the ScreenWonder! - -4.1.8) 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 -your monitor can work with, in Hz. and are the same for -the horizontal frequency, in kHz. - - The defaults are 58;62;31;32 (VGA compatible). - - The defaults for TV/SC1224/SC1435 cover both PAL and NTSC standards. - -4.1.9) keep ------------- - -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 -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 -the Falcon. - - -4.2) atamouse= --------------- - -Syntax: atamouse=,[] - - 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 -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. - - -4.3) 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 - probed (see also below). The default is 1 (HD). Only one drive type - can be selected. If you have two disk drives, select the "better" - type. - - The second parameter tells the kernel whether to use - track buffering (1) or not (0). The default is machine-dependent: - 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. - - -4.4) atascsi= -------------- - -Syntax: atascsi=[,[,[,[,]]]] - - 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. -Below, defaults are noted as n/m, where the first value refers to -TT-SCSI and the latter to Falcon-SCSI. If an illegal value is given -for one parameter, an error message is printed and that one setting is -ignored (others aren't affected). - - : - This is the maximum number of SCSI commands queued internally to the - Atari SCSI driver. A value of 1 effectively turns off the driver - internal multitasking (if it causes problems). Legal values are >= - 1. can be as high as you like, but values greater than - times the number of SCSI targets (LUNs) you have - don't make sense. Default: 16/8. - - : - Maximum number of SCSI commands issued to the driver for one - logical unit (LUN, usually one SCSI target). Legal values start - from 1. If tagged queuing (see below) is not used, values greater - than 2 don't make sense, but waste memory. Otherwise, the maximum - is the number of command tags available to the driver (currently - 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 - 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 - - : - Size of the scatter-gather table, i.e. the number of requests - consecutive on the disk that can be merged into one SCSI command. - Legal values are between 0 and 255. Default: 255/0. Note: This - value is forced to 0 on a Falcon, since scatter-gather isn't - possible with the ST-DMA. Not using scatter-gather hurts - performance significantly. - - : - The SCSI ID to be used by the initiator (your Atari). This is - usually 7, the highest possible ID. Every ID on the SCSI bus must - be unique. Default: determined at run time: If the NV-RAM checksum - is valid, and bit 7 in byte 30 of the NV-RAM is set, the lower 3 - bits of this byte are used as the host ID. (This method is defined - by Atari and also used by some TOS HD drivers.) If the above - isn't given, the default ID is 7. (both, TT and Falcon). - - : - 0 means turn off tagged queuing support, all other values > 0 mean - use tagged queuing for targets that support it. Default: currently - off, but this may change when tagged queuing handling has been - proved to be reliable. - - Tagged queuing means that more than one command can be issued to - one LUN, and the SCSI device itself orders the requests so they - can be performed in optimal order. Not all SCSI devices support - tagged queuing (:-(). - -4.5 switches= -------------- - -Syntax: switches= - - 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 -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 - -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 -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 -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 -switching-off on reset still happens in this case. - -5) Options for Amiga Only: -========================== - -5.1) video= ------------ - -Syntax: video=: - -The parameter specifies the name of the frame buffer, valid -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 -option. - -The is a comma-separated list of the sub-options listed -below. This option is organized similar to the Atari version of the -"video"-option (4.1), but knows fewer sub-options. - -5.1.1) video mode ------------------ - -Again, similar to the video mode for the Atari (see 4.1.1). Predefined -modes depend on the used frame buffer device. - -OCS, ECS and AGA machines all use the color frame buffer. The following -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 - - euro36 : 640x200, 15 kHz, 72 Hz - - euro36-lace : 640x400, 15 kHz, 72 Hz interlaced - - euro72 : 640x400, 29 kHz, 68 Hz - - euro72-lace : 640x800, 29 kHz, 68 Hz interlaced - - super72 : 800x300, 23 kHz, 70 Hz - - super72-lace : 800x600, 23 kHz, 70 Hz interlaced - - dblntsc-ff : 640x400, 27 kHz, 57 Hz - - dblntsc-lace : 640x800, 27 kHz, 57 Hz interlaced - - dblpal-ff : 640x512, 27 kHz, 47 Hz - - 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 - -Please notice that the ECS and VGA modes require either an ECS or AGA -chipset, and that these modes are limited to 2-bit color for the ECS -chipset and 8-bit color for the AGA chipset. - -5.1.2) depth ------------- - -Syntax: depth: - -Specify the number of bit-planes for the selected video-mode. - -5.1.3) inverse --------------- - -Use inverted display (black on white). Functionally the same as the -"inverse" sub-option for the Atari. - -5.1.4) 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 -rows. - -5.1.5) 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 -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). - - -5.2) fd_def_df0= ----------------- - -Syntax: fd_def_df0= - -Sets the df0 value for "silent" floppy drives. The value should be in -hexadecimal with "0x" prefix. - - -5.3) wd33c93= -------------- - -Syntax: wd33c93= - -These options affect the A590/A2091, A3000 and GVP Series II SCSI -controllers. - -The is a comma-separated list of the sub-options listed -below. - -5.3.1) nosync -------------- - -Syntax: nosync:bitmask - - 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 -"wd33c93=nosync:0xff". The default is to disable sync negotiation for -all devices, eg. nosync:0xff. - -5.3.2) period -------------- - -Syntax: period:ns - - `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 - - 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 - - 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 - - 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 -hostadapter and the SCSI-clock jumper present on some GVP -hostadapters. - -5.3.6) next ------------ - - 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 - - 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 -using DMA to chip memory. The default is 0, i.e. to use DMA if -possible. - - -5.4) gvp11= ------------ - -Syntax: gvp11= - - 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 -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 -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 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: */ -- cgit v1.2.3-55-g7522 From 01c0aa794305ae08eb977d0719e43577e93f9ef5 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sun, 14 Apr 2019 08:37:58 -0300 Subject: 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.rst | 27 +++++++++++++++++++++++++++ Documentation/cma/debugfs.txt | 21 --------------------- 2 files changed, 27 insertions(+), 21 deletions(-) create mode 100644 Documentation/cma/debugfs.rst delete mode 100644 Documentation/cma/debugfs.txt diff --git a/Documentation/cma/debugfs.rst b/Documentation/cma/debugfs.rst new file mode 100644 index 000000000000..518fe401b5ee --- /dev/null +++ b/Documentation/cma/debugfs.rst @@ -0,0 +1,27 @@ +: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. + +Each CMA zone represents a directory under /cma/, indexed by the +kernel's CMA index. So the first CMA zone would be: + + /cma/cma-0 + +The structure of the files created under that directory is as follows: + + - [RO] base_pfn: The base PFN (Page Frame Number) of the zone. + - [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:: + + echo 5 > /cma/cma-2/alloc + +would try to allocate 5 pages from the cma-2 area. + + - [WO] free: Free N pages from that CMA area, similar to the above. diff --git a/Documentation/cma/debugfs.txt b/Documentation/cma/debugfs.txt deleted file mode 100644 index 6cef20a8cedc..000000000000 --- a/Documentation/cma/debugfs.txt +++ /dev/null @@ -1,21 +0,0 @@ -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. - -Each CMA zone represents a directory under /cma/, indexed by the -kernel's CMA index. So the first CMA zone would be: - - /cma/cma-0 - -The structure of the files created under that directory is as follows: - - - [RO] base_pfn: The base PFN (Page Frame Number) of the zone. - - [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: - - echo 5 > /cma/cma-2/alloc - -would try to allocate 5 pages from the cma-2 area. - - - [WO] free: Free N pages from that CMA area, similar to the above. -- cgit v1.2.3-55-g7522 From 8db8acee4b326bfd5bc9a164a7f9ef844ec0fd2e Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sun, 14 Apr 2019 08:44:17 -0300 Subject: 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 --- Documentation/console/console.rst | 152 ++++++++++++++++++++++++++++++++++++++ Documentation/console/console.txt | 145 ------------------------------------ Documentation/fb/fbcon.rst | 4 +- drivers/tty/Kconfig | 2 +- 4 files changed, 155 insertions(+), 148 deletions(-) create mode 100644 Documentation/console/console.rst delete mode 100644 Documentation/console/console.txt diff --git a/Documentation/console/console.rst b/Documentation/console/console.rst new file mode 100644 index 000000000000..b374141b027e --- /dev/null +++ b/Documentation/console/console.rst @@ -0,0 +1,152 @@ +:orphan: + +=============== +Console Drivers +=============== + +The Linux kernel has 2 general types of console drivers. The first type is +assigned by the kernel to all the virtual consoles during the boot process. +This type will be called 'system driver', and only one system driver is allowed +to exist. The system driver is persistent and it can never be unloaded, though +it may become inactive. + +The second type has to be explicitly loaded and unloaded. This will be called +'modular driver' by this document. Multiple modular drivers can coexist at +any time with each driver sharing the console with other drivers including +the system driver. However, modular drivers cannot take over the console +that is currently occupied by another modular driver. (Exception: Drivers that +call do_take_over_console() will succeed in the takeover regardless of the type +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:: + + 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:: + + 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:: + + ls /sys/class/vtconsole + . .. vtcon0 vtcon1 + +Each directory in /sys/class/vtconsole has 3 files:: + + ls /sys/class/vtconsole/vtcon0 + . .. bind name uevent + +What do these files signify? + + 1. bind - this is a read/write file. It shows the status of the driver if + 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 + to unbind + + 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:: + + 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 + + 'VGA+' is the name of the driver + + 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. + + 3. uevent - ignore this file + +When unbinding, the modular driver is detached first, and then the system +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:: + + 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. + +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 +driver, make changes, recompile, reload and rebind the driver without any need +for rebooting the kernel. For regular users who may want to switch from +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 +==================== + +do_take_over_console() is now broken up into:: + + do_register_con_driver() + do_bind_con_driver() - private function + +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 +===================================== + +In order for binding to and unbinding from the console to properly work, +console drivers must follow these guidelines: + +1. All drivers, except system drivers, must call either do_register_con_driver() + or do_take_over_console(). do_register_con_driver() will just add the driver + to the console's internal list. It won't take over the + console. do_take_over_console(), as it name implies, will also take over (or + bind to) the console. + +2. All resources allocated during con->con_init() must be released in + con->con_deinit(). + +3. All resources allocated in con->con_startup() must be released when the + driver, which was previously bound, becomes unbound. The console layer + does not have a complementary call to con->con_startup() so it's up to the + driver to check when it's legal to release these resources. Calling + con_is_bound() in con->con_deinit() will help. If the call returned + false(), then it's safe to release the resources. This balance has to be + ensured because con->con_startup() can be called again when a request to + rebind the driver to the console arrives. + +4. Upon exit of the driver, ensure that the driver is totally unbound. If the + condition is satisfied, then the driver must call do_unregister_con_driver() + or give_up_console(). + +5. do_unregister_con_driver() can also be called on conditions which make it + impossible for the driver to service console requests. This can happen + with the framebuffer console that suddenly lost all of its drivers. + +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/console/console.txt b/Documentation/console/console.txt deleted file mode 100644 index d73c2ab4beda..000000000000 --- a/Documentation/console/console.txt +++ /dev/null @@ -1,145 +0,0 @@ -Console Drivers -=============== - -The Linux kernel has 2 general types of console drivers. The first type is -assigned by the kernel to all the virtual consoles during the boot process. -This type will be called 'system driver', and only one system driver is allowed -to exist. The system driver is persistent and it can never be unloaded, though -it may become inactive. - -The second type has to be explicitly loaded and unloaded. This will be called -'modular driver' by this document. Multiple modular drivers can coexist at -any time with each driver sharing the console with other drivers including -the system driver. However, modular drivers cannot take over the console -that is currently occupied by another modular driver. (Exception: Drivers that -call do_take_over_console() will succeed in the takeover regardless of the type -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: - - 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: - - 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: - - ls /sys/class/vtconsole - . .. vtcon0 vtcon1 - -Each directory in /sys/class/vtconsole has 3 files: - - ls /sys/class/vtconsole/vtcon0 - . .. bind name uevent - -What do these files signify? - - 1. bind - this is a read/write file. It shows the status of the driver if - 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 - to unbind - - 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: - - 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 - - 'VGA+' is the name of the driver - - 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. - - 3. uevent - ignore this file - -When unbinding, the modular driver is detached first, and then the system -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: - -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. - -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 -driver, make changes, recompile, reload and rebind the driver without any need -for rebooting the kernel. For regular users who may want to switch from -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: -===================== - -do_take_over_console() is now broken up into: - - do_register_con_driver() - do_bind_con_driver() - private function - -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: -===================================== - -In order for binding to and unbinding from the console to properly work, -console drivers must follow these guidelines: - -1. All drivers, except system drivers, must call either do_register_con_driver() - or do_take_over_console(). do_register_con_driver() will just add the driver - to the console's internal list. It won't take over the - console. do_take_over_console(), as it name implies, will also take over (or - bind to) the console. - -2. All resources allocated during con->con_init() must be released in - con->con_deinit(). - -3. All resources allocated in con->con_startup() must be released when the - driver, which was previously bound, becomes unbound. The console layer - does not have a complementary call to con->con_startup() so it's up to the - driver to check when it's legal to release these resources. Calling - con_is_bound() in con->con_deinit() will help. If the call returned - false(), then it's safe to release the resources. This balance has to be - ensured because con->con_startup() can be called again when a request to - rebind the driver to the console arrives. - -4. Upon exit of the driver, ensure that the driver is totally unbound. If the - condition is satisfied, then the driver must call do_unregister_con_driver() - or give_up_console(). - -5. do_unregister_con_driver() can also be called on conditions which make it - impossible for the driver to service console requests. This can happen - with the framebuffer console that suddenly lost all of its drivers. - -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 . -- cgit v1.2.3-55-g7522 From 93d2c159673325624ef3f2d14ededfcdf76f948b Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sun, 14 Apr 2019 08:50:59 -0300 Subject: 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; -- cgit v1.2.3-55-g7522 From 0d07cf5e53a21e35289adc3ab99b6804ff0c3833 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sun, 14 Apr 2019 08:58:05 -0300 Subject: 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 --- Documentation/early-userspace/README | 151 -------------------- Documentation/early-userspace/buffer-format.rst | 119 ++++++++++++++++ Documentation/early-userspace/buffer-format.txt | 112 --------------- .../early-userspace/early_userspace_support.rst | 154 +++++++++++++++++++++ Documentation/early-userspace/index.rst | 18 +++ Documentation/filesystems/nfs/nfsroot.txt | 2 +- .../filesystems/ramfs-rootfs-initramfs.txt | 4 +- usr/Kconfig | 2 +- 8 files changed, 295 insertions(+), 267 deletions(-) delete mode 100644 Documentation/early-userspace/README create mode 100644 Documentation/early-userspace/buffer-format.rst delete mode 100644 Documentation/early-userspace/buffer-format.txt create mode 100644 Documentation/early-userspace/early_userspace_support.rst create mode 100644 Documentation/early-userspace/index.rst diff --git a/Documentation/early-userspace/README b/Documentation/early-userspace/README deleted file mode 100644 index 955d667dc87e..000000000000 --- a/Documentation/early-userspace/README +++ /dev/null @@ -1,151 +0,0 @@ -Early userspace support -======================= - -Last update: 2004-12-20 tlh - - -"Early userspace" is a set of libraries and programs that provide -various pieces of functionality that are important enough to be -available while a Linux kernel is coming up, but that don't need to be -run inside the kernel itself. - -It consists of several major infrastructure components: - -- gen_init_cpio, a program that builds a cpio-format archive - containing a root filesystem image. This archive is compressed, and - the compressed image is linked into the kernel image. -- initramfs, a chunk of code that unpacks the compressed cpio image - midway through the kernel boot process. -- klibc, a userspace C library, currently packaged separately, that is - optimized for correctness and small size. - -The cpio file format used by initramfs is the "newc" (aka "cpio -H newc") -format, and is documented in the file "buffer-format.txt". There are -two ways to add an early userspace image: specify an existing cpio -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 -will be used directly. Only a single cpio file may be specified in -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 -a way to create images with root-owned files even though the image was -built by an unprivileged user. - -The image is specified as one or more sources in -CONFIG_INITRAMFS_SOURCE. Sources can be either directories or files - -cpio archives are *not* allowed when building from sources. - -A source directory will have it and all of its contents packaged. The -specified directory name will be mapped to '/'. When packaging a -directory, limited user and group ID translation can be performed. -INITRAMFS_ROOT_UID can be set to a user ID that needs to be mapped to -user root (0). INITRAMFS_ROOT_GID can be set to a group ID that needs -to be mapped to group root (0). - -A source file must be directives in the format required by the -usr/gen_init_cpio utility (run 'usr/gen_init_cpio -h' to get the -file format). The directives in the file will be passed directly to -usr/gen_init_cpio. - -When a combination of directories and files are specified then the -initramfs image will be an aggregate of all of them. In this way a user -can create a 'root-image' directory and install all files into it. -Because device-special files cannot be created by a unprivileged user, -special files can be listed in a 'root-files' file. Both 'root-image' -and 'root-files' can be listed in CONFIG_INITRAMFS_SOURCE and a complete -early userspace image can be built by an unprivileged user. - -As a technical note, when directories and files are specified, the -entire CONFIG_INITRAMFS_SOURCE is passed to -usr/gen_initramfs_list.sh. This means that CONFIG_INITRAMFS_SOURCE -can really be interpreted as any legal argument to -gen_initramfs_list.sh. If a directory is specified as an argument then -the contents are scanned, uid/gid translation is performed, and -usr/gen_init_cpio file directives are output. If a directory is -specified as an argument to usr/gen_initramfs_list.sh then the -contents of the file are simply copied to the output. All of the output -directives from directory scanning and file contents copying are -processed by usr/gen_init_cpio. - -See also 'usr/gen_initramfs_list.sh -h'. - -Where's this all leading? -========================= - -The klibc distribution contains some of the necessary software to make -early userspace useful. The klibc distribution is currently -maintained separately from the kernel. - -You can obtain somewhat infrequent snapshots of klibc from -https://www.kernel.org/pub/linux/libs/klibc/ - -For active users, you are better off using the klibc git -repository, at http://git.kernel.org/?p=libs/klibc/klibc.git - -The standalone klibc distribution currently provides three components, -in addition to the klibc library: - -- ipconfig, a program that configures network interfaces. It can - configure them statically, or use DHCP to obtain information - dynamically (aka "IP autoconfiguration"). -- nfsmount, a program that can mount an NFS filesystem. -- kinit, the "glue" that uses ipconfig and nfsmount to replace the old - support for IP autoconfig, mount a filesystem over NFS, and continue - system boot using that filesystem as root. - -kinit is built as a single statically linked binary to save space. - -Eventually, several more chunks of kernel functionality will hopefully -move to early userspace: - -- Almost all of init/do_mounts* (the beginning of this is already in - place) -- ACPI table parsing -- Insert unwieldy subsystem that doesn't really need to be in kernel - space here - -If kinit doesn't meet your current needs and you've got bytes to burn, -the klibc distribution includes a small Bourne-compatible shell (ash) -and a number of other utilities, so you can replace kinit and build -custom initramfs images that meet your needs exactly. - -For questions and help, you can sign up for the early userspace -mailing list at http://www.zytor.com/mailman/listinfo/klibc - -How does it work? -================= - -The kernel has currently 3 ways to mount the root filesystem: - -a) all required device and filesystem drivers compiled into the kernel, no - initrd. init/main.c:init() will call prepare_namespace() to mount the - final root filesystem, based on the root= option and optional init= to run - some other init binary than listed at the end of init/main.c:init(). - -b) some device and filesystem drivers built as modules and stored in an - initrd. The initrd must contain a binary '/linuxrc' which is supposed to - load these driver modules. It is also possible to mount the final root - filesystem via linuxrc and use the pivot_root syscall. The initrd is - mounted and executed via prepare_namespace(). - -c) using initramfs. The call to prepare_namespace() must be skipped. - This means that a binary must do all the work. Said binary can be stored - into initramfs either via modifying usr/gen_init_cpio.c or via the new - initrd format, an cpio archive. It must be called "/init". This binary - is responsible to do all the things prepare_namespace() would do. - - To maintain backwards compatibility, the /init binary will only run if it - comes via an initramfs cpio archive. If this is not the case, - init/main.c:init() will run prepare_namespace() to mount the final root - and exec one of the predefined init binaries. - -Bryan O'Sullivan diff --git a/Documentation/early-userspace/buffer-format.rst b/Documentation/early-userspace/buffer-format.rst new file mode 100644 index 000000000000..7f74e301fdf3 --- /dev/null +++ b/Documentation/early-userspace/buffer-format.rst @@ -0,0 +1,119 @@ +======================= +initramfs buffer format +======================= + +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" +(initramfs) protocol. The initramfs contents is passed using the same +memory buffer protocol used by the initrd protocol, but the contents +is different. The initramfs buffer contains an archive which is +expanded into a ramfs filesystem; this document details the format of +the initramfs buffer format. + +The initramfs buffer format is based around the "newc" or "crc" CPIO +formats, and can be created with the cpio(1) utility. The cpio +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:: + + * is used to indicate "0 or more occurrences of" + (|) indicates alternatives + + indicates concatenation + GZIP() indicates the gzip(1) of the operand + ALGN(n) means padding with null bytes to an n-byte boundary + + initramfs := ("\0" | cpio_archive | cpio_gzip_archive)* + + cpio_gzip_archive := GZIP(cpio_archive) + + cpio_archive := cpio_file* + ( | cpio_trailer) + + cpio_file := ALGN(4) + cpio_header + filename + "\0" + ALGN(4) + data + + cpio_trailer := ALGN(4) + cpio_header + "TRAILER!!!\0" + ALGN(4) + + +In human terms, the initramfs buffer contains a collection of +compressed and/or uncompressed cpio archives (in the "newc" or "crc" +formats); arbitrary amounts zero bytes (for padding) can be added +between members. + +The cpio "TRAILER!!!" entry (cpio end-of-archive) is optional, but is +not ignored; see "handling of hard links" below. + +The structure of the cpio_header is as follows (all fields contain +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 +c_uid 8 bytes File uid +c_gid 8 bytes File gid +c_nlink 8 bytes Number of links +c_mtime 8 bytes Modification time +c_filesize 8 bytes Size of data field +c_maj 8 bytes Major part of file device number +c_min 8 bytes Minor part of file device number +c_rmaj 8 bytes Major part of device node reference +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. + +The c_filesize should be zero for any file which is not a regular file +or symlink. + +The c_chksum field contains a simple 32-bit unsigned sum of all the +bytes in the data field. cpio(1) refers to this as "crc", which is +clearly incorrect (a cyclic redundancy check is a different and +significantly stronger integrity check), however, this is the +algorithm used. + +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 +====================== + +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 +the tuple buffer and the entry is created as usual; if found, a hard +link rather than a second copy of the file is created. It is not +necessary (but permitted) to include a second copy of the file +contents; if the file contents is not included, the c_filesize field +should be set to zero to indicate no data section follows. If data is +present, the previous instance of the file is overwritten; this allows +the data-carrying instance of a file to occur anywhere in the sequence +(GNU cpio is reported to attach the data to the last instance of a +file only.) + +c_filesize must not be zero for a symlink. + +When a "TRAILER!!!" end-of-archive marker is seen, the tuple buffer is +reset. This permits archives which are generated independently to be +concatenated. + +To combine file data from different sources (without having to +regenerate the (c_maj,c_min,c_ino) fields), therefore, either one of +the following techniques can be used: + +a) Separate the different file data sources with a "TRAILER!!!" + end-of-archive marker, or + +b) Make sure c_nlink == 1 for all nondirectory entries. diff --git a/Documentation/early-userspace/buffer-format.txt b/Documentation/early-userspace/buffer-format.txt deleted file mode 100644 index e1fd7f9dad16..000000000000 --- a/Documentation/early-userspace/buffer-format.txt +++ /dev/null @@ -1,112 +0,0 @@ - initramfs buffer format - ----------------------- - - 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" -(initramfs) protocol. The initramfs contents is passed using the same -memory buffer protocol used by the initrd protocol, but the contents -is different. The initramfs buffer contains an archive which is -expanded into a ramfs filesystem; this document details the format of -the initramfs buffer format. - -The initramfs buffer format is based around the "newc" or "crc" CPIO -formats, and can be created with the cpio(1) utility. The cpio -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: - * is used to indicate "0 or more occurrences of" - (|) indicates alternatives - + indicates concatenation - GZIP() indicates the gzip(1) of the operand - ALGN(n) means padding with null bytes to an n-byte boundary - - initramfs := ("\0" | cpio_archive | cpio_gzip_archive)* - - cpio_gzip_archive := GZIP(cpio_archive) - - cpio_archive := cpio_file* + ( | cpio_trailer) - - cpio_file := ALGN(4) + cpio_header + filename + "\0" + ALGN(4) + data - - cpio_trailer := ALGN(4) + cpio_header + "TRAILER!!!\0" + ALGN(4) - - -In human terms, the initramfs buffer contains a collection of -compressed and/or uncompressed cpio archives (in the "newc" or "crc" -formats); arbitrary amounts zero bytes (for padding) can be added -between members. - -The cpio "TRAILER!!!" entry (cpio end-of-archive) is optional, but is -not ignored; see "handling of hard links" below. - -The structure of the cpio_header is as follows (all fields contain -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 -c_uid 8 bytes File uid -c_gid 8 bytes File gid -c_nlink 8 bytes Number of links -c_mtime 8 bytes Modification time -c_filesize 8 bytes Size of data field -c_maj 8 bytes Major part of file device number -c_min 8 bytes Minor part of file device number -c_rmaj 8 bytes Major part of device node reference -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. - -The c_filesize should be zero for any file which is not a regular file -or symlink. - -The c_chksum field contains a simple 32-bit unsigned sum of all the -bytes in the data field. cpio(1) refers to this as "crc", which is -clearly incorrect (a cyclic redundancy check is a different and -significantly stronger integrity check), however, this is the -algorithm used. - -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 - -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 -the tuple buffer and the entry is created as usual; if found, a hard -link rather than a second copy of the file is created. It is not -necessary (but permitted) to include a second copy of the file -contents; if the file contents is not included, the c_filesize field -should be set to zero to indicate no data section follows. If data is -present, the previous instance of the file is overwritten; this allows -the data-carrying instance of a file to occur anywhere in the sequence -(GNU cpio is reported to attach the data to the last instance of a -file only.) - -c_filesize must not be zero for a symlink. - -When a "TRAILER!!!" end-of-archive marker is seen, the tuple buffer is -reset. This permits archives which are generated independently to be -concatenated. - -To combine file data from different sources (without having to -regenerate the (c_maj,c_min,c_ino) fields), therefore, either one of -the following techniques can be used: - -a) Separate the different file data sources with a "TRAILER!!!" - end-of-archive marker, or - -b) Make sure c_nlink == 1 for all nondirectory entries. diff --git a/Documentation/early-userspace/early_userspace_support.rst b/Documentation/early-userspace/early_userspace_support.rst new file mode 100644 index 000000000000..3deefb34046b --- /dev/null +++ b/Documentation/early-userspace/early_userspace_support.rst @@ -0,0 +1,154 @@ +======================= +Early userspace support +======================= + +Last update: 2004-12-20 tlh + + +"Early userspace" is a set of libraries and programs that provide +various pieces of functionality that are important enough to be +available while a Linux kernel is coming up, but that don't need to be +run inside the kernel itself. + +It consists of several major infrastructure components: + +- gen_init_cpio, a program that builds a cpio-format archive + containing a root filesystem image. This archive is compressed, and + the compressed image is linked into the kernel image. +- initramfs, a chunk of code that unpacks the compressed cpio image + midway through the kernel boot process. +- klibc, a userspace C library, currently packaged separately, that is + optimized for correctness and small size. + +The cpio file format used by initramfs is the "newc" (aka "cpio -H newc") +format, and is documented in the file "buffer-format.txt". There are +two ways to add an early userspace image: specify an existing cpio +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 +will be used directly. Only a single cpio file may be specified in +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 +a way to create images with root-owned files even though the image was +built by an unprivileged user. + +The image is specified as one or more sources in +CONFIG_INITRAMFS_SOURCE. Sources can be either directories or files - +cpio archives are *not* allowed when building from sources. + +A source directory will have it and all of its contents packaged. The +specified directory name will be mapped to '/'. When packaging a +directory, limited user and group ID translation can be performed. +INITRAMFS_ROOT_UID can be set to a user ID that needs to be mapped to +user root (0). INITRAMFS_ROOT_GID can be set to a group ID that needs +to be mapped to group root (0). + +A source file must be directives in the format required by the +usr/gen_init_cpio utility (run 'usr/gen_init_cpio -h' to get the +file format). The directives in the file will be passed directly to +usr/gen_init_cpio. + +When a combination of directories and files are specified then the +initramfs image will be an aggregate of all of them. In this way a user +can create a 'root-image' directory and install all files into it. +Because device-special files cannot be created by a unprivileged user, +special files can be listed in a 'root-files' file. Both 'root-image' +and 'root-files' can be listed in CONFIG_INITRAMFS_SOURCE and a complete +early userspace image can be built by an unprivileged user. + +As a technical note, when directories and files are specified, the +entire CONFIG_INITRAMFS_SOURCE is passed to +usr/gen_initramfs_list.sh. This means that CONFIG_INITRAMFS_SOURCE +can really be interpreted as any legal argument to +gen_initramfs_list.sh. If a directory is specified as an argument then +the contents are scanned, uid/gid translation is performed, and +usr/gen_init_cpio file directives are output. If a directory is +specified as an argument to usr/gen_initramfs_list.sh then the +contents of the file are simply copied to the output. All of the output +directives from directory scanning and file contents copying are +processed by usr/gen_init_cpio. + +See also 'usr/gen_initramfs_list.sh -h'. + +Where's this all leading? +========================= + +The klibc distribution contains some of the necessary software to make +early userspace useful. The klibc distribution is currently +maintained separately from the kernel. + +You can obtain somewhat infrequent snapshots of klibc from +https://www.kernel.org/pub/linux/libs/klibc/ + +For active users, you are better off using the klibc git +repository, at http://git.kernel.org/?p=libs/klibc/klibc.git + +The standalone klibc distribution currently provides three components, +in addition to the klibc library: + +- ipconfig, a program that configures network interfaces. It can + configure them statically, or use DHCP to obtain information + dynamically (aka "IP autoconfiguration"). +- nfsmount, a program that can mount an NFS filesystem. +- kinit, the "glue" that uses ipconfig and nfsmount to replace the old + support for IP autoconfig, mount a filesystem over NFS, and continue + system boot using that filesystem as root. + +kinit is built as a single statically linked binary to save space. + +Eventually, several more chunks of kernel functionality will hopefully +move to early userspace: + +- Almost all of init/do_mounts* (the beginning of this is already in + place) +- ACPI table parsing +- Insert unwieldy subsystem that doesn't really need to be in kernel + space here + +If kinit doesn't meet your current needs and you've got bytes to burn, +the klibc distribution includes a small Bourne-compatible shell (ash) +and a number of other utilities, so you can replace kinit and build +custom initramfs images that meet your needs exactly. + +For questions and help, you can sign up for the early userspace +mailing list at http://www.zytor.com/mailman/listinfo/klibc + +How does it work? +================= + +The kernel has currently 3 ways to mount the root filesystem: + +a) all required device and filesystem drivers compiled into the kernel, no + initrd. init/main.c:init() will call prepare_namespace() to mount the + final root filesystem, based on the root= option and optional init= to run + some other init binary than listed at the end of init/main.c:init(). + +b) some device and filesystem drivers built as modules and stored in an + initrd. The initrd must contain a binary '/linuxrc' which is supposed to + load these driver modules. It is also possible to mount the final root + filesystem via linuxrc and use the pivot_root syscall. The initrd is + mounted and executed via prepare_namespace(). + +c) using initramfs. The call to prepare_namespace() must be skipped. + This means that a binary must do all the work. Said binary can be stored + into initramfs either via modifying usr/gen_init_cpio.c or via the new + initrd format, an cpio archive. It must be called "/init". This binary + is responsible to do all the things prepare_namespace() would do. + + To maintain backwards compatibility, the /init binary will only run if it + comes via an initramfs cpio archive. If this is not the case, + init/main.c:init() will run prepare_namespace() to mount the final root + and exec one of the predefined init binaries. + +Bryan O'Sullivan 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. -- cgit v1.2.3-55-g7522 From dc7a12bdfccd94c31f79e294f16f7549bd411b49 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sun, 14 Apr 2019 15:51:10 -0300 Subject: 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/Booting | 218 --------- Documentation/arm/IXP4xx | 172 ------- Documentation/arm/Interrupts | 167 ------- Documentation/arm/Marvell/README | 395 --------------- Documentation/arm/Microchip/README | 169 ------- Documentation/arm/Netwinder | 78 --- Documentation/arm/OMAP/DSS | 362 -------------- Documentation/arm/OMAP/README | 11 - Documentation/arm/OMAP/omap_pm | 154 ------ Documentation/arm/Porting | 135 ------ Documentation/arm/README | 204 -------- Documentation/arm/SA1100/ADSBitsy | 43 -- Documentation/arm/SA1100/Assabet | 300 ------------ Documentation/arm/SA1100/Brutus | 66 --- Documentation/arm/SA1100/CERF | 29 -- Documentation/arm/SA1100/FreeBird | 21 - Documentation/arm/SA1100/GraphicsClient | 98 ---- Documentation/arm/SA1100/GraphicsMaster | 53 -- Documentation/arm/SA1100/HUW_WEBPANEL | 17 - Documentation/arm/SA1100/Itsy | 39 -- Documentation/arm/SA1100/LART | 14 - Documentation/arm/SA1100/PLEB | 11 - Documentation/arm/SA1100/Pangolin | 23 - Documentation/arm/SA1100/Tifon | 7 - Documentation/arm/SA1100/Yopy | 2 - Documentation/arm/SA1100/empeg | 2 - Documentation/arm/SA1100/nanoEngine | 11 - Documentation/arm/SA1100/serial_UART | 47 -- Documentation/arm/SH-Mobile/.gitignore | 1 - Documentation/arm/SPEAr/overview.txt | 63 --- Documentation/arm/Samsung-S3C24XX/CPUfreq.txt | 75 --- Documentation/arm/Samsung-S3C24XX/EB2410ITX.txt | 58 --- Documentation/arm/Samsung-S3C24XX/GPIO.txt | 171 ------- Documentation/arm/Samsung-S3C24XX/H1940.txt | 40 -- Documentation/arm/Samsung-S3C24XX/NAND.txt | 30 -- Documentation/arm/Samsung-S3C24XX/Overview.txt | 318 ------------ Documentation/arm/Samsung-S3C24XX/S3C2412.txt | 120 ----- Documentation/arm/Samsung-S3C24XX/S3C2413.txt | 21 - Documentation/arm/Samsung-S3C24XX/SMDK2440.txt | 56 --- Documentation/arm/Samsung-S3C24XX/Suspend.txt | 137 ------ Documentation/arm/Samsung-S3C24XX/USB-Host.txt | 93 ---- Documentation/arm/Samsung/Bootloader-interface.txt | 68 --- Documentation/arm/Samsung/GPIO.txt | 40 -- Documentation/arm/Samsung/Overview.txt | 86 ---- .../arm/Samsung/clksrc-change-registers.awk | 166 ------- Documentation/arm/Setup | 129 ----- Documentation/arm/VFP/release-notes.txt | 55 --- Documentation/arm/arm.rst | 214 +++++++++ Documentation/arm/booting.rst | 237 +++++++++ Documentation/arm/cluster-pm-race-avoidance.rst | 533 +++++++++++++++++++++ Documentation/arm/cluster-pm-race-avoidance.txt | 498 ------------------- Documentation/arm/firmware.rst | 72 +++ Documentation/arm/firmware.txt | 70 --- Documentation/arm/index.rst | 80 ++++ Documentation/arm/interrupts.rst | 169 +++++++ Documentation/arm/ixp4xx.rst | 173 +++++++ Documentation/arm/kernel_mode_neon.rst | 124 +++++ Documentation/arm/kernel_mode_neon.txt | 121 ----- Documentation/arm/kernel_user_helpers.rst | 268 +++++++++++ Documentation/arm/kernel_user_helpers.txt | 267 ----------- Documentation/arm/keystone/Overview.txt | 55 --- Documentation/arm/keystone/knav-qmss.rst | 60 +++ Documentation/arm/keystone/knav-qmss.txt | 56 --- Documentation/arm/keystone/overview.rst | 74 +++ Documentation/arm/marvel.rst | 488 +++++++++++++++++++ Documentation/arm/mem_alignment | 58 --- Documentation/arm/mem_alignment.rst | 63 +++ Documentation/arm/memory.rst | 93 ++++ Documentation/arm/memory.txt | 88 ---- Documentation/arm/microchip.rst | 204 ++++++++ Documentation/arm/netwinder.rst | 85 ++++ Documentation/arm/nwfpe/NOTES | 29 -- Documentation/arm/nwfpe/README | 70 --- Documentation/arm/nwfpe/README.FPE | 156 ------ Documentation/arm/nwfpe/TODO | 67 --- Documentation/arm/nwfpe/index.rst | 11 + Documentation/arm/nwfpe/netwinder-fpe.rst | 162 +++++++ Documentation/arm/nwfpe/notes.rst | 32 ++ Documentation/arm/nwfpe/nwfpe.rst | 74 +++ Documentation/arm/nwfpe/todo.rst | 72 +++ Documentation/arm/omap/dss.rst | 372 ++++++++++++++ Documentation/arm/omap/index.rst | 10 + Documentation/arm/omap/omap.rst | 18 + Documentation/arm/omap/omap_pm.rst | 165 +++++++ Documentation/arm/porting.rst | 137 ++++++ Documentation/arm/pxa/mfp.rst | 288 +++++++++++ Documentation/arm/pxa/mfp.txt | 286 ----------- Documentation/arm/sa1100/adsbitsy.rst | 51 ++ Documentation/arm/sa1100/assabet.rst | 301 ++++++++++++ Documentation/arm/sa1100/brutus.rst | 69 +++ Documentation/arm/sa1100/cerf.rst | 35 ++ Documentation/arm/sa1100/freebird.rst | 25 + Documentation/arm/sa1100/graphicsclient.rst | 102 ++++ Documentation/arm/sa1100/graphicsmaster.rst | 60 +++ Documentation/arm/sa1100/huw_webpanel.rst | 21 + Documentation/arm/sa1100/index.rst | 23 + Documentation/arm/sa1100/itsy.rst | 47 ++ Documentation/arm/sa1100/lart.rst | 15 + Documentation/arm/sa1100/nanoengine.rst | 11 + Documentation/arm/sa1100/pangolin.rst | 29 ++ Documentation/arm/sa1100/pleb.rst | 13 + Documentation/arm/sa1100/serial_uart.rst | 51 ++ Documentation/arm/sa1100/tifon.rst | 7 + Documentation/arm/sa1100/yopy.rst | 5 + Documentation/arm/samsung-s3c24xx/cpufreq.rst | 76 +++ Documentation/arm/samsung-s3c24xx/eb2410itx.rst | 59 +++ Documentation/arm/samsung-s3c24xx/gpio.rst | 172 +++++++ Documentation/arm/samsung-s3c24xx/h1940.rst | 41 ++ Documentation/arm/samsung-s3c24xx/index.rst | 18 + Documentation/arm/samsung-s3c24xx/nand.rst | 30 ++ Documentation/arm/samsung-s3c24xx/overview.rst | 319 ++++++++++++ Documentation/arm/samsung-s3c24xx/s3c2412.rst | 121 +++++ Documentation/arm/samsung-s3c24xx/s3c2413.rst | 22 + Documentation/arm/samsung-s3c24xx/smdk2440.rst | 57 +++ Documentation/arm/samsung-s3c24xx/suspend.rst | 137 ++++++ Documentation/arm/samsung-s3c24xx/usb-host.rst | 91 ++++ Documentation/arm/samsung/bootloader-interface.rst | 81 ++++ .../arm/samsung/clksrc-change-registers.awk | 166 +++++++ Documentation/arm/samsung/gpio.rst | 41 ++ Documentation/arm/samsung/index.rst | 10 + Documentation/arm/samsung/overview.rst | 89 ++++ Documentation/arm/setup.rst | 108 +++++ Documentation/arm/sh-mobile/.gitignore | 1 + Documentation/arm/spear/overview.rst | 65 +++ Documentation/arm/sti/overview.rst | 36 ++ Documentation/arm/sti/overview.txt | 33 -- Documentation/arm/sti/stih407-overview.rst | 19 + Documentation/arm/sti/stih407-overview.txt | 18 - Documentation/arm/sti/stih415-overview.rst | 14 + Documentation/arm/sti/stih415-overview.txt | 12 - Documentation/arm/sti/stih416-overview.rst | 13 + Documentation/arm/sti/stih416-overview.txt | 12 - Documentation/arm/sti/stih418-overview.rst | 21 + Documentation/arm/sti/stih418-overview.txt | 20 - Documentation/arm/stm32/overview.rst | 2 - Documentation/arm/stm32/stm32f429-overview.rst | 7 +- Documentation/arm/stm32/stm32f746-overview.rst | 7 +- Documentation/arm/stm32/stm32f769-overview.rst | 7 +- Documentation/arm/stm32/stm32h743-overview.rst | 7 +- Documentation/arm/stm32/stm32mp157-overview.rst | 3 +- Documentation/arm/sunxi.rst | 150 ++++++ Documentation/arm/sunxi/README | 102 ---- Documentation/arm/sunxi/clocks.rst | 57 +++ Documentation/arm/sunxi/clocks.txt | 56 --- Documentation/arm/swp_emulation | 27 -- Documentation/arm/swp_emulation.rst | 27 ++ Documentation/arm/tcm.rst | 161 +++++++ Documentation/arm/tcm.txt | 155 ------ Documentation/arm/uefi.rst | 67 +++ Documentation/arm/uefi.txt | 60 --- Documentation/arm/vfp/release-notes.rst | 57 +++ Documentation/arm/vlocks.rst | 212 ++++++++ Documentation/arm/vlocks.txt | 211 -------- Documentation/devicetree/bindings/arm/xen.txt | 2 +- Documentation/devicetree/booting-without-of.txt | 4 +- Documentation/index.rst | 1 + Documentation/translations/zh_CN/arm/Booting | 4 +- .../translations/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 +- 181 files changed, 7731 insertions(+), 7166 deletions(-) delete mode 100644 Documentation/arm/Booting delete mode 100644 Documentation/arm/IXP4xx delete mode 100644 Documentation/arm/Interrupts delete mode 100644 Documentation/arm/Marvell/README delete mode 100644 Documentation/arm/Microchip/README delete mode 100644 Documentation/arm/Netwinder delete mode 100644 Documentation/arm/OMAP/DSS delete mode 100644 Documentation/arm/OMAP/README delete mode 100644 Documentation/arm/OMAP/omap_pm delete mode 100644 Documentation/arm/Porting delete mode 100644 Documentation/arm/README delete mode 100644 Documentation/arm/SA1100/ADSBitsy delete mode 100644 Documentation/arm/SA1100/Assabet delete mode 100644 Documentation/arm/SA1100/Brutus delete mode 100644 Documentation/arm/SA1100/CERF delete mode 100644 Documentation/arm/SA1100/FreeBird delete mode 100644 Documentation/arm/SA1100/GraphicsClient delete mode 100644 Documentation/arm/SA1100/GraphicsMaster delete mode 100644 Documentation/arm/SA1100/HUW_WEBPANEL delete mode 100644 Documentation/arm/SA1100/Itsy delete mode 100644 Documentation/arm/SA1100/LART delete mode 100644 Documentation/arm/SA1100/PLEB delete mode 100644 Documentation/arm/SA1100/Pangolin delete mode 100644 Documentation/arm/SA1100/Tifon delete mode 100644 Documentation/arm/SA1100/Yopy delete mode 100644 Documentation/arm/SA1100/empeg delete mode 100644 Documentation/arm/SA1100/nanoEngine delete mode 100644 Documentation/arm/SA1100/serial_UART delete mode 100644 Documentation/arm/SH-Mobile/.gitignore delete mode 100644 Documentation/arm/SPEAr/overview.txt delete mode 100644 Documentation/arm/Samsung-S3C24XX/CPUfreq.txt delete mode 100644 Documentation/arm/Samsung-S3C24XX/EB2410ITX.txt delete mode 100644 Documentation/arm/Samsung-S3C24XX/GPIO.txt delete mode 100644 Documentation/arm/Samsung-S3C24XX/H1940.txt delete mode 100644 Documentation/arm/Samsung-S3C24XX/NAND.txt delete mode 100644 Documentation/arm/Samsung-S3C24XX/Overview.txt delete mode 100644 Documentation/arm/Samsung-S3C24XX/S3C2412.txt delete mode 100644 Documentation/arm/Samsung-S3C24XX/S3C2413.txt delete mode 100644 Documentation/arm/Samsung-S3C24XX/SMDK2440.txt delete mode 100644 Documentation/arm/Samsung-S3C24XX/Suspend.txt delete mode 100644 Documentation/arm/Samsung-S3C24XX/USB-Host.txt delete mode 100644 Documentation/arm/Samsung/Bootloader-interface.txt delete mode 100644 Documentation/arm/Samsung/GPIO.txt delete mode 100644 Documentation/arm/Samsung/Overview.txt delete mode 100755 Documentation/arm/Samsung/clksrc-change-registers.awk delete mode 100644 Documentation/arm/Setup delete mode 100644 Documentation/arm/VFP/release-notes.txt create mode 100644 Documentation/arm/arm.rst create mode 100644 Documentation/arm/booting.rst create mode 100644 Documentation/arm/cluster-pm-race-avoidance.rst delete mode 100644 Documentation/arm/cluster-pm-race-avoidance.txt create mode 100644 Documentation/arm/firmware.rst delete mode 100644 Documentation/arm/firmware.txt create mode 100644 Documentation/arm/index.rst create mode 100644 Documentation/arm/interrupts.rst create mode 100644 Documentation/arm/ixp4xx.rst create mode 100644 Documentation/arm/kernel_mode_neon.rst delete mode 100644 Documentation/arm/kernel_mode_neon.txt create mode 100644 Documentation/arm/kernel_user_helpers.rst delete mode 100644 Documentation/arm/kernel_user_helpers.txt delete mode 100644 Documentation/arm/keystone/Overview.txt create mode 100644 Documentation/arm/keystone/knav-qmss.rst delete mode 100644 Documentation/arm/keystone/knav-qmss.txt create mode 100644 Documentation/arm/keystone/overview.rst create mode 100644 Documentation/arm/marvel.rst delete mode 100644 Documentation/arm/mem_alignment create mode 100644 Documentation/arm/mem_alignment.rst create mode 100644 Documentation/arm/memory.rst delete mode 100644 Documentation/arm/memory.txt create mode 100644 Documentation/arm/microchip.rst create mode 100644 Documentation/arm/netwinder.rst delete mode 100644 Documentation/arm/nwfpe/NOTES delete mode 100644 Documentation/arm/nwfpe/README delete mode 100644 Documentation/arm/nwfpe/README.FPE delete mode 100644 Documentation/arm/nwfpe/TODO create mode 100644 Documentation/arm/nwfpe/index.rst create mode 100644 Documentation/arm/nwfpe/netwinder-fpe.rst create mode 100644 Documentation/arm/nwfpe/notes.rst create mode 100644 Documentation/arm/nwfpe/nwfpe.rst create mode 100644 Documentation/arm/nwfpe/todo.rst create mode 100644 Documentation/arm/omap/dss.rst create mode 100644 Documentation/arm/omap/index.rst create mode 100644 Documentation/arm/omap/omap.rst create mode 100644 Documentation/arm/omap/omap_pm.rst create mode 100644 Documentation/arm/porting.rst create mode 100644 Documentation/arm/pxa/mfp.rst delete mode 100644 Documentation/arm/pxa/mfp.txt create mode 100644 Documentation/arm/sa1100/adsbitsy.rst create mode 100644 Documentation/arm/sa1100/assabet.rst create mode 100644 Documentation/arm/sa1100/brutus.rst create mode 100644 Documentation/arm/sa1100/cerf.rst create mode 100644 Documentation/arm/sa1100/freebird.rst create mode 100644 Documentation/arm/sa1100/graphicsclient.rst create mode 100644 Documentation/arm/sa1100/graphicsmaster.rst create mode 100644 Documentation/arm/sa1100/huw_webpanel.rst create mode 100644 Documentation/arm/sa1100/index.rst create mode 100644 Documentation/arm/sa1100/itsy.rst create mode 100644 Documentation/arm/sa1100/lart.rst create mode 100644 Documentation/arm/sa1100/nanoengine.rst create mode 100644 Documentation/arm/sa1100/pangolin.rst create mode 100644 Documentation/arm/sa1100/pleb.rst create mode 100644 Documentation/arm/sa1100/serial_uart.rst create mode 100644 Documentation/arm/sa1100/tifon.rst create mode 100644 Documentation/arm/sa1100/yopy.rst create mode 100644 Documentation/arm/samsung-s3c24xx/cpufreq.rst create mode 100644 Documentation/arm/samsung-s3c24xx/eb2410itx.rst create mode 100644 Documentation/arm/samsung-s3c24xx/gpio.rst create mode 100644 Documentation/arm/samsung-s3c24xx/h1940.rst create mode 100644 Documentation/arm/samsung-s3c24xx/index.rst create mode 100644 Documentation/arm/samsung-s3c24xx/nand.rst create mode 100644 Documentation/arm/samsung-s3c24xx/overview.rst create mode 100644 Documentation/arm/samsung-s3c24xx/s3c2412.rst create mode 100644 Documentation/arm/samsung-s3c24xx/s3c2413.rst create mode 100644 Documentation/arm/samsung-s3c24xx/smdk2440.rst create mode 100644 Documentation/arm/samsung-s3c24xx/suspend.rst create mode 100644 Documentation/arm/samsung-s3c24xx/usb-host.rst create mode 100644 Documentation/arm/samsung/bootloader-interface.rst create mode 100755 Documentation/arm/samsung/clksrc-change-registers.awk create mode 100644 Documentation/arm/samsung/gpio.rst create mode 100644 Documentation/arm/samsung/index.rst create mode 100644 Documentation/arm/samsung/overview.rst create mode 100644 Documentation/arm/setup.rst create mode 100644 Documentation/arm/sh-mobile/.gitignore create mode 100644 Documentation/arm/spear/overview.rst create mode 100644 Documentation/arm/sti/overview.rst delete mode 100644 Documentation/arm/sti/overview.txt create mode 100644 Documentation/arm/sti/stih407-overview.rst delete mode 100644 Documentation/arm/sti/stih407-overview.txt create mode 100644 Documentation/arm/sti/stih415-overview.rst delete mode 100644 Documentation/arm/sti/stih415-overview.txt create mode 100644 Documentation/arm/sti/stih416-overview.rst delete mode 100644 Documentation/arm/sti/stih416-overview.txt create mode 100644 Documentation/arm/sti/stih418-overview.rst delete mode 100644 Documentation/arm/sti/stih418-overview.txt create mode 100644 Documentation/arm/sunxi.rst delete mode 100644 Documentation/arm/sunxi/README create mode 100644 Documentation/arm/sunxi/clocks.rst delete mode 100644 Documentation/arm/sunxi/clocks.txt delete mode 100644 Documentation/arm/swp_emulation create mode 100644 Documentation/arm/swp_emulation.rst create mode 100644 Documentation/arm/tcm.rst delete mode 100644 Documentation/arm/tcm.txt create mode 100644 Documentation/arm/uefi.rst delete mode 100644 Documentation/arm/uefi.txt create mode 100644 Documentation/arm/vfp/release-notes.rst create mode 100644 Documentation/arm/vlocks.rst delete mode 100644 Documentation/arm/vlocks.txt diff --git a/Documentation/arm/Booting b/Documentation/arm/Booting deleted file mode 100644 index f1f965ce93d6..000000000000 --- a/Documentation/arm/Booting +++ /dev/null @@ -1,218 +0,0 @@ - Booting ARM Linux - ================= - -Author: Russell King -Date : 18 May 2002 - -The following documentation is relevant to 2.4.18-rmk6 and beyond. - -In order to boot ARM Linux, you require a boot loader, which is a small -program that runs before the main kernel. The boot loader is expected -to initialise various devices, and eventually call the Linux kernel, -passing information to the kernel. - -Essentially, the boot loader should provide (as a minimum) the -following: - -1. Setup and initialise the RAM. -2. Initialise one serial port. -3. Detect the machine type. -4. Setup the kernel tagged list. -5. Load initramfs. -6. Call the kernel image. - - -1. Setup and initialise RAM ---------------------------- - -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 -this in a machine dependent manner. (It may use internal algorithms -to automatically locate and size all RAM, or it may use knowledge of -the RAM in the machine, or any other method the boot loader designer -sees fit.) - - -2. Initialise one serial port ------------------------------ - -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 -which serial port it should use for the kernel console (generally -used for debugging purposes, or communication with the target.) - -As an alternative, the boot loader can pass the relevant 'console=' -option to the kernel via the tagged lists specifying the port, and -serial format options as described in - - Documentation/admin-guide/kernel-parameters.rst. - - -3. Detect the machine type --------------------------- - -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 -looks at the connected hardware is beyond the scope of this document. -The boot loader must ultimately be able to provide a MACH_TYPE_xxx -value to the kernel. (see linux/arch/arm/tools/mach-types). This -should be passed to the kernel in register r1. - -For DT-only platforms, the machine type will be determined by device -tree. set the machine type to all ones (~0). This is not strictly -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 - -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 -boot data is passed to the kernel in register r2. - -4a. Setup the kernel tagged list --------------------------------- - -The boot loader must create and initialise the kernel tagged list. -A valid tagged list starts with ATAG_CORE and ends with ATAG_NONE. -The ATAG_CORE tag may or may not be empty. An empty ATAG_CORE tag -has the size field set to '2' (0x00000002). The ATAG_NONE must set -the size field to zero. - -Any number of tags can be placed in the list. It is undefined -whether a repeated tag appends to the information carried by the -previous tag, or whether it replaces the information in its -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: - - +-----------+ -base -> | ATAG_CORE | | - +-----------+ | - | ATAG_MEM | | increasing address - +-----------+ | - | ATAG_NONE | | - +-----------+ v - -The tagged list should be stored in system RAM. - -The tagged list must be placed in a region of memory where neither -the kernel decompressor nor initrd 'bootp' program will overwrite -it. The recommended placement is in the first 16KiB of RAM. - -4b. Setup the device tree -------------------------- - -The boot loader must load a device tree image (dtb) into system ram -at a 64bit aligned address and initialize it with the boot data. The -dtb format is documented in Documentation/devicetree/booting-without-of.txt. -The kernel will look for the dtb magic value of 0xd00dfeed at the dtb -physical address to determine if a dtb has been passed instead of a -tagged list. - -The boot loader must pass at a minimum the size and location of the -system memory, and the root filesystem location. The dtb must be -placed in a region of memory where the kernel decompressor will not -overwrite it, while remaining within the region which will be covered -by the kernel's low-memory mapping. - -A safe location is just above the 128MiB boundary from start of RAM. - -5. Load initramfs. ------------------- - -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 -while also with the region which will be covered by the kernel's -low-memory mapping. - -A safe location is just above the device tree blob which itself will -be loaded just above the 128MiB boundary from the start of RAM as -recommended above. - -6. Calling the kernel image ---------------------------- - -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, -then it is legal for the boot loader to call the zImage in flash -directly. - -The zImage may also be placed in system RAM and called there. The -kernel should be placed in the first 128MiB of RAM. It is recommended -that it is loaded above 32MiB in order to avoid the need to relocate -prior to decompression, which will make the boot process slightly -faster. - -When booting a raw (non-zImage) kernel the constraints are tighter. -In this case the kernel must be loaded at an offset into system equal -to TEXT_OFFSET - PAGE_OFFSET. - -In any case, the following conditions must be met: - -- Quiesce all DMA capable devices so that memory does not get - corrupted by bogus network packets or disk data. This will save - 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 - -- CPU mode - All forms of interrupts must be disabled (IRQs and FIQs) - - For CPUs which do not include the ARM virtualization extensions, the - CPU must be in SVC mode. (A special exception exists for Angel) - - CPUs which include support for the virtualization extensions can be - entered in HYP mode in order to enable the kernel to make full use of - these extensions. This is the recommended boot method for such CPUs, - unless the virtualisations are already in use by a pre-installed - hypervisor. - - If the kernel is not entered in HYP mode for any reason, it must be - 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 - the HYP mode configuration in addition to the ordinary PL1 (privileged - kernel modes) configuration. In addition, all traps into the - hypervisor must be disabled, and PL1 access must be granted for all - peripherals and CPU resources for which this is architecturally - possible. Except for entering in HYP mode, the system configuration - should be such that a kernel which does not include support for the - virtualization extensions can boot correctly without extra help. - -- The boot loader is expected to call the kernel image by jumping - directly to the first instruction of the kernel image. - - On CPUs supporting the ARM instruction set, the entry must be - made in ARM state, even for a Thumb-2 kernel. - - On CPUs supporting only the Thumb instruction set such as - Cortex-M class CPUs, the entry must be made in Thumb state. diff --git a/Documentation/arm/IXP4xx b/Documentation/arm/IXP4xx deleted file mode 100644 index e48b74de6ac0..000000000000 --- a/Documentation/arm/IXP4xx +++ /dev/null @@ -1,172 +0,0 @@ - -------------------------------------------------------------------------- -Release Notes for Linux on Intel's IXP4xx Network Processor - -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 -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, -routing, firewalling, etc. The IXP46x family is an updated version which -supports faster speeds, new memory and flash configurations, and more -integration such as an on-chip I2C controller. - -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 -stripped of much of the network intelligence. - -2. Linux Support - -Linux currently supports the following features on the IXP4xx chips: - -- Dual serial ports -- PCI interface -- Flash access (MTD/JFFS) -- I2C through GPIO on IXP42x -- GPIO for input/output/interrupts - See arch/arm/mach-ixp4xx/include/mach/platform.h for access functions. -- Timers (watchdog, OS) - -The following components of the chips are not supported by Linux and -require the use of Intel's proprietary CSR software: - -- USB device interface -- Network interfaces (HSS, Utopia, NPEs, etc) -- Network offload functionality - -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 - -DO NOT POST QUESTIONS TO THE LINUX MAILING LISTS REGARDING THE PROPRIETARY -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://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 - -3. Known Issues/Limitations - -3a. Limited inbound PCI window - -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: - -1) A direct mapped window from 0x48000000 to 0x4bffffff (64MB). - 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 - 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 - mmap() PCI devices in this case due to the indirect nature - of the PCI window. - -By default, the direct method is used for performance reasons. If -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 - -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 - 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 - via SLICs. Note that those are not supported by Linux ATM. Finally, - the platform has two mini-PCI slots used for 802.11[bga] cards. - Finally, there is an IDE port hanging off the expansion bus. - -Gateworks Avila Network Platform -http://www.gateworks.com/support/overview.php - - The Avila platform is basically and IXDP425 with the 4 PCI slots - replaced with mini-PCI slots and a CF IDE interface hanging off - the expansion bus. - -Intel IXDP425 Development Platform -http://www.intel.com/design/network/products/npfamily/ixdpg425.htm - - 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. - -Intel IXDP465 Development Platform -http://www.intel.com/design/network/products/npfamily/ixdp465.htm - - This is basically an IXDP425 with an IXP465 and 32M of flash instead - of just 16. - -Intel IXDPG425 Development Platform - - This is basically and ADI Coyote board with a NEC EHCI controller - added. One issue with this board is that the mini-PCI slots only - have the 3.3v line connected, so you can't use a PCI to mini-PCI - adapter with an E100 card. So to NFS root you need to use either - the CSR or a WiFi card and a ramdisk that BOOTPs and then does - a pivot_root to NFS. - -Motorola PrPMC1100 Processor Mezanine Card -http://www.fountainsys.com - - The PrPMC1100 is based on the IXCP1100 and is meant to plug into - and IXP2400/2800 system to act as the system controller. It simply - contains a CPU and 16MB of flash on the board and needs to be - plugged into a carrier board to function. Currently Linux only - supports the Motorola PrPMC carrier board for this platform. - -5. TODO LIST - -- Add support for Coyote IDE -- Add support for edge-based GPIO interrupts -- Add support for CF IDE on expansion bus - -6. Thanks - -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] - -------------------------------------------------------------------------- - -Last Update: 01/04/2005 diff --git a/Documentation/arm/Interrupts b/Documentation/arm/Interrupts deleted file mode 100644 index f09ab1b90ef1..000000000000 --- a/Documentation/arm/Interrupts +++ /dev/null @@ -1,167 +0,0 @@ -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 - -we have TLB v3, TLB v4 (without write buffer), TLB v4 (with write buffer), -and finally TLB v4 (with write buffer, with I TLB invalidate entry). -There is more assembly code inside each of these functions, mainly to -allow more flexible TLB handling for the future. - -Secondly, the IRQ subsystem. - -The 2.5 kernels will be having major changes to the way IRQs are handled. -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: - - GPIO25 IRR:2 - SA1100 ------------> Neponset -----------> SA1111 - IIR:1 - -----------> USAR - IIR:0 - -----------> SMC9196 - -The way stuff currently works, all SA1111 interrupts are mutually -exclusive of each other - if you're processing one interrupt from the -SA1111 and another comes in, you have to wait for that interrupt to -finish processing before you can service the new interrupt. Eg, an -IDE PIO-based interrupt on the SA1111 excludes all other SA1111 and -SMC9196 interrupts until it has finished transferring its multi-sector -data, which can be a long time. Note also that since we loop in the -SA1111 IRQ handler, SA1111 IRQs can hold off SMC9196 IRQs indefinitely. - - -The new approach brings several new ideas... - -We introduce the concept of a "parent" and a "child". For example, -to the Neponset handler, the "parent" is GPIO25, and the "children"d -are SA1111, SMC9196 and USAR. - -We also bring the idea of an IRQ "chip" (mainly to reduce the size of -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: - -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 - handled by do_level_IRQ. -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, - it should be null so people can detect if they are unable to - set the IRQ type. - -For each IRQ, we keep the following information: - - - "disable" depth (number of disable_irq()s without enable_irq()s) - - flags indicating what we can do with this IRQ (valid, probe, - noautounmask) as before - - status of the IRQ (probing, enable, etc) - - chip - - per-IRQ handler - - irqaction structure list - -The handler can be one of the 3 standard handlers - "level", "edge" and -"simple", or your own specific handler if you need to do something special. - -The "level" handler is what we currently have - its pretty simple. -"edge" knows about the brokenness of such IRQ implementations - that you -need to leave the hardware IRQ enabled while processing it, and queueing -further IRQ events should the IRQ happen again while processing. The -"simple" handler is very basic, and does not perform any hardware -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. - -2. New functions to manipulate the irqdesc array. The first 4 are expected - to be useful only to machine specific code. The last is recommended to - only be used by machine specific code, but may be used in drivers if - 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 - - -3. set_GPIO_IRQ_edge() is obsolete, and should be replaced by set_irq_type. - -4. Direct access to SA1111 INTPOL is deprecated. Use set_irq_type instead. - -5. A handler is expected to perform any necessary acknowledgement of the - parent IRQ via the correct chip specific function. For instance, if - the SA1111 is directly connected to a SA1110 GPIO, then you should - acknowledge the SA1110 IRQ each time you re-read the SA1111 IRQ status. - -6. For any child which doesn't have its own IRQ enable/disable controls - (eg, SMC9196), the handler must mask or acknowledge the parent IRQ - while the child handler is called, and the child handler should be the - "simple" handler (not "edge" nor "level"). After the handler completes, - the parent IRQ should be unmasked, and the status of all children must - 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 - -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/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/Microchip/README b/Documentation/arm/Microchip/README deleted file mode 100644 index a366f37d38f1..000000000000 --- a/Documentation/arm/Microchip/README +++ /dev/null @@ -1,169 +0,0 @@ -ARM Microchip SoCs (aka AT91) -============================= - - -Introduction ------------- -This document gives useful information about the ARM Microchip SoCs that are -currently supported in Linux Mainline (you know, the one on kernel.org). - -It is important to note that the Microchip (previously Atmel) ARM-based MPU -product line is historically named "AT91" or "at91" throughout the Linux kernel -development process even if this product prefix has completely disappeared from -the official Microchip product name. Anyway, files, directories, git trees, -git branches/tags and email subject always contain this "at91" sub-string. - - -AT91 SoCs ---------- -Documentation and detailed datasheet for each product are available on -the Microchip website: http://www.microchip.com. - - Flavors: - * ARM 920 based SoC - - at91rm9200 - + Datasheet - http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-1768-32-bit-ARM920T-Embedded-Microprocessor-AT91RM9200_Datasheet.pdf - - * ARM 926 based SoCs - - at91sam9260 - + Datasheet - http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-6221-32-bit-ARM926EJ-S-Embedded-Microprocessor-SAM9260_Datasheet.pdf - - - at91sam9xe - + Datasheet - http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-6254-32-bit-ARM926EJ-S-Embedded-Microprocessor-SAM9XE_Datasheet.pdf - - - at91sam9261 - + Datasheet - http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-6062-ARM926EJ-S-Microprocessor-SAM9261_Datasheet.pdf - - - at91sam9263 - + Datasheet - http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-6249-32-bit-ARM926EJ-S-Embedded-Microprocessor-SAM9263_Datasheet.pdf - - - at91sam9rl - + Datasheet - http://ww1.microchip.com/downloads/en/DeviceDoc/doc6289.pdf - - - at91sam9g20 - + Datasheet - http://ww1.microchip.com/downloads/en/DeviceDoc/DS60001516A.pdf - - - at91sam9g45 family - - at91sam9g45 - - at91sam9g46 - - at91sam9m10 - - at91sam9m11 (device superset) - + Datasheet - http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-6437-32-bit-ARM926-Embedded-Microprocessor-SAM9M11_Datasheet.pdf - - - at91sam9x5 family (aka "The 5 series") - - at91sam9g15 - - at91sam9g25 - - at91sam9g35 - - at91sam9x25 - - at91sam9x35 - + 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 - http://ww1.microchip.com/downloads/en/DeviceDoc/DS60001517A.pdf - - * ARM Cortex-A5 based SoCs - - sama5d3 family - - sama5d31 - - sama5d33 - - sama5d34 - - sama5d35 - - sama5d36 (device superset) - + 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 - http://ww1.microchip.com/downloads/en/DeviceDoc/60001525A.pdf - - - sama5d2 family - - sama5d21 - - sama5d22 - - sama5d23 - - sama5d24 - - sama5d26 - - sama5d27 (device superset) - - sama5d28 (device superset + environmental monitors) - + Datasheet - http://ww1.microchip.com/downloads/en/DeviceDoc/DS60001476B.pdf - - * ARM Cortex-M7 MCUs - - sams70 family - - sams70j19 - - sams70j20 - - sams70j21 - - sams70n19 - - sams70n20 - - sams70n21 - - sams70q19 - - sams70q20 - - sams70q21 - - - samv70 family - - samv70j19 - - samv70j20 - - samv70n19 - - samv70n20 - - samv70q19 - - samv70q20 - - - samv71 family - - samv71j19 - - samv71j20 - - samv71j21 - - samv71n19 - - samv71n20 - - samv71n21 - - samv71q19 - - samv71q20 - - samv71q21 - - + Datasheet - http://ww1.microchip.com/downloads/en/DeviceDoc/60001527A.pdf - - -Linux kernel information ------------------------- -Linux kernel mach directory: arch/arm/mach-at91 -MAINTAINERS entry is: "ARM/Microchip (AT91) SoC support" - - -Device Tree for AT91 SoCs and boards ------------------------------------- -All AT91 SoCs are converted to Device Tree. Since Linux 3.19, these products -must use this method to boot the Linux kernel. - -Work In Progress statement: -Device Tree files and Device Tree bindings that apply to AT91 SoCs and boards are -considered as "Unstable". To be completely clear, any at91 binding can change at -any time. So, be sure to use a Device Tree Binary and a Kernel Image generated from -the same source tree. -Please refer to the Documentation/devicetree/bindings/ABI.txt file for a -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 - shared across SoCs or boards (sama5d3.dtsi or at91sam9x5cm.dtsi for instance). - When collecting nodes for a particular peripheral or topic, the identifier have to - be placed at the end of the file name, separated with a "_" (at91sam9x5_can.dtsi - or sama5d3_gmac.dtsi for example). -- board Device Tree Source files (.dts) are prefixed by the string "at91-" so - that they can be identified easily. Note that some files are historical exceptions - to this rule (sama5d3[13456]ek.dts, usb_a9g20.dts or animeo_ip.dts for example). 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/OMAP/DSS b/Documentation/arm/OMAP/DSS deleted file mode 100644 index 4484e021290e..000000000000 --- a/Documentation/arm/OMAP/DSS +++ /dev/null @@ -1,362 +0,0 @@ -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, -TV-out and multiple display support, but there are lots of small improvements -also. - -The DSS2 driver (omapdss module) is in arch/arm/plat-omap/dss/, and the FB, -panel and controller drivers are in drivers/video/omap2/. DSS1 and DSS2 live -currently side by side, you can choose which one to use. - -Features --------- - -Working and tested features include: - -- MIPI DPI (parallel) output -- MIPI DSI output in command mode -- MIPI DBI (RFBI) output -- SDI output -- TV output -- All pieces can be compiled as a module or inside kernel -- Use DISPC to update any of the outputs -- Use CPU to update RFBI or DSI output -- OMAP DISPC planes -- RGB16, RGB24 packed, RGB24 unpacked -- YUV2, UYVY -- Scaling -- Adjusting DSS FCK to find a good pixel clock -- Use DSI DPLL to create DSS FCK - -Tested boards include: -- OMAP3 SDP board -- Beagle board -- N810 - -omapdss driver --------------- - -The DSS driver does not itself have any support for Linux framebuffer, V4L or -such like the current ones, but it has an internal kernel API that upper level -drivers can use. - -The DSS driver models OMAP's overlays, overlay managers and displays in a -flexible way to enable non-common multi-display configuration. In addition to -modelling the hardware overlays, omapdss supports virtual overlays and overlay -managers. These can be used when updating a display with CPU or system DMA. - -omapdss driver support for audio --------------------------------- -There exist several display technologies and standards that support audio as -well. Hence, it is relevant to update the DSS device driver to provide an audio -interface that may be used by an audio driver or any other driver interested in -the functionality. - -The audio_enable function is intended to prepare the relevant -IP for playback (e.g., enabling an audio FIFO, taking in/out of reset -some IP, enabling companion chips, etc). It is intended to be called before -audio_start. The audio_disable function performs the reverse operation and is -intended to be called after audio_stop. - -While a given DSS device driver may support audio, it is possible that for -certain configurations audio is not supported (e.g., an HDMI display using a -VESA video timing). The audio_supported function is intended to query whether -the current configuration of the display supports audio. - -The audio_config function is intended to configure all the relevant audio -parameters of the display. In order to make the function independent of any -specific DSS device driver, a struct omap_dss_audio is defined. Its purpose -is to contain all the required parameters for audio configuration. At the -moment, such structure contains pointers to IEC-60958 channel status word -and CEA-861 audio infoframe structures. This should be enough to support -HDMI and DisplayPort, as both are based on CEA-861 and IEC-60958. - -The audio_enable/disable, audio_config and audio_supported functions could be -implemented as functions that may sleep. Hence, they should not be called -while holding a spinlock or a readlock. - -The audio_start/audio_stop function is intended to effectively start/stop audio -playback after the configuration has taken place. These functions are designed -to be used in an atomic context. Hence, audio_start should return quickly and be -called only after all the needed resources for audio playback (audio FIFOs, -DMA channels, companion chips, etc) have been enabled to begin data transfers. -audio_stop is designed to only stop the audio transfers. The resources used -for playback are released using audio_disable. - -The enum omap_dss_audio_state may be used to help the implementations of -the interface to keep track of the audio state. The initial state is _DISABLED; -then, the state transitions to _CONFIGURED, and then, when it is ready to -play audio, to _ENABLED. The state _PLAYING is used when the audio is being -rendered. - - -Panel and controller drivers ----------------------------- - -The drivers implement panel or controller specific functionality and are not -usually visible to users except through omapfb driver. They register -themselves to the DSS driver. - -omapfb driver -------------- - -The omapfb driver implements arbitrary number of standard linux framebuffers. -These framebuffers can be routed flexibly to any overlays, thus allowing very -dynamic display architecture. - -The driver exports some omapfb specific ioctls, which are compatible with the -ioctls in the old driver. - -The rest of the non standard features are exported via sysfs. Whether the final -implementation will use sysfs, or ioctls, is still open. - -V4L2 drivers ------------- - -V4L2 is being implemented in TI. - -From omapdss point of view the V4L2 drivers should be similar to framebuffer -driver. - -Architecture --------------------- - -Some clarification what the different components do: - - - Framebuffer is a memory area inside OMAP's SRAM/SDRAM that contains the - pixel data for the image. Framebuffer has width and height and color - depth. - - Overlay defines where the pixels are read from and where they go on the - screen. The overlay may be smaller than framebuffer, thus displaying only - part of the framebuffer. The position of the overlay may be changed if - the overlay is smaller than the display. - - Overlay manager combines the overlays in to one image and feeds them to - display. - - Display is the actual physical display device. - -A framebuffer can be connected to multiple overlays to show the same pixel data -on all of the overlays. Note that in this case the overlay input sizes must be -the same, but, in case of video overlays, the output size can be different. Any -framebuffer can be connected to any overlay. - -An overlay can be connected to one overlay manager. Also DISPC overlays can be -connected only to DISPC overlay managers, and virtual overlays can be only -connected to virtual overlays. - -An overlay manager can be connected to one display. There are certain -restrictions which kinds of displays an overlay manager can be connected: - - - DISPC TV overlay manager can be only connected to TV display. - - Virtual overlay managers can only be connected to DBI or DSI displays. - - DISPC LCD overlay manager can be connected to all displays, except TV - display. - -Sysfs ------ -The sysfs interface is mainly used for testing. I don't think sysfs -interface is the best for this in the final version, but I don't quite know -what would be the best interfaces for these things. - -The sysfs interface is divided to two parts: DSS and FB. - -/sys/class/graphics/fb? directory: -mirror 0=off, 1=on -rotate Rotation 0-3 for 0, 90, 180, 270 degrees -rotate_type 0 = DMA rotation, 1 = VRFB rotation -overlays List of overlay numbers to which framebuffer pixels go -phys_addr Physical address of the framebuffer -virt_addr Virtual address of the framebuffer -size Size of the framebuffer - -/sys/devices/platform/omapdss/overlay? directory: -enabled 0=off, 1=on -input_size width,height (ie. the framebuffer size) -manager Destination overlay manager name -name -output_size width,height -position x,y -screen_width width -global_alpha global alpha 0-255 0=transparent 255=opaque - -/sys/devices/platform/omapdss/manager? directory: -display Destination display -name -alpha_blending_enabled 0=off, 1=on -trans_key_enabled 0=off, 1=on -trans_key_type gfx-destination, video-source -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 -enabled 0=off, 1=on -name -rotate Rotation 0-3 for 0, 90, 180, 270 degrees -timings Display timings (pixclock,xres/hfp/hbp/hsw,yres/vfp/vbp/vsw) - When writing, two special timings are accepted for tv-out: - "pal" and "ntsc" -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. - -Examples --------- - -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 - -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 - -fb0=/sys/class/graphics/fb0 -fb1=/sys/class/graphics/fb1 -fb2=/sys/class/graphics/fb2 - -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. - -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 - -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 ----------- - -OMAP FB allocates the framebuffer memory using the standard dma allocator. You -can enable Contiguous Memory Allocator (CONFIG_CMA) to improve the dma -allocator, and if CMA is enabled, you use "cma=" kernel parameter to increase -the global memory area for CMA. - -Using DSI DPLL to generate pixel clock it is possible produce the pixel clock -of 86.5MHz (max possible), and with that you get 1280x1024@57 output from DVI. - -Rotation and mirroring currently only supports RGB565 and RGB8888 modes. VRFB -does not support mirroring. - -VRFB rotation requires much more memory than non-rotated framebuffer, so you -probably need to increase your vram setting before using VRFB rotation. Also, -many applications may not work with VRFB if they do not pay attention to all -framebuffer parameters. - -Kernel boot arguments ---------------------- - -omapfb.mode=:[,...] - - Default video mode for specified displays. For example, - "dvi:800x400MR-24@60". See drivers/video/modedb.c. - There are also two special modes: "pal" and "ntsc" that - can be used to tv out. - -omapfb.vram=:[@][,...] - - VRAM allocated for a framebuffer. Normally omapfb allocates vram - depending on the display size. With this you can manually allocate - more or define the physical address of each framebuffer. For example, - "1:4M" to allocate 4M for fb1. - -omapfb.debug= - - Enable debug printing. You have to have OMAPFB debug support enabled - in kernel config. - -omapfb.test= - - Draw test pattern to framebuffer whenever framebuffer settings change. - You need to have OMAPFB debug support enabled in kernel config. - -omapfb.vrfb= - - Use VRFB rotation for all framebuffers. - -omapfb.rotate= - - Default rotation applied to all framebuffers. - 0 - 0 degree rotation - 1 - 90 degree rotation - 2 - 180 degree rotation - 3 - 270 degree rotation - -omapfb.mirror= - - Default mirror for all framebuffers. Only works with DMA rotation. - -omapdss.def_disp= - - Name of default display, to which all overlays will be connected. - Common examples are "lcd" or "tv". - -omapdss.debug= - - Enable debug printing. You have to have DSS debug support enabled in - kernel config. - -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 - diff --git a/Documentation/arm/OMAP/README b/Documentation/arm/OMAP/README deleted file mode 100644 index 90c6c57d61e8..000000000000 --- a/Documentation/arm/OMAP/README +++ /dev/null @@ -1,11 +0,0 @@ -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. - -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 deleted file mode 100644 index 4ae915a9f899..000000000000 --- a/Documentation/arm/OMAP/omap_pm +++ /dev/null @@ -1,154 +0,0 @@ - -The OMAP PM interface -===================== - -This document describes the temporary OMAP PM interface. Driver -authors use these functions to communicate minimum latency or -throughput constraints to the kernel power management code. -Over time, the intention is to merge features from the OMAP PM -interface into the Linux PM QoS code. - -Drivers need to express PM parameters which: - -- support the range of power management parameters present in the TI SRF; - -- separate the drivers from the underlying PM parameter - implementation, whether it is the TI SRF or Linux PM QoS or Linux - latency framework or something else; - -- specify PM parameters in terms of fundamental units, such as - latency and throughput, rather than units which are specific to OMAP - or to particular OMAP variants; - -- allow drivers which are shared with other architectures (e.g., - DaVinci) to add these constraints in a way which won't affect non-OMAP - systems, - -- can be implemented immediately with minimal disruption of other - architectures. - - -This document proposes the OMAP PM interface, including the following -five power management functions for driver code: - -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: - (*pdata->set_max_dev_wakeup_lat)(struct device *dev, unsigned long t) - -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: - (*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 - (*pdata->get_dev_context_loss_count)(struct device *dev) - - -Further documentation for all OMAP PM interface functions can be -found in arch/arm/plat-omap/include/mach/omap-pm.h. - - -The OMAP PM layer is intended to be temporary ---------------------------------------------- - -The intention is that eventually the Linux PM QoS layer should support -the range of power management features present in OMAP3. As this -happens, existing drivers using the OMAP PM interface can be modified -to use the Linux PM QoS code; and the OMAP PM interface can disappear. - - -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 -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: - - if (pdata->set_max_dev_wakeup_lat) - (*pdata->set_max_dev_wakeup_lat)(dev, t); - -The most common usage of these functions will probably be to specify -the maximum time from when an interrupt occurs, to when the device -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, - - /* Limit MPU wakeup latency */ - if (pdata->set_max_mpu_wakeup_lat) - (*pdata->set_max_mpu_wakeup_lat)(dev, tc); - - /* Limit device powerdomain wakeup latency */ - if (pdata->set_max_dev_wakeup_lat) - (*pdata->set_max_dev_wakeup_lat)(dev, td); - - /* total wakeup latency in this example: (tc + td) */ - -The PM parameters can be overwritten by calling the function again -with the new value. The settings can be removed by calling the -function with a t argument of -1 (except in the case of -set_max_bus_tput(), which should be called with an r argument of 0). - -The fifth function above, omap_pm_get_dev_context_loss_count(), -is intended as an optimization to allow drivers to determine whether the -device has lost its internal context. If context has been lost, the -driver must restore its internal context before proceeding. - - -Other specialized interface functions -------------------------------------- - -The five functions listed above are intended to be usable by any -device driver. DSPBridge and CPUFreq have a few special requirements. -DSPBridge expresses target DSP performance levels in terms of OPP IDs. -CPUFreq expresses target MPU performance levels in terms of MPU -frequency. The OMAP PM interface contains functions for these -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) - -7. (*pdata->dsp_set_min_opp)(u8 opp_id) - -8. (*pdata->dsp_get_opp)(void) - -9. (*pdata->cpu_get_freq_table)(void) - -10. (*pdata->cpu_set_freq)(unsigned long f) - -11. (*pdata->cpu_get_freq)(void) - -Customizing OPP for platform -============================ -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 - #include "pm.h" - .... - static void __init omap_xyz_init_irq(void) - { - .... - /* Initialize the default table */ - omapx_opp_init(); - /* Do customization to the defaults */ - .... - } -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 deleted file mode 100644 index a492233931b9..000000000000 --- a/Documentation/arm/Porting +++ /dev/null @@ -1,135 +0,0 @@ -Taken from list archive at http://lists.arm.linux.org.uk/pipermail/linux-arm-kernel/2001-July/004064.html - -Initial definitions -------------------- - -The following symbol definitions rely on you knowing the translation that -__virt_to_phys() does for your machine. This macro converts the passed -virtual address to a physical address. Normally, it is simply: - - phys = virt - PAGE_OFFSET + PHYS_OFFSET - - -Decompressor Symbols --------------------- - -ZTEXTADDR - Start address of decompressor. There's no point in talking about - virtual or physical addresses here, since the MMU will be off at - the time when you call the decompressor code. You normally call - the kernel at this address to start it booting. This doesn't have - to be located in RAM, it can be in flash or other read-only or - read-write addressable medium. - -ZBSSADDR - Start address of zero-initialised work area for the decompressor. - This must be pointing at RAM. The decompressor will zero initialise - this for you. Again, the MMU will be off. - -ZRELADDR - This is the address where the decompressed kernel will be written, - and eventually executed. The following constraint must be valid: - - __virt_to_phys(TEXTADDR) == ZRELADDR - - The initial part of the kernel is carefully coded to be position - independent. - -INITRD_PHYS - Physical address to place the initial RAM disk. Only relevant if - you are using the bootpImage stuff (which only works on the old - struct param_struct). - -INITRD_VIRT - Virtual address of the initial RAM disk. The following constraint - must be valid: - - __virt_to_phys(INITRD_VIRT) == INITRD_PHYS - -PARAMS_PHYS - Physical address of the struct param_struct or tag list, giving the - kernel various parameters about its execution environment. - - -Kernel Symbols --------------- - -PHYS_OFFSET - Physical start address of the first bank of RAM. - -PAGE_OFFSET - Virtual start address of the first bank of RAM. During the kernel - boot phase, virtual address PAGE_OFFSET will be mapped to physical - address PHYS_OFFSET, along with any other mappings you supply. - This should be the same value as TASK_SIZE. - -TASK_SIZE - The maximum size of a user process in bytes. Since user space - always starts at zero, this is the maximum address that a user - process can access+1. The user space stack grows down from this - address. - - Any virtual address below TASK_SIZE is deemed to be user process - area, and therefore managed dynamically on a process by process - basis by the kernel. I'll call this the user segment. - - Anything above TASK_SIZE is common to all processes. I'll call - this the kernel segment. - - (In other words, you can't put IO mappings below TASK_SIZE, and - hence PAGE_OFFSET). - -TEXTADDR - Virtual start address of kernel, normally PAGE_OFFSET + 0x8000. - This is where the kernel image ends up. With the latest kernels, - it must be located at 32768 bytes into a 128MB region. Previous - kernels placed a restriction of 256MB here. - -DATAADDR - Virtual address for the kernel data segment. Must not be defined - when using the decompressor. - -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). - Normally, the vmalloc() area starts VMALLOC_OFFSET bytes above the - last virtual RAM address (found using variable high_memory). - -VMALLOC_OFFSET - Offset normally incorporated into VMALLOC_START to provide a hole - between virtual RAM and the vmalloc area. We do this to allow - out of bounds memory accesses (eg, something writing off the end - of the mapped memory map) to be caught. Normally set to 8MB. - -Architecture Specific Macros ----------------------------- - -BOOT_MEM(pram,pio,vio) - `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 - use with the debugging macros in arch/arm/kernel/debug-armv.S. - - `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 - MAPIO function). - -BOOT_PARAMS - Same as, and see PARAMS_PHYS. - -FIXUP(func) - Machine specific fixups, run before memory subsystems have been - initialised. - -MAPIO(func) - Machine specific function to map IO areas (including the debug - region above). - -INITIRQ(func) - Machine specific function to initialise interrupts. - diff --git a/Documentation/arm/README b/Documentation/arm/README deleted file mode 100644 index 9d1e5b2c92e6..000000000000 --- a/Documentation/arm/README +++ /dev/null @@ -1,204 +0,0 @@ - ARM Linux 2.6 - ============= - - Please check for - updates. - -Compilation of kernel ---------------------- - - In order to compile ARM Linux, you will need a compiler capable of - generating ARM ELF code with GNU extensions. GCC 3.3 is known to be - a good compiler. Fortunately, you needn't guess. The kernel will report - an error if your compiler is a recognized offender. - - To build ARM Linux natively, you shouldn't have to alter the ARCH = line - in the top level Makefile. However, if you don't have the ARM Linux ELF - tools installed as default, then you should change the CROSS_COMPILE - line as detailed below. - - If you wish to cross-compile, then alter the following lines in the top - level make file: - - ARCH = - with - ARCH = arm - - and - - CROSS_COMPILE= - to - CROSS_COMPILE= - 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 - 'make zImage' instead of 'make Image'. - - -Bug reports etc ---------------- - - Please send patches to the patch system. For more information, see - http://www.arm.linux.org.uk/developer/patches/info.php Always include some - explanation as to what the patch does and why it is needed. - - 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/ - - When sending bug reports, please ensure that they contain all relevant - information, eg. the kernel messages that were printed before/during - the problem, what you were doing, etc. - - -Include files -------------- - - Several new include directories have been created under include/asm-arm, - 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 - categories) - - -Machine/Platform support ------------------------- - - The ARM tree contains support for a lot of different machine types. To - continue supporting these differences, it has become necessary to split - machine-specific parts by directory. For this, the machine category is - used to select which directories and files get included (we will use - $(MACHINE) to refer to the category) - - To this end, we now have arch/arm/mach-$(MACHINE) directories which are - designed to house the non-driver files for a particular machine (eg, PCI, - memory management, architecture definitions etc). For all future - machines, there should be a corresponding arch/arm/mach-$(MACHINE)/include/mach - directory. - - -Modules -------- - - Although modularisation is supported (and required for the FP emulator), - each module on an ARM2/ARM250/ARM3 machine when is loaded will take - memory up to the next 32k boundary due to the size of the pages. - Therefore, is modularisation on these machines really worth it? - - However, ARM6 and up machines allow modules to take multiples of 4k, and - as such Acorn RiscPCs and other architectures using these processors can - make good use of modularisation. - - -ADFS Image files ----------------- - - You can access image files on your ADFS partitions by mounting the ADFS - partition, and then using the loopback device driver. You must have - losetup installed. - - Please note that the PCEmulator DOS partitions have a partition table at - the start, and as such, you will have to give '-o offset' to losetup. - - -Request to developers ---------------------- - - When writing device drivers which include a separate assembler file, please - include it in with the C file, and not the arch/arm/lib directory. This - allows the driver to be compiled as a loadable module without requiring - half the code to be compiled into the kernel image. - - In general, try to avoid using assembler unless it is really necessary. It - makes drivers far less easy to port to other hardware. - - -ST506 hard drives ------------------ - - The ST506 hard drive controllers seem to be working fine (if a little - slowly). At the moment they will only work off the controllers on an - A4x0's motherboard, but for it to work off a Podule just requires - someone with a podule to add the addresses for the IRQ mask and the - 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 - 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 - RiscOS gets; but it's a heck of a lot better than the 50K/s I was getting - last week :-) - - Known bug: Drive data errors can cause a hang; including cases where - the controller has fixed the error using ECC. (Possibly ONLY - in that case...hmm). - - -1772 Floppy ------------ - This also seems to work OK, but hasn't been stressed much lately. It - hasn't got any code for disc change detection in there at the moment which - could be a bit of a problem! Suggestions on the correct way to do this - are welcome. - - -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, - 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 - not been made because it would complicate patching. - - Previous registrations may be found online. - - - -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. - - Due to the large number of machines which the ARM port of Linux provides - for, we have a method to manage this which ensures that we don't end up - duplicating large amounts of code. - - We group machine (or platform) support code into machine classes. A - class typically based around one or more system on a chip devices, and - acts as a natural container around the actual implementations. These - classes are given directories - arch/arm/mach- and - arch/arm/mach- - which contain the source files to/include/mach - support the machine class. This directories also contain any machine - specific supporting code. - - For example, the SA1100 class is based upon the SA1100 and SA1110 SoC - devices, and contains the code to support the way the on-board and off- - board devices are used, or the device is setup, and provides that - machine specific "personality." - - For platforms that support device tree (DT), the machine selection is - controlled at runtime by passing the device tree blob to the kernel. At - compile-time, support for the machine type must be selected. This allows for - a single multiplatform kernel build to be used for several machine types. - - For platforms that do not use device tree, this machine selection is - controlled by the machine type ID, which acts both as a run-time and a - compile-time code selection method. You can register a new machine via the - web site at: - - - - Note: Please do not register a machine type for DT-only platforms. If your - platform is DT-only, you do not need a registered machine type. - ---- -Russell King (15/03/2004) diff --git a/Documentation/arm/SA1100/ADSBitsy b/Documentation/arm/SA1100/ADSBitsy deleted file mode 100644 index f9f62e8c0719..000000000000 --- a/Documentation/arm/SA1100/ADSBitsy +++ /dev/null @@ -1,43 +0,0 @@ -ADS Bitsy Single Board Computer -(It is different from Bitsy(iPAQ) of Compaq) - -For more details, contact Applied Data Systems or see -http://www.applieddata.net/products.html - -The Linux support for this product has been provided by -Woojung Huh - -Use 'make adsbitsy_config' before any 'make config'. -This will set up defaults for ADS Bitsy support. - -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: -- SA1100 LCD frame buffer (8/16bpp...sort of) -- SA1111 USB Master -- SA1100 serial port -- pcmcia, compact flash -- touchscreen(ucb1200) -- console on LCD screen -- serial ports (ttyS[0-2]) - - ttyS0 is default for serial console - -To do: -- everything else! :-) - -Notes: - -- The flash on board is divided into 3 partitions. - You should be careful to use flash on board. - Its partition is different from GraphicsClient Plus and GraphicsMaster - -- 16bpp mode requires a different cable than what ships with the board. - Contact ADS or look through the manual to wire your own. Currently, - if you compile with 16bit mode support and switch into a lower bpp - mode, the timing is off so the image is corrupted. This will be - fixed soon. - -Any contribution can be sent to nico@fluxnic.net and will be greatly welcome! diff --git a/Documentation/arm/SA1100/Assabet b/Documentation/arm/SA1100/Assabet deleted file mode 100644 index e08a6739e72c..000000000000 --- a/Documentation/arm/SA1100/Assabet +++ /dev/null @@ -1,300 +0,0 @@ -The Intel Assabet (SA-1110 evaluation) board -============================================ - -Please see: -http://developer.intel.com - -Also some notes from John G Dorsey : -http://www.cs.cmu.edu/~wearable/software/assabet.html - - -Building the kernel -------------------- - -To build the kernel with current defaults: - - make assabet_config - make oldconfig - make zImage - -The resulting kernel image should be available in linux/arch/arm/boot/zImage. - - -Installing a bootloader ------------------------ - -A couple of bootloaders able to boot Linux on Assabet are available: - -BLOB (http://www.lartmaker.nl/lartware/blob/) - - BLOB is a bootloader used within the LART project. Some contributed - patches were merged into BLOB to add support for Assabet. - -Compaq's Bootldr + John Dorsey's patch for Assabet support -(http://www.handhelds.org/Compaq/bootldr.html) -(http://www.wearablegroup.org/software/bootldr/) - - Bootldr is the bootloader developed by Compaq for the iPAQ Pocket PC. - John Dorsey has produced add-on patches to add support for Assabet and - the JFFS filesystem. - -RedBoot (http://sources.redhat.com/redboot/) - - RedBoot is a bootloader developed by Red Hat based on the eCos RTOS - hardware abstraction layer. It supports Assabet amongst many other - hardware platforms. - -RedBoot is currently the recommended choice since it's the only one to have -networking support, and is the most actively maintained. - -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/ - -Look for redboot-assabet*.tgz. Some installation infos are provided in -redboot-assabet*.txt. - - -Initial RedBoot configuration ------------------------------ - -The commands used here are explained in The RedBoot User's Guide available -on-line at http://sources.redhat.com/ecos/docs.html. -Please refer to it for explanations. - -If you have a CF network card (my Assabet kit contained a CF+ LP-E from -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: - - 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: - - fconfig -i - - -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: - - load zImage -r -b 0x100000 - -If you rather want to use Y-Modem upload over the serial port: - - load -m ymodem -r -b 0x100000 - -To write it to flash: - - fis create "Linux kernel" -b 0x100000 -l 0xc0000 - - -Booting the kernel ------------------- - -The kernel still requires a filesystem to boot. A ramdisk image can be loaded -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: - - fis load "Linux kernel" - -or loaded as described previously. To boot the kernel: - - exec -b 0x100000 -l 0xc0000 - -The ramdisk image could be stored into flash as well, but there are better -solutions for on-flash filesystems as mentioned below. - - -Using JFFS2 ------------ - -Using JFFS2 (the Second Journalling Flash File System) is probably the most -convenient way to store a writable filesystem into flash. JFFS2 is used in -conjunction with the MTD layer which is responsible for low-level flash -management. More information on the Linux MTD can be found on-line at: -http://www.linux-mtd.infradead.org/. A JFFS howto with some infos about -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: - - load sample_img.jffs2 -r -b 0x100000 - -The result should look like: - -RedBoot> load sample_img.jffs2 -r -b 0x100000 -Raw file loaded 0x00100000-0x00377424 - -Now we must know the size of the unallocated flash: - - fis free - -Result: - -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: - -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: - - fis unlock -f 0x500E0000 -l 0x2e0000 - fis erase -f 0x500E0000 -l 0x2e0000 - fis write -b 0x100000 -l 0x277424 -f 0x500E0000 - fis create "JFFS2" -n -f 0x500E0000 -l 0x2e0000 - -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: - -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: - -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: - - fis load "Linux kernel" - exec -b 0x100000 -l 0xc0000 -c "root=/dev/mtdblock2" - -Of course other filesystems than JFFS might be used, like cramfs for example. -You might want to boot with a root filesystem over NFS, etc. It is also -possible, and sometimes more convenient, to flash a filesystem directly from -within Linux while booted from a ramdisk or NFS. The Linux MTD repository has -many tools to deal with flash memory as well, to erase it for example. JFFS2 -can then be mounted directly on a freshly erased partition and files can be -copied over directly. Etc... - - -RedBoot scripting ------------------ - -All the commands above aren't so useful if they have to be typed in every -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: - -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. - - - -Nicolas Pitre -nico@fluxnic.net -June 12, 2001 - - -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. - - Video: - 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. - - 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. - - Other: - 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. - -More stuff can be found in the -np (Nicolas Pitre's) tree. - diff --git a/Documentation/arm/SA1100/Brutus b/Documentation/arm/SA1100/Brutus deleted file mode 100644 index 6a3aa95e9bfd..000000000000 --- a/Documentation/arm/SA1100/Brutus +++ /dev/null @@ -1,66 +0,0 @@ -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: - - make brutus_config - make config - [accept all the defaults] - make zImage - -The resulting kernel will end up in linux/arch/arm/boot/zImage. This file -must be loaded at 0xc0008000 in Brutus's memory and execution started at -0xc0008000 as well with the value of registers r0 = 0 and r1 = 16 upon -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 -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: - ------ 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 ----- - -Then load the kernel and ramdisk with: - - angelboot -f angelboot.opt zImage - -The first Brutus serial port (assumed to be linked to /dev/ttyS0 on your -host PC) is used by angel to load the kernel and ramdisk image. The serial -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: - - 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 -ftp.netwinder.org/users/n/nico. - -A full PCMCIA support is still missing, although it's possible to hack -some drivers in order to drive already inserted cards at boot time with -little modifications. - -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 deleted file mode 100644 index b3d845301ef1..000000000000 --- a/Documentation/arm/SA1100/CERF +++ /dev/null @@ -1,29 +0,0 @@ -*** The StrongARM version of the CerfBoard/Cube has been discontinued *** - -The Intrinsyc CerfBoard is a StrongARM 1110-based computer on a board -that measures approximately 2" square. It includes an Ethernet -controller, an RS232-compatible serial port, a USB function port, and -one CompactFlash+ slot on the back. Pictures can be found at the -Intrinsyc website, http://www.intrinsyc.com. - -This document describes the support in the Linux kernel for the -Intrinsyc CerfBoard. - -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 - Network Devices) - - Serial ports with a serial console (hardcoded to 38400 8N1) - -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: - - make ARCH=arm CROSS_COMPILE=arm-linux- cerfcube_defconfig - make ARCH=arm CROSS_COMPILE=arm-linux- zImage - make ARCH=arm CROSS_COMPILE=arm-linux- modules - cp arch/arm/boot/zImage - -support@intrinsyc.com 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/GraphicsClient b/Documentation/arm/SA1100/GraphicsClient deleted file mode 100644 index 867bb35943af..000000000000 --- a/Documentation/arm/SA1100/GraphicsClient +++ /dev/null @@ -1,98 +0,0 @@ -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 -Nicolas Pitre . Continued development work by -Woojung Huh - -It's currently possible to mount a root filesystem via NFS providing a -complete Linux environment. Otherwise a ramdisk image may be used. The -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: - - r0 = 0 - r1 = 29 (this is the GraphicsClient architecture number) - -Linux can be used with the ADS BootLoader that ships with the -newer rev boards. See their documentation on how to load Linux. -Angel is not available for the GraphicsClient Plus AFAIK. - -There is a board known as just the GraphicsClient that ADS used to -produce but has end of lifed. This code will not work on the older -board with the ADS bootloader, but should still work with Angel, -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: - ------ 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 ----- - -Then the kernel (and ramdisk if otherfile/otherbase lines above are -uncommented) would be loaded with: - - angelboot -f angelboot.opt zImage - -Here it is assumed that the board is connected to ttyS1 on your PC -and that minicom is preconfigured with /dev/ttyS1, 38400 baud, 8N1, no flow -control by default. - -If any other bootloader is used, ensure it accomplish the same, especially -for r0/r1 register values before jumping into the kernel. - - -Supported peripherals: -- SA1100 LCD frame buffer (8/16bpp...sort of) -- on-board SMC 92C96 ethernet NIC -- SA1100 serial port -- flash memory access (MTD/JFFS) -- pcmcia -- touchscreen(ucb1200) -- ps/2 keyboard -- console on LCD screen -- serial ports (ttyS[0-2]) - - ttyS0 is default for serial console -- Smart I/O (ADC, keypad, digital inputs, etc) - 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: -- UCB1200 audio with new ucb_generic layer -- everything else! :-) - -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 - read-only to keep you from blasting over the bootloader. :) mtd1 is - for the ramdisk.gz image. mtd2 is user flash space and can be - utilized for either JFFS or if you're feeling crazy, running ext2 - on top of it. If you're not using the ADS bootloader, you're - welcome to blast over the mtd1 partition also. - -- 16bpp mode requires a different cable than what ships with the board. - Contact ADS or look through the manual to wire your own. Currently, - if you compile with 16bit mode support and switch into a lower bpp - mode, the timing is off so the image is corrupted. This will be - 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 deleted file mode 100644 index 9145088a0ba2..000000000000 --- a/Documentation/arm/SA1100/GraphicsMaster +++ /dev/null @@ -1,53 +0,0 @@ -ADS GraphicsMaster 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 -Nicolas Pitre . Continued development work by -Woojung Huh - -Use 'make graphicsmaster_config' before any 'make config'. -This will set up defaults for GraphicsMaster support. - -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: -- SA1100 LCD frame buffer (8/16bpp...sort of) -- SA1111 USB Master -- on-board SMC 92C96 ethernet NIC -- SA1100 serial port -- flash memory access (MTD/JFFS) -- pcmcia, compact flash -- touchscreen(ucb1200) -- ps/2 keyboard -- console on LCD screen -- serial ports (ttyS[0-2]) - - ttyS0 is default for serial console -- Smart I/O (ADC, keypad, digital inputs, etc) - 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: -- everything else! :-) - -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 - from blasting over the bootloader. :) mtd1 is - for the ramdisk.gz image. mtd2 is user flash space and can be - utilized for either JFFS or if you're feeling crazy, running ext2 - on top of it. If you're not using the ADS bootloader, you're - welcome to blast over the mtd1 partition also. - -- 16bpp mode requires a different cable than what ships with the board. - Contact ADS or look through the manual to wire your own. Currently, - if you compile with 16bit mode support and switch into a lower bpp - mode, the timing is off so the image is corrupted. This will be - fixed soon. - -Any contribution can be sent to nico@fluxnic.net and will be greatly welcome! diff --git a/Documentation/arm/SA1100/HUW_WEBPANEL b/Documentation/arm/SA1100/HUW_WEBPANEL deleted file mode 100644 index fd56b48d4833..000000000000 --- a/Documentation/arm/SA1100/HUW_WEBPANEL +++ /dev/null @@ -1,17 +0,0 @@ -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: - make huw_webpanel_config - make oldconfig - [accept all defaults] - make zImage - -Mostly of the work is done by: -Roman Jordan jor@hoeft-wessel.de -Christoph Schulz schu@hoeft-wessel.de - -2000/12/18/ - diff --git a/Documentation/arm/SA1100/Itsy b/Documentation/arm/SA1100/Itsy deleted file mode 100644 index 44b94997fa0d..000000000000 --- a/Documentation/arm/SA1100/Itsy +++ /dev/null @@ -1,39 +0,0 @@ -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. - -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 -enabled. - -To build, do a "make menuconfig" (or xmenuconfig) and select Itsy support. -Disable Flash and LCD support. and then do a make zImage. -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 -Make sure the start-routine address is set to 0x00060000. - -Next, flash the params-itsy program to 0x00060000 ("p 1 0x00060000" in the -flash menu) Flash the kernel in arch/arm/boot/zImage into 0x08340000 -("p 1 0x00340000"). Finally flash an initial ramdisk into 0xC8000000 -("p 2 0x0") We used ramdisk-2-30.gz from the 0.11 version directory on -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 -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 -the itsy. (i.e. grep for CONFIG_SA1100_ITSY and you'll find where it is.) - - -This should get you a properly booting 2.4 kernel on the itsy. diff --git a/Documentation/arm/SA1100/LART b/Documentation/arm/SA1100/LART deleted file mode 100644 index 6d412b685598..000000000000 --- a/Documentation/arm/SA1100/LART +++ /dev/null @@ -1,14 +0,0 @@ -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 -other StrongARM-gadgets. Almost all SA signals are directly accessible -through a number of connectors. The powersupply accepts voltages -between 3.5V and 16V and is overdimensioned to support a range of -daughterboards. A quad Ethernet / IDE / PS2 / sound daughterboard -is under development, with plenty of others in different stages of -planning. - -The hardware designs for this board have been released under an open license; -see the LART page at http://www.lartmaker.nl/ for more information. diff --git a/Documentation/arm/SA1100/PLEB b/Documentation/arm/SA1100/PLEB deleted file mode 100644 index b9c8a631a351..000000000000 --- a/Documentation/arm/SA1100/PLEB +++ /dev/null @@ -1,11 +0,0 @@ -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. - -PLEB support has yet to be fully integrated. - -For more information, see: - - http://www.cse.unsw.edu.au - - diff --git a/Documentation/arm/SA1100/Pangolin b/Documentation/arm/SA1100/Pangolin deleted file mode 100644 index 077a6120e129..000000000000 --- a/Documentation/arm/SA1100/Pangolin +++ /dev/null @@ -1,23 +0,0 @@ -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: - - make pangolin_config - make oldconfig - make zImage - -Supported peripherals: -- SA1110 serial port (UART1/UART2/UART3) -- flash memory access -- compact flash driver -- UDA1341 sound driver -- SA1100 LCD controller for 800x600 16bpp TFT-LCD -- MQ-200 driver for 800x600 16bpp TFT-LCD -- Penmount(touch panel) driver -- PCMCIA driver -- SMC91C94 LAN driver -- IDE driver (experimental) diff --git a/Documentation/arm/SA1100/Tifon b/Documentation/arm/SA1100/Tifon deleted file mode 100644 index dd1934d9c851..000000000000 --- a/Documentation/arm/SA1100/Tifon +++ /dev/null @@ -1,7 +0,0 @@ -Tifon ------ - -More info has to come... - -Contact: Peter Danielsson - diff --git a/Documentation/arm/SA1100/Yopy b/Documentation/arm/SA1100/Yopy deleted file mode 100644 index e14f16d836ac..000000000000 --- a/Documentation/arm/SA1100/Yopy +++ /dev/null @@ -1,2 +0,0 @@ -See http://www.yopydeveloper.org for more. - 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/nanoEngine b/Documentation/arm/SA1100/nanoEngine deleted file mode 100644 index 48a7934f95f6..000000000000 --- a/Documentation/arm/SA1100/nanoEngine +++ /dev/null @@ -1,11 +0,0 @@ -nanoEngine ----------- - -"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/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/SH-Mobile/.gitignore b/Documentation/arm/SH-Mobile/.gitignore deleted file mode 100644 index c928dbf3cc88..000000000000 --- a/Documentation/arm/SH-Mobile/.gitignore +++ /dev/null @@ -1 +0,0 @@ -vrl4 diff --git a/Documentation/arm/SPEAr/overview.txt b/Documentation/arm/SPEAr/overview.txt deleted file mode 100644 index 1b049be6c84f..000000000000 --- a/Documentation/arm/SPEAr/overview.txt +++ /dev/null @@ -1,63 +0,0 @@ - SPEAr ARM Linux Overview - ========================== - -Introduction ------------- - - SPEAr (Structured Processor Enhanced Architecture). - weblink : http://www.st.com/spear - - The ST Microelectronics SPEAr range of ARM9/CortexA9 System-on-Chip CPUs are - supported by the 'spear' platform of ARM Linux. Currently SPEAr1310, - SPEAr1340, SPEAr300, SPEAr310, SPEAr320 and SPEAr600 SOCs are supported. - - Hierarchy in SPEAr is as follows: - - SPEAr (Platform) - - SPEAr3XX (3XX SOC series, based on ARM9) - - SPEAr300 (SOC) - - SPEAr300 Evaluation Board - - SPEAr310 (SOC) - - SPEAr310 Evaluation Board - - SPEAr320 (SOC) - - SPEAr320 Evaluation Board - - SPEAr6XX (6XX SOC series, based on ARM9) - - SPEAr600 (SOC) - - SPEAr600 Evaluation Board - - SPEAr13XX (13XX SOC series, based on ARM CORTEXA9) - - SPEAr1310 (SOC) - - SPEAr1310 Evaluation Board - - SPEAr1340 (SOC) - - SPEAr1340 Evaluation Board - - Configuration - ------------- - - A generic configuration is provided for each machine, and can be used as the - default by - make spear13xx_defconfig - make spear3xx_defconfig - make spear6xx_defconfig - - Layout - ------ - - The common files for multiple machine families (SPEAr3xx, SPEAr6xx and - SPEAr13xx) are located in the platform code contained in arch/arm/plat-spear - with headers in plat/. - - Each machine series have a directory with name arch/arm/mach-spear followed by - series name. Like mach-spear3xx, mach-spear6xx and mach-spear13xx. - - Common file for machines of spear3xx family is mach-spear3xx/spear3xx.c, for - spear6xx is mach-spear6xx/spear6xx.c and for spear13xx family is - mach-spear13xx/spear13xx.c. mach-spear* also contain soc/machine specific - files, like spear1310.c, spear1340.c spear300.c, spear310.c, spear320.c and - spear600.c. mach-spear* doesn't contains board specific files as they fully - support Flattened Device Tree. - - - Document Author - --------------- - - Viresh Kumar , (c) 2010-2012 ST Microelectronics diff --git a/Documentation/arm/Samsung-S3C24XX/CPUfreq.txt b/Documentation/arm/Samsung-S3C24XX/CPUfreq.txt deleted file mode 100644 index fa968aa99d67..000000000000 --- a/Documentation/arm/Samsung-S3C24XX/CPUfreq.txt +++ /dev/null @@ -1,75 +0,0 @@ - S3C24XX CPUfreq support - ======================= - -Introduction ------------- - - The S3C24XX series support a number of power saving systems, such as - the ability to change the core, memory and peripheral operating - frequencies. The core control is exported via the CPUFreq driver - which has a number of different manual or automatic controls over the - rate the core is running at. - - There are two forms of the driver depending on the specific CPU and - how the clocks are arranged. The first implementation used as single - PLL to feed the ARM, memory and peripherals via a series of dividers - and muxes and this is the implementation that is documented here. A - newer version where there is a separate PLL and clock divider for the - ARM core is available as a separate driver. - - -Layout ------- - - The code core manages the CPU specific drivers, any data that they - need to register and the interface to the generic drivers/cpufreq - system. Each CPU registers a driver to control the PLL, clock dividers - and anything else associated with it. Any board that wants to use this - framework needs to supply at least basic details of what is required. - - The core registers with drivers/cpufreq at init time if all the data - necessary has been supplied. - - -CPU support ------------ - - The support for each CPU depends on the facilities provided by the - SoC and the driver as each device has different PLL and clock chains - associated with it. - - -Slow Mode ---------- - - The SLOW mode where the PLL is turned off altogether and the - system is fed by the external crystal input is currently not - supported. - - -sysfs ------ - - The core code exports extra information via sysfs in the directory - devices/system/cpu/cpu0/arch-freq. - - -Board Support -------------- - - Each board that wants to use the cpufreq code must register some basic - information with the core driver to provide information about what the - board requires and any restrictions being placed on it. - - The board needs to supply information about whether it needs the IO bank - timings changing, any maximum frequency limits and information about the - SDRAM refresh rate. - - - - -Document Author ---------------- - -Ben Dooks, Copyright 2009 Simtec Electronics -Licensed under GPLv2 diff --git a/Documentation/arm/Samsung-S3C24XX/EB2410ITX.txt b/Documentation/arm/Samsung-S3C24XX/EB2410ITX.txt deleted file mode 100644 index b87292e05f2f..000000000000 --- a/Documentation/arm/Samsung-S3C24XX/EB2410ITX.txt +++ /dev/null @@ -1,58 +0,0 @@ - Simtec Electronics EB2410ITX (BAST) - =================================== - - http://www.simtec.co.uk/products/EB2410ITX/ - -Introduction ------------- - - The EB2410ITX is a S3C2410 based development board with a variety of - peripherals and expansion connectors. This board is also known by - the shortened name of Bast. - - -Configuration -------------- - - To set the default configuration, use `make bast_defconfig` which - supports the commonly used features of this board. - - -Support -------- - - Official support information can be found on the Simtec Electronics - website, at the product page http://www.simtec.co.uk/products/EB2410ITX/ - - Useful links: - - - Resources Page http://www.simtec.co.uk/products/EB2410ITX/resources.html - - - Board FAQ at http://www.simtec.co.uk/products/EB2410ITX/faq.html - - - Bootloader info http://www.simtec.co.uk/products/SWABLE/resources.html - and FAQ http://www.simtec.co.uk/products/SWABLE/faq.html - - -MTD ---- - - The NAND and NOR support has been merged from the linux-mtd project. - Any problems, see http://www.linux-mtd.infradead.org/ for more - information or up-to-date versions of linux-mtd. - - -IDE ---- - - Both onboard IDE ports are supported, however there is no support for - changing speed of devices, PIO Mode 4 capable drives should be used. - - -Maintainers ------------ - - This board is maintained by Simtec Electronics. - - -Copyright 2004 Ben Dooks, Simtec Electronics diff --git a/Documentation/arm/Samsung-S3C24XX/GPIO.txt b/Documentation/arm/Samsung-S3C24XX/GPIO.txt deleted file mode 100644 index e8f918b96123..000000000000 --- a/Documentation/arm/Samsung-S3C24XX/GPIO.txt +++ /dev/null @@ -1,171 +0,0 @@ - S3C24XX GPIO Control - ==================== - -Introduction ------------- - - The s3c2410 kernel provides an interface to configure and - manipulate the state of the GPIO pins, and find out other - information about them. - - There are a number of conditions attached to the configuration - 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. - - -GPIOLIB -------- - - With the event of the GPIOLIB in drivers/gpio, support for some - of the GPIO functions such as reading and writing a pin will - be removed in favour of this common access method. - - Once all the extant drivers have been converted, the functions - 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 - 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() - - -GPIOLIB conversion ------------------- - -If you need to convert your board or driver to use gpiolib from the phased -out s3c2410 API, then here are some notes on the process. - -1) If your board is exclusively using an GPIO, say to control peripheral - power, then it will require to claim the gpio with gpio_request() before - it can use it. - - It is recommended to check the return value, with at least WARN_ON() - during initialisation. - -2) The s3c2410_gpio_cfgpin() can be directly replaced with s3c_gpio_cfgpin() - as they have the same arguments, and can either take the pin specific - values, or the more generic special-function-number arguments. - -3) s3c2410_gpio_pullup() changes have the problem that while the - s3c2410_gpio_pullup(x, 1) can be easily translated to the - s3c_gpio_setpull(x, S3C_GPIO_PULL_NONE), the s3c2410_gpio_pullup(x, 0) - are not so easy. - - The s3c2410_gpio_pullup(x, 0) case enables the pull-up (or in the case - of some of the devices, a pull-down) and as such the new API distinguishes - between the UP and DOWN case. There is currently no 'just turn on' setting - which may be required if this becomes a problem. - -4) s3c2410_gpio_setpin() can be replaced by gpio_set_value(), the old call - does not implicitly configure the relevant gpio to output. The gpio - direction should be changed before using gpio_set_value(). - -5) s3c2410_gpio_getpin() is replaceable by gpio_get_value() if the pin - has been set to input. It is currently unknown what the behaviour is - when using gpio_get_value() on an output pin (s3c2410_gpio_getpin - would return the value the pin is supposed to be outputting). - -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 -numberspace, so there is no problem with converting the gpio numbering -between the calls. - - -Headers -------- - - See arch/arm/mach-s3c24xx/include/mach/regs-gpio.h for the list - of GPIO pins, and the configuration values for them. This - is included by using #include - - -PIN Numbers ------------ - - Each pin has an unique number associated with it in regs-gpio.h, - e.g. S3C2410_GPA(0) or S3C2410_GPF(1). These defines are used to tell - the GPIO functions which pin is to be used. - - With the conversion to gpiolib, there is no longer a direct conversion - from gpio pin number to register base address as in earlier kernels. This - is due to the number space required for newer SoCs where the later - GPIOs are not contiguous. - - -Configuring a pin ------------------ - - The following function allows the configuration of a given pin to - be changed. - - void s3c_gpio_cfgpin(unsigned int pin, unsigned int function); - - e.g.: - - s3c_gpio_cfgpin(S3C2410_GPA(0), S3C_GPIO_SFN(1)); - s3c_gpio_cfgpin(S3C2410_GPE(8), S3C_GPIO_SFN(2)); - - which would turn GPA(0) into the lowest Address line A0, and set - GPE(8) to be connected to the SDIO/MMC controller's SDDAT1 line. - - -Reading the current configuration ---------------------------------- - - The current configuration of a pin can be read by using standard - gpiolib function: - - s3c_gpio_getcfg(unsigned int pin); - - The return value will be from the same set of values which can be - passed to s3c_gpio_cfgpin(). - - -Configuring a pull-up resistor ------------------------------- - - A large proportion of the GPIO pins on the S3C2410 can have weak - pull-up resistors enabled. This can be configured by the following - function: - - void s3c_gpio_setpull(unsigned int pin, unsigned int to); - - Where the to value is S3C_GPIO_PULL_NONE to set the pull-up off, - and S3C_GPIO_PULL_UP to enable the specified pull-up. Any other - values are currently undefined. - - -Getting and setting the state of a PIN --------------------------------------- - - These calls are now implemented by the relevant gpiolib calls, convert - your board or driver to use gpiolib. - - -Getting the IRQ number associated with a PIN --------------------------------------------- - - A standard gpiolib function can map the given pin number to an IRQ - number to pass to the IRQ system. - - int gpio_to_irq(unsigned int pin); - - Note, not all pins have an IRQ. - - -Author -------- - -Ben Dooks, 03 October 2004 -Copyright 2004 Ben Dooks, Simtec Electronics diff --git a/Documentation/arm/Samsung-S3C24XX/H1940.txt b/Documentation/arm/Samsung-S3C24XX/H1940.txt deleted file mode 100644 index b738859b1fc0..000000000000 --- a/Documentation/arm/Samsung-S3C24XX/H1940.txt +++ /dev/null @@ -1,40 +0,0 @@ - HP IPAQ H1940 - ============= - -http://www.handhelds.org/projects/h1940.html - -Introduction ------------- - - The HP H1940 is a S3C2410 based handheld device, with - bluetooth connectivity. - - -Support -------- - - A variety of information is available - - handhelds.org project page: - - http://www.handhelds.org/projects/h1940.html - - handhelds.org wiki page: - - http://handhelds.org/moin/moin.cgi/HpIpaqH1940 - - Herbert Pötzl pages: - - http://vserver.13thfloor.at/H1940/ - - -Maintainers ------------ - - This project is being maintained and developed by a variety - of people, including Ben Dooks, Arnaud Patard, and Herbert Pötzl. - - Thanks to the many others who have also provided support. - - -(c) 2005 Ben Dooks diff --git a/Documentation/arm/Samsung-S3C24XX/NAND.txt b/Documentation/arm/Samsung-S3C24XX/NAND.txt deleted file mode 100644 index bc478a3409b8..000000000000 --- a/Documentation/arm/Samsung-S3C24XX/NAND.txt +++ /dev/null @@ -1,30 +0,0 @@ - S3C24XX NAND Support - ==================== - -Introduction ------------- - -Small Page NAND ---------------- - -The driver uses a 512 byte (1 page) ECC code for this setup. The -ECC code is not directly compatible with the default kernel ECC -code, so the driver enforces its own OOB layout and ECC parameters - -Large Page NAND ---------------- - -The driver is capable of handling NAND flash with a 2KiB page -size, with support for hardware ECC generation and correction. - -Unlike the 512byte page mode, the driver generates ECC data for -each 256 byte block in an 2KiB page. This means that more than -one error in a page can be rectified. It also means that the -OOB layout remains the default kernel layout for these flashes. - - -Document Author ---------------- - -Ben Dooks, Copyright 2007 Simtec Electronics - diff --git a/Documentation/arm/Samsung-S3C24XX/Overview.txt b/Documentation/arm/Samsung-S3C24XX/Overview.txt deleted file mode 100644 index 00d3c3141e21..000000000000 --- a/Documentation/arm/Samsung-S3C24XX/Overview.txt +++ /dev/null @@ -1,318 +0,0 @@ - S3C24XX ARM Linux Overview - ========================== - - - -Introduction ------------- - - The Samsung S3C24XX range of ARM9 System-on-Chip CPUs are supported - by the 's3c2410' architecture of ARM Linux. Currently the S3C2410, - S3C2412, S3C2413, S3C2416, S3C2440, S3C2442, S3C2443 and S3C2450 devices - are supported. - - Support for the S3C2400 and S3C24A0 series was never completed and the - corresponding code has been removed after a while. If someone wishes to - revive this effort, partial support can be retrieved from earlier Linux - versions. - - The S3C2416 and S3C2450 devices are very similar and S3C2450 support is - included under the arch/arm/mach-s3c2416 directory. Note, while core - support for these SoCs is in, work on some of the extra peripherals - and extra interrupts is still ongoing. - - -Configuration -------------- - - A generic S3C2410 configuration is provided, and can be used as the - default by `make s3c2410_defconfig`. This configuration has support - for all the machines, and the commonly used features on them. - - Certain machines may have their own default configurations as well, - please check the machine specific documentation. - - -Layout ------- - - The core support files are located in the platform code contained in - arch/arm/plat-s3c24xx with headers in include/asm-arm/plat-s3c24xx. - This directory should be kept to items shared between the platform - code (arch/arm/plat-s3c24xx) and the arch/arm/mach-s3c24* code. - - Each cpu has a directory with the support files for it, and the - machines that carry the device. For example S3C2410 is contained - in arch/arm/mach-s3c2410 and S3C2440 in arch/arm/mach-s3c2440 - - Register, kernel and platform data definitions are held in the - arch/arm/mach-s3c2410 directory./include/mach - -arch/arm/plat-s3c24xx: - - Files in here are either common to all the s3c24xx family, - or are common to only some of them with names to indicate this - status. The files that are not common to all are generally named - with the initial cpu they support in the series to ensure a short - name without any possibility of confusion with newer devices. - - As an example, initially s3c244x would cover s3c2440 and s3c2442, but - with the s3c2443 which does not share many of the same drivers in - this directory, the name becomes invalid. We stick to s3c2440- - to indicate a driver that is s3c2440 and s3c2442 compatible. - - This does mean that to find the status of any given SoC, a number - of directories may need to be searched. - - -Machines --------- - - The currently supported machines are as follows: - - Simtec Electronics EB2410ITX (BAST) - - A general purpose development board, see EB2410ITX.txt for further - details - - Simtec Electronics IM2440D20 (Osiris) - - CPU Module from Simtec Electronics, with a S3C2440A CPU, nand flash - and a PCMCIA controller. - - Samsung SMDK2410 - - Samsung's own development board, geared for PDA work. - - Samsung/Aiji SMDK2412 - - The S3C2412 version of the SMDK2440. - - Samsung/Aiji SMDK2413 - - The S3C2412 version of the SMDK2440. - - Samsung/Meritech SMDK2440 - - The S3C2440 compatible version of the SMDK2440, which has the - option of an S3C2440 or S3C2442 CPU module. - - Thorcom VR1000 - - Custom embedded board - - HP IPAQ 1940 - - Handheld (IPAQ), available in several varieties - - HP iPAQ rx3715 - - S3C2440 based IPAQ, with a number of variations depending on - features shipped. - - Acer N30 - - A S3C2410 based PDA from Acer. There is a Wiki page at - http://handhelds.org/moin/moin.cgi/AcerN30Documentation . - - AML M5900 - - American Microsystems' M5900 - - Nex Vision Nexcoder - Nex Vision Otom - - Two machines by Nex Vision - - -Adding New Machines -------------------- - - The architecture has been designed to support as many machines as can - be configured for it in one kernel build, and any future additions - should keep this in mind before altering items outside of their own - machine files. - - Machine definitions should be kept in linux/arch/arm/mach-s3c2410, - and there are a number of examples that can be looked at. - - Read the kernel patch submission policies as well as the - Documentation/arm directory before submitting patches. The - ARM kernel series is managed by Russell King, and has a patch system - located at http://www.arm.linux.org.uk/developer/patches/ - as well as mailing lists that can be found from the same site. - - As a courtesy, please notify of any new - machines or other modifications. - - Any large scale modifications, or new drivers should be discussed - on the ARM kernel mailing list (linux-arm-kernel) before being - attempted. See http://www.arm.linux.org.uk/mailinglists/ for the - mailing list information. - - -I2C ---- - - The hardware I2C core in the CPU is supported in single master - mode, and can be configured via platform data. - - -RTC ---- - - Support for the onboard RTC unit, including alarm function. - - This has recently been upgraded to use the new RTC core, - and the module has been renamed to rtc-s3c to fit in with - the new rtc naming scheme. - - -Watchdog --------- - - The onchip watchdog is available via the standard watchdog - interface. - - -NAND ----- - - The current kernels now have support for the s3c2410 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 - - -SD/MMC ------- - - The SD/MMC hardware pre S3C2443 is supported in the current - kernel, the driver is drivers/mmc/host/s3cmci.c and supports - 1 and 4 bit SD or MMC cards. - - The SDIO behaviour of this driver has not been fully tested. There is no - current support for hardware SDIO interrupts. - - -Serial ------- - - The s3c2410 serial driver provides support for the internal - serial ports. These devices appear as /dev/ttySAC0 through 3. - - To create device nodes for these, use the following commands - - mknod ttySAC0 c 204 64 - mknod ttySAC1 c 204 65 - mknod ttySAC2 c 204 66 - - -GPIO ----- - - The core contains support for manipulating the GPIO, see the - documentation in GPIO.txt in the same directory as this file. - - Newer kernels carry GPIOLIB, and support is being moved towards - this with some of the older support in line to be removed. - - 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 - implementation. - - -Clock Management ----------------- - - The core provides the interface defined in the header file - include/asm-arm/hardware/clock.h, to allow control over the - various clock units - - -Suspend to RAM --------------- - - For boards that provide support for suspend to RAM, the - system can be placed into low power suspend. - - See Suspend.txt for more information. - - -SPI ---- - - SPI drivers are available for both the in-built hardware - (although there is no DMA support yet) and a generic - GPIO based solution. - - -LEDs ----- - - There is support for GPIO based LEDs via a platform driver - in the LED subsystem. - - -Platform Data -------------- - - Whenever a device has platform specific data that is specified - on a per-machine basis, care should be taken to ensure the - following: - - 1) that default data is not left in the device to confuse the - driver if a machine does not set it at startup - - 2) the data should (if possible) be marked as __initdata, - to ensure that the data is thrown away if the machine is - not the one currently in use. - - The best way of doing this is to make a function that - 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 - - 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"); - } - } - - Note, since the code is marked as __init, it should not be - exported outside arch/arm/mach-s3c2410/, or exported to - modules via EXPORT_SYMBOL() and related functions. - - -Port Contributors ------------------ - - Ben Dooks (BJD) - Vincent Sanders - Herbert Potzl - Arnaud Patard (RTP) - Roc Wu - Klaus Fetscher - Dimitry Andric - Shannon Holland - Guillaume Gourat (NexVision) - Christer Weinigel (wingel) (Acer N30) - Lucas Correia Villa Real (S3C2400 port) - - -Document Author ---------------- - -Ben Dooks, Copyright 2004-2006 Simtec Electronics diff --git a/Documentation/arm/Samsung-S3C24XX/S3C2412.txt b/Documentation/arm/Samsung-S3C24XX/S3C2412.txt deleted file mode 100644 index dc1fd362d3c1..000000000000 --- a/Documentation/arm/Samsung-S3C24XX/S3C2412.txt +++ /dev/null @@ -1,120 +0,0 @@ - S3C2412 ARM Linux Overview - ========================== - -Introduction ------------- - - The S3C2412 is part of the S3C24XX range of ARM9 System-on-Chip CPUs - from Samsung. This part has an ARM926-EJS core, capable of running up - to 266MHz (see data-sheet for more information) - - -Clock ------ - - The core clock code provides a set of clocks to the drivers, and allows - for source selection and a number of other features. - - -Power ------ - - No support for suspend/resume to RAM in the current system. - - -DMA ---- - - No current support for DMA. - - -GPIO ----- - - There is support for setting the GPIO to input/output/special function - and reading or writing to them. - - -UART ----- - - The UART hardware is similar to the S3C2440, and is supported by the - s3c2410 driver in the drivers/serial directory. - - -NAND ----- - - The NAND hardware is similar to the S3C2440, and is supported by the - s3c2410 driver in the drivers/mtd/nand/raw directory. - - -USB Host --------- - - The USB hardware is similar to the S3C2410, with extended clock source - control. The OHCI portion is supported by the ohci-s3c2410 driver, and - the clock control selection is supported by the core clock code. - - -USB Device ----------- - - No current support in the kernel - - -IRQs ----- - - All the standard, and external interrupt sources are supported. The - extra sub-sources are not yet supported. - - -RTC ---- - - The RTC hardware is similar to the S3C2410, and is supported by the - s3c2410-rtc driver. - - -Watchdog --------- - - The watchdog hardware is the same as the S3C2410, and is supported by - the s3c2410_wdt driver. - - -MMC/SD/SDIO ------------ - - No current support for the MMC/SD/SDIO block. - -IIC ---- - - The IIC hardware is the same as the S3C2410, and is supported by the - i2c-s3c24xx driver. - - -IIS ---- - - No current support for the IIS interface. - - -SPI ---- - - No current support for the SPI interfaces. - - -ATA ---- - - No current support for the on-board ATA block. - - -Document Author ---------------- - -Ben Dooks, Copyright 2006 Simtec Electronics diff --git a/Documentation/arm/Samsung-S3C24XX/S3C2413.txt b/Documentation/arm/Samsung-S3C24XX/S3C2413.txt deleted file mode 100644 index 909bdc7dd7b5..000000000000 --- a/Documentation/arm/Samsung-S3C24XX/S3C2413.txt +++ /dev/null @@ -1,21 +0,0 @@ - S3C2413 ARM Linux Overview - ========================== - -Introduction ------------- - - The S3C2413 is an extended version of the S3C2412, with an camera - interface and mobile DDR memory support. See the S3C2412 support - documentation for more information. - - -Camera Interface ---------------- - - This block is currently not supported. - - -Document Author ---------------- - -Ben Dooks, Copyright 2006 Simtec Electronics diff --git a/Documentation/arm/Samsung-S3C24XX/SMDK2440.txt b/Documentation/arm/Samsung-S3C24XX/SMDK2440.txt deleted file mode 100644 index 429390bd4684..000000000000 --- a/Documentation/arm/Samsung-S3C24XX/SMDK2440.txt +++ /dev/null @@ -1,56 +0,0 @@ - Samsung/Meritech SMDK2440 - ========================= - -Introduction ------------- - - The SMDK2440 is a two part evaluation board for the Samsung S3C2440 - processor. It includes support for LCD, SmartMedia, Audio, SD and - 10MBit Ethernet, and expansion headers for various signals, including - the camera and unused GPIO. - - -Configuration -------------- - - To set the default configuration, use `make smdk2440_defconfig` which - will configure the common features of this board, or use - `make s3c2410_config` to include support for all s3c2410/s3c2440 machines - - -Support -------- - - Ben Dooks' SMDK2440 site at http://www.fluff.org/ben/smdk2440/ which - includes linux based USB download tools. - - Some of the h1940 patches that can be found from the H1940 project - site at http://www.handhelds.org/projects/h1940.html can also be - applied to this board. - - -Peripherals ------------ - - There is no current support for any of the extra peripherals on the - base-board itself. - - -MTD ---- - - The NAND flash should be supported by the in kernel MTD NAND support, - NOR flash will be added later. - - -Maintainers ------------ - - This board is being maintained by Ben Dooks, for more info, see - http://www.fluff.org/ben/smdk2440/ - - Many thanks to Dimitry Andric of TomTom for the loan of the SMDK2440, - and to Simtec Electronics for allowing me time to work on this. - - -(c) 2004 Ben Dooks diff --git a/Documentation/arm/Samsung-S3C24XX/Suspend.txt b/Documentation/arm/Samsung-S3C24XX/Suspend.txt deleted file mode 100644 index cb4f0c0cdf9d..000000000000 --- a/Documentation/arm/Samsung-S3C24XX/Suspend.txt +++ /dev/null @@ -1,137 +0,0 @@ - S3C24XX Suspend Support - ======================= - - -Introduction ------------- - - The S3C24XX supports a low-power suspend mode, where the SDRAM is kept - in Self-Refresh mode, and all but the essential peripheral blocks are - powered down. For more information on how this works, please look - at the relevant CPU datasheet from Samsung. - - -Requirements ------------- - - 1) A bootloader that can support the necessary resume operation - - 2) Support for at least 1 source for resume - - 3) CONFIG_PM enabled in the kernel - - 4) Any peripherals that are going to be powered down at the same - time require suspend/resume support. - - -Resuming --------- - - The S3C2410 user manual defines the process of sending the CPU to - sleep and how it resumes. The default behaviour of the Linux code - is to set the GSTATUS3 register to the physical address of the - code to resume Linux operation. - - GSTATUS4 is currently left alone by the sleep code, and is free to - use for any other purposes (for example, the EB2410ITX uses this to - save memory configuration in). - - -Machine Support ---------------- - - The machine specific functions must call the s3c_pm_init() function - to say that its bootloader is capable of resuming. This can be as - simple as adding the following to the machine's definition: - - INITMACHINE(s3c_pm_init) - - A board can do its own setup before calling s3c_pm_init, if it - needs to setup anything else for power management support. - - There is currently no support for over-riding the default method of - saving the resume address, if your board requires it, then contact - the maintainer and discuss what is required. - - Note, the original method of adding an late_initcall() is wrong, - 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: - - -static irqreturn_t button_irq(int irq, void *pw) -{ - return IRQ_HANDLED; -} - -statuc void __init machine_init(void) -{ - ... - - request_irq(IRQ_EINT0, button_irq, IRQF_TRIGGER_FALLING, - "button-irq-eint0", NULL); - - enable_irq_wake(IRQ_EINT0); - - s3c_pm_init(); -} - - -Debugging ---------- - - There are several important things to remember when using PM suspend: - - 1) The uart drivers will disable the clocks to the UART blocks when - suspending, which means that use of printascii() or similar direct - access to the UARTs will cause the debug to stop. - - 2) While the pm code itself will attempt to re-enable the UART clocks, - care should be taken that any external clock sources that the UARTs - rely on are still enabled at that point. - - 3) If any debugging is placed in the resume path, then it must have the - relevant clocks and peripherals setup before use (ie, bootloader). - - For example, if you transmit a character from the UART, the baud - rate and uart controls must be setup beforehand. - - -Configuration -------------- - - The S3C2410 specific configuration in `System Type` defines various - aspects of how the S3C2410 suspend and resume support is configured - - `S3C2410 PM Suspend debug` - - This option prints messages to the serial console before and after - the actual suspend, giving detailed information on what is - happening - - - `S3C2410 PM Suspend Memory CRC` - - Allows the entire memory to be checksummed before and after the - suspend to see if there has been any corruption of the contents. - - Note, the time to calculate the CRC is dependent on the CPU speed - and the size of memory. For an 64Mbyte RAM area on an 200MHz - S3C2410, this can take approximately 4 seconds to complete. - - This support requires the CRC32 function to be enabled. - - - `S3C2410 PM Suspend CRC Chunksize (KiB)` - - Defines the size of memory each CRC chunk covers. A smaller value - will mean that the CRC data block will take more memory, but will - identify any faults with better precision - - -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.txt deleted file mode 100644 index f82b1faefad5..000000000000 --- a/Documentation/arm/Samsung-S3C24XX/USB-Host.txt +++ /dev/null @@ -1,93 +0,0 @@ - S3C24XX USB Host support - ======================== - - - -Introduction ------------- - - This document details the S3C2410/S3C2440 in-built OHCI USB host support. - -Configuration -------------- - - Enable at least the following kernel options: - - menuconfig: - - Device Drivers ---> - USB support ---> - <*> Support for Host-side USB - <*> OHCI HCD support - - - .config: - CONFIG_USB - CONFIG_USB_OHCI_HCD - - - Once these options are configured, the standard set of USB device - drivers can be configured and used. - - -Board Support -------------- - - The driver attaches to a platform device, which will need to be - added by the board specific support file in linux/arch/arm/mach-s3c2410, - such as mach-bast.c or mach-smdk2410.c - - The platform device's platform_data field is only needed if the - board implements extra power control or over-current monitoring. - - The OHCI driver does not ensure the state of the S3C2410's MISCCTRL - register, so if both ports are to be used for the host, then it is - the board support file's responsibility to ensure that the second - port is configured to be connected to the OHCI core. - - -Platform Data -------------- - - See arch/arm/mach-s3c2410/include/mach/usb-control.h for the - descriptions of the platform device data. An implementation - can be found in linux/arch/arm/mach-s3c2410/usb-simtec.c . - - The `struct s3c2410_hcd_info` contains a pair of functions - that get called to enable over-current detection, and to - control the port power status. - - 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, - with bit X being 1 for an over-current on port X. - - The function s3c2410_usb_report_oc() has been provided to - 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. - - - -Document Author ---------------- - -Ben Dooks, Copyright 2005 Simtec Electronics diff --git a/Documentation/arm/Samsung/Bootloader-interface.txt b/Documentation/arm/Samsung/Bootloader-interface.txt deleted file mode 100644 index d17ed518a7ea..000000000000 --- a/Documentation/arm/Samsung/Bootloader-interface.txt +++ /dev/null @@ -1,68 +0,0 @@ - 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 -and boot loaders on Samsung Exynos based boards. This is not a definition -of interface but rather a description of existing state, a reference -for information purpose only. - -In the document "boot loader" means any of following: U-boot, proprietary -SBOOT or any other firmware for ARMv7 and ARMv8 initializing the board before -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 -0x1c + 4*cpu exynos4_secondary_startup (Exynos4412) Secondary CPU boot -0x20 0xfcba0d10 (Magic cookie) AFTR -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 -0x0804 0x00000bad (Magic cookie) System suspend -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 - -AFTR - ARM Off Top Running, a low power mode, Cortex cores and many other -modules are power gated, except the TOP modules -MCPM - Multi-Cluster Power Management diff --git a/Documentation/arm/Samsung/GPIO.txt b/Documentation/arm/Samsung/GPIO.txt deleted file mode 100644 index 795adfd88081..000000000000 --- a/Documentation/arm/Samsung/GPIO.txt +++ /dev/null @@ -1,40 +0,0 @@ - Samsung GPIO implementation - =========================== - -Introduction ------------- - -This outlines the Samsung GPIO implementation and the architecture -specific calls provided alongside the drivers/gpio core. - - -S3C24XX (Legacy) ----------------- - -See Documentation/arm/Samsung-S3C24XX/GPIO.txt for more information -about these devices. Their implementation has been brought into line -with the core samsung implementation described in this document. - - -GPIOLIB integration -------------------- - -The gpio implementation uses gpiolib as much as possible, only providing -specific calls for the items that require Samsung specific handling, such -as pin special-function or pull resistor control. - -GPIO numbering is synchronised between the Samsung and gpiolib system. - - -PIN configuration ------------------ - -Pin configuration is specific to the Samsung architecture, with each SoC -registering the necessary information for the core gpio configuration -implementation to configure pins as necessary. - -The s3c_gpio_cfgpin() and s3c_gpio_setpull() provide the means for a -driver or machine to change gpio configuration. - -See arch/arm/plat-samsung/include/plat/gpio-cfg.h for more information -on these functions. diff --git a/Documentation/arm/Samsung/Overview.txt b/Documentation/arm/Samsung/Overview.txt deleted file mode 100644 index 8f7309bad460..000000000000 --- a/Documentation/arm/Samsung/Overview.txt +++ /dev/null @@ -1,86 +0,0 @@ - Samsung ARM Linux Overview - ========================== - -Introduction ------------- - - The Samsung range of ARM SoCs spans many similar devices, from the initial - ARM9 through to the newest ARM cores. This document shows an overview of - the current kernel support, how to use it and where to find the code - that supports this. - - The currently supported SoCs are: - - - S3C24XX: See Documentation/arm/Samsung-S3C24XX/Overview.txt for full list - - S3C64XX: S3C6400 and S3C6410 - - S5PC110 / S5PV210 - - -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 - on the implementation details and specific support. - - -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 - - -Layout ------- - - The directory layout is currently being restructured, and consists of - several platform directories and then the machine specific directories - of the CPUs being built for. - - plat-samsung provides the base for all the implementations, and is the - last in the line of include directories that are processed for the build - specific information. It contains the base clock, GPIO and device definitions - to get the system running. - - plat-s3c24xx is for s3c24xx specific builds, see the S3C24XX docs. - - plat-s5p is for s5p specific builds, and contains common support for the - S5P specific systems. Not all S5Ps use all the features in this directory - due to differences in the hardware. - - -Layout changes --------------- - - The old plat-s3c and plat-s5pc1xx directories have been removed, with - support moved to either plat-samsung or plat-s5p as necessary. These moves - where to simplify the include and dependency issues involved with having - so many different platform directories. - - -Port Contributors ------------------ - - Ben Dooks (BJD) - Vincent Sanders - Herbert Potzl - Arnaud Patard (RTP) - Roc Wu - Klaus Fetscher - Dimitry Andric - Shannon Holland - Guillaume Gourat (NexVision) - Christer Weinigel (wingel) (Acer N30) - Lucas Correia Villa Real (S3C2400 port) - - -Document Author ---------------- - -Copyright 2009-2010 Ben Dooks diff --git a/Documentation/arm/Samsung/clksrc-change-registers.awk b/Documentation/arm/Samsung/clksrc-change-registers.awk deleted file mode 100755 index 7be1b8aa7cd9..000000000000 --- a/Documentation/arm/Samsung/clksrc-change-registers.awk +++ /dev/null @@ -1,166 +0,0 @@ -#!/usr/bin/awk -f -# -# Copyright 2010 Ben Dooks -# -# Released under GPLv2 - -# example usage -# ./clksrc-change-registers.awk arch/arm/plat-s5pc1xx/include/plat/regs-clock.h < src > dst - -function extract_value(s) -{ - eqat = index(s, "=") - comat = index(s, ",") - return substr(s, eqat+2, (comat-eqat)-2) -} - -function remove_brackets(b) -{ - return substr(b, 2, length(b)-2) -} - -function splitdefine(l, p) -{ - r = split(l, tp) - - p[0] = tp[2] - p[1] = remove_brackets(tp[3]) -} - -function find_length(f) -{ - if (0) - printf "find_length " f "\n" > "/dev/stderr" - - if (f ~ /0x1/) - return 1 - else if (f ~ /0x3/) - return 2 - else if (f ~ /0x7/) - return 3 - else if (f ~ /0xf/) - return 4 - - printf "unknown length " f "\n" > "/dev/stderr" - exit -} - -function find_shift(s) -{ - id = index(s, "<") - if (id <= 0) { - printf "cannot find shift " s "\n" > "/dev/stderr" - exit - } - - return substr(s, id+2) -} - - -BEGIN { - if (ARGC < 2) { - print "too few arguments" > "/dev/stderr" - exit - } - -# read the header file and find the mask values that we will need -# to replace and create an associative array of values - - while (getline line < ARGV[1] > 0) { - if (line ~ /\#define.*_MASK/ && - !(line ~ /USB_SIG_MASK/)) { - splitdefine(line, fields) - name = fields[0] - if (0) - printf "MASK " line "\n" > "/dev/stderr" - dmask[name,0] = find_length(fields[1]) - dmask[name,1] = find_shift(fields[1]) - if (0) - printf "=> '" name "' LENGTH=" dmask[name,0] " SHIFT=" dmask[name,1] "\n" > "/dev/stderr" - } else { - } - } - - delete ARGV[1] -} - -/clksrc_clk.*=.*{/ { - shift="" - mask="" - divshift="" - reg_div="" - reg_src="" - indent=1 - - print $0 - - for(; indent >= 1;) { - if ((getline line) <= 0) { - printf "unexpected end of file" > "/dev/stderr" - exit 1; - } - - if (line ~ /\.shift/) { - shift = extract_value(line) - } else if (line ~ /\.mask/) { - mask = extract_value(line) - } else if (line ~ /\.reg_divider/) { - reg_div = extract_value(line) - } else if (line ~ /\.reg_source/) { - reg_src = extract_value(line) - } else if (line ~ /\.divider_shift/) { - divshift = extract_value(line) - } else if (line ~ /{/) { - indent++ - print line - } else if (line ~ /}/) { - indent-- - - if (indent == 0) { - if (0) { - printf "shift '" shift "' ='" dmask[shift,0] "'\n" > "/dev/stderr" - printf "mask '" mask "'\n" > "/dev/stderr" - printf "dshft '" divshift "'\n" > "/dev/stderr" - printf "rdiv '" reg_div "'\n" > "/dev/stderr" - printf "rsrc '" reg_src "'\n" > "/dev/stderr" - } - - generated = mask - sub(reg_src, reg_div, generated) - - if (0) { - printf "/* rsrc " reg_src " */\n" - printf "/* rdiv " reg_div " */\n" - printf "/* shift " shift " */\n" - printf "/* mask " mask " */\n" - printf "/* generated " generated " */\n" - } - - if (reg_div != "") { - printf "\t.reg_div = { " - printf ".reg = " reg_div ", " - printf ".shift = " dmask[generated,1] ", " - printf ".size = " dmask[generated,0] ", " - printf "},\n" - } - - printf "\t.reg_src = { " - printf ".reg = " reg_src ", " - printf ".shift = " dmask[mask,1] ", " - printf ".size = " dmask[mask,0] ", " - - printf "},\n" - - } - - print line - } else { - print line - } - - if (0) - printf indent ":" line "\n" > "/dev/stderr" - } -} - -// && ! /clksrc_clk.*=.*{/ { print $0 } diff --git a/Documentation/arm/Setup b/Documentation/arm/Setup deleted file mode 100644 index 0cb1e64bde80..000000000000 --- a/Documentation/arm/Setup +++ /dev/null @@ -1,129 +0,0 @@ -Kernel initialisation parameters on ARM Linux ---------------------------------------------- - -The following document describes the kernel initialisation parameter -structure, otherwise known as 'struct param_struct' which is used -for most ARM Linux architectures. - -This structure is used to pass initialisation parameters from the -kernel loader to the Linux kernel proper, and may be short lived -through the kernel initialisation process. As a general rule, it -should not be referenced outside of arch/arm/kernel/setup.c:setup_arch(). - -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. - - If the system contains separate VRAM, this value should not - 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 - - rootdev - - major/minor number pair of device to mount as the root filesystem. - - 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. - - It's generally a good idea to set these to be either standard VGA, or - the equivalent character size of your fbcon display. This then allows - all the bootup messages to be displayed correctly. - - 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 - - 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 - - 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 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 - 0-66 MHz. If no params are passed or a value of zero is passed, - 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/VFP/release-notes.txt b/Documentation/arm/VFP/release-notes.txt deleted file mode 100644 index 28a2795705ca..000000000000 --- a/Documentation/arm/VFP/release-notes.txt +++ /dev/null @@ -1,55 +0,0 @@ -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 -provides support for the exceptions bounced from VFP hardware found -on ARM926EJ-S. - -This release has been validated against the SoftFloat-2b library by -John R. Hauser using the TestFloat-2a test suite. Details of this -library and test suite can be found at: - - http://www.jhauser.us/arithmetic/SoftFloat.html - -The operations which have been tested with this package are: - - - fdiv - - fsub - - fadd - - fmul - - fcmp - - fcmpe - - fcvtd - - fcvts - - fsito - - ftosi - - fsqrt - -All the above pass softfloat tests with the following exceptions: - -- fadd/fsub shows some differences in the handling of +0 / -0 results - when input operands differ in signs. -- the handling of underflow exceptions is slightly different. If a - result underflows before rounding, but becomes a normalised number - after rounding, we do not signal an underflow exception. - -Other operations which have been tested by basic assembly-only tests -are: - - - fcpy - - fabs - - fneg - - ftoui - - ftosiz - - ftouiz - -The combination operations have not been tested: - - - fmac - - fnmac - - fmsc - - fnmsc - - fnmul diff --git a/Documentation/arm/arm.rst b/Documentation/arm/arm.rst new file mode 100644 index 000000000000..2edc509df92a --- /dev/null +++ b/Documentation/arm/arm.rst @@ -0,0 +1,214 @@ +======================= +ARM Linux 2.6 and upper +======================= + + Please check for + updates. + +Compilation of kernel +--------------------- + + In order to compile ARM Linux, you will need a compiler capable of + generating ARM ELF code with GNU extensions. GCC 3.3 is known to be + a good compiler. Fortunately, you needn't guess. The kernel will report + an error if your compiler is a recognized offender. + + To build ARM Linux natively, you shouldn't have to alter the ARCH = line + in the top level Makefile. However, if you don't have the ARM Linux ELF + tools installed as default, then you should change the CROSS_COMPILE + line as detailed below. + + If you wish to cross-compile, then alter the following lines in the top + level make file:: + + ARCH = + + with:: + + ARCH = arm + + and:: + + CROSS_COMPILE= + + to:: + + CROSS_COMPILE= + + 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 + 'make zImage' instead of 'make Image'. + + +Bug reports etc +--------------- + + Please send patches to the patch system. For more information, see + http://www.arm.linux.org.uk/developer/patches/info.php Always include some + explanation as to what the patch does and why it is needed. + + 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/ + + When sending bug reports, please ensure that they contain all relevant + information, eg. the kernel messages that were printed before/during + the problem, what you were doing, etc. + + +Include files +------------- + + Several new include directories have been created under include/asm-arm, + 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 + categories) + ============= ========================================================== + + +Machine/Platform support +------------------------ + + The ARM tree contains support for a lot of different machine types. To + continue supporting these differences, it has become necessary to split + machine-specific parts by directory. For this, the machine category is + used to select which directories and files get included (we will use + $(MACHINE) to refer to the category) + + To this end, we now have arch/arm/mach-$(MACHINE) directories which are + designed to house the non-driver files for a particular machine (eg, PCI, + memory management, architecture definitions etc). For all future + machines, there should be a corresponding arch/arm/mach-$(MACHINE)/include/mach + directory. + + +Modules +------- + + Although modularisation is supported (and required for the FP emulator), + each module on an ARM2/ARM250/ARM3 machine when is loaded will take + memory up to the next 32k boundary due to the size of the pages. + Therefore, is modularisation on these machines really worth it? + + However, ARM6 and up machines allow modules to take multiples of 4k, and + as such Acorn RiscPCs and other architectures using these processors can + make good use of modularisation. + + +ADFS Image files +---------------- + + You can access image files on your ADFS partitions by mounting the ADFS + partition, and then using the loopback device driver. You must have + losetup installed. + + Please note that the PCEmulator DOS partitions have a partition table at + the start, and as such, you will have to give '-o offset' to losetup. + + +Request to developers +--------------------- + + When writing device drivers which include a separate assembler file, please + include it in with the C file, and not the arch/arm/lib directory. This + allows the driver to be compiled as a loadable module without requiring + half the code to be compiled into the kernel image. + + In general, try to avoid using assembler unless it is really necessary. It + makes drivers far less easy to port to other hardware. + + +ST506 hard drives +----------------- + + The ST506 hard drive controllers seem to be working fine (if a little + slowly). At the moment they will only work off the controllers on an + A4x0's motherboard, but for it to work off a Podule just requires + someone with a podule to add the addresses for the IRQ mask and the + 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 + 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 + RiscOS gets; but it's a heck of a lot better than the 50K/s I was getting + last week :-) + + Known bug: Drive data errors can cause a hang; including cases where + the controller has fixed the error using ECC. (Possibly ONLY + in that case...hmm). + + +1772 Floppy +----------- + This also seems to work OK, but hasn't been stressed much lately. It + hasn't got any code for disc change detection in there at the moment which + could be a bit of a problem! Suggestions on the correct way to do this + are welcome. + + +`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, + 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 + not been made because it would complicate patching. + + Previous registrations may be found online. + + + +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. + + Due to the large number of machines which the ARM port of Linux provides + for, we have a method to manage this which ensures that we don't end up + duplicating large amounts of code. + + We group machine (or platform) support code into machine classes. A + class typically based around one or more system on a chip devices, and + acts as a natural container around the actual implementations. These + classes are given directories - arch/arm/mach- and + arch/arm/mach- - which contain the source files to/include/mach + support the machine class. This directories also contain any machine + specific supporting code. + + For example, the SA1100 class is based upon the SA1100 and SA1110 SoC + devices, and contains the code to support the way the on-board and off- + board devices are used, or the device is setup, and provides that + machine specific "personality." + + For platforms that support device tree (DT), the machine selection is + controlled at runtime by passing the device tree blob to the kernel. At + compile-time, support for the machine type must be selected. This allows for + a single multiplatform kernel build to be used for several machine types. + + For platforms that do not use device tree, this machine selection is + controlled by the machine type ID, which acts both as a run-time and a + compile-time code selection method. You can register a new machine via the + web site at: + + + + Note: Please do not register a machine type for DT-only platforms. If your + platform is DT-only, you do not need a registered machine type. + +--- + +Russell King (15/03/2004) diff --git a/Documentation/arm/booting.rst b/Documentation/arm/booting.rst new file mode 100644 index 000000000000..4babb6c6ae1e --- /dev/null +++ b/Documentation/arm/booting.rst @@ -0,0 +1,237 @@ +================= +Booting ARM Linux +================= + +Author: Russell King + +Date : 18 May 2002 + +The following documentation is relevant to 2.4.18-rmk6 and beyond. + +In order to boot ARM Linux, you require a boot loader, which is a small +program that runs before the main kernel. The boot loader is expected +to initialise various devices, and eventually call the Linux kernel, +passing information to the kernel. + +Essentially, the boot loader should provide (as a minimum) the +following: + +1. Setup and initialise the RAM. +2. Initialise one serial port. +3. Detect the machine type. +4. Setup the kernel tagged list. +5. Load initramfs. +6. Call the kernel image. + + +1. Setup and initialise RAM +--------------------------- + +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 +this in a machine dependent manner. (It may use internal algorithms +to automatically locate and size all RAM, or it may use knowledge of +the RAM in the machine, or any other method the boot loader designer +sees fit.) + + +2. Initialise one serial port +----------------------------- + +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 +which serial port it should use for the kernel console (generally +used for debugging purposes, or communication with the target.) + +As an alternative, the boot loader can pass the relevant 'console=' +option to the kernel via the tagged lists specifying the port, and +serial format options as described in + + Documentation/admin-guide/kernel-parameters.rst. + + +3. Detect the machine type +-------------------------- + +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 +looks at the connected hardware is beyond the scope of this document. +The boot loader must ultimately be able to provide a MACH_TYPE_xxx +value to the kernel. (see linux/arch/arm/tools/mach-types). This +should be passed to the kernel in register r1. + +For DT-only platforms, the machine type will be determined by device +tree. set the machine type to all ones (~0). This is not strictly +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 + +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 +boot data is passed to the kernel in register r2. + +4a. Setup the kernel tagged list +-------------------------------- + +The boot loader must create and initialise the kernel tagged list. +A valid tagged list starts with ATAG_CORE and ends with ATAG_NONE. +The ATAG_CORE tag may or may not be empty. An empty ATAG_CORE tag +has the size field set to '2' (0x00000002). The ATAG_NONE must set +the size field to zero. + +Any number of tags can be placed in the list. It is undefined +whether a repeated tag appends to the information carried by the +previous tag, or whether it replaces the information in its +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:: + + +-----------+ + base -> | ATAG_CORE | | + +-----------+ | + | ATAG_MEM | | increasing address + +-----------+ | + | ATAG_NONE | | + +-----------+ v + +The tagged list should be stored in system RAM. + +The tagged list must be placed in a region of memory where neither +the kernel decompressor nor initrd 'bootp' program will overwrite +it. The recommended placement is in the first 16KiB of RAM. + +4b. Setup the device tree +------------------------- + +The boot loader must load a device tree image (dtb) into system ram +at a 64bit aligned address and initialize it with the boot data. The +dtb format is documented in Documentation/devicetree/booting-without-of.txt. +The kernel will look for the dtb magic value of 0xd00dfeed at the dtb +physical address to determine if a dtb has been passed instead of a +tagged list. + +The boot loader must pass at a minimum the size and location of the +system memory, and the root filesystem location. The dtb must be +placed in a region of memory where the kernel decompressor will not +overwrite it, while remaining within the region which will be covered +by the kernel's low-memory mapping. + +A safe location is just above the 128MiB boundary from start of RAM. + +5. Load initramfs. +------------------ + +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 +while also with the region which will be covered by the kernel's +low-memory mapping. + +A safe location is just above the device tree blob which itself will +be loaded just above the 128MiB boundary from the start of RAM as +recommended above. + +6. Calling the kernel image +--------------------------- + +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, +then it is legal for the boot loader to call the zImage in flash +directly. + +The zImage may also be placed in system RAM and called there. The +kernel should be placed in the first 128MiB of RAM. It is recommended +that it is loaded above 32MiB in order to avoid the need to relocate +prior to decompression, which will make the boot process slightly +faster. + +When booting a raw (non-zImage) kernel the constraints are tighter. +In this case the kernel must be loaded at an offset into system equal +to TEXT_OFFSET - PAGE_OFFSET. + +In any case, the following conditions must be met: + +- Quiesce all DMA capable devices so that memory does not get + corrupted by bogus network packets or disk data. This will save + 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 + +- CPU mode + + All forms of interrupts must be disabled (IRQs and FIQs) + + For CPUs which do not include the ARM virtualization extensions, the + CPU must be in SVC mode. (A special exception exists for Angel) + + CPUs which include support for the virtualization extensions can be + entered in HYP mode in order to enable the kernel to make full use of + these extensions. This is the recommended boot method for such CPUs, + unless the virtualisations are already in use by a pre-installed + hypervisor. + + If the kernel is not entered in HYP mode for any reason, it must be + 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 + the HYP mode configuration in addition to the ordinary PL1 (privileged + kernel modes) configuration. In addition, all traps into the + hypervisor must be disabled, and PL1 access must be granted for all + peripherals and CPU resources for which this is architecturally + possible. Except for entering in HYP mode, the system configuration + should be such that a kernel which does not include support for the + virtualization extensions can boot correctly without extra help. + +- The boot loader is expected to call the kernel image by jumping + directly to the first instruction of the kernel image. + + On CPUs supporting the ARM instruction set, the entry must be + made in ARM state, even for a Thumb-2 kernel. + + On CPUs supporting only the Thumb instruction set such as + Cortex-M class CPUs, the entry must be made in Thumb state. diff --git a/Documentation/arm/cluster-pm-race-avoidance.rst b/Documentation/arm/cluster-pm-race-avoidance.rst new file mode 100644 index 000000000000..aa58603d3f28 --- /dev/null +++ b/Documentation/arm/cluster-pm-race-avoidance.rst @@ -0,0 +1,533 @@ +========================================================= +Cluster-wide Power-up/power-down race avoidance algorithm +========================================================= + +This file documents the algorithm which is used to coordinate CPU and +cluster setup and teardown operations and to manage hardware coherency +controls safely. + +The section "Rationale" explains what the algorithm is for and why it is +needed. "Basic model" explains general concepts using a simplified view +of the system. The other sections explain the actual details of the +algorithm in use. + + +Rationale +--------- + +In a system containing multiple CPUs, it is desirable to have the +ability to turn off individual CPUs when the system is idle, reducing +power consumption and thermal dissipation. + +In a system containing multiple clusters of CPUs, it is also desirable +to have the ability to turn off entire clusters. + +Turning entire clusters off and on is a risky business, because it +involves performing potentially destructive operations affecting a group +of independently running CPUs, while the OS continues to run. This +means that we need some coordination in order to ensure that critical +cluster-level operations are only performed when it is truly safe to do +so. + +Simple locking may not be sufficient to solve this problem, because +mechanisms like Linux spinlocks may rely on coherency mechanisms which +are not immediately enabled when a cluster powers up. Since enabling or +disabling those mechanisms may itself be a non-atomic operation (such as +writing some hardware registers and invalidating large caches), other +methods of coordination are required in order to guarantee safe +power-down and power-up at the cluster level. + +The mechanism presented in this document describes a coherent memory +based protocol for performing the needed coordination. It aims to be as +lightweight as possible, while providing the required safety properties. + + +Basic model +----------- + +Each cluster and CPU is assigned a state, as follows: + + - DOWN + - COMING_UP + - UP + - GOING_DOWN + +:: + + +---------> UP ----------+ + | v + + COMING_UP GOING_DOWN + + ^ | + +--------- DOWN <--------+ + + +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. + 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 + 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 + state. It may be part way through the process of teardown and + coherency exit. + + +Each CPU has one of these states assigned to it at any point in time. +The CPU states are described in the "CPU state" section, below. + +Each cluster is also assigned a state, but it is necessary to split the +state value into two parts (the "cluster" state and "inbound" state) and +to introduce additional states in order to avoid races between different +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. + + +CPU state +--------- + +In this algorithm, each individual core in a multi-core processor is +referred to as a "CPU". CPUs are assumed to be single-threaded: +therefore, a CPU can only be doing one thing at a single point in time. + +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 + +:: + + cluster setup and + CPU setup complete policy decision + +-----------> CPU_UP ------------+ + | v + + CPU_COMING_UP CPU_GOING_DOWN + + ^ | + +----------- CPU_DOWN <----------+ + policy decision CPU teardown complete + or hardware event + + +The definitions of the four states correspond closely to the states of +the basic model. + +Transitions between states occur as follows. + +A trigger event (spontaneous) means that the CPU can transition to the +next state as a result of making local progress only, with no +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 + + Trigger events: + a) an explicit hardware power-up operation, resulting + from a policy decision on another CPU; + + b) a hardware event, such as an interrupt. + + +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. + + Refer to the "Cluster state" section for a description of the + CLUSTER_UP state. + + +CPU_UP: + When a CPU reaches the CPU_UP state, it is safe for the CPU to + start participating in local coherency. + + This is done by jumping to the kernel's CPU resume code. + + Note that the definition of this state is slightly different + from the basic model definition: CPU_UP does not mean that the + CPU is coherent yet, but it does mean that it is safe to resume + the kernel. The kernel handles the rest of the resume + procedure, so the remaining steps are not visible as part of the + race avoidance algorithm. + + 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 + + +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) + + +Cluster state +------------- + +A cluster is a group of connected CPUs with some common resources. +Because a cluster contains multiple CPUs, it can be doing multiple +things at the same time. This has some implications. In particular, a +CPU can start up while another CPU is tearing the cluster down. + +In this discussion, the "outbound side" is the view of the cluster state +as seen by a CPU tearing the cluster down. The "inbound side" is the +view of the cluster state as seen by a CPU setting the CPU up. + +In order to enable safe coordination in such situations, it is important +that a CPU which is setting up the cluster can advertise its state +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: + + - 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 + + + The different pairings of these states results in six possible + states for the cluster as a whole:: + + CLUSTER_UP + +==========> INBOUND_NOT_COMING_UP -------------+ + # | + | + CLUSTER_UP <----+ | + INBOUND_COMING_UP | v + + ^ CLUSTER_GOING_DOWN CLUSTER_GOING_DOWN + # INBOUND_COMING_UP <=== INBOUND_NOT_COMING_UP + + CLUSTER_DOWN | | + INBOUND_COMING_UP <----+ | + | + ^ | + +=========== CLUSTER_DOWN <------------+ + INBOUND_NOT_COMING_UP + + Transitions -----> can only be made by the outbound CPU, and + only involve changes to the "cluster" state. + + Transitions ===##> can only be made by the inbound CPU, and only + involve changes to the "inbound" state, except where there is no + further transition possible on the outbound side (i.e., the + outbound CPU has put the cluster into the CLUSTER_DOWN state). + + The race avoidance algorithm does not provide a way to determine + which exact CPUs within the cluster play these roles. This must + be decided in advance by some other means. Refer to the section + "Last man and first man selection" for more explanation. + + + CLUSTER_DOWN/INBOUND_NOT_COMING_UP is the only state where the + cluster can actually be powered down. + + The parallelism of the inbound and outbound CPUs is observed by + the existence of two different paths from CLUSTER_GOING_DOWN/ + INBOUND_NOT_COMING_UP (corresponding to GOING_DOWN in the basic + model) to CLUSTER_DOWN/INBOUND_COMING_UP (corresponding to + COMING_UP in the basic model). The second path avoids cluster + teardown completely. + + CLUSTER_UP/INBOUND_COMING_UP is equivalent to UP in the basic + model. The final transition to CLUSTER_UP/INBOUND_NOT_COMING_UP + is trivial and merely resets the state machine ready for the + next cycle. + + Details of the allowable transitions follow. + + The next state in each case is notated + + / () + + where the is the side on which the transition + can occur; either the inbound or the outbound side. + + +CLUSTER_DOWN/INBOUND_NOT_COMING_UP: + 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; + + b) a hardware event, such as an interrupt. + + +CLUSTER_DOWN/INBOUND_COMING_UP: + + In this state, an inbound CPU sets up the cluster, including + enabling of hardware coherency at the cluster level and any + other operations (such as cache invalidation) which are required + in order to achieve this. + + The purpose of this state is to do sufficient cluster-level + 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) + + +CLUSTER_UP/INBOUND_COMING_UP: + + Cluster-level setup is complete and hardware coherency is + enabled for the cluster. Other CPUs in the cluster can safely + enter coherency. + + This is a transient state, leading immediately to + 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) + + +CLUSTER_UP/INBOUND_NOT_COMING_UP: + + Cluster-level setup is complete and hardware coherency is + enabled for the cluster. Other CPUs in the cluster can safely + enter coherency. + + 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 + + +CLUSTER_GOING_DOWN/INBOUND_NOT_COMING_UP: + + An outbound CPU is tearing the cluster down. The selected CPU + must wait in this state until all CPUs in the cluster are in the + CPU_DOWN state. + + When all CPUs are in the CPU_DOWN state, the cluster can be torn + down, for example by cleaning data caches and exiting + cluster-level coherency. + + To avoid wasteful unnecessary teardown operations, the outbound + should check the inbound cluster state for asynchronous + transitions to INBOUND_COMING_UP. Alternatively, individual + CPUs can be checked for entry into CPU_COMING_UP or CPU_UP. + + + Next states: + + CLUSTER_DOWN/INBOUND_NOT_COMING_UP (outbound) + Conditions: + cluster torn down and ready to power off + Trigger events: + (spontaneous) + + CLUSTER_GOING_DOWN/INBOUND_COMING_UP (inbound) + Conditions: + none + + Trigger events: + a) an explicit hardware power-up operation, + resulting from a policy decision on another + CPU; + + b) a hardware event, such as an interrupt. + + +CLUSTER_GOING_DOWN/INBOUND_COMING_UP: + + The cluster is (or was) being torn down, but another CPU has + come online in the meantime and is trying to set up the cluster + again. + + If the outbound CPU observes this state, it has two choices: + + a) back out of teardown, restoring the cluster to the + CLUSTER_UP state; + + b) finish tearing the cluster down and put the cluster + in the CLUSTER_DOWN state; the inbound CPU will + set up the cluster again from there. + + Choice (a) permits the removal of some latency by avoiding + unnecessary teardown and setup operations in situations where + the cluster is not really going to be powered down. + + + Next states: + + CLUSTER_UP/INBOUND_COMING_UP (outbound) + Conditions: + cluster-level setup and hardware + coherency complete + + Trigger events: + (spontaneous) + + CLUSTER_DOWN/INBOUND_COMING_UP (outbound) + Conditions: + cluster torn down and ready to power off + + Trigger events: + (spontaneous) + + +Last man and First man selection +-------------------------------- + +The CPU which performs cluster tear-down operations on the outbound side +is commonly referred to as the "last man". + +The CPU which performs cluster setup on the inbound side is commonly +referred to as the "first man". + +The race avoidance algorithm documented above does not provide a +mechanism to choose which CPUs should play these roles. + + +Last man: + +When shutting down the cluster, all the CPUs involved are initially +executing Linux and hence coherent. Therefore, ordinary spinlocks can +be used to select a last man safely, before the CPUs become +non-coherent. + + +First man: + +Because CPUs may power up asynchronously in response to external wake-up +events, a dynamic mechanism is needed to make sure that only one CPU +attempts to play the first man role and do the cluster-level +initialisation: any other CPUs must wait for this to complete before +proceeding. + +Cluster-level initialisation may involve actions such as configuring +coherency controls in the bus fabric. + +The current implementation in mcpm_head.S uses a separate mutual exclusion +mechanism to do this arbitration. This mechanism is documented in +detail in vlocks.txt. + + +Features and Limitations +------------------------ + +Implementation: + + The current ARM-based implementation is split between + arch/arm/common/mcpm_head.S (low-level inbound CPU operations) and + arch/arm/common/mcpm_entry.c (everything else): + + __mcpm_cpu_going_down() signals the transition of a CPU to the + CPU_GOING_DOWN state. + + __mcpm_cpu_down() signals the transition of a CPU to the CPU_DOWN + 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. + + __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). + + 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. + +Deep topologies: + + As currently described and implemented, the algorithm does not + support CPU topologies involving more than two levels (i.e., + clusters of clusters are not supported). The algorithm could be + extended by replicating the cluster-level states for the + additional topological levels, and modifying the transition + rules for the intermediate (non-outermost) cluster levels. + + +Colophon +-------- + +Originally created and documented by Dave Martin for Linaro Limited, in +collaboration with Nicolas Pitre and Achin Gupta. + +Copyright (C) 2012-2013 Linaro Limited +Distributed under the terms of Version 2 of the GNU General Public +License, as defined in linux/COPYING. diff --git a/Documentation/arm/cluster-pm-race-avoidance.txt b/Documentation/arm/cluster-pm-race-avoidance.txt deleted file mode 100644 index 750b6fc24af9..000000000000 --- a/Documentation/arm/cluster-pm-race-avoidance.txt +++ /dev/null @@ -1,498 +0,0 @@ -Cluster-wide Power-up/power-down race avoidance algorithm -========================================================= - -This file documents the algorithm which is used to coordinate CPU and -cluster setup and teardown operations and to manage hardware coherency -controls safely. - -The section "Rationale" explains what the algorithm is for and why it is -needed. "Basic model" explains general concepts using a simplified view -of the system. The other sections explain the actual details of the -algorithm in use. - - -Rationale ---------- - -In a system containing multiple CPUs, it is desirable to have the -ability to turn off individual CPUs when the system is idle, reducing -power consumption and thermal dissipation. - -In a system containing multiple clusters of CPUs, it is also desirable -to have the ability to turn off entire clusters. - -Turning entire clusters off and on is a risky business, because it -involves performing potentially destructive operations affecting a group -of independently running CPUs, while the OS continues to run. This -means that we need some coordination in order to ensure that critical -cluster-level operations are only performed when it is truly safe to do -so. - -Simple locking may not be sufficient to solve this problem, because -mechanisms like Linux spinlocks may rely on coherency mechanisms which -are not immediately enabled when a cluster powers up. Since enabling or -disabling those mechanisms may itself be a non-atomic operation (such as -writing some hardware registers and invalidating large caches), other -methods of coordination are required in order to guarantee safe -power-down and power-up at the cluster level. - -The mechanism presented in this document describes a coherent memory -based protocol for performing the needed coordination. It aims to be as -lightweight as possible, while providing the required safety properties. - - -Basic model ------------ - -Each cluster and CPU is assigned a state, as follows: - - DOWN - COMING_UP - UP - GOING_DOWN - - +---------> UP ----------+ - | v - - COMING_UP GOING_DOWN - - ^ | - +--------- DOWN <--------+ - - -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. - 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 - 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 - state. It may be part way through the process of teardown and - coherency exit. - - -Each CPU has one of these states assigned to it at any point in time. -The CPU states are described in the "CPU state" section, below. - -Each cluster is also assigned a state, but it is necessary to split the -state value into two parts (the "cluster" state and "inbound" state) and -to introduce additional states in order to avoid races between different -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. - - -CPU state ---------- - -In this algorithm, each individual core in a multi-core processor is -referred to as a "CPU". CPUs are assumed to be single-threaded: -therefore, a CPU can only be doing one thing at a single point in time. - -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 - - cluster setup and - CPU setup complete policy decision - +-----------> CPU_UP ------------+ - | v - - CPU_COMING_UP CPU_GOING_DOWN - - ^ | - +----------- CPU_DOWN <----------+ - policy decision CPU teardown complete - or hardware event - - -The definitions of the four states correspond closely to the states of -the basic model. - -Transitions between states occur as follows. - -A trigger event (spontaneous) means that the CPU can transition to the -next state as a result of making local progress only, with no -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 - - Trigger events: - - a) an explicit hardware power-up operation, resulting - from a policy decision on another CPU; - - b) a hardware event, such as an interrupt. - - -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. - - Refer to the "Cluster state" section for a description of the - CLUSTER_UP state. - - -CPU_UP: - When a CPU reaches the CPU_UP state, it is safe for the CPU to - start participating in local coherency. - - This is done by jumping to the kernel's CPU resume code. - - Note that the definition of this state is slightly different - from the basic model definition: CPU_UP does not mean that the - CPU is coherent yet, but it does mean that it is safe to resume - the kernel. The kernel handles the rest of the resume - procedure, so the remaining steps are not visible as part of the - race avoidance algorithm. - - 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 - - -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) - - -Cluster state -------------- - -A cluster is a group of connected CPUs with some common resources. -Because a cluster contains multiple CPUs, it can be doing multiple -things at the same time. This has some implications. In particular, a -CPU can start up while another CPU is tearing the cluster down. - -In this discussion, the "outbound side" is the view of the cluster state -as seen by a CPU tearing the cluster down. The "inbound side" is the -view of the cluster state as seen by a CPU setting the CPU up. - -In order to enable safe coordination in such situations, it is important -that a CPU which is setting up the cluster can advertise its state -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: - - 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 - - - The different pairings of these states results in six possible - states for the cluster as a whole: - - CLUSTER_UP - +==========> INBOUND_NOT_COMING_UP -------------+ - # | - | - CLUSTER_UP <----+ | - INBOUND_COMING_UP | v - - ^ CLUSTER_GOING_DOWN CLUSTER_GOING_DOWN - # INBOUND_COMING_UP <=== INBOUND_NOT_COMING_UP - - CLUSTER_DOWN | | - INBOUND_COMING_UP <----+ | - | - ^ | - +=========== CLUSTER_DOWN <------------+ - INBOUND_NOT_COMING_UP - - Transitions -----> can only be made by the outbound CPU, and - only involve changes to the "cluster" state. - - Transitions ===##> can only be made by the inbound CPU, and only - involve changes to the "inbound" state, except where there is no - further transition possible on the outbound side (i.e., the - outbound CPU has put the cluster into the CLUSTER_DOWN state). - - The race avoidance algorithm does not provide a way to determine - which exact CPUs within the cluster play these roles. This must - be decided in advance by some other means. Refer to the section - "Last man and first man selection" for more explanation. - - - CLUSTER_DOWN/INBOUND_NOT_COMING_UP is the only state where the - cluster can actually be powered down. - - The parallelism of the inbound and outbound CPUs is observed by - the existence of two different paths from CLUSTER_GOING_DOWN/ - INBOUND_NOT_COMING_UP (corresponding to GOING_DOWN in the basic - model) to CLUSTER_DOWN/INBOUND_COMING_UP (corresponding to - COMING_UP in the basic model). The second path avoids cluster - teardown completely. - - CLUSTER_UP/INBOUND_COMING_UP is equivalent to UP in the basic - model. The final transition to CLUSTER_UP/INBOUND_NOT_COMING_UP - is trivial and merely resets the state machine ready for the - next cycle. - - Details of the allowable transitions follow. - - The next state in each case is notated - - / () - - where the is the side on which the transition - can occur; either the inbound or the outbound side. - - -CLUSTER_DOWN/INBOUND_NOT_COMING_UP: - - 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; - - b) a hardware event, such as an interrupt. - - -CLUSTER_DOWN/INBOUND_COMING_UP: - - In this state, an inbound CPU sets up the cluster, including - enabling of hardware coherency at the cluster level and any - other operations (such as cache invalidation) which are required - in order to achieve this. - - The purpose of this state is to do sufficient cluster-level - 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) - - -CLUSTER_UP/INBOUND_COMING_UP: - - Cluster-level setup is complete and hardware coherency is - enabled for the cluster. Other CPUs in the cluster can safely - enter coherency. - - This is a transient state, leading immediately to - 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) - - -CLUSTER_UP/INBOUND_NOT_COMING_UP: - - Cluster-level setup is complete and hardware coherency is - enabled for the cluster. Other CPUs in the cluster can safely - enter coherency. - - 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 - - -CLUSTER_GOING_DOWN/INBOUND_NOT_COMING_UP: - - An outbound CPU is tearing the cluster down. The selected CPU - must wait in this state until all CPUs in the cluster are in the - CPU_DOWN state. - - When all CPUs are in the CPU_DOWN state, the cluster can be torn - down, for example by cleaning data caches and exiting - cluster-level coherency. - - To avoid wasteful unnecessary teardown operations, the outbound - should check the inbound cluster state for asynchronous - transitions to INBOUND_COMING_UP. Alternatively, individual - CPUs can be checked for entry into CPU_COMING_UP or CPU_UP. - - - Next states: - - CLUSTER_DOWN/INBOUND_NOT_COMING_UP (outbound) - Conditions: cluster torn down and ready to power off - Trigger events: (spontaneous) - - CLUSTER_GOING_DOWN/INBOUND_COMING_UP (inbound) - Conditions: none - Trigger events: - - a) an explicit hardware power-up operation, - resulting from a policy decision on another - CPU; - - b) a hardware event, such as an interrupt. - - -CLUSTER_GOING_DOWN/INBOUND_COMING_UP: - - The cluster is (or was) being torn down, but another CPU has - come online in the meantime and is trying to set up the cluster - again. - - If the outbound CPU observes this state, it has two choices: - - a) back out of teardown, restoring the cluster to the - CLUSTER_UP state; - - b) finish tearing the cluster down and put the cluster - in the CLUSTER_DOWN state; the inbound CPU will - set up the cluster again from there. - - Choice (a) permits the removal of some latency by avoiding - unnecessary teardown and setup operations in situations where - the cluster is not really going to be powered down. - - - Next states: - - CLUSTER_UP/INBOUND_COMING_UP (outbound) - Conditions: cluster-level setup and hardware - coherency complete - Trigger events: (spontaneous) - - CLUSTER_DOWN/INBOUND_COMING_UP (outbound) - Conditions: cluster torn down and ready to power off - Trigger events: (spontaneous) - - -Last man and First man selection --------------------------------- - -The CPU which performs cluster tear-down operations on the outbound side -is commonly referred to as the "last man". - -The CPU which performs cluster setup on the inbound side is commonly -referred to as the "first man". - -The race avoidance algorithm documented above does not provide a -mechanism to choose which CPUs should play these roles. - - -Last man: - -When shutting down the cluster, all the CPUs involved are initially -executing Linux and hence coherent. Therefore, ordinary spinlocks can -be used to select a last man safely, before the CPUs become -non-coherent. - - -First man: - -Because CPUs may power up asynchronously in response to external wake-up -events, a dynamic mechanism is needed to make sure that only one CPU -attempts to play the first man role and do the cluster-level -initialisation: any other CPUs must wait for this to complete before -proceeding. - -Cluster-level initialisation may involve actions such as configuring -coherency controls in the bus fabric. - -The current implementation in mcpm_head.S uses a separate mutual exclusion -mechanism to do this arbitration. This mechanism is documented in -detail in vlocks.txt. - - -Features and Limitations ------------------------- - -Implementation: - - The current ARM-based implementation is split between - arch/arm/common/mcpm_head.S (low-level inbound CPU operations) and - arch/arm/common/mcpm_entry.c (everything else): - - __mcpm_cpu_going_down() signals the transition of a CPU to the - CPU_GOING_DOWN state. - - __mcpm_cpu_down() signals the transition of a CPU to the CPU_DOWN - 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. - - __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). - - 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. - -Deep topologies: - - As currently described and implemented, the algorithm does not - support CPU topologies involving more than two levels (i.e., - clusters of clusters are not supported). The algorithm could be - extended by replicating the cluster-level states for the - additional topological levels, and modifying the transition - rules for the intermediate (non-outermost) cluster levels. - - -Colophon --------- - -Originally created and documented by Dave Martin for Linaro Limited, in -collaboration with Nicolas Pitre and Achin Gupta. - -Copyright (C) 2012-2013 Linaro Limited -Distributed under the terms of Version 2 of the GNU General Public -License, as defined in linux/COPYING. diff --git a/Documentation/arm/firmware.rst b/Documentation/arm/firmware.rst new file mode 100644 index 000000000000..efd844baec1d --- /dev/null +++ b/Documentation/arm/firmware.rst @@ -0,0 +1,72 @@ +========================================================================== +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 +world, which changes the way some things have to be initialized. This makes +a need to provide an interface for such platforms to specify available firmware +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:: + + void register_firmware_ops(const struct firmware_ops *ops) + +The ops pointer must be non-NULL. More information about struct firmware_ops +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:: + + #define call_firmware_op(op, ...) \ + ((firmware_ops->op) ? firmware_ops->op(__VA_ARGS__) : (-ENOSYS)) + +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:: + + /* board file */ + + static int platformX_do_idle(void) + { + /* tell platformX firmware to enter idle */ + return 0; + } + + static int platformX_cpu_boot(int i) + { + /* tell platformX firmware to boot CPU i */ + return 0; + } + + static const struct firmware_ops platformX_firmware_ops = { + .do_idle = exynos_do_idle, + .cpu_boot = exynos_cpu_boot, + /* other operations not available on platformX */ + }; + + /* init_early callback of machine descriptor */ + static void __init board_init_early(void) + { + register_firmware_ops(&platformX_firmware_ops); + } + +Example of using a firmware operation:: + + /* some platform code, e.g. SMP initialization */ + + __raw_writel(__pa_symbol(exynos4_secondary_startup), + CPU1_BOOT_REG); + + /* Call Exynos specific smc call */ + if (call_firmware_op(cpu_boot, cpu) == -ENOSYS) + cpu_boot_legacy(...); /* Try legacy way */ + + gic_raise_softirq(cpumask_of(cpu), 1); diff --git a/Documentation/arm/firmware.txt b/Documentation/arm/firmware.txt deleted file mode 100644 index 7f175dbb427e..000000000000 --- a/Documentation/arm/firmware.txt +++ /dev/null @@ -1,70 +0,0 @@ -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 -world, which changes the way some things have to be initialized. This makes -a need to provide an interface for such platforms to specify available firmware -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. - - void register_firmware_ops(const struct firmware_ops *ops) - -The ops pointer must be non-NULL. More information about struct firmware_ops -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 - - #define call_firmware_op(op, ...) \ - ((firmware_ops->op) ? firmware_ops->op(__VA_ARGS__) : (-ENOSYS)) - -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: - - /* board file */ - - static int platformX_do_idle(void) - { - /* tell platformX firmware to enter idle */ - return 0; - } - - static int platformX_cpu_boot(int i) - { - /* tell platformX firmware to boot CPU i */ - return 0; - } - - static const struct firmware_ops platformX_firmware_ops = { - .do_idle = exynos_do_idle, - .cpu_boot = exynos_cpu_boot, - /* other operations not available on platformX */ - }; - - /* init_early callback of machine descriptor */ - static void __init board_init_early(void) - { - register_firmware_ops(&platformX_firmware_ops); - } - -Example of using a firmware operation: - - /* some platform code, e.g. SMP initialization */ - - __raw_writel(__pa_symbol(exynos4_secondary_startup), - CPU1_BOOT_REG); - - /* Call Exynos specific smc call */ - if (call_firmware_op(cpu_boot, cpu) == -ENOSYS) - cpu_boot_legacy(...); /* Try legacy way */ - - gic_raise_softirq(cpumask_of(cpu), 1); 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.rst b/Documentation/arm/interrupts.rst new file mode 100644 index 000000000000..2ae70e0e9732 --- /dev/null +++ b/Documentation/arm/interrupts.rst @@ -0,0 +1,169 @@ +========== +Interrupts +========== + +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 - +we have TLB v3, TLB v4 (without write buffer), TLB v4 (with write buffer), +and finally TLB v4 (with write buffer, with I TLB invalidate entry). +There is more assembly code inside each of these functions, mainly to +allow more flexible TLB handling for the future. + +Secondly, the IRQ subsystem. + +The 2.5 kernels will be having major changes to the way IRQs are handled. +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:: + + GPIO25 IRR:2 + SA1100 ------------> Neponset -----------> SA1111 + IIR:1 + -----------> USAR + IIR:0 + -----------> SMC9196 + +The way stuff currently works, all SA1111 interrupts are mutually +exclusive of each other - if you're processing one interrupt from the +SA1111 and another comes in, you have to wait for that interrupt to +finish processing before you can service the new interrupt. Eg, an +IDE PIO-based interrupt on the SA1111 excludes all other SA1111 and +SMC9196 interrupts until it has finished transferring its multi-sector +data, which can be a long time. Note also that since we loop in the +SA1111 IRQ handler, SA1111 IRQs can hold off SMC9196 IRQs indefinitely. + + +The new approach brings several new ideas... + +We introduce the concept of a "parent" and a "child". For example, +to the Neponset handler, the "parent" is GPIO25, and the "children"d +are SA1111, SMC9196 and USAR. + +We also bring the idea of an IRQ "chip" (mainly to reduce the size of +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:: + + 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 + handled by do_level_IRQ. +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, + it should be null so people can detect if they are unable to + set the IRQ type. + +For each IRQ, we keep the following information: + + - "disable" depth (number of disable_irq()s without enable_irq()s) + - flags indicating what we can do with this IRQ (valid, probe, + noautounmask) as before + - status of the IRQ (probing, enable, etc) + - chip + - per-IRQ handler + - irqaction structure list + +The handler can be one of the 3 standard handlers - "level", "edge" and +"simple", or your own specific handler if you need to do something special. + +The "level" handler is what we currently have - its pretty simple. +"edge" knows about the brokenness of such IRQ implementations - that you +need to leave the hardware IRQ enabled while processing it, and queueing +further IRQ events should the IRQ happen again while processing. The +"simple" handler is very basic, and does not perform any hardware +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. + +2. New functions to manipulate the irqdesc array. The first 4 are expected + to be useful only to machine specific code. The last is recommended to + only be used by machine specific code, but may be used in drivers if + 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 + + +3. set_GPIO_IRQ_edge() is obsolete, and should be replaced by set_irq_type. + +4. Direct access to SA1111 INTPOL is deprecated. Use set_irq_type instead. + +5. A handler is expected to perform any necessary acknowledgement of the + parent IRQ via the correct chip specific function. For instance, if + the SA1111 is directly connected to a SA1110 GPIO, then you should + acknowledge the SA1110 IRQ each time you re-read the SA1111 IRQ status. + +6. For any child which doesn't have its own IRQ enable/disable controls + (eg, SMC9196), the handler must mask or acknowledge the parent IRQ + while the child handler is called, and the child handler should be the + "simple" handler (not "edge" nor "level"). After the handler completes, + the parent IRQ should be unmasked, and the status of all children must + 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` + +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.rst b/Documentation/arm/ixp4xx.rst new file mode 100644 index 000000000000..a57235616294 --- /dev/null +++ b/Documentation/arm/ixp4xx.rst @@ -0,0 +1,173 @@ +=========================================================== +Release Notes for Linux on Intel's IXP4xx Network Processor +=========================================================== + +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 +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, +routing, firewalling, etc. The IXP46x family is an updated version which +supports faster speeds, new memory and flash configurations, and more +integration such as an on-chip I2C controller. + +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 +stripped of much of the network intelligence. + +2. Linux Support + +Linux currently supports the following features on the IXP4xx chips: + +- Dual serial ports +- PCI interface +- Flash access (MTD/JFFS) +- I2C through GPIO on IXP42x +- GPIO for input/output/interrupts + See arch/arm/mach-ixp4xx/include/mach/platform.h for access functions. +- Timers (watchdog, OS) + +The following components of the chips are not supported by Linux and +require the use of Intel's proprietary CSR software: + +- USB device interface +- Network interfaces (HSS, Utopia, NPEs, etc) +- Network offload functionality + +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 + +DO NOT POST QUESTIONS TO THE LINUX MAILING LISTS REGARDING THE PROPRIETARY +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://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 + +3. Known Issues/Limitations + +3a. Limited inbound PCI window + +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: + +1) A direct mapped window from 0x48000000 to 0x4bffffff (64MB). + 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 + 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 + mmap() PCI devices in this case due to the indirect nature + of the PCI window. + +By default, the direct method is used for performance reasons. If +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 + +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 + 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 + via SLICs. Note that those are not supported by Linux ATM. Finally, + the platform has two mini-PCI slots used for 802.11[bga] cards. + Finally, there is an IDE port hanging off the expansion bus. + +Gateworks Avila Network Platform +http://www.gateworks.com/support/overview.php + + The Avila platform is basically and IXDP425 with the 4 PCI slots + replaced with mini-PCI slots and a CF IDE interface hanging off + the expansion bus. + +Intel IXDP425 Development Platform +http://www.intel.com/design/network/products/npfamily/ixdpg425.htm + + 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. + +Intel IXDP465 Development Platform +http://www.intel.com/design/network/products/npfamily/ixdp465.htm + + This is basically an IXDP425 with an IXP465 and 32M of flash instead + of just 16. + +Intel IXDPG425 Development Platform + + This is basically and ADI Coyote board with a NEC EHCI controller + added. One issue with this board is that the mini-PCI slots only + have the 3.3v line connected, so you can't use a PCI to mini-PCI + adapter with an E100 card. So to NFS root you need to use either + the CSR or a WiFi card and a ramdisk that BOOTPs and then does + a pivot_root to NFS. + +Motorola PrPMC1100 Processor Mezanine Card +http://www.fountainsys.com + + The PrPMC1100 is based on the IXCP1100 and is meant to plug into + and IXP2400/2800 system to act as the system controller. It simply + contains a CPU and 16MB of flash on the board and needs to be + plugged into a carrier board to function. Currently Linux only + supports the Motorola PrPMC carrier board for this platform. + +5. TODO LIST + +- Add support for Coyote IDE +- Add support for edge-based GPIO interrupts +- Add support for CF IDE on expansion bus + +6. Thanks + +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] + +------------------------------------------------------------------------- + +Last Update: 01/04/2005 diff --git a/Documentation/arm/kernel_mode_neon.rst b/Documentation/arm/kernel_mode_neon.rst new file mode 100644 index 000000000000..9bfb71a2a9b9 --- /dev/null +++ b/Documentation/arm/kernel_mode_neon.rst @@ -0,0 +1,124 @@ +================ +Kernel mode NEON +================ + +TL;DR summary +------------- +* Use only NEON instructions, or VFP instructions that don't rely on support + code +* Isolate your NEON code in a separate compilation unit, and compile it with + '-march=armv7-a -mfpu=neon -mfloat-abi=softfp' +* Put kernel_neon_begin() and kernel_neon_end() calls around the calls into your + NEON code +* Don't sleep in your NEON code, and be aware that it will be executed with + preemption disabled + + +Introduction +------------ +It is possible to use NEON instructions (and in some cases, VFP instructions) in +code that runs in kernel mode. However, for performance reasons, the NEON/VFP +register file is not preserved and restored at every context switch or taken +exception like the normal register file is, so some manual intervention is +required. Furthermore, special care is required for code that may sleep [i.e., +may call schedule()], as NEON or VFP instructions will be executed in a +non-preemptible section for reasons outlined below. + + +Lazy preserve and restore +------------------------- +The NEON/VFP register file is managed using lazy preserve (on UP systems) and +lazy restore (on both SMP and UP systems). This means that the register file is +kept 'live', and is only preserved and restored when multiple tasks are +contending for the NEON/VFP unit (or, in the SMP case, when a task migrates to +another core). Lazy restore is implemented by disabling the NEON/VFP unit after +every context switch, resulting in a trap when subsequently a NEON/VFP +instruction is issued, allowing the kernel to step in and perform the restore if +necessary. + +Any use of the NEON/VFP unit in kernel mode should not interfere with this, so +it is required to do an 'eager' preserve of the NEON/VFP register file, and +enable the NEON/VFP unit explicitly so no exceptions are generated on first +subsequent use. This is handled by the function kernel_neon_begin(), which +should be called before any kernel mode NEON or VFP instructions are issued. +Likewise, the NEON/VFP unit should be disabled again after use to make sure user +mode will hit the lazy restore trap upon next use. This is handled by the +function kernel_neon_end(). + + +Interruptions in kernel mode +---------------------------- +For reasons of performance and simplicity, it was decided that there shall be no +preserve/restore mechanism for the kernel mode NEON/VFP register contents. This +implies that interruptions of a kernel mode NEON section can only be allowed if +they are guaranteed not to touch the NEON/VFP registers. For this reason, the +following rules and restrictions apply in the kernel: +* NEON/VFP code is not allowed in interrupt context; +* NEON/VFP code is not allowed to sleep; +* NEON/VFP code is executed with preemption disabled. + +If latency is a concern, it is possible to put back to back calls to +kernel_neon_end() and kernel_neon_begin() in places in your code where none of +the NEON registers are live. (Additional calls to kernel_neon_begin() should be +reasonably cheap if no context switch occurred in the meantime) + + +VFP and support code +-------------------- +Earlier versions of VFP (prior to version 3) rely on software support for things +like IEEE-754 compliant underflow handling etc. When the VFP unit needs such +software assistance, it signals the kernel by raising an undefined instruction +exception. The kernel responds by inspecting the VFP control registers and the +current instruction and arguments, and emulates the instruction in software. + +Such software assistance is currently not implemented for VFP instructions +executed in kernel mode. If such a condition is encountered, the kernel will +fail and generate an OOPS. + + +Separating NEON code from ordinary code +--------------------------------------- +The compiler is not aware of the special significance of kernel_neon_begin() and +kernel_neon_end(), i.e., that it is only allowed to issue NEON/VFP instructions +between calls to these respective functions. Furthermore, GCC may generate NEON +instructions of its own at -O3 level if -mfpu=neon is selected, and even if the +kernel is currently compiled at -O2, future changes may result in NEON/VFP +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 + into the unit containing the NEON code from a compilation unit which is *not* + built with the GCC flag '-mfpu=neon' set. + +As the kernel is compiled with '-msoft-float', the above will guarantee that +both NEON and VFP instructions will only ever appear in designated compilation +units at any optimization level. + + +NEON assembler +-------------- +NEON assembler is supported with no additional caveats as long as the rules +above are followed. + + +NEON code generated by GCC +-------------------------- +The GCC option -ftree-vectorize (implied by -O3) tries to exploit implicit +parallelism, and generates NEON code from ordinary C source code. This is fully +supported as long as the rules above are followed. + + +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); +* Include last, or at least after diff --git a/Documentation/arm/kernel_mode_neon.txt b/Documentation/arm/kernel_mode_neon.txt deleted file mode 100644 index b9e060c5b61e..000000000000 --- a/Documentation/arm/kernel_mode_neon.txt +++ /dev/null @@ -1,121 +0,0 @@ -Kernel mode NEON -================ - -TL;DR summary -------------- -* Use only NEON instructions, or VFP instructions that don't rely on support - code -* Isolate your NEON code in a separate compilation unit, and compile it with - '-march=armv7-a -mfpu=neon -mfloat-abi=softfp' -* Put kernel_neon_begin() and kernel_neon_end() calls around the calls into your - NEON code -* Don't sleep in your NEON code, and be aware that it will be executed with - preemption disabled - - -Introduction ------------- -It is possible to use NEON instructions (and in some cases, VFP instructions) in -code that runs in kernel mode. However, for performance reasons, the NEON/VFP -register file is not preserved and restored at every context switch or taken -exception like the normal register file is, so some manual intervention is -required. Furthermore, special care is required for code that may sleep [i.e., -may call schedule()], as NEON or VFP instructions will be executed in a -non-preemptible section for reasons outlined below. - - -Lazy preserve and restore -------------------------- -The NEON/VFP register file is managed using lazy preserve (on UP systems) and -lazy restore (on both SMP and UP systems). This means that the register file is -kept 'live', and is only preserved and restored when multiple tasks are -contending for the NEON/VFP unit (or, in the SMP case, when a task migrates to -another core). Lazy restore is implemented by disabling the NEON/VFP unit after -every context switch, resulting in a trap when subsequently a NEON/VFP -instruction is issued, allowing the kernel to step in and perform the restore if -necessary. - -Any use of the NEON/VFP unit in kernel mode should not interfere with this, so -it is required to do an 'eager' preserve of the NEON/VFP register file, and -enable the NEON/VFP unit explicitly so no exceptions are generated on first -subsequent use. This is handled by the function kernel_neon_begin(), which -should be called before any kernel mode NEON or VFP instructions are issued. -Likewise, the NEON/VFP unit should be disabled again after use to make sure user -mode will hit the lazy restore trap upon next use. This is handled by the -function kernel_neon_end(). - - -Interruptions in kernel mode ----------------------------- -For reasons of performance and simplicity, it was decided that there shall be no -preserve/restore mechanism for the kernel mode NEON/VFP register contents. This -implies that interruptions of a kernel mode NEON section can only be allowed if -they are guaranteed not to touch the NEON/VFP registers. For this reason, the -following rules and restrictions apply in the kernel: -* NEON/VFP code is not allowed in interrupt context; -* NEON/VFP code is not allowed to sleep; -* NEON/VFP code is executed with preemption disabled. - -If latency is a concern, it is possible to put back to back calls to -kernel_neon_end() and kernel_neon_begin() in places in your code where none of -the NEON registers are live. (Additional calls to kernel_neon_begin() should be -reasonably cheap if no context switch occurred in the meantime) - - -VFP and support code --------------------- -Earlier versions of VFP (prior to version 3) rely on software support for things -like IEEE-754 compliant underflow handling etc. When the VFP unit needs such -software assistance, it signals the kernel by raising an undefined instruction -exception. The kernel responds by inspecting the VFP control registers and the -current instruction and arguments, and emulates the instruction in software. - -Such software assistance is currently not implemented for VFP instructions -executed in kernel mode. If such a condition is encountered, the kernel will -fail and generate an OOPS. - - -Separating NEON code from ordinary code ---------------------------------------- -The compiler is not aware of the special significance of kernel_neon_begin() and -kernel_neon_end(), i.e., that it is only allowed to issue NEON/VFP instructions -between calls to these respective functions. Furthermore, GCC may generate NEON -instructions of its own at -O3 level if -mfpu=neon is selected, and even if the -kernel is currently compiled at -O2, future changes may result in NEON/VFP -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 - into the unit containing the NEON code from a compilation unit which is *not* - built with the GCC flag '-mfpu=neon' set. - -As the kernel is compiled with '-msoft-float', the above will guarantee that -both NEON and VFP instructions will only ever appear in designated compilation -units at any optimization level. - - -NEON assembler --------------- -NEON assembler is supported with no additional caveats as long as the rules -above are followed. - - -NEON code generated by GCC --------------------------- -The GCC option -ftree-vectorize (implied by -O3) tries to exploit implicit -parallelism, and generates NEON code from ordinary C source code. This is fully -supported as long as the rules above are followed. - - -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); -* Include last, or at least after diff --git a/Documentation/arm/kernel_user_helpers.rst b/Documentation/arm/kernel_user_helpers.rst new file mode 100644 index 000000000000..eb6f3d916622 --- /dev/null +++ b/Documentation/arm/kernel_user_helpers.rst @@ -0,0 +1,268 @@ +============================ +Kernel-provided User Helpers +============================ + +These are segment of kernel provided user code reachable from user space +at a fixed address in kernel memory. This is used to provide user space +with some operations which require kernel help because of unimplemented +native feature and/or instructions in many ARM CPUs. The idea is for this +code to be executed directly in user mode for best efficiency but which is +too intimate with the kernel counter part to be left to user libraries. +In fact this code might even differ from one CPU to another depending on +the available instruction set, or whether it is a SMP systems. In other +words, the kernel reserves the right to change this code as needed without +warning. Only the entry points and their results as documented here are +guaranteed to be stable. + +This is different from (but doesn't preclude) a full blown VDSO +implementation, however a VDSO would prevent some assembly tricks with +constants that allows for efficient branching to those code segments. And +since those code segments only use a few cycles before returning to user +code, the overhead of a VDSO indirect far call would add a measurable +overhead to such minimalistic operations. + +User space is expected to bypass those helpers and implement those things +inline (either in the code emitted directly by the compiler, or part of +the implementation of a library call) when optimizing for a recent enough +processor that has the necessary native support, but only if resulting +binaries are already to be incompatible with earlier ARM processors due to +usage of similar native instructions for other things. In other words +don't make binaries unable to run on earlier processors just for the sake +of not using these kernel helpers if your compiled code is not going to +use new instructions for other purpose. + +New helpers may be added over time, so an older kernel may be missing some +helpers present in a newer kernel. For this reason, programs must check +the value of __kuser_helper_version (see below) before assuming that it is +safe to call any particular helper. This check should ideally be +performed only once at process startup time, and execution aborted early +if the required helpers are not provided by the kernel version that +process is running on. + +kuser_helper_version +-------------------- + +Location: 0xffff0ffc + +Reference declaration:: + + extern int32_t __kuser_helper_version; + +Definition: + + This field contains the number of helpers being implemented by the + running kernel. User space may read this to determine the availability + of a particular helper. + +Usage example:: + + #define __kuser_helper_version (*(int32_t *)0xffff0ffc) + + void check_kuser_version(void) + { + if (__kuser_helper_version < 2) { + fprintf(stderr, "can't do atomic operations, kernel too old\n"); + abort(); + } + } + +Notes: + + User space may assume that the value of this field never changes + during the lifetime of any single process. This means that this + field can be read once during the initialisation of a library or + startup phase of a program. + +kuser_get_tls +------------- + +Location: 0xffff0fe0 + +Reference prototype:: + + void * __kuser_get_tls(void); + +Input: + + lr = return address + +Output: + + r0 = TLS value + +Clobbered registers: + + none + +Definition: + + Get the TLS value as previously set via the __ARM_NR_set_tls syscall. + +Usage example:: + + typedef void * (__kuser_get_tls_t)(void); + #define __kuser_get_tls (*(__kuser_get_tls_t *)0xffff0fe0) + + void foo() + { + void *tls = __kuser_get_tls(); + printf("TLS = %p\n", tls); + } + +Notes: + + - Valid only if __kuser_helper_version >= 1 (from kernel version 2.6.12). + +kuser_cmpxchg +------------- + +Location: 0xffff0fc0 + +Reference prototype:: + + int __kuser_cmpxchg(int32_t oldval, int32_t newval, volatile int32_t *ptr); + +Input: + + r0 = oldval + r1 = newval + r2 = ptr + lr = return address + +Output: + + r0 = success code (zero or non-zero) + C flag = set if r0 == 0, clear if r0 != 0 + +Clobbered registers: + + r3, ip, flags + +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 + optimization in the calling code. + +Usage example:: + + 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 old, new; + + do { + old = *ptr; + new = old + val; + } while(__kuser_cmpxchg(old, new, ptr)); + + return new; + } + +Notes: + + - This routine already includes memory barriers as needed. + + - Valid only if __kuser_helper_version >= 2 (from kernel version 2.6.12). + +kuser_memory_barrier +-------------------- + +Location: 0xffff0fa0 + +Reference prototype:: + + void __kuser_memory_barrier(void); + +Input: + + lr = return address + +Output: + + none + +Clobbered registers: + + none + +Definition: + + Apply any needed memory barrier to preserve consistency with data modified + manually and __kuser_cmpxchg usage. + +Usage example:: + + typedef void (__kuser_dmb_t)(void); + #define __kuser_dmb (*(__kuser_dmb_t *)0xffff0fa0) + +Notes: + + - Valid only if __kuser_helper_version >= 3 (from kernel version 2.6.15). + +kuser_cmpxchg64 +--------------- + +Location: 0xffff0f60 + +Reference prototype:: + + int __kuser_cmpxchg64(const int64_t *oldval, + const int64_t *newval, + volatile int64_t *ptr); + +Input: + + r0 = pointer to oldval + r1 = pointer to newval + r2 = pointer to target value + lr = return address + +Output: + + r0 = success code (zero or non-zero) + C flag = set if r0 == 0, clear if r0 != 0 + +Clobbered registers: + + r3, lr, flags + +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 + 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:: + + 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 old, new; + + do { + old = *ptr; + new = old + val; + } while(__kuser_cmpxchg64(&old, &new, ptr)); + + return new; + } + +Notes: + + - This routine already includes memory barriers as needed. + + - Due to the length of this sequence, this spans 2 conventional kuser + "slots", therefore 0xffff0f80 is not used as a valid entry point. + + - Valid only if __kuser_helper_version >= 5 (from kernel version 3.1). diff --git a/Documentation/arm/kernel_user_helpers.txt b/Documentation/arm/kernel_user_helpers.txt deleted file mode 100644 index 5673594717cf..000000000000 --- a/Documentation/arm/kernel_user_helpers.txt +++ /dev/null @@ -1,267 +0,0 @@ -Kernel-provided User Helpers -============================ - -These are segment of kernel provided user code reachable from user space -at a fixed address in kernel memory. This is used to provide user space -with some operations which require kernel help because of unimplemented -native feature and/or instructions in many ARM CPUs. The idea is for this -code to be executed directly in user mode for best efficiency but which is -too intimate with the kernel counter part to be left to user libraries. -In fact this code might even differ from one CPU to another depending on -the available instruction set, or whether it is a SMP systems. In other -words, the kernel reserves the right to change this code as needed without -warning. Only the entry points and their results as documented here are -guaranteed to be stable. - -This is different from (but doesn't preclude) a full blown VDSO -implementation, however a VDSO would prevent some assembly tricks with -constants that allows for efficient branching to those code segments. And -since those code segments only use a few cycles before returning to user -code, the overhead of a VDSO indirect far call would add a measurable -overhead to such minimalistic operations. - -User space is expected to bypass those helpers and implement those things -inline (either in the code emitted directly by the compiler, or part of -the implementation of a library call) when optimizing for a recent enough -processor that has the necessary native support, but only if resulting -binaries are already to be incompatible with earlier ARM processors due to -usage of similar native instructions for other things. In other words -don't make binaries unable to run on earlier processors just for the sake -of not using these kernel helpers if your compiled code is not going to -use new instructions for other purpose. - -New helpers may be added over time, so an older kernel may be missing some -helpers present in a newer kernel. For this reason, programs must check -the value of __kuser_helper_version (see below) before assuming that it is -safe to call any particular helper. This check should ideally be -performed only once at process startup time, and execution aborted early -if the required helpers are not provided by the kernel version that -process is running on. - -kuser_helper_version --------------------- - -Location: 0xffff0ffc - -Reference declaration: - - extern int32_t __kuser_helper_version; - -Definition: - - This field contains the number of helpers being implemented by the - running kernel. User space may read this to determine the availability - of a particular helper. - -Usage example: - -#define __kuser_helper_version (*(int32_t *)0xffff0ffc) - -void check_kuser_version(void) -{ - if (__kuser_helper_version < 2) { - fprintf(stderr, "can't do atomic operations, kernel too old\n"); - abort(); - } -} - -Notes: - - User space may assume that the value of this field never changes - during the lifetime of any single process. This means that this - field can be read once during the initialisation of a library or - startup phase of a program. - -kuser_get_tls -------------- - -Location: 0xffff0fe0 - -Reference prototype: - - void * __kuser_get_tls(void); - -Input: - - lr = return address - -Output: - - r0 = TLS value - -Clobbered registers: - - none - -Definition: - - Get the TLS value as previously set via the __ARM_NR_set_tls syscall. - -Usage example: - -typedef void * (__kuser_get_tls_t)(void); -#define __kuser_get_tls (*(__kuser_get_tls_t *)0xffff0fe0) - -void foo() -{ - void *tls = __kuser_get_tls(); - printf("TLS = %p\n", tls); -} - -Notes: - - - Valid only if __kuser_helper_version >= 1 (from kernel version 2.6.12). - -kuser_cmpxchg -------------- - -Location: 0xffff0fc0 - -Reference prototype: - - int __kuser_cmpxchg(int32_t oldval, int32_t newval, volatile int32_t *ptr); - -Input: - - r0 = oldval - r1 = newval - r2 = ptr - lr = return address - -Output: - - r0 = success code (zero or non-zero) - C flag = set if r0 == 0, clear if r0 != 0 - -Clobbered registers: - - r3, ip, flags - -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 - optimization in the calling code. - -Usage example: - -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 old, new; - - do { - old = *ptr; - new = old + val; - } while(__kuser_cmpxchg(old, new, ptr)); - - return new; -} - -Notes: - - - This routine already includes memory barriers as needed. - - - Valid only if __kuser_helper_version >= 2 (from kernel version 2.6.12). - -kuser_memory_barrier --------------------- - -Location: 0xffff0fa0 - -Reference prototype: - - void __kuser_memory_barrier(void); - -Input: - - lr = return address - -Output: - - none - -Clobbered registers: - - none - -Definition: - - Apply any needed memory barrier to preserve consistency with data modified - manually and __kuser_cmpxchg usage. - -Usage example: - -typedef void (__kuser_dmb_t)(void); -#define __kuser_dmb (*(__kuser_dmb_t *)0xffff0fa0) - -Notes: - - - Valid only if __kuser_helper_version >= 3 (from kernel version 2.6.15). - -kuser_cmpxchg64 ---------------- - -Location: 0xffff0f60 - -Reference prototype: - - int __kuser_cmpxchg64(const int64_t *oldval, - const int64_t *newval, - volatile int64_t *ptr); - -Input: - - r0 = pointer to oldval - r1 = pointer to newval - r2 = pointer to target value - lr = return address - -Output: - - r0 = success code (zero or non-zero) - C flag = set if r0 == 0, clear if r0 != 0 - -Clobbered registers: - - r3, lr, flags - -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 - 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: - -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 old, new; - - do { - old = *ptr; - new = old + val; - } while(__kuser_cmpxchg64(&old, &new, ptr)); - - return new; -} - -Notes: - - - This routine already includes memory barriers as needed. - - - Due to the length of this sequence, this spans 2 conventional kuser - "slots", therefore 0xffff0f80 is not used as a valid entry point. - - - Valid only if __kuser_helper_version >= 5 (from kernel version 3.1). diff --git a/Documentation/arm/keystone/Overview.txt b/Documentation/arm/keystone/Overview.txt deleted file mode 100644 index 400c0c270d2e..000000000000 --- a/Documentation/arm/keystone/Overview.txt +++ /dev/null @@ -1,55 +0,0 @@ - TI Keystone Linux Overview - -------------------------- - -Introduction ------------- -Keystone range of SoCs are based on ARM Cortex-A15 MPCore Processors -and c66x DSP cores. This document describes essential information required -for users to run Linux on Keystone based EVMs from Texas Instruments. - -Following SoCs & EVMs are currently supported:- - ------------- 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 - ------------- K2E SoC and EVM --------------------------------------------------- - -a.k.a Keystone 2 Edison SoC -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 - ------------- K2L SoC and EVM --------------------------------------------------- - -a.k.a Keystone 2 Lamarr SoC -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 - -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 - -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/keystone/knav-qmss.rst b/Documentation/arm/keystone/knav-qmss.rst new file mode 100644 index 000000000000..7f7638d80b42 --- /dev/null +++ b/Documentation/arm/keystone/knav-qmss.rst @@ -0,0 +1,60 @@ +====================================================================== +Texas Instruments Keystone Navigator Queue Management SubSystem driver +====================================================================== + +Driver source code path + drivers/soc/ti/knav_qmss.c + drivers/soc/ti/knav_qmss_acc.c + +The QMSS (Queue Manager Sub System) found on Keystone SOCs is one of +the main hardware sub system which forms the backbone of the Keystone +multi-core Navigator. QMSS consist of queue managers, packed-data structure +processors(PDSP), linking RAM, descriptor pools and infrastructure +Packet DMA. +The Queue Manager is a hardware module that is responsible for accelerating +management of the packet queues. Packets are queued/de-queued by writing or +reading descriptor address to a particular memory mapped location. The PDSPs +perform QMSS related functions like accumulation, QoS, or event management. +Linking RAM registers are used to link the descriptors which are stored in +descriptor RAM. Descriptor RAM is configurable as internal or external memory. +The QMSS driver manages the PDSP setups, linking RAM regions, +queue pool management (allocation, push, pop and notify) and descriptor +pool management. + +knav qmss driver provides a set of APIs to drivers to open/close qmss queues, +allocate descriptor pools, map the descriptors, push/pop to queues etc. For +details of the available APIs, please refers to include/linux/soc/ti/knav_qmss.h + +DT documentation is available at +Documentation/devicetree/bindings/soc/ti/keystone-navigator-qmss.txt + +Accumulator QMSS queues using PDSP firmware +============================================ +The QMSS PDSP firmware support accumulator channel that can monitor a single +queue or multiple contiguous queues. drivers/soc/ti/knav_qmss_acc.c is the +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 +ubifs file system and provide a sym link to k2_qmss_pdsp_acc48_k2_le_1_0_0_9.bin +in the file system and boot up the kernel. User would see + + "firmware file ks2_qmss_pdsp_acc48.bin downloaded for PDSP" + +in the boot up log if loading of firmware to PDSP is successful. + +Use of accumulated queues requires the firmware image to be present in the +file system. The driver doesn't acc queues to the supported queue range if +PDSP is not running in the SoC. The API call fails if there is a queue open +request to an acc queue and PDSP is not running. So make sure to copy firmware +to file system before using these queue types. diff --git a/Documentation/arm/keystone/knav-qmss.txt b/Documentation/arm/keystone/knav-qmss.txt deleted file mode 100644 index fcdb9fd5f53a..000000000000 --- a/Documentation/arm/keystone/knav-qmss.txt +++ /dev/null @@ -1,56 +0,0 @@ -* Texas Instruments Keystone Navigator Queue Management SubSystem driver - -Driver source code path - drivers/soc/ti/knav_qmss.c - drivers/soc/ti/knav_qmss_acc.c - -The QMSS (Queue Manager Sub System) found on Keystone SOCs is one of -the main hardware sub system which forms the backbone of the Keystone -multi-core Navigator. QMSS consist of queue managers, packed-data structure -processors(PDSP), linking RAM, descriptor pools and infrastructure -Packet DMA. -The Queue Manager is a hardware module that is responsible for accelerating -management of the packet queues. Packets are queued/de-queued by writing or -reading descriptor address to a particular memory mapped location. The PDSPs -perform QMSS related functions like accumulation, QoS, or event management. -Linking RAM registers are used to link the descriptors which are stored in -descriptor RAM. Descriptor RAM is configurable as internal or external memory. -The QMSS driver manages the PDSP setups, linking RAM regions, -queue pool management (allocation, push, pop and notify) and descriptor -pool management. - -knav qmss driver provides a set of APIs to drivers to open/close qmss queues, -allocate descriptor pools, map the descriptors, push/pop to queues etc. For -details of the available APIs, please refers to include/linux/soc/ti/knav_qmss.h - -DT documentation is available at -Documentation/devicetree/bindings/soc/ti/keystone-navigator-qmss.txt - -Accumulator QMSS queues using PDSP firmware -============================================ -The QMSS PDSP firmware support accumulator channel that can monitor a single -queue or multiple contiguous queues. drivers/soc/ti/knav_qmss_acc.c is the -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 -ubifs file system and provide a sym link to k2_qmss_pdsp_acc48_k2_le_1_0_0_9.bin -in the file system and boot up the kernel. User would see - - "firmware file ks2_qmss_pdsp_acc48.bin downloaded for PDSP" - -in the boot up log if loading of firmware to PDSP is successful. - -Use of accumulated queues requires the firmware image to be present in the -file system. The driver doesn't acc queues to the supported queue range if -PDSP is not running in the SoC. The API call fails if there is a queue open -request to an acc queue and PDSP is not running. So make sure to copy firmware -to file system before using these queue types. diff --git a/Documentation/arm/keystone/overview.rst b/Documentation/arm/keystone/overview.rst new file mode 100644 index 000000000000..cd90298c493c --- /dev/null +++ b/Documentation/arm/keystone/overview.rst @@ -0,0 +1,74 @@ +========================== +TI Keystone Linux Overview +========================== + +Introduction +------------ +Keystone range of SoCs are based on ARM Cortex-A15 MPCore Processors +and c66x DSP cores. This document describes essential information required +for users to run Linux on Keystone based EVMs from Texas Instruments. + +Following SoCs & EVMs are currently supported:- + +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 + +K2E SoC and EVM +=============== + +a.k.a Keystone 2 Edison SoC + +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 + +K2L SoC and EVM +=============== + +a.k.a Keystone 2 Lamarr SoC + +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 + +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 + +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 deleted file mode 100644 index e110e2781039..000000000000 --- a/Documentation/arm/mem_alignment +++ /dev/null @@ -1,58 +0,0 @@ -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 -bad idea to configure it out, but Russell King has some good reasons for -doing so on some f***ed up ARM architectures like the EBSA110. However -this is not the case on many design I'm aware of, like all SA11x0 based -ones. - -Of course this is a bad idea to rely on the alignment trap to perform -unaligned memory access in general. If those access are predictable, you -are better to use the macros provided by include/asm/unaligned.h. The -alignment trap can fixup misaligned access for the exception cases, but at -a high performance cost. It better be rare. - -Now for user space applications, it is possible to configure the alignment -trap to SIGBUS any code performing unaligned access (good for debugging bad -code), or even fixup the access by software like for kernel code. The later -mode isn't recommended for performance reasons (just think about the -floating point emulation that works about the same way). Fix your code -instead! - -Please note that randomly changing the behaviour without good thought is -real bad - it changes the behaviour of all unaligned instructions in user -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 - fault code. - -1 The kernel will attempt to fix up the user process - performing the unaligned access. This is of course - slow (think about the floating point emulator) and - not recommended for production use. - -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: - - echo 1 > /proc/cpu/alignment - -You can also read the content of the same file to get statistical -information on unaligned access occurrences plus the current mode of -operation for user space code. - - -Nicolas Pitre, Mar 13, 2001. Modified Russell King, Nov 30, 2001. diff --git a/Documentation/arm/mem_alignment.rst b/Documentation/arm/mem_alignment.rst new file mode 100644 index 000000000000..aa22893b62bc --- /dev/null +++ b/Documentation/arm/mem_alignment.rst @@ -0,0 +1,63 @@ +================ +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 +bad idea to configure it out, but Russell King has some good reasons for +doing so on some f***ed up ARM architectures like the EBSA110. However +this is not the case on many design I'm aware of, like all SA11x0 based +ones. + +Of course this is a bad idea to rely on the alignment trap to perform +unaligned memory access in general. If those access are predictable, you +are better to use the macros provided by include/asm/unaligned.h. The +alignment trap can fixup misaligned access for the exception cases, but at +a high performance cost. It better be rare. + +Now for user space applications, it is possible to configure the alignment +trap to SIGBUS any code performing unaligned access (good for debugging bad +code), or even fixup the access by software like for kernel code. The later +mode isn't recommended for performance reasons (just think about the +floating point emulation that works about the same way). Fix your code +instead! + +Please note that randomly changing the behaviour without good thought is +real bad - it changes the behaviour of all unaligned instructions in user +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 + fault code. + +1 The kernel will attempt to fix up the user process + performing the unaligned access. This is of course + slow (think about the floating point emulator) and + not recommended for production use. + +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:: + + echo 1 > /proc/cpu/alignment + +You can also read the content of the same file to get statistical +information on unaligned access occurrences plus the current mode of +operation for user space code. + + +Nicolas Pitre, Mar 13, 2001. Modified Russell King, Nov 30, 2001. diff --git a/Documentation/arm/memory.rst b/Documentation/arm/memory.rst new file mode 100644 index 000000000000..0521b4ce5c96 --- /dev/null +++ b/Documentation/arm/memory.rst @@ -0,0 +1,93 @@ +================================= +Kernel Memory Layout on ARM Linux +================================= + + Russell King + + November 17, 2005 (2.6.15) + +This document describes the virtual memory layout which the Linux +kernel uses for ARM processors. It indicates which regions are +free for platforms to use, and which are used by generic code. + +The ARM CPU is capable of addressing a maximum of 4GB virtual memory +space, and this must be shared between user space processes, the +kernel, and hardware devices. + +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. + +ffff4000 ffffffff cache aliasing on ARMv6 and later CPUs. + +ffff1000 ffff7fff Reserved. + Platforms must not use this address range. + +ffff0000 ffff0fff CPU vector page. + The CPU vectors are mapped here if the + CPU supports vector relocation (control + register V bit.) + +fffe0000 fffeffff XScale cache flush area. This is used + in proc-xscale.S to flush the whole data + cache. (XScale does not have TCM.) + +fffe8000 fffeffff DTCM mapping area for platforms with + DTCM mounted inside the CPU. + +fffe0000 fffe7fff ITCM mapping area for platforms with + ITCM mounted inside the CPU. + +ffc00000 ffefffff Fixmap mapping region. Addresses provided + by fix_to_virt() will be located here. + +fee00000 feffffff Mapping of PCI I/O space. This is a static + mapping within the vmalloc space. + +VMALLOC_START VMALLOC_END-1 vmalloc() / ioremap() space. + Memory returned by vmalloc/ioremap will + be dynamically placed in this region. + Machine specific static mappings are also + located here through iotable_init(). + VMALLOC_START is based upon the value + of the high_memory variable, and VMALLOC_END + is equal to 0xff800000. + +PAGE_OFFSET high_memory-1 Kernel direct-mapped RAM region. + This maps the platforms RAM, and typically + maps all platform RAM in a 1:1 relationship. + +PKMAP_BASE PAGE_OFFSET-1 Permanent kernel mappings + One way of mapping HIGHMEM pages into kernel + space. + +MODULES_VADDR MODULES_END-1 Kernel module space + Kernel modules inserted via insmod are + placed here using dynamic mappings. + +00001000 TASK_SIZE-1 User space mappings + Per-thread mappings are placed here via + the mmap() system call. + +00000000 00000fff CPU vector page / null pointer trap + CPUs which do not support vector remapping + 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 +at run time. + +Since future CPUs may impact the kernel mapping layout, user programs +must not access any memory which is not mapped inside their 0x0001000 +to TASK_SIZE address range. If they wish to access these areas, they +must set up their own mappings using open() and mmap(). diff --git a/Documentation/arm/memory.txt b/Documentation/arm/memory.txt deleted file mode 100644 index 546a39048eb0..000000000000 --- a/Documentation/arm/memory.txt +++ /dev/null @@ -1,88 +0,0 @@ - Kernel Memory Layout on ARM Linux - - Russell King - November 17, 2005 (2.6.15) - -This document describes the virtual memory layout which the Linux -kernel uses for ARM processors. It indicates which regions are -free for platforms to use, and which are used by generic code. - -The ARM CPU is capable of addressing a maximum of 4GB virtual memory -space, and this must be shared between user space processes, the -kernel, and hardware devices. - -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. - -ffff4000 ffffffff cache aliasing on ARMv6 and later CPUs. - -ffff1000 ffff7fff Reserved. - Platforms must not use this address range. - -ffff0000 ffff0fff CPU vector page. - The CPU vectors are mapped here if the - CPU supports vector relocation (control - register V bit.) - -fffe0000 fffeffff XScale cache flush area. This is used - in proc-xscale.S to flush the whole data - cache. (XScale does not have TCM.) - -fffe8000 fffeffff DTCM mapping area for platforms with - DTCM mounted inside the CPU. - -fffe0000 fffe7fff ITCM mapping area for platforms with - ITCM mounted inside the CPU. - -ffc00000 ffefffff Fixmap mapping region. Addresses provided - by fix_to_virt() will be located here. - -fee00000 feffffff Mapping of PCI I/O space. This is a static - mapping within the vmalloc space. - -VMALLOC_START VMALLOC_END-1 vmalloc() / ioremap() space. - Memory returned by vmalloc/ioremap will - be dynamically placed in this region. - Machine specific static mappings are also - located here through iotable_init(). - VMALLOC_START is based upon the value - of the high_memory variable, and VMALLOC_END - is equal to 0xff800000. - -PAGE_OFFSET high_memory-1 Kernel direct-mapped RAM region. - This maps the platforms RAM, and typically - maps all platform RAM in a 1:1 relationship. - -PKMAP_BASE PAGE_OFFSET-1 Permanent kernel mappings - One way of mapping HIGHMEM pages into kernel - space. - -MODULES_VADDR MODULES_END-1 Kernel module space - Kernel modules inserted via insmod are - placed here using dynamic mappings. - -00001000 TASK_SIZE-1 User space mappings - Per-thread mappings are placed here via - the mmap() system call. - -00000000 00000fff CPU vector page / null pointer trap - CPUs which do not support vector remapping - 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 -at run time. - -Since future CPUs may impact the kernel mapping layout, user programs -must not access any memory which is not mapped inside their 0x0001000 -to TASK_SIZE address range. If they wish to access these areas, they -must set up their own mappings using open() and mmap(). diff --git a/Documentation/arm/microchip.rst b/Documentation/arm/microchip.rst new file mode 100644 index 000000000000..c9a44c98e868 --- /dev/null +++ b/Documentation/arm/microchip.rst @@ -0,0 +1,204 @@ +============================= +ARM Microchip SoCs (aka AT91) +============================= + + +Introduction +------------ +This document gives useful information about the ARM Microchip SoCs that are +currently supported in Linux Mainline (you know, the one on kernel.org). + +It is important to note that the Microchip (previously Atmel) ARM-based MPU +product line is historically named "AT91" or "at91" throughout the Linux kernel +development process even if this product prefix has completely disappeared from +the official Microchip product name. Anyway, files, directories, git trees, +git branches/tags and email subject always contain this "at91" sub-string. + + +AT91 SoCs +--------- +Documentation and detailed datasheet for each product are available on +the Microchip website: http://www.microchip.com. + + Flavors: + * ARM 920 based SoC + - at91rm9200 + + * Datasheet + + http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-1768-32-bit-ARM920T-Embedded-Microprocessor-AT91RM9200_Datasheet.pdf + + * ARM 926 based SoCs + - at91sam9260 + + * Datasheet + + http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-6221-32-bit-ARM926EJ-S-Embedded-Microprocessor-SAM9260_Datasheet.pdf + + - at91sam9xe + + * Datasheet + + http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-6254-32-bit-ARM926EJ-S-Embedded-Microprocessor-SAM9XE_Datasheet.pdf + + - at91sam9261 + + * Datasheet + + http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-6062-ARM926EJ-S-Microprocessor-SAM9261_Datasheet.pdf + + - at91sam9263 + + * Datasheet + + http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-6249-32-bit-ARM926EJ-S-Embedded-Microprocessor-SAM9263_Datasheet.pdf + + - at91sam9rl + + * Datasheet + + http://ww1.microchip.com/downloads/en/DeviceDoc/doc6289.pdf + + - at91sam9g20 + + * Datasheet + + http://ww1.microchip.com/downloads/en/DeviceDoc/DS60001516A.pdf + + - at91sam9g45 family + - at91sam9g45 + - at91sam9g46 + - at91sam9m10 + - at91sam9m11 (device superset) + + * Datasheet + + http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-6437-32-bit-ARM926-Embedded-Microprocessor-SAM9M11_Datasheet.pdf + + - at91sam9x5 family (aka "The 5 series") + - at91sam9g15 + - at91sam9g25 + - at91sam9g35 + - at91sam9x25 + - at91sam9x35 + + * 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 + + http://ww1.microchip.com/downloads/en/DeviceDoc/DS60001517A.pdf + + * ARM Cortex-A5 based SoCs + - sama5d3 family + + - sama5d31 + - sama5d33 + - sama5d34 + - sama5d35 + - sama5d36 (device superset) + + * 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 + + http://ww1.microchip.com/downloads/en/DeviceDoc/60001525A.pdf + + - sama5d2 family + + - sama5d21 + - sama5d22 + - sama5d23 + - sama5d24 + - sama5d26 + - sama5d27 (device superset) + - sama5d28 (device superset + environmental monitors) + + * Datasheet + + http://ww1.microchip.com/downloads/en/DeviceDoc/DS60001476B.pdf + + * ARM Cortex-M7 MCUs + - sams70 family + + - sams70j19 + - sams70j20 + - sams70j21 + - sams70n19 + - sams70n20 + - sams70n21 + - sams70q19 + - sams70q20 + - sams70q21 + + - samv70 family + + - samv70j19 + - samv70j20 + - samv70n19 + - samv70n20 + - samv70q19 + - samv70q20 + + - samv71 family + + - samv71j19 + - samv71j20 + - samv71j21 + - samv71n19 + - samv71n20 + - samv71n21 + - samv71q19 + - samv71q20 + - samv71q21 + + * Datasheet + + http://ww1.microchip.com/downloads/en/DeviceDoc/60001527A.pdf + + +Linux kernel information +------------------------ +Linux kernel mach directory: arch/arm/mach-at91 +MAINTAINERS entry is: "ARM/Microchip (AT91) SoC support" + + +Device Tree for AT91 SoCs and boards +------------------------------------ +All AT91 SoCs are converted to Device Tree. Since Linux 3.19, these products +must use this method to boot the Linux kernel. + +Work In Progress statement: +Device Tree files and Device Tree bindings that apply to AT91 SoCs and boards are +considered as "Unstable". To be completely clear, any at91 binding can change at +any time. So, be sure to use a Device Tree Binary and a Kernel Image generated from +the same source tree. +Please refer to the Documentation/devicetree/bindings/ABI.txt file for a +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 + shared across SoCs or boards (sama5d3.dtsi or at91sam9x5cm.dtsi for instance). + When collecting nodes for a particular peripheral or topic, the identifier have to + be placed at the end of the file name, separated with a "_" (at91sam9x5_can.dtsi + or sama5d3_gmac.dtsi for example). +- board Device Tree Source files (.dts) are prefixed by the string "at91-" so + that they can be identified easily. Note that some files are historical exceptions + to this rule (sama5d3[13456]ek.dts, usb_a9g20.dts or animeo_ip.dts for example). 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/NOTES b/Documentation/arm/nwfpe/NOTES deleted file mode 100644 index 40577b5a49d3..000000000000 --- a/Documentation/arm/nwfpe/NOTES +++ /dev/null @@ -1,29 +0,0 @@ -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. - -I also found one oddity in the emulator. I don't think it is serious but -will point it out. The ARM calling conventions require floating point -registers f4-f7 to be preserved over a function call. The compiler quite -often uses an stfe instruction to save f4 on the stack upon entry to a -function, and an ldfe instruction to restore it before returning. - -I was looking at some code, that calculated a double result, stored it in f4 -then made a function call. Upon return from the function call the number in -f4 had been converted to an extended value in the emulator. - -This is a side effect of the stfe instruction. The double in f4 had to be -converted to extended, then stored. If an lfm/sfm combination had been used, -then no conversion would occur. This has performance considerations. The -result from the function call and f4 were used in a multiplication. If the -emulator sees a multiply of a double and extended, it promotes the double to -extended, then does the multiply in extended precision. - -This code will cause this problem: - -double x, y, z; -z = log(x)/log(y); - -The result of log(x) (a double) will be calculated, returned in f0, then -moved to f4 to preserve it over the log(y) call. The division will be done -in extended precision, due to the stfe instruction used to save f4 in log(y). diff --git a/Documentation/arm/nwfpe/README b/Documentation/arm/nwfpe/README deleted file mode 100644 index 771871de0c8b..000000000000 --- a/Documentation/arm/nwfpe/README +++ /dev/null @@ -1,70 +0,0 @@ -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 -written in C, with a small number of routines in inline assembler -where required. It was written quickly, with a goal of implementing a -working version of all the floating point instructions the compiler -emits as the first target. I have attempted to be as optimal as -possible, but there remains much room for improvement. - -I have attempted to make the emulator as portable as possible. One of -the problems is with leading underscores on kernel symbols. Elf -kernels have no leading underscores, a.out compiled kernels do. I -have attempted to use the C_SYMBOL_NAME macro wherever this may be -important. - -Another choice I made was in the file structure. I have attempted to -contain all operating system specific code in one module (fpmodule.*). -All the other files contain emulator specific code. This should allow -others to port the emulator to NetBSD for instance relatively easily. - -The floating point operations are based on SoftFloat Release 2, by -John Hauser. SoftFloat is a software implementation of floating-point -that conforms to the IEC/IEEE Standard for Binary Floating-point -Arithmetic. As many as four formats are supported: single precision, -double precision, extended double precision, and quadruple precision. -All operations required by the standard are implemented, except for -conversions to and from decimal. We use only the single precision, -double precision and extended double precision formats. The port of -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 -remains to be done, and other ideas for the emulator. - -Bug reports, comments, suggestions should be directed to me at -. General reports of "this program doesn't -work correctly when your emulator is installed" are useful for -determining that bugs still exist; but are virtually useless when -attempting to isolate the problem. Please report them, but don't -expect quick action. Bugs still exist. The problem remains in isolating -which instruction contains the bug. Small programs illustrating a specific -problem are a godsend. - -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 -legal notice for SoftFloat is included below. - -------------------------------------------------------------------------------- -SoftFloat Legal Notice - -SoftFloat was written by John R. Hauser. This work was made possible in -part by the International Computer Science Institute, located at Suite 600, -1947 Center Street, Berkeley, California 94704. Funding was partially -provided by the National Science Foundation under grant MIP-9311980. The -original version of this code was written as part of a project to build -a fixed-point vector processor in collaboration with the University of -California at Berkeley, overseen by Profs. Nelson Morgan and John Wawrzynek. - -THIS SOFTWARE IS DISTRIBUTED AS IS, FOR FREE. Although reasonable effort -has been made to avoid it, THIS SOFTWARE MAY CONTAIN FAULTS THAT WILL AT -TIMES RESULT IN INCORRECT BEHAVIOR. USE OF THIS SOFTWARE IS RESTRICTED TO -PERSONS AND ORGANIZATIONS WHO CAN AND WILL TAKE FULL RESPONSIBILITY FOR ANY -AND ALL LOSSES, COSTS, OR OTHER PROBLEMS ARISING FROM ITS USE. -------------------------------------------------------------------------------- diff --git a/Documentation/arm/nwfpe/README.FPE b/Documentation/arm/nwfpe/README.FPE deleted file mode 100644 index 26f5d7bb9a41..000000000000 --- a/Documentation/arm/nwfpe/README.FPE +++ /dev/null @@ -1,156 +0,0 @@ -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 - -Note: items enclosed in {} are optional. - -Floating Point Coprocessor Data Transfer Instructions (CPDT) ------------------------------------------------------------- - -LDF/STF - load and store floating - -{cond} Fd, Rn -{cond} Fd, [Rn, #]{!} -{cond} Fd, [Rn], # - -These instructions are fully implemented. - -LFM/SFM - load and store multiple floating - -Form 1 syntax: -{cond} Fd, , [Rn] -{cond} Fd, , [Rn, #]{!} -{cond} Fd, , [Rn], # - -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 -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. - -Floating Point Coprocessor Register Transfer Instructions (CPRT) ----------------------------------------------------------------- - -Conversions, read/write status/control register instructions - -FLT{cond}{P,M,Z} Fn, Rd Convert integer to floating point -FIX{cond}{P,M,Z} Rd, Fn Convert floating point to integer -WFS{cond} Rd Write floating point status register -RFS{cond} Rd Read floating point status register -WFC{cond} Rd Write floating point control register -RFC{cond} Rd Read floating point control register - -FLT/FIX are fully implemented. - -RFS/WFS are fully implemented. - -RFC/WFC are fully implemented. RFC/WFC are supervisor only instructions, and -presently check the CPU mode, and do an invalid instruction trap if not called -from supervisor mode. - -Compare instructions - -CMF{cond} Fn, Fm Compare floating -CMFE{cond} Fn, Fm Compare floating with exception -CNF{cond} Fn, Fm Compare negated floating -CNFE{cond} Fn, Fm Compare negated floating with exception - -These are fully implemented. - -Floating Point Coprocessor Data Instructions (CPDT) ---------------------------------------------------- - -Dyadic operations: - -ADF{cond}{P,M,Z} Fd, Fn, - add -SUF{cond}{P,M,Z} Fd, Fn, - subtract -RSF{cond}{P,M,Z} Fd, Fn, - reverse subtract -MUF{cond}{P,M,Z} Fd, Fn, - multiply -DVF{cond}{P,M,Z} Fd, Fn, - divide -RDV{cond}{P,M,Z} Fd, Fn, - reverse divide - -These are fully implemented. - -FML{cond}{P,M,Z} Fd, Fn, - fast multiply -FDV{cond}{P,M,Z} Fd, Fn, - fast divide -FRD{cond}{P,M,Z} Fd, Fn, - fast reverse divide - -These are fully implemented as well. They use the same algorithm as the -non-fast versions. Hence, in this implementation their performance is -equivalent to the MUF/DVF/RDV instructions. This is acceptable according -to the ARM manual. The manual notes these are defined only for single -operands, on the actual FPA11 hardware they do not work for double or -extended precision operands. The emulator currently does not check -the requested permissions conditions, and performs the requested operation. - -RMF{cond}{P,M,Z} Fd, Fn, - IEEE remainder - -This is fully implemented. - -Monadic operations: - -MVF{cond}{P,M,Z} Fd, - move -MNF{cond}{P,M,Z} Fd, - move negated - -These are fully implemented. - -ABS{cond}{P,M,Z} Fd, - absolute value -SQT{cond}{P,M,Z} Fd, - square root -RND{cond}{P,M,Z} Fd, - round - -These are fully implemented. - -URD{cond}{P,M,Z} Fd, - unnormalized round -NRM{cond}{P,M,Z} Fd, - normalize - -These are implemented. URD is implemented using the same code as the RND -instruction. Since URD cannot return a unnormalized number, NRM becomes -a NOP. - -Library calls: - -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 -be implemented in future versions. - -Signalling: - -Signals are implemented. However current ELF kernels produced by Rebel.com -have a bug in them that prevents the module from generating a SIGFPE. This -is caused by a failure to alias fp_current to the kernel variable -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 -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 -distribution) can be loaded to replace the functionality of the emulator -built into the kernel. diff --git a/Documentation/arm/nwfpe/TODO b/Documentation/arm/nwfpe/TODO deleted file mode 100644 index 8027061b60eb..000000000000 --- a/Documentation/arm/nwfpe/TODO +++ /dev/null @@ -1,67 +0,0 @@ -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 - -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 -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 -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 -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 -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. -Many architectures allow the rounding mode to be specified by modifying bits -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 -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. - -This would require a method of getting/setting the flag, and the bits -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 - for the Acorn FPE, but not limited to it: - - The floating point control register (FPCR) may only be present in some - implementations: it is there to control the hardware in an implementation- - specific manner, for example to disable the floating point system. The user - mode of the ARM is not permitted to use this register (since the right is - reserved to alter it between implementations) and the WFC and RFC - instructions will trap if tried in user mode. - - 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]. 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/netwinder-fpe.rst b/Documentation/arm/nwfpe/netwinder-fpe.rst new file mode 100644 index 000000000000..cbb320960fc4 --- /dev/null +++ b/Documentation/arm/nwfpe/netwinder-fpe.rst @@ -0,0 +1,162 @@ +============= +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 + +Note: items enclosed in {} are optional. + +Floating Point Coprocessor Data Transfer Instructions (CPDT) +------------------------------------------------------------ + +LDF/STF - load and store floating + +{cond} Fd, Rn +{cond} Fd, [Rn, #]{!} +{cond} Fd, [Rn], # + +These instructions are fully implemented. + +LFM/SFM - load and store multiple floating + +Form 1 syntax: +{cond} Fd, , [Rn] +{cond} Fd, , [Rn, #]{!} +{cond} Fd, , [Rn], # + +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 +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. + +Floating Point Coprocessor Register Transfer Instructions (CPRT) +---------------------------------------------------------------- + +Conversions, read/write status/control register instructions + +FLT{cond}{P,M,Z} Fn, Rd Convert integer to floating point +FIX{cond}{P,M,Z} Rd, Fn Convert floating point to integer +WFS{cond} Rd Write floating point status register +RFS{cond} Rd Read floating point status register +WFC{cond} Rd Write floating point control register +RFC{cond} Rd Read floating point control register + +FLT/FIX are fully implemented. + +RFS/WFS are fully implemented. + +RFC/WFC are fully implemented. RFC/WFC are supervisor only instructions, and +presently check the CPU mode, and do an invalid instruction trap if not called +from supervisor mode. + +Compare instructions + +CMF{cond} Fn, Fm Compare floating +CMFE{cond} Fn, Fm Compare floating with exception +CNF{cond} Fn, Fm Compare negated floating +CNFE{cond} Fn, Fm Compare negated floating with exception + +These are fully implemented. + +Floating Point Coprocessor Data Instructions (CPDT) +--------------------------------------------------- + +Dyadic operations: + +ADF{cond}{P,M,Z} Fd, Fn, - add +SUF{cond}{P,M,Z} Fd, Fn, - subtract +RSF{cond}{P,M,Z} Fd, Fn, - reverse subtract +MUF{cond}{P,M,Z} Fd, Fn, - multiply +DVF{cond}{P,M,Z} Fd, Fn, - divide +RDV{cond}{P,M,Z} Fd, Fn, - reverse divide + +These are fully implemented. + +FML{cond}{P,M,Z} Fd, Fn, - fast multiply +FDV{cond}{P,M,Z} Fd, Fn, - fast divide +FRD{cond}{P,M,Z} Fd, Fn, - fast reverse divide + +These are fully implemented as well. They use the same algorithm as the +non-fast versions. Hence, in this implementation their performance is +equivalent to the MUF/DVF/RDV instructions. This is acceptable according +to the ARM manual. The manual notes these are defined only for single +operands, on the actual FPA11 hardware they do not work for double or +extended precision operands. The emulator currently does not check +the requested permissions conditions, and performs the requested operation. + +RMF{cond}{P,M,Z} Fd, Fn, - IEEE remainder + +This is fully implemented. + +Monadic operations: + +MVF{cond}{P,M,Z} Fd, - move +MNF{cond}{P,M,Z} Fd, - move negated + +These are fully implemented. + +ABS{cond}{P,M,Z} Fd, - absolute value +SQT{cond}{P,M,Z} Fd, - square root +RND{cond}{P,M,Z} Fd, - round + +These are fully implemented. + +URD{cond}{P,M,Z} Fd, - unnormalized round +NRM{cond}{P,M,Z} Fd, - normalize + +These are implemented. URD is implemented using the same code as the RND +instruction. Since URD cannot return a unnormalized number, NRM becomes +a NOP. + +Library calls: + +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 +be implemented in future versions. + +Signalling: + +Signals are implemented. However current ELF kernels produced by Rebel.com +have a bug in them that prevents the module from generating a SIGFPE. This +is caused by a failure to alias fp_current to the kernel variable +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 +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 +distribution) can be loaded to replace the functionality of the emulator +built into the kernel. diff --git a/Documentation/arm/nwfpe/notes.rst b/Documentation/arm/nwfpe/notes.rst new file mode 100644 index 000000000000..102e55af8439 --- /dev/null +++ b/Documentation/arm/nwfpe/notes.rst @@ -0,0 +1,32 @@ +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. + +I also found one oddity in the emulator. I don't think it is serious but +will point it out. The ARM calling conventions require floating point +registers f4-f7 to be preserved over a function call. The compiler quite +often uses an stfe instruction to save f4 on the stack upon entry to a +function, and an ldfe instruction to restore it before returning. + +I was looking at some code, that calculated a double result, stored it in f4 +then made a function call. Upon return from the function call the number in +f4 had been converted to an extended value in the emulator. + +This is a side effect of the stfe instruction. The double in f4 had to be +converted to extended, then stored. If an lfm/sfm combination had been used, +then no conversion would occur. This has performance considerations. The +result from the function call and f4 were used in a multiplication. If the +emulator sees a multiply of a double and extended, it promotes the double to +extended, then does the multiply in extended precision. + +This code will cause this problem: + +double x, y, z; +z = log(x)/log(y); + +The result of log(x) (a double) will be calculated, returned in f0, then +moved to f4 to preserve it over the log(y) call. The division will be done +in extended precision, due to the stfe instruction used to save f4 in log(y). diff --git a/Documentation/arm/nwfpe/nwfpe.rst b/Documentation/arm/nwfpe/nwfpe.rst new file mode 100644 index 000000000000..35cd90dacbff --- /dev/null +++ b/Documentation/arm/nwfpe/nwfpe.rst @@ -0,0 +1,74 @@ +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 +written in C, with a small number of routines in inline assembler +where required. It was written quickly, with a goal of implementing a +working version of all the floating point instructions the compiler +emits as the first target. I have attempted to be as optimal as +possible, but there remains much room for improvement. + +I have attempted to make the emulator as portable as possible. One of +the problems is with leading underscores on kernel symbols. Elf +kernels have no leading underscores, a.out compiled kernels do. I +have attempted to use the C_SYMBOL_NAME macro wherever this may be +important. + +Another choice I made was in the file structure. I have attempted to +contain all operating system specific code in one module (fpmodule.*). +All the other files contain emulator specific code. This should allow +others to port the emulator to NetBSD for instance relatively easily. + +The floating point operations are based on SoftFloat Release 2, by +John Hauser. SoftFloat is a software implementation of floating-point +that conforms to the IEC/IEEE Standard for Binary Floating-point +Arithmetic. As many as four formats are supported: single precision, +double precision, extended double precision, and quadruple precision. +All operations required by the standard are implemented, except for +conversions to and from decimal. We use only the single precision, +double precision and extended double precision formats. The port of +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 +remains to be done, and other ideas for the emulator. + +Bug reports, comments, suggestions should be directed to me at +. General reports of "this program doesn't +work correctly when your emulator is installed" are useful for +determining that bugs still exist; but are virtually useless when +attempting to isolate the problem. Please report them, but don't +expect quick action. Bugs still exist. The problem remains in isolating +which instruction contains the bug. Small programs illustrating a specific +problem are a godsend. + +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 +legal notice for SoftFloat is included below. + +------------------------------------------------------------------------------- + +SoftFloat Legal Notice + +SoftFloat was written by John R. Hauser. This work was made possible in +part by the International Computer Science Institute, located at Suite 600, +1947 Center Street, Berkeley, California 94704. Funding was partially +provided by the National Science Foundation under grant MIP-9311980. The +original version of this code was written as part of a project to build +a fixed-point vector processor in collaboration with the University of +California at Berkeley, overseen by Profs. Nelson Morgan and John Wawrzynek. + +THIS SOFTWARE IS DISTRIBUTED AS IS, FOR FREE. Although reasonable effort +has been made to avoid it, THIS SOFTWARE MAY CONTAIN FAULTS THAT WILL AT +TIMES RESULT IN INCORRECT BEHAVIOR. USE OF THIS SOFTWARE IS RESTRICTED TO +PERSONS AND ORGANIZATIONS WHO CAN AND WILL TAKE FULL RESPONSIBILITY FOR ANY +AND ALL LOSSES, COSTS, OR OTHER PROBLEMS ARISING FROM ITS USE. +------------------------------------------------------------------------------- diff --git a/Documentation/arm/nwfpe/todo.rst b/Documentation/arm/nwfpe/todo.rst new file mode 100644 index 000000000000..393f11b14540 --- /dev/null +++ b/Documentation/arm/nwfpe/todo.rst @@ -0,0 +1,72 @@ +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 + +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 +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 +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 +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 +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. +Many architectures allow the rounding mode to be specified by modifying bits +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 +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. + +This would require a method of getting/setting the flag, and the bits +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 + for the Acorn FPE, but not limited to it: + + The floating point control register (FPCR) may only be present in some + implementations: it is there to control the hardware in an implementation- + specific manner, for example to disable the floating point system. The user + mode of the ARM is not permitted to use this register (since the right is + reserved to alter it between implementations) and the WFC and RFC + instructions will trap if tried in user mode. + + 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. diff --git a/Documentation/arm/omap/dss.rst b/Documentation/arm/omap/dss.rst new file mode 100644 index 000000000000..a40c4d9c717a --- /dev/null +++ b/Documentation/arm/omap/dss.rst @@ -0,0 +1,372 @@ +========================= +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, +TV-out and multiple display support, but there are lots of small improvements +also. + +The DSS2 driver (omapdss module) is in arch/arm/plat-omap/dss/, and the FB, +panel and controller drivers are in drivers/video/omap2/. DSS1 and DSS2 live +currently side by side, you can choose which one to use. + +Features +-------- + +Working and tested features include: + +- MIPI DPI (parallel) output +- MIPI DSI output in command mode +- MIPI DBI (RFBI) output +- SDI output +- TV output +- All pieces can be compiled as a module or inside kernel +- Use DISPC to update any of the outputs +- Use CPU to update RFBI or DSI output +- OMAP DISPC planes +- RGB16, RGB24 packed, RGB24 unpacked +- YUV2, UYVY +- Scaling +- Adjusting DSS FCK to find a good pixel clock +- Use DSI DPLL to create DSS FCK + +Tested boards include: +- OMAP3 SDP board +- Beagle board +- N810 + +omapdss driver +-------------- + +The DSS driver does not itself have any support for Linux framebuffer, V4L or +such like the current ones, but it has an internal kernel API that upper level +drivers can use. + +The DSS driver models OMAP's overlays, overlay managers and displays in a +flexible way to enable non-common multi-display configuration. In addition to +modelling the hardware overlays, omapdss supports virtual overlays and overlay +managers. These can be used when updating a display with CPU or system DMA. + +omapdss driver support for audio +-------------------------------- +There exist several display technologies and standards that support audio as +well. Hence, it is relevant to update the DSS device driver to provide an audio +interface that may be used by an audio driver or any other driver interested in +the functionality. + +The audio_enable function is intended to prepare the relevant +IP for playback (e.g., enabling an audio FIFO, taking in/out of reset +some IP, enabling companion chips, etc). It is intended to be called before +audio_start. The audio_disable function performs the reverse operation and is +intended to be called after audio_stop. + +While a given DSS device driver may support audio, it is possible that for +certain configurations audio is not supported (e.g., an HDMI display using a +VESA video timing). The audio_supported function is intended to query whether +the current configuration of the display supports audio. + +The audio_config function is intended to configure all the relevant audio +parameters of the display. In order to make the function independent of any +specific DSS device driver, a struct omap_dss_audio is defined. Its purpose +is to contain all the required parameters for audio configuration. At the +moment, such structure contains pointers to IEC-60958 channel status word +and CEA-861 audio infoframe structures. This should be enough to support +HDMI and DisplayPort, as both are based on CEA-861 and IEC-60958. + +The audio_enable/disable, audio_config and audio_supported functions could be +implemented as functions that may sleep. Hence, they should not be called +while holding a spinlock or a readlock. + +The audio_start/audio_stop function is intended to effectively start/stop audio +playback after the configuration has taken place. These functions are designed +to be used in an atomic context. Hence, audio_start should return quickly and be +called only after all the needed resources for audio playback (audio FIFOs, +DMA channels, companion chips, etc) have been enabled to begin data transfers. +audio_stop is designed to only stop the audio transfers. The resources used +for playback are released using audio_disable. + +The enum omap_dss_audio_state may be used to help the implementations of +the interface to keep track of the audio state. The initial state is _DISABLED; +then, the state transitions to _CONFIGURED, and then, when it is ready to +play audio, to _ENABLED. The state _PLAYING is used when the audio is being +rendered. + + +Panel and controller drivers +---------------------------- + +The drivers implement panel or controller specific functionality and are not +usually visible to users except through omapfb driver. They register +themselves to the DSS driver. + +omapfb driver +------------- + +The omapfb driver implements arbitrary number of standard linux framebuffers. +These framebuffers can be routed flexibly to any overlays, thus allowing very +dynamic display architecture. + +The driver exports some omapfb specific ioctls, which are compatible with the +ioctls in the old driver. + +The rest of the non standard features are exported via sysfs. Whether the final +implementation will use sysfs, or ioctls, is still open. + +V4L2 drivers +------------ + +V4L2 is being implemented in TI. + +From omapdss point of view the V4L2 drivers should be similar to framebuffer +driver. + +Architecture +-------------------- + +Some clarification what the different components do: + + - Framebuffer is a memory area inside OMAP's SRAM/SDRAM that contains the + pixel data for the image. Framebuffer has width and height and color + depth. + - Overlay defines where the pixels are read from and where they go on the + screen. The overlay may be smaller than framebuffer, thus displaying only + part of the framebuffer. The position of the overlay may be changed if + the overlay is smaller than the display. + - Overlay manager combines the overlays in to one image and feeds them to + display. + - Display is the actual physical display device. + +A framebuffer can be connected to multiple overlays to show the same pixel data +on all of the overlays. Note that in this case the overlay input sizes must be +the same, but, in case of video overlays, the output size can be different. Any +framebuffer can be connected to any overlay. + +An overlay can be connected to one overlay manager. Also DISPC overlays can be +connected only to DISPC overlay managers, and virtual overlays can be only +connected to virtual overlays. + +An overlay manager can be connected to one display. There are certain +restrictions which kinds of displays an overlay manager can be connected: + + - DISPC TV overlay manager can be only connected to TV display. + - Virtual overlay managers can only be connected to DBI or DSI displays. + - DISPC LCD overlay manager can be connected to all displays, except TV + display. + +Sysfs +----- +The sysfs interface is mainly used for testing. I don't think sysfs +interface is the best for this in the final version, but I don't quite know +what would be the best interfaces for these things. + +The sysfs interface is divided to two parts: DSS and FB. + +/sys/class/graphics/fb? directory: +mirror 0=off, 1=on +rotate Rotation 0-3 for 0, 90, 180, 270 degrees +rotate_type 0 = DMA rotation, 1 = VRFB rotation +overlays List of overlay numbers to which framebuffer pixels go +phys_addr Physical address of the framebuffer +virt_addr Virtual address of the framebuffer +size Size of the framebuffer + +/sys/devices/platform/omapdss/overlay? directory: +enabled 0=off, 1=on +input_size width,height (ie. the framebuffer size) +manager Destination overlay manager name +name +output_size width,height +position x,y +screen_width width +global_alpha global alpha 0-255 0=transparent 255=opaque + +/sys/devices/platform/omapdss/manager? directory: +display Destination display +name +alpha_blending_enabled 0=off, 1=on +trans_key_enabled 0=off, 1=on +trans_key_type gfx-destination, video-source +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 +enabled 0=off, 1=on +name +rotate Rotation 0-3 for 0, 90, 180, 270 degrees +timings Display timings (pixclock,xres/hfp/hbp/hsw,yres/vfp/vbp/vsw) + When writing, two special timings are accepted for tv-out: + "pal" and "ntsc" +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. + +Examples +-------- + +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 + + 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 + + fb0=/sys/class/graphics/fb0 + fb1=/sys/class/graphics/fb1 + fb2=/sys/class/graphics/fb2 + +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:: + + 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 + + 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 +---------- + +OMAP FB allocates the framebuffer memory using the standard dma allocator. You +can enable Contiguous Memory Allocator (CONFIG_CMA) to improve the dma +allocator, and if CMA is enabled, you use "cma=" kernel parameter to increase +the global memory area for CMA. + +Using DSI DPLL to generate pixel clock it is possible produce the pixel clock +of 86.5MHz (max possible), and with that you get 1280x1024@57 output from DVI. + +Rotation and mirroring currently only supports RGB565 and RGB8888 modes. VRFB +does not support mirroring. + +VRFB rotation requires much more memory than non-rotated framebuffer, so you +probably need to increase your vram setting before using VRFB rotation. Also, +many applications may not work with VRFB if they do not pay attention to all +framebuffer parameters. + +Kernel boot arguments +--------------------- + +omapfb.mode=:[,...] + - Default video mode for specified displays. For example, + "dvi:800x400MR-24@60". See drivers/video/modedb.c. + There are also two special modes: "pal" and "ntsc" that + can be used to tv out. + +omapfb.vram=:[@][,...] + - VRAM allocated for a framebuffer. Normally omapfb allocates vram + depending on the display size. With this you can manually allocate + more or define the physical address of each framebuffer. For example, + "1:4M" to allocate 4M for fb1. + +omapfb.debug= + - Enable debug printing. You have to have OMAPFB debug support enabled + in kernel config. + +omapfb.test= + - Draw test pattern to framebuffer whenever framebuffer settings change. + You need to have OMAPFB debug support enabled in kernel config. + +omapfb.vrfb= + - Use VRFB rotation for all framebuffers. + +omapfb.rotate= + - Default rotation applied to all framebuffers. + 0 - 0 degree rotation + 1 - 90 degree rotation + 2 - 180 degree rotation + 3 - 270 degree rotation + +omapfb.mirror= + - Default mirror for all framebuffers. Only works with DMA rotation. + +omapdss.def_disp= + - Name of default display, to which all overlays will be connected. + Common examples are "lcd" or "tv". + +omapdss.debug= + - Enable debug printing. You have to have DSS debug support enabled in + kernel config. + +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 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/omap.rst b/Documentation/arm/omap/omap.rst new file mode 100644 index 000000000000..f440c0f4613f --- /dev/null +++ b/Documentation/arm/omap/omap.rst @@ -0,0 +1,18 @@ +============ +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. + +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.rst b/Documentation/arm/omap/omap_pm.rst new file mode 100644 index 000000000000..a335e4c8ce2c --- /dev/null +++ b/Documentation/arm/omap/omap_pm.rst @@ -0,0 +1,165 @@ +===================== +The OMAP PM interface +===================== + +This document describes the temporary OMAP PM interface. Driver +authors use these functions to communicate minimum latency or +throughput constraints to the kernel power management code. +Over time, the intention is to merge features from the OMAP PM +interface into the Linux PM QoS code. + +Drivers need to express PM parameters which: + +- support the range of power management parameters present in the TI SRF; + +- separate the drivers from the underlying PM parameter + implementation, whether it is the TI SRF or Linux PM QoS or Linux + latency framework or something else; + +- specify PM parameters in terms of fundamental units, such as + latency and throughput, rather than units which are specific to OMAP + or to particular OMAP variants; + +- allow drivers which are shared with other architectures (e.g., + DaVinci) to add these constraints in a way which won't affect non-OMAP + systems, + +- can be implemented immediately with minimal disruption of other + architectures. + + +This document proposes the OMAP PM interface, including the following +five power management functions for driver code: + +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:: + + (*pdata->set_max_dev_wakeup_lat)(struct device *dev, unsigned long t) + +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:: + + (*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:: + + (*pdata->get_dev_context_loss_count)(struct device *dev) + + +Further documentation for all OMAP PM interface functions can be +found in arch/arm/plat-omap/include/mach/omap-pm.h. + + +The OMAP PM layer is intended to be temporary +--------------------------------------------- + +The intention is that eventually the Linux PM QoS layer should support +the range of power management features present in OMAP3. As this +happens, existing drivers using the OMAP PM interface can be modified +to use the Linux PM QoS code; and the OMAP PM interface can disappear. + + +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` +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:: + + if (pdata->set_max_dev_wakeup_lat) + (*pdata->set_max_dev_wakeup_lat)(dev, t); + +The most common usage of these functions will probably be to specify +the maximum time from when an interrupt occurs, to when the device +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:: + + /* Limit MPU wakeup latency */ + if (pdata->set_max_mpu_wakeup_lat) + (*pdata->set_max_mpu_wakeup_lat)(dev, tc); + + /* Limit device powerdomain wakeup latency */ + if (pdata->set_max_dev_wakeup_lat) + (*pdata->set_max_dev_wakeup_lat)(dev, td); + + /* total wakeup latency in this example: (tc + td) */ + +The PM parameters can be overwritten by calling the function again +with the new value. The settings can be removed by calling the +function with a t argument of -1 (except in the case of +set_max_bus_tput(), which should be called with an r argument of 0). + +The fifth function above, omap_pm_get_dev_context_loss_count(), +is intended as an optimization to allow drivers to determine whether the +device has lost its internal context. If context has been lost, the +driver must restore its internal context before proceeding. + + +Other specialized interface functions +------------------------------------- + +The five functions listed above are intended to be usable by any +device driver. DSPBridge and CPUFreq have a few special requirements. +DSPBridge expresses target DSP performance levels in terms of OPP IDs. +CPUFreq expresses target MPU performance levels in terms of MPU +frequency. The OMAP PM interface contains functions for these +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)` + +7. `(*pdata->dsp_set_min_opp)(u8 opp_id)` + +8. `(*pdata->dsp_get_opp)(void)` + +9. `(*pdata->cpu_get_freq_table)(void)` + +10. `(*pdata->cpu_set_freq)(unsigned long f)` + +11. `(*pdata->cpu_get_freq)(void)` + +Customizing OPP for platform +============================ +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:: + + #include "pm.h" + .... + static void __init omap_xyz_init_irq(void) + { + .... + /* Initialize the default table */ + omapx_opp_init(); + /* Do customization to the defaults */ + .... + } + +NOTE: + omapx_opp_init will be omap3_opp_init or as required + based on the omap family. diff --git a/Documentation/arm/porting.rst b/Documentation/arm/porting.rst new file mode 100644 index 000000000000..bd21958bdb2d --- /dev/null +++ b/Documentation/arm/porting.rst @@ -0,0 +1,137 @@ +======= +Porting +======= + +Taken from list archive at http://lists.arm.linux.org.uk/pipermail/linux-arm-kernel/2001-July/004064.html + +Initial definitions +------------------- + +The following symbol definitions rely on you knowing the translation that +__virt_to_phys() does for your machine. This macro converts the passed +virtual address to a physical address. Normally, it is simply: + + phys = virt - PAGE_OFFSET + PHYS_OFFSET + + +Decompressor Symbols +-------------------- + +ZTEXTADDR + Start address of decompressor. There's no point in talking about + virtual or physical addresses here, since the MMU will be off at + the time when you call the decompressor code. You normally call + the kernel at this address to start it booting. This doesn't have + to be located in RAM, it can be in flash or other read-only or + read-write addressable medium. + +ZBSSADDR + Start address of zero-initialised work area for the decompressor. + This must be pointing at RAM. The decompressor will zero initialise + this for you. Again, the MMU will be off. + +ZRELADDR + This is the address where the decompressed kernel will be written, + and eventually executed. The following constraint must be valid: + + __virt_to_phys(TEXTADDR) == ZRELADDR + + The initial part of the kernel is carefully coded to be position + independent. + +INITRD_PHYS + Physical address to place the initial RAM disk. Only relevant if + you are using the bootpImage stuff (which only works on the old + struct param_struct). + +INITRD_VIRT + Virtual address of the initial RAM disk. The following constraint + must be valid: + + __virt_to_phys(INITRD_VIRT) == INITRD_PHYS + +PARAMS_PHYS + Physical address of the struct param_struct or tag list, giving the + kernel various parameters about its execution environment. + + +Kernel Symbols +-------------- + +PHYS_OFFSET + Physical start address of the first bank of RAM. + +PAGE_OFFSET + Virtual start address of the first bank of RAM. During the kernel + boot phase, virtual address PAGE_OFFSET will be mapped to physical + address PHYS_OFFSET, along with any other mappings you supply. + This should be the same value as TASK_SIZE. + +TASK_SIZE + The maximum size of a user process in bytes. Since user space + always starts at zero, this is the maximum address that a user + process can access+1. The user space stack grows down from this + address. + + Any virtual address below TASK_SIZE is deemed to be user process + area, and therefore managed dynamically on a process by process + basis by the kernel. I'll call this the user segment. + + Anything above TASK_SIZE is common to all processes. I'll call + this the kernel segment. + + (In other words, you can't put IO mappings below TASK_SIZE, and + hence PAGE_OFFSET). + +TEXTADDR + Virtual start address of kernel, normally PAGE_OFFSET + 0x8000. + This is where the kernel image ends up. With the latest kernels, + it must be located at 32768 bytes into a 128MB region. Previous + kernels placed a restriction of 256MB here. + +DATAADDR + Virtual address for the kernel data segment. Must not be defined + when using the decompressor. + +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). + Normally, the vmalloc() area starts VMALLOC_OFFSET bytes above the + last virtual RAM address (found using variable high_memory). + +VMALLOC_OFFSET + Offset normally incorporated into VMALLOC_START to provide a hole + between virtual RAM and the vmalloc area. We do this to allow + out of bounds memory accesses (eg, something writing off the end + of the mapped memory map) to be caught. Normally set to 8MB. + +Architecture Specific Macros +---------------------------- + +BOOT_MEM(pram,pio,vio) + `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 + use with the debugging macros in arch/arm/kernel/debug-armv.S. + + `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 + MAPIO function). + +BOOT_PARAMS + Same as, and see PARAMS_PHYS. + +FIXUP(func) + Machine specific fixups, run before memory subsystems have been + initialised. + +MAPIO(func) + Machine specific function to map IO areas (including the debug + region above). + +INITIRQ(func) + Machine specific function to initialise interrupts. diff --git a/Documentation/arm/pxa/mfp.rst b/Documentation/arm/pxa/mfp.rst new file mode 100644 index 000000000000..ac34e5d7ee44 --- /dev/null +++ b/Documentation/arm/pxa/mfp.rst @@ -0,0 +1,288 @@ +============================================== +MFP Configuration for PXA2xx/PXA3xx Processors +============================================== + + Eric Miao + +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 +============= + +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:: + + +--------+ + | |--(GPIO19)--+ + | GPIO | | + | |--(GPIO...) | + +--------+ | + | +---------+ + +--------+ +------>| | + | PWM2 |--(PWM_OUT)-------->| MFP | + +--------+ +------>| |-------> to external PAD + | +---->| | + +--------+ | | +-->| | + | SSP2 |---(TXD)----+ | | +---------+ + +--------+ | | + | | + +--------+ | | + | Keypad |--(MKOUT4)----+ | + +--------+ | + | + +--------+ | + | UART2 |---(TXD)--------+ + +--------+ + +NOTE: the external pad is named as MFP_PIN_GPIO19, it doesn't necessarily +mean it's dedicated for GPIO19, only as a hint that internally this pin +can be routed from GPIO19 of the GPIO controller. + +To better understand the change from PXA25x/PXA27x GPIO alternate function +to this new MFP mechanism, here are several key points: + + 1. GPIO controller on PXA3xx is now a dedicated controller, same as other + internal controllers like PWM, SSP and UART, with 128 internal signals + which can be routed to external through one or more MFPs (e.g. GPIO<0> + can be routed through either MFP_PIN_GPIO0 as well as MFP_PIN_GPIO0_2, + see arch/arm/mach-pxa/mfp-pxa300.h) + + 2. Alternate function configuration is removed from this GPIO controller, + the remaining functions are pure GPIO-specific, i.e. + + - GPIO signal level control + - GPIO direction control + - GPIO level change detection + + 3. Low power state for each pin is now controlled by MFP, this means the + PGSRx registers on PXA2xx are now useless on PXA3xx + + 4. Wakeup detection is now controlled by MFP, PWER does not control the + wakeup from GPIO(s) any more, depending on the sleeping state, ADxER + (as defined in pxa3xx-regs.h) controls the wakeup from MFP + +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 +============= + +For board code writers, here are some guidelines: + +1. include ONE of the following header files in your .c: + + - #include "mfp-pxa25x.h" + - #include "mfp-pxa27x.h" + - #include "mfp-pxa300.h" + - #include "mfp-pxa320.h" + - #include "mfp-pxa930.h" + + NOTE: only one file in your .c, depending on the processors used, + because pin configuration definitions may conflict in these file (i.e. + same name, different meaning and settings on different processors). E.g. + for zylonite platform, which support both PXA300/PXA310 and PXA320, two + separate files are introduced: zylonite_pxa300.c and zylonite_pxa320.c + (in addition to handle MFP configuration differences, they also handle + the other differences between the two combinations). + + NOTE: PXA300 and PXA310 are almost identical in pin configurations (with + 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.:: + + static unsigned long mainstone_pin_config[] __initdata = { + /* Chip Select */ + GPIO15_nCS_1, + + /* LCD - 16bpp Active TFT */ + GPIOxx_TFT_LCD_16BPP, + GPIO16_PWM0_OUT, /* Backlight */ + + /* MMC */ + GPIO32_MMC_CLK, + GPIO112_MMC_CMD, + GPIO92_MMC_DAT_0, + GPIO109_MMC_DAT_1, + GPIO110_MMC_DAT_2, + GPIO111_MMC_DAT_3, + + ... + + /* 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, + adding '__initdata' will help save some additional bytes here. + + b) when there is only one possible pin configurations for a component, + some simplified definitions can be used, e.g. GPIOxx_TFT_LCD_16BPP on + PXA25x and PXA27x processors + + c) if by board design, a pin can be configured to wake up the system + from low power state, it can be 'OR'ed with any of: + + WAKEUP_ON_EDGE_BOTH + WAKEUP_ON_EDGE_RISE + WAKEUP_ON_EDGE_FALL + WAKEUP_ON_LEVEL_HIGH - specifically for enabling of keypad GPIOs, + + to indicate that this pin has the capability of wake-up the system, + and on which edge(s). This, however, doesn't necessarily mean the + pin _will_ wakeup the system, it will only when set_irq_wake() is + invoked with the corresponding GPIO IRQ (GPIO_IRQ(xx) or gpio_to_irq()) + and eventually calls gpio_set_wake() for the actual register setting. + + 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 + the peripheral IRQ to enable the wakeup. + + +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):: + + 31 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 + +-------------------------+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ + | RESERVED |PS|PU|PD| DRIVE |SS|SD|SO|EC|EF|ER|--| AF_SEL | + +-------------------------+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ + + Bit 3: RESERVED + Bit 4: EDGE_RISE_EN - enable detection of rising edge on this pin + Bit 5: EDGE_FALL_EN - enable detection of falling edge on this pin + Bit 6: EDGE_CLEAR - disable edge detection on this pin + Bit 7: SLEEP_OE_N - enable outputs during low power modes + Bit 8: SLEEP_DATA - output data on the pin during low power modes + Bit 9: SLEEP_SEL - selection control for low power modes signals + Bit 13: PULLDOWN_EN - enable the internal pull-down resistor on this pin + Bit 14: PULLUP_EN - enable the internal pull-up resistor on this pin + Bit 15: PULL_SEL - pull state controlled by selected alternate function + (0) or by PULL{UP,DOWN}_EN bits (1) + + Bit 0 - 2: AF_SEL - alternate function selection, 8 possibilities, from 0-7 + Bit 10-12: DRIVE - drive strength and slew rate + 0b000 - fast 1mA + 0b001 - fast 2mA + 0b002 - fast 3mA + 0b003 - fast 4mA + 0b004 - slow 6mA + 0b005 - fast 6mA + 0b006 - slow 10mA + 0b007 - fast 10mA + +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. + +The basic idea of this design is to introduce definitions for all possible pin +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 +-------------- + + - 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 + + - arch/arm/mach-pxa/mfp-pxa3xx.h + + for PXA3xx specific MFPR register bit definitions and PXA3xx common pin + configurations + + - arch/arm/mach-pxa/mfp-pxa2xx.h + + for PXA2xx specific definitions and PXA25x/PXA27x common pin configurations + + - arch/arm/mach-pxa/mfp-pxa25x.h + arch/arm/mach-pxa/mfp-pxa27x.h + arch/arm/mach-pxa/mfp-pxa300.h + arch/arm/mach-pxa/mfp-pxa320.h + arch/arm/mach-pxa/mfp-pxa930.h + + for processor specific definitions + + - arch/arm/mach-pxa/mfp-pxa3xx.c + - arch/arm/mach-pxa/mfp-pxa2xx.c + + for implementation of the pin configuration to take effect for the actual + processor. + +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 + */ + + 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 + modes. + + NOTE: this is the default setting of this pin being configured as SSP3_RXD + which can be modified a bit in board code, though it is not recommended to + do so, simply because this default setting is usually carefully encoded, + and is supposed to work in most cases. + +Register Settings +----------------- + + Register settings on PXA3xx for a pin configuration is actually very + straight-forward, most bits can be converted directly into MFPR value + in a easier way. Two sets of MFPR values are calculated: the run-time + ones and the low power mode ones, to allow different settings. + + The conversion from a generic pin configuration to the actual register + settings on PXA2xx is a bit complicated: many registers are involved, + including GAFRx, GPDRx, PGSRx, PWER, PKWR, PFER and PRER. Please see + mfp-pxa2xx.c for how the conversion is made. diff --git a/Documentation/arm/pxa/mfp.txt b/Documentation/arm/pxa/mfp.txt deleted file mode 100644 index 0b7cab978c02..000000000000 --- a/Documentation/arm/pxa/mfp.txt +++ /dev/null @@ -1,286 +0,0 @@ - MFP Configuration for PXA2xx/PXA3xx Processors - - Eric Miao - -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 -=============== - -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: - - +--------+ - | |--(GPIO19)--+ - | GPIO | | - | |--(GPIO...) | - +--------+ | - | +---------+ - +--------+ +------>| | - | PWM2 |--(PWM_OUT)-------->| MFP | - +--------+ +------>| |-------> to external PAD - | +---->| | - +--------+ | | +-->| | - | SSP2 |---(TXD)----+ | | +---------+ - +--------+ | | - | | - +--------+ | | - | Keypad |--(MKOUT4)----+ | - +--------+ | - | - +--------+ | - | UART2 |---(TXD)--------+ - +--------+ - -NOTE: the external pad is named as MFP_PIN_GPIO19, it doesn't necessarily -mean it's dedicated for GPIO19, only as a hint that internally this pin -can be routed from GPIO19 of the GPIO controller. - -To better understand the change from PXA25x/PXA27x GPIO alternate function -to this new MFP mechanism, here are several key points: - - 1. GPIO controller on PXA3xx is now a dedicated controller, same as other - internal controllers like PWM, SSP and UART, with 128 internal signals - which can be routed to external through one or more MFPs (e.g. GPIO<0> - can be routed through either MFP_PIN_GPIO0 as well as MFP_PIN_GPIO0_2, - see arch/arm/mach-pxa/mfp-pxa300.h) - - 2. Alternate function configuration is removed from this GPIO controller, - the remaining functions are pure GPIO-specific, i.e. - - - GPIO signal level control - - GPIO direction control - - GPIO level change detection - - 3. Low power state for each pin is now controlled by MFP, this means the - PGSRx registers on PXA2xx are now useless on PXA3xx - - 4. Wakeup detection is now controlled by MFP, PWER does not control the - wakeup from GPIO(s) any more, depending on the sleeping state, ADxER - (as defined in pxa3xx-regs.h) controls the wakeup from MFP - -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 -=============== - -For board code writers, here are some guidelines: - -1. include ONE of the following header files in your .c: - - - #include "mfp-pxa25x.h" - - #include "mfp-pxa27x.h" - - #include "mfp-pxa300.h" - - #include "mfp-pxa320.h" - - #include "mfp-pxa930.h" - - NOTE: only one file in your .c, depending on the processors used, - because pin configuration definitions may conflict in these file (i.e. - same name, different meaning and settings on different processors). E.g. - for zylonite platform, which support both PXA300/PXA310 and PXA320, two - separate files are introduced: zylonite_pxa300.c and zylonite_pxa320.c - (in addition to handle MFP configuration differences, they also handle - the other differences between the two combinations). - - NOTE: PXA300 and PXA310 are almost identical in pin configurations (with - 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.: - - static unsigned long mainstone_pin_config[] __initdata = { - /* Chip Select */ - GPIO15_nCS_1, - - /* LCD - 16bpp Active TFT */ - GPIOxx_TFT_LCD_16BPP, - GPIO16_PWM0_OUT, /* Backlight */ - - /* MMC */ - GPIO32_MMC_CLK, - GPIO112_MMC_CMD, - GPIO92_MMC_DAT_0, - GPIO109_MMC_DAT_1, - GPIO110_MMC_DAT_2, - GPIO111_MMC_DAT_3, - - ... - - /* 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, - adding '__initdata' will help save some additional bytes here. - - b) when there is only one possible pin configurations for a component, - some simplified definitions can be used, e.g. GPIOxx_TFT_LCD_16BPP on - PXA25x and PXA27x processors - - c) if by board design, a pin can be configured to wake up the system - from low power state, it can be 'OR'ed with any of: - - WAKEUP_ON_EDGE_BOTH - WAKEUP_ON_EDGE_RISE - WAKEUP_ON_EDGE_FALL - WAKEUP_ON_LEVEL_HIGH - specifically for enabling of keypad GPIOs, - - to indicate that this pin has the capability of wake-up the system, - and on which edge(s). This, however, doesn't necessarily mean the - pin _will_ wakeup the system, it will only when set_irq_wake() is - invoked with the corresponding GPIO IRQ (GPIO_IRQ(xx) or gpio_to_irq()) - and eventually calls gpio_set_wake() for the actual register setting. - - 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 - the peripheral IRQ to enable the wakeup. - - - 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): - - 31 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 - +-------------------------+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ - | RESERVED |PS|PU|PD| DRIVE |SS|SD|SO|EC|EF|ER|--| AF_SEL | - +-------------------------+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ - - Bit 3: RESERVED - Bit 4: EDGE_RISE_EN - enable detection of rising edge on this pin - Bit 5: EDGE_FALL_EN - enable detection of falling edge on this pin - Bit 6: EDGE_CLEAR - disable edge detection on this pin - Bit 7: SLEEP_OE_N - enable outputs during low power modes - Bit 8: SLEEP_DATA - output data on the pin during low power modes - Bit 9: SLEEP_SEL - selection control for low power modes signals - Bit 13: PULLDOWN_EN - enable the internal pull-down resistor on this pin - Bit 14: PULLUP_EN - enable the internal pull-up resistor on this pin - Bit 15: PULL_SEL - pull state controlled by selected alternate function - (0) or by PULL{UP,DOWN}_EN bits (1) - - Bit 0 - 2: AF_SEL - alternate function selection, 8 possibilities, from 0-7 - Bit 10-12: DRIVE - drive strength and slew rate - 0b000 - fast 1mA - 0b001 - fast 2mA - 0b002 - fast 3mA - 0b003 - fast 4mA - 0b004 - slow 6mA - 0b005 - fast 6mA - 0b006 - slow 10mA - 0b007 - fast 10mA - - 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. - -The basic idea of this design is to introduce definitions for all possible pin -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 - -------------- - - - 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 - - - arch/arm/mach-pxa/mfp-pxa3xx.h - - for PXA3xx specific MFPR register bit definitions and PXA3xx common pin - configurations - - - arch/arm/mach-pxa/mfp-pxa2xx.h - - for PXA2xx specific definitions and PXA25x/PXA27x common pin configurations - - - arch/arm/mach-pxa/mfp-pxa25x.h - arch/arm/mach-pxa/mfp-pxa27x.h - arch/arm/mach-pxa/mfp-pxa300.h - arch/arm/mach-pxa/mfp-pxa320.h - arch/arm/mach-pxa/mfp-pxa930.h - - for processor specific definitions - - - arch/arm/mach-pxa/mfp-pxa3xx.c - - arch/arm/mach-pxa/mfp-pxa2xx.c - - for implementation of the pin configuration to take effect for the actual - processor. - - 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 - */ - - 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 - modes. - - NOTE: this is the default setting of this pin being configured as SSP3_RXD - which can be modified a bit in board code, though it is not recommended to - do so, simply because this default setting is usually carefully encoded, - and is supposed to work in most cases. - - Register Settings - ----------------- - - Register settings on PXA3xx for a pin configuration is actually very - straight-forward, most bits can be converted directly into MFPR value - in a easier way. Two sets of MFPR values are calculated: the run-time - ones and the low power mode ones, to allow different settings. - - The conversion from a generic pin configuration to the actual register - settings on PXA2xx is a bit complicated: many registers are involved, - including GAFRx, GPDRx, PGSRx, PWER, PKWR, PFER and PRER. Please see - mfp-pxa2xx.c for how the conversion is made. diff --git a/Documentation/arm/sa1100/adsbitsy.rst b/Documentation/arm/sa1100/adsbitsy.rst new file mode 100644 index 000000000000..c179cb26b682 --- /dev/null +++ b/Documentation/arm/sa1100/adsbitsy.rst @@ -0,0 +1,51 @@ +=============================== +ADS Bitsy Single Board Computer +=============================== + +(It is different from Bitsy(iPAQ) of Compaq) + +For more details, contact Applied Data Systems or see +http://www.applieddata.net/products.html + +The Linux support for this product has been provided by +Woojung Huh + +Use 'make adsbitsy_config' before any 'make config'. +This will set up defaults for ADS Bitsy support. + +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 +===================== + +- SA1100 LCD frame buffer (8/16bpp...sort of) +- SA1111 USB Master +- SA1100 serial port +- pcmcia, compact flash +- touchscreen(ucb1200) +- console on LCD screen +- serial ports (ttyS[0-2]) + - ttyS0 is default for serial console + +To do +===== + +- everything else! :-) + +Notes +===== + +- The flash on board is divided into 3 partitions. + You should be careful to use flash on board. + Its partition is different from GraphicsClient Plus and GraphicsMaster + +- 16bpp mode requires a different cable than what ships with the board. + Contact ADS or look through the manual to wire your own. Currently, + if you compile with 16bit mode support and switch into a lower bpp + mode, the timing is off so the image is corrupted. This will be + fixed soon. + +Any contribution can be sent to nico@fluxnic.net and will be greatly welcome! diff --git a/Documentation/arm/sa1100/assabet.rst b/Documentation/arm/sa1100/assabet.rst new file mode 100644 index 000000000000..3e704831c311 --- /dev/null +++ b/Documentation/arm/sa1100/assabet.rst @@ -0,0 +1,301 @@ +============================================ +The Intel Assabet (SA-1110 evaluation) board +============================================ + +Please see: +http://developer.intel.com + +Also some notes from John G Dorsey : +http://www.cs.cmu.edu/~wearable/software/assabet.html + + +Building the kernel +------------------- + +To build the kernel with current defaults:: + + make assabet_config + make oldconfig + make zImage + +The resulting kernel image should be available in linux/arch/arm/boot/zImage. + + +Installing a bootloader +----------------------- + +A couple of bootloaders able to boot Linux on Assabet are available: + +BLOB (http://www.lartmaker.nl/lartware/blob/) + + BLOB is a bootloader used within the LART project. Some contributed + patches were merged into BLOB to add support for Assabet. + +Compaq's Bootldr + John Dorsey's patch for Assabet support +(http://www.handhelds.org/Compaq/bootldr.html) +(http://www.wearablegroup.org/software/bootldr/) + + Bootldr is the bootloader developed by Compaq for the iPAQ Pocket PC. + John Dorsey has produced add-on patches to add support for Assabet and + the JFFS filesystem. + +RedBoot (http://sources.redhat.com/redboot/) + + RedBoot is a bootloader developed by Red Hat based on the eCos RTOS + hardware abstraction layer. It supports Assabet amongst many other + hardware platforms. + +RedBoot is currently the recommended choice since it's the only one to have +networking support, and is the most actively maintained. + +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/ + +Look for redboot-assabet*.tgz. Some installation infos are provided in +redboot-assabet*.txt. + + +Initial RedBoot configuration +----------------------------- + +The commands used here are explained in The RedBoot User's Guide available +on-line at http://sources.redhat.com/ecos/docs.html. +Please refer to it for explanations. + +If you have a CF network card (my Assabet kit contained a CF+ LP-E from +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:: + + 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:: + + fconfig -i + + +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:: + + load zImage -r -b 0x100000 + +If you rather want to use Y-Modem upload over the serial port:: + + load -m ymodem -r -b 0x100000 + +To write it to flash:: + + fis create "Linux kernel" -b 0x100000 -l 0xc0000 + + +Booting the kernel +------------------ + +The kernel still requires a filesystem to boot. A ramdisk image can be loaded +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:: + + fis load "Linux kernel" + +or loaded as described previously. To boot the kernel:: + + exec -b 0x100000 -l 0xc0000 + +The ramdisk image could be stored into flash as well, but there are better +solutions for on-flash filesystems as mentioned below. + + +Using JFFS2 +----------- + +Using JFFS2 (the Second Journalling Flash File System) is probably the most +convenient way to store a writable filesystem into flash. JFFS2 is used in +conjunction with the MTD layer which is responsible for low-level flash +management. More information on the Linux MTD can be found on-line at: +http://www.linux-mtd.infradead.org/. A JFFS howto with some infos about +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:: + + load sample_img.jffs2 -r -b 0x100000 + +The result should look like:: + + RedBoot> load sample_img.jffs2 -r -b 0x100000 + Raw file loaded 0x00100000-0x00377424 + +Now we must know the size of the unallocated flash:: + + fis free + +Result:: + + 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:: + + 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:: + + fis unlock -f 0x500E0000 -l 0x2e0000 + fis erase -f 0x500E0000 -l 0x2e0000 + fis write -b 0x100000 -l 0x277424 -f 0x500E0000 + fis create "JFFS2" -n -f 0x500E0000 -l 0x2e0000 + +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:: + + 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:: + + 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:: + + fis load "Linux kernel" + exec -b 0x100000 -l 0xc0000 -c "root=/dev/mtdblock2" + +Of course other filesystems than JFFS might be used, like cramfs for example. +You might want to boot with a root filesystem over NFS, etc. It is also +possible, and sometimes more convenient, to flash a filesystem directly from +within Linux while booted from a ramdisk or NFS. The Linux MTD repository has +many tools to deal with flash memory as well, to erase it for example. JFFS2 +can then be mounted directly on a freshly erased partition and files can be +copied over directly. Etc... + + +RedBoot scripting +----------------- + +All the commands above aren't so useful if they have to be typed in every +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:: + + 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. + + + +Nicolas Pitre +nico@fluxnic.net + +June 12, 2001 + + +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. + + Video: + - 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. + + 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. + + Other: + - 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. + - 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.rst b/Documentation/arm/sa1100/brutus.rst new file mode 100644 index 000000000000..e1a23bee6d44 --- /dev/null +++ b/Documentation/arm/sa1100/brutus.rst @@ -0,0 +1,69 @@ +====== +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:: + + make brutus_config + make config + [accept all the defaults] + make zImage + +The resulting kernel will end up in linux/arch/arm/boot/zImage. This file +must be loaded at 0xc0008000 in Brutus's memory and execution started at +0xc0008000 as well with the value of registers r0 = 0 and r1 = 16 upon +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 +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:: + + 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:: + + angelboot -f angelboot.opt zImage + +The first Brutus serial port (assumed to be linked to /dev/ttyS0 on your +host PC) is used by angel to load the kernel and ramdisk image. The serial +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 +=================== + + - 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 +ftp.netwinder.org/users/n/nico. + +A full PCMCIA support is still missing, although it's possible to hack +some drivers in order to drive already inserted cards at boot time with +little modifications. + +Any contribution is welcome. + +Please send patches to nico@fluxnic.net + +Have Fun ! diff --git a/Documentation/arm/sa1100/cerf.rst b/Documentation/arm/sa1100/cerf.rst new file mode 100644 index 000000000000..7fa71b609bf9 --- /dev/null +++ b/Documentation/arm/sa1100/cerf.rst @@ -0,0 +1,35 @@ +============== +CerfBoard/Cube +============== + +*** The StrongARM version of the CerfBoard/Cube has been discontinued *** + +The Intrinsyc CerfBoard is a StrongARM 1110-based computer on a board +that measures approximately 2" square. It includes an Ethernet +controller, an RS232-compatible serial port, a USB function port, and +one CompactFlash+ slot on the back. Pictures can be found at the +Intrinsyc website, http://www.intrinsyc.com. + +This document describes the support in the Linux kernel for the +Intrinsyc CerfBoard. + +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 + Network Devices) + - Serial ports with a serial console (hardcoded to 38400 8N1) + +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:: + + make ARCH=arm CROSS_COMPILE=arm-linux- cerfcube_defconfig + make ARCH=arm CROSS_COMPILE=arm-linux- zImage + make ARCH=arm CROSS_COMPILE=arm-linux- modules + cp arch/arm/boot/zImage + +support@intrinsyc.com 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.rst b/Documentation/arm/sa1100/graphicsclient.rst new file mode 100644 index 000000000000..a73d61c3ce91 --- /dev/null +++ b/Documentation/arm/sa1100/graphicsclient.rst @@ -0,0 +1,102 @@ +============================================= +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 +Nicolas Pitre . Continued development work by +Woojung Huh + +It's currently possible to mount a root filesystem via NFS providing a +complete Linux environment. Otherwise a ramdisk image may be used. The +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:: + + r0 = 0 + r1 = 29 (this is the GraphicsClient architecture number) + +Linux can be used with the ADS BootLoader that ships with the +newer rev boards. See their documentation on how to load Linux. +Angel is not available for the GraphicsClient Plus AFAIK. + +There is a board known as just the GraphicsClient that ADS used to +produce but has end of lifed. This code will not work on the older +board with the ADS bootloader, but should still work with Angel, +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:: + + 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:: + + angelboot -f angelboot.opt zImage + +Here it is assumed that the board is connected to ttyS1 on your PC +and that minicom is preconfigured with /dev/ttyS1, 38400 baud, 8N1, no flow +control by default. + +If any other bootloader is used, ensure it accomplish the same, especially +for r0/r1 register values before jumping into the kernel. + + +Supported peripherals +===================== + +- SA1100 LCD frame buffer (8/16bpp...sort of) +- on-board SMC 92C96 ethernet NIC +- SA1100 serial port +- flash memory access (MTD/JFFS) +- pcmcia +- touchscreen(ucb1200) +- ps/2 keyboard +- console on LCD screen +- serial ports (ttyS[0-2]) + - ttyS0 is default for serial console +- Smart I/O (ADC, keypad, digital inputs, etc) + 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 +===== + +- UCB1200 audio with new ucb_generic layer +- everything else! :-) + +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 + read-only to keep you from blasting over the bootloader. :) mtd1 is + for the ramdisk.gz image. mtd2 is user flash space and can be + utilized for either JFFS or if you're feeling crazy, running ext2 + on top of it. If you're not using the ADS bootloader, you're + welcome to blast over the mtd1 partition also. + +- 16bpp mode requires a different cable than what ships with the board. + Contact ADS or look through the manual to wire your own. Currently, + if you compile with 16bit mode support and switch into a lower bpp + mode, the timing is off so the image is corrupted. This will be + fixed soon. + +Any contribution can be sent to nico@fluxnic.net and will be greatly welcome! diff --git a/Documentation/arm/sa1100/graphicsmaster.rst b/Documentation/arm/sa1100/graphicsmaster.rst new file mode 100644 index 000000000000..e39892514f0c --- /dev/null +++ b/Documentation/arm/sa1100/graphicsmaster.rst @@ -0,0 +1,60 @@ +======================================== +ADS GraphicsMaster 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 +Nicolas Pitre . Continued development work by +Woojung Huh + +Use 'make graphicsmaster_config' before any 'make config'. +This will set up defaults for GraphicsMaster support. + +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 +===================== + +- SA1100 LCD frame buffer (8/16bpp...sort of) +- SA1111 USB Master +- on-board SMC 92C96 ethernet NIC +- SA1100 serial port +- flash memory access (MTD/JFFS) +- pcmcia, compact flash +- touchscreen(ucb1200) +- ps/2 keyboard +- console on LCD screen +- serial ports (ttyS[0-2]) + - ttyS0 is default for serial console +- Smart I/O (ADC, keypad, digital inputs, etc) + 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 +===== + +- everything else! :-) + +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 + from blasting over the bootloader. :) mtd1 is + for the ramdisk.gz image. mtd2 is user flash space and can be + utilized for either JFFS or if you're feeling crazy, running ext2 + on top of it. If you're not using the ADS bootloader, you're + welcome to blast over the mtd1 partition also. + +- 16bpp mode requires a different cable than what ships with the board. + Contact ADS or look through the manual to wire your own. Currently, + if you compile with 16bit mode support and switch into a lower bpp + mode, the timing is off so the image is corrupted. This will be + fixed soon. + +Any contribution can be sent to nico@fluxnic.net and will be greatly welcome! diff --git a/Documentation/arm/sa1100/huw_webpanel.rst b/Documentation/arm/sa1100/huw_webpanel.rst new file mode 100644 index 000000000000..1dc7ccb165f0 --- /dev/null +++ b/Documentation/arm/sa1100/huw_webpanel.rst @@ -0,0 +1,21 @@ +======================= +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:: + + make huw_webpanel_config + make oldconfig + [accept all defaults] + make zImage + +Mostly of the work is done by: +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.rst b/Documentation/arm/sa1100/itsy.rst new file mode 100644 index 000000000000..f49896ba3ef1 --- /dev/null +++ b/Documentation/arm/sa1100/itsy.rst @@ -0,0 +1,47 @@ +==== +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. + +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 +enabled. + +To build, do a "make menuconfig" (or xmenuconfig) and select Itsy support. +Disable Flash and LCD support. and then do a make zImage. +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 + +Make sure the start-routine address is set to 0x00060000. + +Next, flash the params-itsy program to 0x00060000 ("p 1 0x00060000" in the +flash menu) Flash the kernel in arch/arm/boot/zImage into 0x08340000 +("p 1 0x00340000"). Finally flash an initial ramdisk into 0xC8000000 +("p 2 0x0") We used ramdisk-2-30.gz from the 0.11 version directory on +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 +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 +the itsy. (i.e. grep for CONFIG_SA1100_ITSY and you'll find where it is.) + + +This should get you a properly booting 2.4 kernel on the itsy. diff --git a/Documentation/arm/sa1100/lart.rst b/Documentation/arm/sa1100/lart.rst new file mode 100644 index 000000000000..94c0568d1095 --- /dev/null +++ b/Documentation/arm/sa1100/lart.rst @@ -0,0 +1,15 @@ +==================================== +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 +other StrongARM-gadgets. Almost all SA signals are directly accessible +through a number of connectors. The powersupply accepts voltages +between 3.5V and 16V and is overdimensioned to support a range of +daughterboards. A quad Ethernet / IDE / PS2 / sound daughterboard +is under development, with plenty of others in different stages of +planning. + +The hardware designs for this board have been released under an open license; +see the LART page at http://www.lartmaker.nl/ for more information. diff --git a/Documentation/arm/sa1100/nanoengine.rst b/Documentation/arm/sa1100/nanoengine.rst new file mode 100644 index 000000000000..47f1a14cf98a --- /dev/null +++ b/Documentation/arm/sa1100/nanoengine.rst @@ -0,0 +1,11 @@ +========== +nanoEngine +========== + +"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.rst b/Documentation/arm/sa1100/pangolin.rst new file mode 100644 index 000000000000..f0c5c1618553 --- /dev/null +++ b/Documentation/arm/sa1100/pangolin.rst @@ -0,0 +1,29 @@ +======== +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:: + + make pangolin_config + make oldconfig + make zImage + +Supported peripherals +===================== + +- SA1110 serial port (UART1/UART2/UART3) +- flash memory access +- compact flash driver +- UDA1341 sound driver +- SA1100 LCD controller for 800x600 16bpp TFT-LCD +- MQ-200 driver for 800x600 16bpp TFT-LCD +- Penmount(touch panel) driver +- PCMCIA driver +- SMC91C94 LAN driver +- IDE driver (experimental) diff --git a/Documentation/arm/sa1100/pleb.rst b/Documentation/arm/sa1100/pleb.rst new file mode 100644 index 000000000000..d5b732967aa3 --- /dev/null +++ b/Documentation/arm/sa1100/pleb.rst @@ -0,0 +1,13 @@ +==== +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. + +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.rst b/Documentation/arm/sa1100/tifon.rst new file mode 100644 index 000000000000..c26e910b9ea7 --- /dev/null +++ b/Documentation/arm/sa1100/tifon.rst @@ -0,0 +1,7 @@ +===== +Tifon +===== + +More info has to come... + +Contact: Peter Danielsson diff --git a/Documentation/arm/sa1100/yopy.rst b/Documentation/arm/sa1100/yopy.rst new file mode 100644 index 000000000000..5b35a5f61a44 --- /dev/null +++ b/Documentation/arm/sa1100/yopy.rst @@ -0,0 +1,5 @@ +==== +Yopy +==== + +See http://www.yopydeveloper.org for more. diff --git a/Documentation/arm/samsung-s3c24xx/cpufreq.rst b/Documentation/arm/samsung-s3c24xx/cpufreq.rst new file mode 100644 index 000000000000..2ddc26c03b1f --- /dev/null +++ b/Documentation/arm/samsung-s3c24xx/cpufreq.rst @@ -0,0 +1,76 @@ +======================= +S3C24XX CPUfreq support +======================= + +Introduction +------------ + + The S3C24XX series support a number of power saving systems, such as + the ability to change the core, memory and peripheral operating + frequencies. The core control is exported via the CPUFreq driver + which has a number of different manual or automatic controls over the + rate the core is running at. + + There are two forms of the driver depending on the specific CPU and + how the clocks are arranged. The first implementation used as single + PLL to feed the ARM, memory and peripherals via a series of dividers + and muxes and this is the implementation that is documented here. A + newer version where there is a separate PLL and clock divider for the + ARM core is available as a separate driver. + + +Layout +------ + + The code core manages the CPU specific drivers, any data that they + need to register and the interface to the generic drivers/cpufreq + system. Each CPU registers a driver to control the PLL, clock dividers + and anything else associated with it. Any board that wants to use this + framework needs to supply at least basic details of what is required. + + The core registers with drivers/cpufreq at init time if all the data + necessary has been supplied. + + +CPU support +----------- + + The support for each CPU depends on the facilities provided by the + SoC and the driver as each device has different PLL and clock chains + associated with it. + + +Slow Mode +--------- + + The SLOW mode where the PLL is turned off altogether and the + system is fed by the external crystal input is currently not + supported. + + +sysfs +----- + + The core code exports extra information via sysfs in the directory + devices/system/cpu/cpu0/arch-freq. + + +Board Support +------------- + + Each board that wants to use the cpufreq code must register some basic + information with the core driver to provide information about what the + board requires and any restrictions being placed on it. + + The board needs to supply information about whether it needs the IO bank + timings changing, any maximum frequency limits and information about the + SDRAM refresh rate. + + + + +Document Author +--------------- + +Ben Dooks, Copyright 2009 Simtec Electronics +Licensed under GPLv2 diff --git a/Documentation/arm/samsung-s3c24xx/eb2410itx.rst b/Documentation/arm/samsung-s3c24xx/eb2410itx.rst new file mode 100644 index 000000000000..7863c93652f8 --- /dev/null +++ b/Documentation/arm/samsung-s3c24xx/eb2410itx.rst @@ -0,0 +1,59 @@ +=================================== +Simtec Electronics EB2410ITX (BAST) +=================================== + + http://www.simtec.co.uk/products/EB2410ITX/ + +Introduction +------------ + + The EB2410ITX is a S3C2410 based development board with a variety of + peripherals and expansion connectors. This board is also known by + the shortened name of Bast. + + +Configuration +------------- + + To set the default configuration, use `make bast_defconfig` which + supports the commonly used features of this board. + + +Support +------- + + Official support information can be found on the Simtec Electronics + website, at the product page http://www.simtec.co.uk/products/EB2410ITX/ + + Useful links: + + - Resources Page http://www.simtec.co.uk/products/EB2410ITX/resources.html + + - Board FAQ at http://www.simtec.co.uk/products/EB2410ITX/faq.html + + - Bootloader info http://www.simtec.co.uk/products/SWABLE/resources.html + and FAQ http://www.simtec.co.uk/products/SWABLE/faq.html + + +MTD +--- + + The NAND and NOR support has been merged from the linux-mtd project. + Any problems, see http://www.linux-mtd.infradead.org/ for more + information or up-to-date versions of linux-mtd. + + +IDE +--- + + Both onboard IDE ports are supported, however there is no support for + changing speed of devices, PIO Mode 4 capable drives should be used. + + +Maintainers +----------- + + This board is maintained by Simtec Electronics. + + +Copyright 2004 Ben Dooks, Simtec Electronics diff --git a/Documentation/arm/samsung-s3c24xx/gpio.rst b/Documentation/arm/samsung-s3c24xx/gpio.rst new file mode 100644 index 000000000000..f7c3d7d011a2 --- /dev/null +++ b/Documentation/arm/samsung-s3c24xx/gpio.rst @@ -0,0 +1,172 @@ +==================== +S3C24XX GPIO Control +==================== + +Introduction +------------ + + The s3c2410 kernel provides an interface to configure and + manipulate the state of the GPIO pins, and find out other + information about them. + + There are a number of conditions attached to the configuration + 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.rst for the core implementation. + + +GPIOLIB +------- + + With the event of the GPIOLIB in drivers/gpio, support for some + of the GPIO functions such as reading and writing a pin will + be removed in favour of this common access method. + + Once all the extant drivers have been converted, the functions + 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 + 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() + + +GPIOLIB conversion +------------------ + +If you need to convert your board or driver to use gpiolib from the phased +out s3c2410 API, then here are some notes on the process. + +1) If your board is exclusively using an GPIO, say to control peripheral + power, then it will require to claim the gpio with gpio_request() before + it can use it. + + It is recommended to check the return value, with at least WARN_ON() + during initialisation. + +2) The s3c2410_gpio_cfgpin() can be directly replaced with s3c_gpio_cfgpin() + as they have the same arguments, and can either take the pin specific + values, or the more generic special-function-number arguments. + +3) s3c2410_gpio_pullup() changes have the problem that while the + s3c2410_gpio_pullup(x, 1) can be easily translated to the + s3c_gpio_setpull(x, S3C_GPIO_PULL_NONE), the s3c2410_gpio_pullup(x, 0) + are not so easy. + + The s3c2410_gpio_pullup(x, 0) case enables the pull-up (or in the case + of some of the devices, a pull-down) and as such the new API distinguishes + between the UP and DOWN case. There is currently no 'just turn on' setting + which may be required if this becomes a problem. + +4) s3c2410_gpio_setpin() can be replaced by gpio_set_value(), the old call + does not implicitly configure the relevant gpio to output. The gpio + direction should be changed before using gpio_set_value(). + +5) s3c2410_gpio_getpin() is replaceable by gpio_get_value() if the pin + has been set to input. It is currently unknown what the behaviour is + when using gpio_get_value() on an output pin (s3c2410_gpio_getpin + would return the value the pin is supposed to be outputting). + +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 +numberspace, so there is no problem with converting the gpio numbering +between the calls. + + +Headers +------- + + See arch/arm/mach-s3c24xx/include/mach/regs-gpio.h for the list + of GPIO pins, and the configuration values for them. This + is included by using #include + + +PIN Numbers +----------- + + Each pin has an unique number associated with it in regs-gpio.h, + e.g. S3C2410_GPA(0) or S3C2410_GPF(1). These defines are used to tell + the GPIO functions which pin is to be used. + + With the conversion to gpiolib, there is no longer a direct conversion + from gpio pin number to register base address as in earlier kernels. This + is due to the number space required for newer SoCs where the later + GPIOs are not contiguous. + + +Configuring a pin +----------------- + + The following function allows the configuration of a given pin to + be changed. + + void s3c_gpio_cfgpin(unsigned int pin, unsigned int function); + + e.g.: + + s3c_gpio_cfgpin(S3C2410_GPA(0), S3C_GPIO_SFN(1)); + s3c_gpio_cfgpin(S3C2410_GPE(8), S3C_GPIO_SFN(2)); + + which would turn GPA(0) into the lowest Address line A0, and set + GPE(8) to be connected to the SDIO/MMC controller's SDDAT1 line. + + +Reading the current configuration +--------------------------------- + + The current configuration of a pin can be read by using standard + gpiolib function: + + s3c_gpio_getcfg(unsigned int pin); + + The return value will be from the same set of values which can be + passed to s3c_gpio_cfgpin(). + + +Configuring a pull-up resistor +------------------------------ + + A large proportion of the GPIO pins on the S3C2410 can have weak + pull-up resistors enabled. This can be configured by the following + function: + + void s3c_gpio_setpull(unsigned int pin, unsigned int to); + + Where the to value is S3C_GPIO_PULL_NONE to set the pull-up off, + and S3C_GPIO_PULL_UP to enable the specified pull-up. Any other + values are currently undefined. + + +Getting and setting the state of a PIN +-------------------------------------- + + These calls are now implemented by the relevant gpiolib calls, convert + your board or driver to use gpiolib. + + +Getting the IRQ number associated with a PIN +-------------------------------------------- + + A standard gpiolib function can map the given pin number to an IRQ + number to pass to the IRQ system. + + int gpio_to_irq(unsigned int pin); + + Note, not all pins have an IRQ. + + +Author +------- + +Ben Dooks, 03 October 2004 +Copyright 2004 Ben Dooks, Simtec Electronics diff --git a/Documentation/arm/samsung-s3c24xx/h1940.rst b/Documentation/arm/samsung-s3c24xx/h1940.rst new file mode 100644 index 000000000000..62a562c178e3 --- /dev/null +++ b/Documentation/arm/samsung-s3c24xx/h1940.rst @@ -0,0 +1,41 @@ +============= +HP IPAQ H1940 +============= + +http://www.handhelds.org/projects/h1940.html + +Introduction +------------ + + The HP H1940 is a S3C2410 based handheld device, with + bluetooth connectivity. + + +Support +------- + + A variety of information is available + + handhelds.org project page: + + http://www.handhelds.org/projects/h1940.html + + handhelds.org wiki page: + + http://handhelds.org/moin/moin.cgi/HpIpaqH1940 + + Herbert Pötzl pages: + + http://vserver.13thfloor.at/H1940/ + + +Maintainers +----------- + + This project is being maintained and developed by a variety + of people, including Ben Dooks, Arnaud Patard, and Herbert Pötzl. + + Thanks to the many others who have also provided support. + + +(c) 2005 Ben Dooks 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.rst b/Documentation/arm/samsung-s3c24xx/nand.rst new file mode 100644 index 000000000000..938995694ee7 --- /dev/null +++ b/Documentation/arm/samsung-s3c24xx/nand.rst @@ -0,0 +1,30 @@ +==================== +S3C24XX NAND Support +==================== + +Introduction +------------ + +Small Page NAND +--------------- + +The driver uses a 512 byte (1 page) ECC code for this setup. The +ECC code is not directly compatible with the default kernel ECC +code, so the driver enforces its own OOB layout and ECC parameters + +Large Page NAND +--------------- + +The driver is capable of handling NAND flash with a 2KiB page +size, with support for hardware ECC generation and correction. + +Unlike the 512byte page mode, the driver generates ECC data for +each 256 byte block in an 2KiB page. This means that more than +one error in a page can be rectified. It also means that the +OOB layout remains the default kernel layout for these flashes. + + +Document Author +--------------- + +Ben Dooks, Copyright 2007 Simtec Electronics diff --git a/Documentation/arm/samsung-s3c24xx/overview.rst b/Documentation/arm/samsung-s3c24xx/overview.rst new file mode 100644 index 000000000000..e9a1dc7276b5 --- /dev/null +++ b/Documentation/arm/samsung-s3c24xx/overview.rst @@ -0,0 +1,319 @@ +========================== +S3C24XX ARM Linux Overview +========================== + + + +Introduction +------------ + + The Samsung S3C24XX range of ARM9 System-on-Chip CPUs are supported + by the 's3c2410' architecture of ARM Linux. Currently the S3C2410, + S3C2412, S3C2413, S3C2416, S3C2440, S3C2442, S3C2443 and S3C2450 devices + are supported. + + Support for the S3C2400 and S3C24A0 series was never completed and the + corresponding code has been removed after a while. If someone wishes to + revive this effort, partial support can be retrieved from earlier Linux + versions. + + The S3C2416 and S3C2450 devices are very similar and S3C2450 support is + included under the arch/arm/mach-s3c2416 directory. Note, while core + support for these SoCs is in, work on some of the extra peripherals + and extra interrupts is still ongoing. + + +Configuration +------------- + + A generic S3C2410 configuration is provided, and can be used as the + default by `make s3c2410_defconfig`. This configuration has support + for all the machines, and the commonly used features on them. + + Certain machines may have their own default configurations as well, + please check the machine specific documentation. + + +Layout +------ + + The core support files are located in the platform code contained in + arch/arm/plat-s3c24xx with headers in include/asm-arm/plat-s3c24xx. + This directory should be kept to items shared between the platform + code (arch/arm/plat-s3c24xx) and the arch/arm/mach-s3c24* code. + + Each cpu has a directory with the support files for it, and the + machines that carry the device. For example S3C2410 is contained + in arch/arm/mach-s3c2410 and S3C2440 in arch/arm/mach-s3c2440 + + Register, kernel and platform data definitions are held in the + arch/arm/mach-s3c2410 directory./include/mach + +arch/arm/plat-s3c24xx: + + Files in here are either common to all the s3c24xx family, + or are common to only some of them with names to indicate this + status. The files that are not common to all are generally named + with the initial cpu they support in the series to ensure a short + name without any possibility of confusion with newer devices. + + As an example, initially s3c244x would cover s3c2440 and s3c2442, but + with the s3c2443 which does not share many of the same drivers in + this directory, the name becomes invalid. We stick to s3c2440- + to indicate a driver that is s3c2440 and s3c2442 compatible. + + This does mean that to find the status of any given SoC, a number + of directories may need to be searched. + + +Machines +-------- + + The currently supported machines are as follows: + + Simtec Electronics EB2410ITX (BAST) + + A general purpose development board, see EB2410ITX.txt for further + details + + Simtec Electronics IM2440D20 (Osiris) + + CPU Module from Simtec Electronics, with a S3C2440A CPU, nand flash + and a PCMCIA controller. + + Samsung SMDK2410 + + Samsung's own development board, geared for PDA work. + + Samsung/Aiji SMDK2412 + + The S3C2412 version of the SMDK2440. + + Samsung/Aiji SMDK2413 + + The S3C2412 version of the SMDK2440. + + Samsung/Meritech SMDK2440 + + The S3C2440 compatible version of the SMDK2440, which has the + option of an S3C2440 or S3C2442 CPU module. + + Thorcom VR1000 + + Custom embedded board + + HP IPAQ 1940 + + Handheld (IPAQ), available in several varieties + + HP iPAQ rx3715 + + S3C2440 based IPAQ, with a number of variations depending on + features shipped. + + Acer N30 + + A S3C2410 based PDA from Acer. There is a Wiki page at + http://handhelds.org/moin/moin.cgi/AcerN30Documentation . + + AML M5900 + + American Microsystems' M5900 + + Nex Vision Nexcoder + Nex Vision Otom + + Two machines by Nex Vision + + +Adding New Machines +------------------- + + The architecture has been designed to support as many machines as can + be configured for it in one kernel build, and any future additions + should keep this in mind before altering items outside of their own + machine files. + + Machine definitions should be kept in linux/arch/arm/mach-s3c2410, + and there are a number of examples that can be looked at. + + Read the kernel patch submission policies as well as the + Documentation/arm directory before submitting patches. The + ARM kernel series is managed by Russell King, and has a patch system + located at http://www.arm.linux.org.uk/developer/patches/ + as well as mailing lists that can be found from the same site. + + As a courtesy, please notify of any new + machines or other modifications. + + Any large scale modifications, or new drivers should be discussed + on the ARM kernel mailing list (linux-arm-kernel) before being + attempted. See http://www.arm.linux.org.uk/mailinglists/ for the + mailing list information. + + +I2C +--- + + The hardware I2C core in the CPU is supported in single master + mode, and can be configured via platform data. + + +RTC +--- + + Support for the onboard RTC unit, including alarm function. + + This has recently been upgraded to use the new RTC core, + and the module has been renamed to rtc-s3c to fit in with + the new rtc naming scheme. + + +Watchdog +-------- + + The onchip watchdog is available via the standard watchdog + interface. + + +NAND +---- + + The current kernels now have support for the s3c2410 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.rst + + +SD/MMC +------ + + The SD/MMC hardware pre S3C2443 is supported in the current + kernel, the driver is drivers/mmc/host/s3cmci.c and supports + 1 and 4 bit SD or MMC cards. + + The SDIO behaviour of this driver has not been fully tested. There is no + current support for hardware SDIO interrupts. + + +Serial +------ + + The s3c2410 serial driver provides support for the internal + serial ports. These devices appear as /dev/ttySAC0 through 3. + + To create device nodes for these, use the following commands + + mknod ttySAC0 c 204 64 + mknod ttySAC1 c 204 65 + mknod ttySAC2 c 204 66 + + +GPIO +---- + + The core contains support for manipulating the GPIO, see the + documentation in GPIO.txt in the same directory as this file. + + Newer kernels carry GPIOLIB, and support is being moved towards + this with some of the older support in line to be removed. + + 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.rst for the S3C24XX specific + support and Documentation/arm/samsung/gpio.rst for the core Samsung + implementation. + + +Clock Management +---------------- + + The core provides the interface defined in the header file + include/asm-arm/hardware/clock.h, to allow control over the + various clock units + + +Suspend to RAM +-------------- + + For boards that provide support for suspend to RAM, the + system can be placed into low power suspend. + + See Suspend.txt for more information. + + +SPI +--- + + SPI drivers are available for both the in-built hardware + (although there is no DMA support yet) and a generic + GPIO based solution. + + +LEDs +---- + + There is support for GPIO based LEDs via a platform driver + in the LED subsystem. + + +Platform Data +------------- + + Whenever a device has platform specific data that is specified + on a per-machine basis, care should be taken to ensure the + following: + + 1) that default data is not left in the device to confuse the + driver if a machine does not set it at startup + + 2) the data should (if possible) be marked as __initdata, + to ensure that the data is thrown away if the machine is + not the one currently in use. + + The best way of doing this is to make a function that + 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:: + + 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"); + } + } + + Note, since the code is marked as __init, it should not be + exported outside arch/arm/mach-s3c2410/, or exported to + modules via EXPORT_SYMBOL() and related functions. + + +Port Contributors +----------------- + + Ben Dooks (BJD) + Vincent Sanders + Herbert Potzl + Arnaud Patard (RTP) + Roc Wu + Klaus Fetscher + Dimitry Andric + Shannon Holland + Guillaume Gourat (NexVision) + Christer Weinigel (wingel) (Acer N30) + Lucas Correia Villa Real (S3C2400 port) + + +Document Author +--------------- + +Ben Dooks, Copyright 2004-2006 Simtec Electronics diff --git a/Documentation/arm/samsung-s3c24xx/s3c2412.rst b/Documentation/arm/samsung-s3c24xx/s3c2412.rst new file mode 100644 index 000000000000..68b985fc6bf4 --- /dev/null +++ b/Documentation/arm/samsung-s3c24xx/s3c2412.rst @@ -0,0 +1,121 @@ +========================== +S3C2412 ARM Linux Overview +========================== + +Introduction +------------ + + The S3C2412 is part of the S3C24XX range of ARM9 System-on-Chip CPUs + from Samsung. This part has an ARM926-EJS core, capable of running up + to 266MHz (see data-sheet for more information) + + +Clock +----- + + The core clock code provides a set of clocks to the drivers, and allows + for source selection and a number of other features. + + +Power +----- + + No support for suspend/resume to RAM in the current system. + + +DMA +--- + + No current support for DMA. + + +GPIO +---- + + There is support for setting the GPIO to input/output/special function + and reading or writing to them. + + +UART +---- + + The UART hardware is similar to the S3C2440, and is supported by the + s3c2410 driver in the drivers/serial directory. + + +NAND +---- + + The NAND hardware is similar to the S3C2440, and is supported by the + s3c2410 driver in the drivers/mtd/nand/raw directory. + + +USB Host +-------- + + The USB hardware is similar to the S3C2410, with extended clock source + control. The OHCI portion is supported by the ohci-s3c2410 driver, and + the clock control selection is supported by the core clock code. + + +USB Device +---------- + + No current support in the kernel + + +IRQs +---- + + All the standard, and external interrupt sources are supported. The + extra sub-sources are not yet supported. + + +RTC +--- + + The RTC hardware is similar to the S3C2410, and is supported by the + s3c2410-rtc driver. + + +Watchdog +-------- + + The watchdog hardware is the same as the S3C2410, and is supported by + the s3c2410_wdt driver. + + +MMC/SD/SDIO +----------- + + No current support for the MMC/SD/SDIO block. + +IIC +--- + + The IIC hardware is the same as the S3C2410, and is supported by the + i2c-s3c24xx driver. + + +IIS +--- + + No current support for the IIS interface. + + +SPI +--- + + No current support for the SPI interfaces. + + +ATA +--- + + No current support for the on-board ATA block. + + +Document Author +--------------- + +Ben Dooks, Copyright 2006 Simtec Electronics diff --git a/Documentation/arm/samsung-s3c24xx/s3c2413.rst b/Documentation/arm/samsung-s3c24xx/s3c2413.rst new file mode 100644 index 000000000000..1f51e207fc46 --- /dev/null +++ b/Documentation/arm/samsung-s3c24xx/s3c2413.rst @@ -0,0 +1,22 @@ +========================== +S3C2413 ARM Linux Overview +========================== + +Introduction +------------ + + The S3C2413 is an extended version of the S3C2412, with an camera + interface and mobile DDR memory support. See the S3C2412 support + documentation for more information. + + +Camera Interface +---------------- + + This block is currently not supported. + + +Document Author +--------------- + +Ben Dooks, Copyright 2006 Simtec Electronics diff --git a/Documentation/arm/samsung-s3c24xx/smdk2440.rst b/Documentation/arm/samsung-s3c24xx/smdk2440.rst new file mode 100644 index 000000000000..524fd0b4afaf --- /dev/null +++ b/Documentation/arm/samsung-s3c24xx/smdk2440.rst @@ -0,0 +1,57 @@ +========================= +Samsung/Meritech SMDK2440 +========================= + +Introduction +------------ + + The SMDK2440 is a two part evaluation board for the Samsung S3C2440 + processor. It includes support for LCD, SmartMedia, Audio, SD and + 10MBit Ethernet, and expansion headers for various signals, including + the camera and unused GPIO. + + +Configuration +------------- + + To set the default configuration, use `make smdk2440_defconfig` which + will configure the common features of this board, or use + `make s3c2410_config` to include support for all s3c2410/s3c2440 machines + + +Support +------- + + Ben Dooks' SMDK2440 site at http://www.fluff.org/ben/smdk2440/ which + includes linux based USB download tools. + + Some of the h1940 patches that can be found from the H1940 project + site at http://www.handhelds.org/projects/h1940.html can also be + applied to this board. + + +Peripherals +----------- + + There is no current support for any of the extra peripherals on the + base-board itself. + + +MTD +--- + + The NAND flash should be supported by the in kernel MTD NAND support, + NOR flash will be added later. + + +Maintainers +----------- + + This board is being maintained by Ben Dooks, for more info, see + http://www.fluff.org/ben/smdk2440/ + + Many thanks to Dimitry Andric of TomTom for the loan of the SMDK2440, + and to Simtec Electronics for allowing me time to work on this. + + +(c) 2004 Ben Dooks diff --git a/Documentation/arm/samsung-s3c24xx/suspend.rst b/Documentation/arm/samsung-s3c24xx/suspend.rst new file mode 100644 index 000000000000..b4f3ae9fe76e --- /dev/null +++ b/Documentation/arm/samsung-s3c24xx/suspend.rst @@ -0,0 +1,137 @@ +======================= +S3C24XX Suspend Support +======================= + + +Introduction +------------ + + The S3C24XX supports a low-power suspend mode, where the SDRAM is kept + in Self-Refresh mode, and all but the essential peripheral blocks are + powered down. For more information on how this works, please look + at the relevant CPU datasheet from Samsung. + + +Requirements +------------ + + 1) A bootloader that can support the necessary resume operation + + 2) Support for at least 1 source for resume + + 3) CONFIG_PM enabled in the kernel + + 4) Any peripherals that are going to be powered down at the same + time require suspend/resume support. + + +Resuming +-------- + + The S3C2410 user manual defines the process of sending the CPU to + sleep and how it resumes. The default behaviour of the Linux code + is to set the GSTATUS3 register to the physical address of the + code to resume Linux operation. + + GSTATUS4 is currently left alone by the sleep code, and is free to + use for any other purposes (for example, the EB2410ITX uses this to + save memory configuration in). + + +Machine Support +--------------- + + The machine specific functions must call the s3c_pm_init() function + to say that its bootloader is capable of resuming. This can be as + simple as adding the following to the machine's definition: + + INITMACHINE(s3c_pm_init) + + A board can do its own setup before calling s3c_pm_init, if it + needs to setup anything else for power management support. + + There is currently no support for over-riding the default method of + saving the resume address, if your board requires it, then contact + the maintainer and discuss what is required. + + Note, the original method of adding an late_initcall() is wrong, + 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:: + + + static irqreturn_t button_irq(int irq, void *pw) + { + return IRQ_HANDLED; + } + + statuc void __init machine_init(void) + { + ... + + request_irq(IRQ_EINT0, button_irq, IRQF_TRIGGER_FALLING, + "button-irq-eint0", NULL); + + enable_irq_wake(IRQ_EINT0); + + s3c_pm_init(); + } + + +Debugging +--------- + + There are several important things to remember when using PM suspend: + + 1) The uart drivers will disable the clocks to the UART blocks when + suspending, which means that use of printascii() or similar direct + access to the UARTs will cause the debug to stop. + + 2) While the pm code itself will attempt to re-enable the UART clocks, + care should be taken that any external clock sources that the UARTs + rely on are still enabled at that point. + + 3) If any debugging is placed in the resume path, then it must have the + relevant clocks and peripherals setup before use (ie, bootloader). + + For example, if you transmit a character from the UART, the baud + rate and uart controls must be setup beforehand. + + +Configuration +------------- + + The S3C2410 specific configuration in `System Type` defines various + aspects of how the S3C2410 suspend and resume support is configured + + `S3C2410 PM Suspend debug` + + This option prints messages to the serial console before and after + the actual suspend, giving detailed information on what is + happening + + + `S3C2410 PM Suspend Memory CRC` + + Allows the entire memory to be checksummed before and after the + suspend to see if there has been any corruption of the contents. + + Note, the time to calculate the CRC is dependent on the CPU speed + and the size of memory. For an 64Mbyte RAM area on an 200MHz + S3C2410, this can take approximately 4 seconds to complete. + + This support requires the CRC32 function to be enabled. + + + `S3C2410 PM Suspend CRC Chunksize (KiB)` + + Defines the size of memory each CRC chunk covers. A smaller value + will mean that the CRC data block will take more memory, but will + identify any faults with better precision + + +Document Author +--------------- + +Ben Dooks, Copyright 2004 Simtec Electronics diff --git a/Documentation/arm/samsung-s3c24xx/usb-host.rst b/Documentation/arm/samsung-s3c24xx/usb-host.rst new file mode 100644 index 000000000000..c84268bd1884 --- /dev/null +++ b/Documentation/arm/samsung-s3c24xx/usb-host.rst @@ -0,0 +1,91 @@ +======================== +S3C24XX USB Host support +======================== + + + +Introduction +------------ + + This document details the S3C2410/S3C2440 in-built OHCI USB host support. + +Configuration +------------- + + Enable at least the following kernel options: + + menuconfig:: + + Device Drivers ---> + USB support ---> + <*> Support for Host-side USB + <*> OHCI HCD support + + + .config: + + - CONFIG_USB + - CONFIG_USB_OHCI_HCD + + + Once these options are configured, the standard set of USB device + drivers can be configured and used. + + +Board Support +------------- + + The driver attaches to a platform device, which will need to be + added by the board specific support file in linux/arch/arm/mach-s3c2410, + such as mach-bast.c or mach-smdk2410.c + + The platform device's platform_data field is only needed if the + board implements extra power control or over-current monitoring. + + The OHCI driver does not ensure the state of the S3C2410's MISCCTRL + register, so if both ports are to be used for the host, then it is + the board support file's responsibility to ensure that the second + port is configured to be connected to the OHCI core. + + +Platform Data +------------- + + See arch/arm/mach-s3c2410/include/mach/usb-control.h for the + descriptions of the platform device data. An implementation + can be found in linux/arch/arm/mach-s3c2410/usb-simtec.c . + + The `struct s3c2410_hcd_info` contains a pair of functions + that get called to enable over-current detection, and to + control the port power status. + + 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, + with bit X being 1 for an over-current on port X. + + The function s3c2410_usb_report_oc() has been provided to + 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. + + + +Document Author +--------------- + +Ben Dooks, Copyright 2005 Simtec Electronics diff --git a/Documentation/arm/samsung/bootloader-interface.rst b/Documentation/arm/samsung/bootloader-interface.rst new file mode 100644 index 000000000000..a56f325dae78 --- /dev/null +++ b/Documentation/arm/samsung/bootloader-interface.rst @@ -0,0 +1,81 @@ +========================================================== +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 +and boot loaders on Samsung Exynos based boards. This is not a definition +of interface but rather a description of existing state, a reference +for information purpose only. + +In the document "boot loader" means any of following: U-boot, proprietary +SBOOT or any other firmware for ARMv7 and ARMv8 initializing the board before +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 +0x1c + 4*cpu exynos4_secondary_startup (Exynos4412) Secondary CPU boot +0x20 0xfcba0d10 (Magic cookie) AFTR +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 +0x0804 0x00000bad (Magic cookie) System suspend +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 + +AFTR - ARM Off Top Running, a low power mode, Cortex cores and many other +modules are power gated, except the TOP modules +MCPM - Multi-Cluster Power Management diff --git a/Documentation/arm/samsung/clksrc-change-registers.awk b/Documentation/arm/samsung/clksrc-change-registers.awk new file mode 100755 index 000000000000..7be1b8aa7cd9 --- /dev/null +++ b/Documentation/arm/samsung/clksrc-change-registers.awk @@ -0,0 +1,166 @@ +#!/usr/bin/awk -f +# +# Copyright 2010 Ben Dooks +# +# Released under GPLv2 + +# example usage +# ./clksrc-change-registers.awk arch/arm/plat-s5pc1xx/include/plat/regs-clock.h < src > dst + +function extract_value(s) +{ + eqat = index(s, "=") + comat = index(s, ",") + return substr(s, eqat+2, (comat-eqat)-2) +} + +function remove_brackets(b) +{ + return substr(b, 2, length(b)-2) +} + +function splitdefine(l, p) +{ + r = split(l, tp) + + p[0] = tp[2] + p[1] = remove_brackets(tp[3]) +} + +function find_length(f) +{ + if (0) + printf "find_length " f "\n" > "/dev/stderr" + + if (f ~ /0x1/) + return 1 + else if (f ~ /0x3/) + return 2 + else if (f ~ /0x7/) + return 3 + else if (f ~ /0xf/) + return 4 + + printf "unknown length " f "\n" > "/dev/stderr" + exit +} + +function find_shift(s) +{ + id = index(s, "<") + if (id <= 0) { + printf "cannot find shift " s "\n" > "/dev/stderr" + exit + } + + return substr(s, id+2) +} + + +BEGIN { + if (ARGC < 2) { + print "too few arguments" > "/dev/stderr" + exit + } + +# read the header file and find the mask values that we will need +# to replace and create an associative array of values + + while (getline line < ARGV[1] > 0) { + if (line ~ /\#define.*_MASK/ && + !(line ~ /USB_SIG_MASK/)) { + splitdefine(line, fields) + name = fields[0] + if (0) + printf "MASK " line "\n" > "/dev/stderr" + dmask[name,0] = find_length(fields[1]) + dmask[name,1] = find_shift(fields[1]) + if (0) + printf "=> '" name "' LENGTH=" dmask[name,0] " SHIFT=" dmask[name,1] "\n" > "/dev/stderr" + } else { + } + } + + delete ARGV[1] +} + +/clksrc_clk.*=.*{/ { + shift="" + mask="" + divshift="" + reg_div="" + reg_src="" + indent=1 + + print $0 + + for(; indent >= 1;) { + if ((getline line) <= 0) { + printf "unexpected end of file" > "/dev/stderr" + exit 1; + } + + if (line ~ /\.shift/) { + shift = extract_value(line) + } else if (line ~ /\.mask/) { + mask = extract_value(line) + } else if (line ~ /\.reg_divider/) { + reg_div = extract_value(line) + } else if (line ~ /\.reg_source/) { + reg_src = extract_value(line) + } else if (line ~ /\.divider_shift/) { + divshift = extract_value(line) + } else if (line ~ /{/) { + indent++ + print line + } else if (line ~ /}/) { + indent-- + + if (indent == 0) { + if (0) { + printf "shift '" shift "' ='" dmask[shift,0] "'\n" > "/dev/stderr" + printf "mask '" mask "'\n" > "/dev/stderr" + printf "dshft '" divshift "'\n" > "/dev/stderr" + printf "rdiv '" reg_div "'\n" > "/dev/stderr" + printf "rsrc '" reg_src "'\n" > "/dev/stderr" + } + + generated = mask + sub(reg_src, reg_div, generated) + + if (0) { + printf "/* rsrc " reg_src " */\n" + printf "/* rdiv " reg_div " */\n" + printf "/* shift " shift " */\n" + printf "/* mask " mask " */\n" + printf "/* generated " generated " */\n" + } + + if (reg_div != "") { + printf "\t.reg_div = { " + printf ".reg = " reg_div ", " + printf ".shift = " dmask[generated,1] ", " + printf ".size = " dmask[generated,0] ", " + printf "},\n" + } + + printf "\t.reg_src = { " + printf ".reg = " reg_src ", " + printf ".shift = " dmask[mask,1] ", " + printf ".size = " dmask[mask,0] ", " + + printf "},\n" + + } + + print line + } else { + print line + } + + if (0) + printf indent ":" line "\n" > "/dev/stderr" + } +} + +// && ! /clksrc_clk.*=.*{/ { print $0 } diff --git a/Documentation/arm/samsung/gpio.rst b/Documentation/arm/samsung/gpio.rst new file mode 100644 index 000000000000..5f7cadd7159e --- /dev/null +++ b/Documentation/arm/samsung/gpio.rst @@ -0,0 +1,41 @@ +=========================== +Samsung GPIO implementation +=========================== + +Introduction +------------ + +This outlines the Samsung GPIO implementation and the architecture +specific calls provided alongside the drivers/gpio core. + + +S3C24XX (Legacy) +---------------- + +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. + + +GPIOLIB integration +------------------- + +The gpio implementation uses gpiolib as much as possible, only providing +specific calls for the items that require Samsung specific handling, such +as pin special-function or pull resistor control. + +GPIO numbering is synchronised between the Samsung and gpiolib system. + + +PIN configuration +----------------- + +Pin configuration is specific to the Samsung architecture, with each SoC +registering the necessary information for the core gpio configuration +implementation to configure pins as necessary. + +The s3c_gpio_cfgpin() and s3c_gpio_setpull() provide the means for a +driver or machine to change gpio configuration. + +See arch/arm/plat-samsung/include/plat/gpio-cfg.h for more information +on these functions. 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.rst b/Documentation/arm/samsung/overview.rst new file mode 100644 index 000000000000..e74307897416 --- /dev/null +++ b/Documentation/arm/samsung/overview.rst @@ -0,0 +1,89 @@ +========================== +Samsung ARM Linux Overview +========================== + +Introduction +------------ + + The Samsung range of ARM SoCs spans many similar devices, from the initial + ARM9 through to the newest ARM cores. This document shows an overview of + the current kernel support, how to use it and where to find the code + that supports this. + + The currently supported SoCs are: + + - S3C24XX: See Documentation/arm/samsung-s3c24xx/overview.rst for full list + - S3C64XX: S3C6400 and S3C6410 + - S5PC110 / S5PV210 + + +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.rst for more information + on the implementation details and specific support. + + +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 + + +Layout +------ + + The directory layout is currently being restructured, and consists of + several platform directories and then the machine specific directories + of the CPUs being built for. + + plat-samsung provides the base for all the implementations, and is the + last in the line of include directories that are processed for the build + specific information. It contains the base clock, GPIO and device definitions + to get the system running. + + plat-s3c24xx is for s3c24xx specific builds, see the S3C24XX docs. + + plat-s5p is for s5p specific builds, and contains common support for the + S5P specific systems. Not all S5Ps use all the features in this directory + due to differences in the hardware. + + +Layout changes +-------------- + + The old plat-s3c and plat-s5pc1xx directories have been removed, with + support moved to either plat-samsung or plat-s5p as necessary. These moves + where to simplify the include and dependency issues involved with having + so many different platform directories. + + +Port Contributors +----------------- + + Ben Dooks (BJD) + Vincent Sanders + Herbert Potzl + Arnaud Patard (RTP) + Roc Wu + Klaus Fetscher + Dimitry Andric + Shannon Holland + Guillaume Gourat (NexVision) + Christer Weinigel (wingel) (Acer N30) + Lucas Correia Villa Real (S3C2400 port) + + +Document Author +--------------- + +Copyright 2009-2010 Ben Dooks diff --git a/Documentation/arm/setup.rst b/Documentation/arm/setup.rst new file mode 100644 index 000000000000..8e12ef3fb9a7 --- /dev/null +++ b/Documentation/arm/setup.rst @@ -0,0 +1,108 @@ +============================================= +Kernel initialisation parameters on ARM Linux +============================================= + +The following document describes the kernel initialisation parameter +structure, otherwise known as 'struct param_struct' which is used +for most ARM Linux architectures. + +This structure is used to pass initialisation parameters from the +kernel loader to the Linux kernel proper, and may be short lived +through the kernel initialisation process. As a general rule, it +should not be referenced outside of arch/arm/kernel/setup.c:setup_arch(). + +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. + + If the system contains separate VRAM, this value should not + 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 + ===== ======================== + + rootdev + major/minor number pair of device to mount as the root filesystem. + + 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. + + It's generally a good idea to set these to be either standard VGA, or + the equivalent character size of your fbcon display. This then allows + all the bootup messages to be displayed correctly. + + 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 + 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 + 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 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 + 0-66 MHz. If no params are passed or a value of zero is passed, + 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 new file mode 100644 index 000000000000..c928dbf3cc88 --- /dev/null +++ b/Documentation/arm/sh-mobile/.gitignore @@ -0,0 +1 @@ +vrl4 diff --git a/Documentation/arm/spear/overview.rst b/Documentation/arm/spear/overview.rst new file mode 100644 index 000000000000..8a1a87aca427 --- /dev/null +++ b/Documentation/arm/spear/overview.rst @@ -0,0 +1,65 @@ +======================== +SPEAr ARM Linux Overview +======================== + +Introduction +------------ + + SPEAr (Structured Processor Enhanced Architecture). + weblink : http://www.st.com/spear + + The ST Microelectronics SPEAr range of ARM9/CortexA9 System-on-Chip CPUs are + supported by the 'spear' platform of ARM Linux. Currently SPEAr1310, + SPEAr1340, SPEAr300, SPEAr310, SPEAr320 and SPEAr600 SOCs are supported. + + Hierarchy in SPEAr is as follows: + + SPEAr (Platform) + - SPEAr3XX (3XX SOC series, based on ARM9) + - SPEAr300 (SOC) + - SPEAr300 Evaluation Board + - SPEAr310 (SOC) + - SPEAr310 Evaluation Board + - SPEAr320 (SOC) + - SPEAr320 Evaluation Board + - SPEAr6XX (6XX SOC series, based on ARM9) + - SPEAr600 (SOC) + - SPEAr600 Evaluation Board + - SPEAr13XX (13XX SOC series, based on ARM CORTEXA9) + - SPEAr1310 (SOC) + - SPEAr1310 Evaluation Board + - SPEAr1340 (SOC) + - SPEAr1340 Evaluation Board + +Configuration +------------- + + A generic configuration is provided for each machine, and can be used as the + default by:: + + make spear13xx_defconfig + make spear3xx_defconfig + make spear6xx_defconfig + +Layout +------ + + The common files for multiple machine families (SPEAr3xx, SPEAr6xx and + SPEAr13xx) are located in the platform code contained in arch/arm/plat-spear + with headers in plat/. + + Each machine series have a directory with name arch/arm/mach-spear followed by + series name. Like mach-spear3xx, mach-spear6xx and mach-spear13xx. + + Common file for machines of spear3xx family is mach-spear3xx/spear3xx.c, for + spear6xx is mach-spear6xx/spear6xx.c and for spear13xx family is + mach-spear13xx/spear13xx.c. mach-spear* also contain soc/machine specific + files, like spear1310.c, spear1340.c spear300.c, spear310.c, spear320.c and + spear600.c. mach-spear* doesn't contains board specific files as they fully + support Flattened Device Tree. + + +Document Author +--------------- + + Viresh Kumar , (c) 2010-2012 ST Microelectronics diff --git a/Documentation/arm/sti/overview.rst b/Documentation/arm/sti/overview.rst new file mode 100644 index 000000000000..70743617a74f --- /dev/null +++ b/Documentation/arm/sti/overview.rst @@ -0,0 +1,36 @@ +====================== +STi ARM Linux Overview +====================== + +Introduction +------------ + + The ST Microelectronics Multimedia and Application Processors range of + CortexA9 System-on-Chip are supported by the 'STi' platform of + ARM Linux. Currently STiH415, STiH416 SOCs are supported with both + B2000 and B2020 Reference boards. + + +configuration +------------- + + A generic configuration is provided for both STiH415/416, and can be used as the + default by:: + + make stih41x_defconfig + +Layout +------ + + All the files for multiple machine families (STiH415, STiH416, and STiG125) + are located in the platform code contained in arch/arm/mach-sti + + There is a generic board board-dt.c in the mach folder which support + Flattened Device Tree, which means, It works with any compatible board with + Device Trees. + + +Document Author +--------------- + + Srinivas Kandagatla , (c) 2013 ST Microelectronics diff --git a/Documentation/arm/sti/overview.txt b/Documentation/arm/sti/overview.txt deleted file mode 100644 index 1a4e93d6027f..000000000000 --- a/Documentation/arm/sti/overview.txt +++ /dev/null @@ -1,33 +0,0 @@ - STi ARM Linux Overview - ========================== - -Introduction ------------- - - The ST Microelectronics Multimedia and Application Processors range of - CortexA9 System-on-Chip are supported by the 'STi' platform of - ARM Linux. Currently STiH415, STiH416 SOCs are supported with both - B2000 and B2020 Reference boards. - - - configuration - ------------- - - A generic configuration is provided for both STiH415/416, and can be used as the - default by - make stih41x_defconfig - - Layout - ------ - All the files for multiple machine families (STiH415, STiH416, and STiG125) - are located in the platform code contained in arch/arm/mach-sti - - There is a generic board board-dt.c in the mach folder which support - Flattened Device Tree, which means, It works with any compatible board with - Device Trees. - - - Document Author - --------------- - - Srinivas Kandagatla , (c) 2013 ST Microelectronics diff --git a/Documentation/arm/sti/stih407-overview.rst b/Documentation/arm/sti/stih407-overview.rst new file mode 100644 index 000000000000..027e75bc7b7c --- /dev/null +++ b/Documentation/arm/sti/stih407-overview.rst @@ -0,0 +1,19 @@ +================ +STiH407 Overview +================ + +Introduction +------------ + + The STiH407 is the new generation of SoC for Multi-HD, AVC set-top boxes + and server/connected client application for satellite, cable, terrestrial + and IP-STB markets. + + Features + - ARM Cortex-A9 1.5 GHz dual core CPU (28nm) + - SATA2, USB 3.0, PCIe, Gbit Ethernet + +Document Author +--------------- + + Maxime Coquelin , (c) 2014 ST Microelectronics diff --git a/Documentation/arm/sti/stih407-overview.txt b/Documentation/arm/sti/stih407-overview.txt deleted file mode 100644 index 3343f32f58bc..000000000000 --- a/Documentation/arm/sti/stih407-overview.txt +++ /dev/null @@ -1,18 +0,0 @@ - STiH407 Overview - ================ - -Introduction ------------- - - The STiH407 is the new generation of SoC for Multi-HD, AVC set-top boxes - and server/connected client application for satellite, cable, terrestrial - and IP-STB markets. - - Features - - ARM Cortex-A9 1.5 GHz dual core CPU (28nm) - - SATA2, USB 3.0, PCIe, Gbit Ethernet - - Document Author - --------------- - - Maxime Coquelin , (c) 2014 ST Microelectronics diff --git a/Documentation/arm/sti/stih415-overview.rst b/Documentation/arm/sti/stih415-overview.rst new file mode 100644 index 000000000000..b67452d610c4 --- /dev/null +++ b/Documentation/arm/sti/stih415-overview.rst @@ -0,0 +1,14 @@ +================ +STiH415 Overview +================ + +Introduction +------------ + + The STiH415 is the next generation of HD, AVC set-top box processors + for satellite, cable, terrestrial and IP-STB markets. + + Features: + + - ARM Cortex-A9 1.0 GHz, dual-core CPU + - SATA2x2,USB 2.0x3, PCIe, Gbit Ethernet MACx2 diff --git a/Documentation/arm/sti/stih415-overview.txt b/Documentation/arm/sti/stih415-overview.txt deleted file mode 100644 index 1383e33f265d..000000000000 --- a/Documentation/arm/sti/stih415-overview.txt +++ /dev/null @@ -1,12 +0,0 @@ - STiH415 Overview - ================ - -Introduction ------------- - - The STiH415 is the next generation of HD, AVC set-top box processors - for satellite, cable, terrestrial and IP-STB markets. - - 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.rst b/Documentation/arm/sti/stih416-overview.rst new file mode 100644 index 000000000000..93f17d74d8db --- /dev/null +++ b/Documentation/arm/sti/stih416-overview.rst @@ -0,0 +1,13 @@ +================ +STiH416 Overview +================ + +Introduction +------------ + + The STiH416 is the next generation of HD, AVC set-top box processors + for satellite, cable, terrestrial and IP-STB markets. + + Features + - ARM Cortex-A9 1.2 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.txt deleted file mode 100644 index 558444c201c6..000000000000 --- a/Documentation/arm/sti/stih416-overview.txt +++ /dev/null @@ -1,12 +0,0 @@ - STiH416 Overview - ================ - -Introduction ------------- - - The STiH416 is the next generation of HD, AVC set-top box processors - for satellite, cable, terrestrial and IP-STB markets. - - Features - - ARM Cortex-A9 1.2 GHz dual core CPU - - SATA2x2,USB 2.0x3, PCIe, Gbit Ethernet MACx2 diff --git a/Documentation/arm/sti/stih418-overview.rst b/Documentation/arm/sti/stih418-overview.rst new file mode 100644 index 000000000000..b563c1f4fe5a --- /dev/null +++ b/Documentation/arm/sti/stih418-overview.rst @@ -0,0 +1,21 @@ +================ +STiH418 Overview +================ + +Introduction +------------ + + The STiH418 is the new generation of SoC for UHDp60 set-top boxes + and server/connected client application for satellite, cable, terrestrial + and IP-STB markets. + + Features + - ARM Cortex-A9 1.5 GHz quad core CPU (28nm) + - SATA2, USB 3.0, PCIe, Gbit Ethernet + - HEVC L5.1 Main 10 + - VP9 + +Document Author +--------------- + + Maxime Coquelin , (c) 2015 ST Microelectronics diff --git a/Documentation/arm/sti/stih418-overview.txt b/Documentation/arm/sti/stih418-overview.txt deleted file mode 100644 index 1cd8fc80646d..000000000000 --- a/Documentation/arm/sti/stih418-overview.txt +++ /dev/null @@ -1,20 +0,0 @@ - STiH418 Overview - ================ - -Introduction ------------- - - The STiH418 is the new generation of SoC for UHDp60 set-top boxes - and server/connected client application for satellite, cable, terrestrial - and IP-STB markets. - - Features - - ARM Cortex-A9 1.5 GHz quad core CPU (28nm) - - SATA2, USB 3.0, PCIe, Gbit Ethernet - - HEVC L5.1 Main 10 - - VP9 - - 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.rst b/Documentation/arm/sunxi.rst new file mode 100644 index 000000000000..b037428aee98 --- /dev/null +++ b/Documentation/arm/sunxi.rst @@ -0,0 +1,150 @@ +================== +ARM Allwinner SoCs +================== + +This document lists all the ARM Allwinner SoCs that are currently +supported in mainline by the Linux kernel. This document will also +provide links to documentation and/or datasheet for these SoCs. + +SunXi family +------------ + Linux kernel mach directory: arch/arm/mach-sunxi + + Flavors: + + * ARM926 based SoCs + - Allwinner F20 (sun3i) + + * Not Supported + + * ARM Cortex-A8 based SoCs + - Allwinner A10 (sun4i) + + * Datasheet + + http://dl.linux-sunxi.org/A10/A10%20Datasheet%20-%20v1.21%20%282012-04-06%29.pdf + * 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 + + http://dl.linux-sunxi.org/A10s/A10s%20Datasheet%20-%20v1.20%20%282012-03-27%29.pdf + + - Allwinner A13 / R8 (sun5i) + + * Datasheet + + http://dl.linux-sunxi.org/A13/A13%20Datasheet%20-%20v1.12%20%282012-03-29%29.pdf + * 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 + + http://linux-sunxi.org/File:Allwinner_V3s_Datasheet_V1.0.pdf + + * Dual ARM Cortex-A7 based SoCs + - Allwinner A20 (sun7i) + + * User Manual + + http://dl.linux-sunxi.org/A20/A20%20User%20Manual%202013-03-22.pdf + + - Allwinner A23 (sun8i) + + * Datasheet + + http://dl.linux-sunxi.org/A23/A23%20Datasheet%20V1.0%2020130830.pdf + + * 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 + + http://dl.linux-sunxi.org/A31/A3x_release_document/A31/IC/A31%20datasheet%20V1.3%2020131106.pdf + + * User Manual + + http://dl.linux-sunxi.org/A31/A3x_release_document/A31/IC/A31%20user%20manual%20V1.1%2020130630.pdf + + - Allwinner A31s (sun6i) + + * Datasheet + + http://dl.linux-sunxi.org/A31/A3x_release_document/A31s/IC/A31s%20datasheet%20V1.3%2020131106.pdf + + * 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 + + http://dl.linux-sunxi.org/A33/A33%20Datasheet%20release%201.1.pdf + + * 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 + H3 drivers and memory map. + + - Allwinner H3 (sun8i) + + * Datasheet + + http://dl.linux-sunxi.org/H3/Allwinner_H3_Datasheet_V1.0.pdf + + - Allwinner R40 (sun8i) + + * Datasheet + + https://github.com/tinalinux/docs/raw/r40-v1.y/R40_Datasheet_V1.0.pdf + + * 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 + + http://dl.linux-sunxi.org/A80/A80_Datasheet_Revision_1.0_0404.pdf + + * Octa ARM Cortex-A7 based SoCs + - Allwinner A83T + + * Datasheet + + https://github.com/allwinner-zh/documents/raw/master/A83T/A83T_Datasheet_v1.3_20150510.pdf + + * 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 + + http://dl.linux-sunxi.org/A64/A64_Datasheet_V1.1.pdf + + * User Manual + + http://dl.linux-sunxi.org/A64/Allwinner%20A64%20User%20Manual%20v1.0.pdf diff --git a/Documentation/arm/sunxi/README b/Documentation/arm/sunxi/README deleted file mode 100644 index f8efc21998bf..000000000000 --- a/Documentation/arm/sunxi/README +++ /dev/null @@ -1,102 +0,0 @@ -ARM Allwinner SoCs -================== - -This document lists all the ARM Allwinner SoCs that are currently -supported in mainline by the Linux kernel. This document will also -provide links to documentation and/or datasheet for these SoCs. - -SunXi family ------------- - Linux kernel mach directory: arch/arm/mach-sunxi - - Flavors: - * ARM926 based SoCs - - Allwinner F20 (sun3i) - + Not Supported - - * ARM Cortex-A8 based SoCs - - Allwinner A10 (sun4i) - + Datasheet - http://dl.linux-sunxi.org/A10/A10%20Datasheet%20-%20v1.21%20%282012-04-06%29.pdf - + 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 - http://dl.linux-sunxi.org/A10s/A10s%20Datasheet%20-%20v1.20%20%282012-03-27%29.pdf - - - Allwinner A13 / R8 (sun5i) - + Datasheet - http://dl.linux-sunxi.org/A13/A13%20Datasheet%20-%20v1.12%20%282012-03-29%29.pdf - + 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 - http://linux-sunxi.org/File:Allwinner_V3s_Datasheet_V1.0.pdf - - * Dual ARM Cortex-A7 based SoCs - - Allwinner A20 (sun7i) - + User Manual - http://dl.linux-sunxi.org/A20/A20%20User%20Manual%202013-03-22.pdf - - - Allwinner A23 (sun8i) - + Datasheet - http://dl.linux-sunxi.org/A23/A23%20Datasheet%20V1.0%2020130830.pdf - + 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 - http://dl.linux-sunxi.org/A31/A3x_release_document/A31/IC/A31%20datasheet%20V1.3%2020131106.pdf - + User Manual - http://dl.linux-sunxi.org/A31/A3x_release_document/A31/IC/A31%20user%20manual%20V1.1%2020130630.pdf - - - Allwinner A31s (sun6i) - + Datasheet - http://dl.linux-sunxi.org/A31/A3x_release_document/A31s/IC/A31s%20datasheet%20V1.3%2020131106.pdf - + 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 - http://dl.linux-sunxi.org/A33/A33%20Datasheet%20release%201.1.pdf - + 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 - H3 drivers and memory map. - - - Allwinner H3 (sun8i) - + Datasheet - http://dl.linux-sunxi.org/H3/Allwinner_H3_Datasheet_V1.0.pdf - - - Allwinner R40 (sun8i) - + Datasheet - https://github.com/tinalinux/docs/raw/r40-v1.y/R40_Datasheet_V1.0.pdf - + 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 - http://dl.linux-sunxi.org/A80/A80_Datasheet_Revision_1.0_0404.pdf - - * Octa ARM Cortex-A7 based SoCs - - Allwinner A83T - + Datasheet - https://github.com/allwinner-zh/documents/raw/master/A83T/A83T_Datasheet_v1.3_20150510.pdf - + 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 - http://dl.linux-sunxi.org/A64/A64_Datasheet_V1.1.pdf - + User Manual - http://dl.linux-sunxi.org/A64/Allwinner%20A64%20User%20Manual%20v1.0.pdf diff --git a/Documentation/arm/sunxi/clocks.rst b/Documentation/arm/sunxi/clocks.rst new file mode 100644 index 000000000000..23bd03f3e21f --- /dev/null +++ b/Documentation/arm/sunxi/clocks.rst @@ -0,0 +1,57 @@ +======================================================= +Frequently asked questions about the sunxi clock system +======================================================= + +This document contains useful bits of information that people tend to ask +about the sunxi clock system, as well as accompanying ASCII art when adequate. + +Q: Why is the main 24MHz oscillator gatable? Wouldn't that break the + system? + +A: The 24MHz oscillator allows gating to save power. Indeed, if gated + carelessly the system would stop functioning, but with the right + 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:: + + 24MHz 32kHz + | + PLL1 + \ + \_ CPU Mux + | + [CPU] + + When you are about to suspend, you switch the CPU Mux to the 32kHz + oscillator:: + + 24Mhz 32kHz + | | + PLL1 | + / + CPU Mux _/ + | + [CPU] + + Finally you can gate the main oscillator:: + + 32kHz + | + | + / + CPU Mux _/ + | + [CPU] + +Q: Were can I learn more about the sunxi clocks? + +A: The linux-sunxi wiki contains a page documenting the clock registers, + you can find it at + + http://linux-sunxi.org/A10/CCM + + The authoritative source for information at this time is the ccmu driver + released by Allwinner, you can find it at + + https://github.com/linux-sunxi/linux-sunxi/tree/sunxi-3.0/arch/arm/mach-sun4i/clock/ccmu diff --git a/Documentation/arm/sunxi/clocks.txt b/Documentation/arm/sunxi/clocks.txt deleted file mode 100644 index e09a88aa3136..000000000000 --- a/Documentation/arm/sunxi/clocks.txt +++ /dev/null @@ -1,56 +0,0 @@ -Frequently asked questions about the sunxi clock system -======================================================= - -This document contains useful bits of information that people tend to ask -about the sunxi clock system, as well as accompanying ASCII art when adequate. - -Q: Why is the main 24MHz oscillator gatable? Wouldn't that break the - system? - -A: The 24MHz oscillator allows gating to save power. Indeed, if gated - carelessly the system would stop functioning, but with the right - 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 - - 24MHz 32kHz - | - PLL1 - \ - \_ CPU Mux - | - [CPU] - - When you are about to suspend, you switch the CPU Mux to the 32kHz - oscillator: - - 24Mhz 32kHz - | | - PLL1 | - / - CPU Mux _/ - | - [CPU] - - Finally you can gate the main oscillator - - 32kHz - | - | - / - CPU Mux _/ - | - [CPU] - -Q: Were can I learn more about the sunxi clocks? - -A: The linux-sunxi wiki contains a page documenting the clock registers, - you can find it at - - http://linux-sunxi.org/A10/CCM - - The authoritative source for information at this time is the ccmu driver - released by Allwinner, you can find it at - - https://github.com/linux-sunxi/linux-sunxi/tree/sunxi-3.0/arch/arm/mach-sun4i/clock/ccmu diff --git a/Documentation/arm/swp_emulation b/Documentation/arm/swp_emulation deleted file mode 100644 index af903d22fd93..000000000000 --- a/Documentation/arm/swp_emulation +++ /dev/null @@ -1,27 +0,0 @@ -Software emulation of deprecated SWP instruction (CONFIG_SWP_EMULATE) ---------------------------------------------------------------------- - -ARMv6 architecture deprecates use of the SWP/SWPB instructions, and recommeds -moving to the load-locked/store-conditional instructions LDREX and STREX. - -ARMv7 multiprocessing extensions introduce the ability to disable these -instructions, triggering an undefined instruction exception when executed. -Trapped instructions are emulated using an LDREX/STREX or LDREXB/STREXB -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 ---- - -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/swp_emulation.rst b/Documentation/arm/swp_emulation.rst new file mode 100644 index 000000000000..6a608a9c3715 --- /dev/null +++ b/Documentation/arm/swp_emulation.rst @@ -0,0 +1,27 @@ +Software emulation of deprecated SWP instruction (CONFIG_SWP_EMULATE) +--------------------------------------------------------------------- + +ARMv6 architecture deprecates use of the SWP/SWPB instructions, and recommeds +moving to the load-locked/store-conditional instructions LDREX and STREX. + +ARMv7 multiprocessing extensions introduce the ability to disable these +instructions, triggering an undefined instruction exception when executed. +Trapped instructions are emulated using an LDREX/STREX or LDREXB/STREXB +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 + + +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.rst b/Documentation/arm/tcm.rst new file mode 100644 index 000000000000..effd9c7bc968 --- /dev/null +++ b/Documentation/arm/tcm.rst @@ -0,0 +1,161 @@ +================================================== +ARM TCM (Tightly-Coupled Memory) handling in Linux +================================================== + +Written by Linus Walleij + +Some ARM SoC:s have a so-called TCM (Tightly-Coupled Memory). +This is usually just a few (4-64) KiB of RAM inside the ARM +processor. + +Due to being embedded inside the CPU The TCM has a +Harvard-architecture, so there is an ITCM (instruction TCM) +and a DTCM (data TCM). The DTCM can not contain any +instructions, but the ITCM can actually contain data. +The size of DTCM or ITCM is minimum 4KiB so the typical +minimum configuration is 4KiB ITCM and 4KiB DTCM. + +ARM CPU:s have special registers to read out status, physical +location and size of TCM memories. arch/arm/include/asm/cputype.h +defines a CPUID_TCM register that you can read out from the +system control coprocessor. Documentation from ARM can be found +at http://infocenter.arm.com, search for "TCM Status Register" +to see documents for all CPUs. Reading this register you can +determine if ITCM (bits 1-0) and/or DTCM (bit 17-16) is present +in the machine. + +There is further a TCM region register (search for "TCM Region +Registers" at the ARM site) that can report and modify the location +size of TCM memories at runtime. This is used to read out and modify +TCM location and size. Notice that this is not a MMU table: you +actually move the physical location of the TCM around. At the +place you put it, it will mask any underlying RAM from the +CPU so it is usually wise not to overlap any physical RAM with +the TCM. + +The TCM memory can then be remapped to another address again using +the MMU, but notice that the TCM if often used in situations where +the MMU is turned off. To avoid confusion the current Linux +implementation will map the TCM 1 to 1 from physical to virtual +memory in the location specified by the kernel. Currently Linux +will map ITCM to 0xfffe0000 and on, and DTCM to 0xfffe8000 and +on, supporting a maximum of 32KiB of ITCM and 32KiB of DTCM. + +Newer versions of the region registers also support dividing these +TCMs in two separate banks, so for example an 8KiB ITCM is divided +into two 4KiB banks with its own control registers. The idea is to +be able to lock and hide one of the banks for use by the secure +world (TrustZone). + +TCM is used for a few things: + +- FIQ and other interrupt handlers that need deterministic + timing and cannot wait for cache misses. + +- Idle loops where all external RAM is set to self-refresh + retention mode, so only on-chip RAM is accessible by + the CPU and then we hang inside ITCM waiting for an + interrupt. + +- Other operations which implies shutting off or reconfiguring + the external RAM controller. + +There is an interface for using TCM on the ARM architecture +in . Using this interface it is possible to: + +- Define the physical address and size of ITCM and DTCM. + +- Tag functions to be compiled into ITCM. + +- Tag data and constants to be allocated to DTCM and ITCM. + +- Have the remaining TCM RAM added to a special + allocation pool with gen_pool_create() and gen_pool_add() + and provice tcm_alloc() and tcm_free() for this + memory. Such a heap is great for things like saving + device state when shutting off device power domains. + +A machine that has TCM memory shall select HAVE_TCM from +arch/arm/Kconfig for itself. Code that needs to use TCM shall +#include + +Functions to go into itcm can be tagged like this: +int __tcmfunc foo(int bar); + +Since these are marked to become long_calls and you may want +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; + +Constants can be tagged like this:: + + int __tcmconst foo; + +To put assembler into TCM just use:: + + .section ".tcm.text" or .section ".tcm.data" + +respectively. + +Example code:: + + #include + + /* 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) + { + int i; + for (i = 0; i < 100; i++) + tcmvar ++; + } + + 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) + { + u32 *tcmem; + int i; + + hello_tcm(); + printk("Hello TCM executed from ITCM RAM\n"); + + printk("TCM variable from testrun: %u @ %p\n", tcmvar, &tcmvar); + tcmvar = 0xDEADBEEFU; + printk("TCM variable: 0x%x @ %p\n", tcmvar, &tcmvar); + + printk("TCM assigned variable: 0x%x @ %p\n", tcmassigned, &tcmassigned); + + printk("TCM constant: 0x%x @ %p\n", tcmconst, &tcmconst); + + /* Allocate some TCM memory from the pool */ + tcmem = tcm_alloc(20); + if (tcmem) { + printk("TCM Allocated 20 bytes of TCM @ %p\n", tcmem); + tcmem[0] = 0xDEADBEEFU; + tcmem[1] = 0x2BADBABEU; + tcmem[2] = 0xCAFEBABEU; + tcmem[3] = 0xDEADBEEFU; + tcmem[4] = 0x2BADBABEU; + for (i = 0; i < 5; i++) + printk("TCM tcmem[%d] = %08x\n", i, tcmem[i]); + tcm_free(tcmem, 20); + } + } diff --git a/Documentation/arm/tcm.txt b/Documentation/arm/tcm.txt deleted file mode 100644 index 7c15871c1885..000000000000 --- a/Documentation/arm/tcm.txt +++ /dev/null @@ -1,155 +0,0 @@ -ARM TCM (Tightly-Coupled Memory) handling in Linux ----- -Written by Linus Walleij - -Some ARM SoC:s have a so-called TCM (Tightly-Coupled Memory). -This is usually just a few (4-64) KiB of RAM inside the ARM -processor. - -Due to being embedded inside the CPU The TCM has a -Harvard-architecture, so there is an ITCM (instruction TCM) -and a DTCM (data TCM). The DTCM can not contain any -instructions, but the ITCM can actually contain data. -The size of DTCM or ITCM is minimum 4KiB so the typical -minimum configuration is 4KiB ITCM and 4KiB DTCM. - -ARM CPU:s have special registers to read out status, physical -location and size of TCM memories. arch/arm/include/asm/cputype.h -defines a CPUID_TCM register that you can read out from the -system control coprocessor. Documentation from ARM can be found -at http://infocenter.arm.com, search for "TCM Status Register" -to see documents for all CPUs. Reading this register you can -determine if ITCM (bits 1-0) and/or DTCM (bit 17-16) is present -in the machine. - -There is further a TCM region register (search for "TCM Region -Registers" at the ARM site) that can report and modify the location -size of TCM memories at runtime. This is used to read out and modify -TCM location and size. Notice that this is not a MMU table: you -actually move the physical location of the TCM around. At the -place you put it, it will mask any underlying RAM from the -CPU so it is usually wise not to overlap any physical RAM with -the TCM. - -The TCM memory can then be remapped to another address again using -the MMU, but notice that the TCM if often used in situations where -the MMU is turned off. To avoid confusion the current Linux -implementation will map the TCM 1 to 1 from physical to virtual -memory in the location specified by the kernel. Currently Linux -will map ITCM to 0xfffe0000 and on, and DTCM to 0xfffe8000 and -on, supporting a maximum of 32KiB of ITCM and 32KiB of DTCM. - -Newer versions of the region registers also support dividing these -TCMs in two separate banks, so for example an 8KiB ITCM is divided -into two 4KiB banks with its own control registers. The idea is to -be able to lock and hide one of the banks for use by the secure -world (TrustZone). - -TCM is used for a few things: - -- FIQ and other interrupt handlers that need deterministic - timing and cannot wait for cache misses. - -- Idle loops where all external RAM is set to self-refresh - retention mode, so only on-chip RAM is accessible by - the CPU and then we hang inside ITCM waiting for an - interrupt. - -- Other operations which implies shutting off or reconfiguring - the external RAM controller. - -There is an interface for using TCM on the ARM architecture -in . Using this interface it is possible to: - -- Define the physical address and size of ITCM and DTCM. - -- Tag functions to be compiled into ITCM. - -- Tag data and constants to be allocated to DTCM and ITCM. - -- Have the remaining TCM RAM added to a special - allocation pool with gen_pool_create() and gen_pool_add() - and provice tcm_alloc() and tcm_free() for this - memory. Such a heap is great for things like saving - device state when shutting off device power domains. - -A machine that has TCM memory shall select HAVE_TCM from -arch/arm/Kconfig for itself. Code that needs to use TCM shall -#include - -Functions to go into itcm can be tagged like this: -int __tcmfunc foo(int bar); - -Since these are marked to become long_calls and you may want -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; - -Constants can be tagged like this: -int __tcmconst foo; - -To put assembler into TCM just use -.section ".tcm.text" or .section ".tcm.data" -respectively. - -Example code: - -#include - -/* 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) -{ - int i; - for (i = 0; i < 100; i++) - tcmvar ++; -} - -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) -{ - u32 *tcmem; - int i; - - hello_tcm(); - printk("Hello TCM executed from ITCM RAM\n"); - - printk("TCM variable from testrun: %u @ %p\n", tcmvar, &tcmvar); - tcmvar = 0xDEADBEEFU; - printk("TCM variable: 0x%x @ %p\n", tcmvar, &tcmvar); - - printk("TCM assigned variable: 0x%x @ %p\n", tcmassigned, &tcmassigned); - - printk("TCM constant: 0x%x @ %p\n", tcmconst, &tcmconst); - - /* Allocate some TCM memory from the pool */ - tcmem = tcm_alloc(20); - if (tcmem) { - printk("TCM Allocated 20 bytes of TCM @ %p\n", tcmem); - tcmem[0] = 0xDEADBEEFU; - tcmem[1] = 0x2BADBABEU; - tcmem[2] = 0xCAFEBABEU; - tcmem[3] = 0xDEADBEEFU; - tcmem[4] = 0x2BADBABEU; - for (i = 0; i < 5; i++) - printk("TCM tcmem[%d] = %08x\n", i, tcmem[i]); - tcm_free(tcmem, 20); - } -} diff --git a/Documentation/arm/uefi.rst b/Documentation/arm/uefi.rst new file mode 100644 index 000000000000..f868330df6be --- /dev/null +++ b/Documentation/arm/uefi.rst @@ -0,0 +1,67 @@ +================================================ +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/. + +UEFI is an evolution of its predecessor 'EFI', so the terms EFI and +UEFI are used somewhat interchangeably in this document and associated +source code. As a rule, anything new uses 'UEFI', whereas 'EFI' refers +to legacy code or specifications. + +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 + +The implementation depends on receiving information about the UEFI environment +in a Flattened Device Tree (FDT) - so is only available with CONFIG_OF. + +UEFI stub +========= +The "stub" is a feature that extends the Image/zImage into a valid UEFI +PE/COFF executable, including a loader application that makes it possible to +load the kernel directly from the UEFI shell, boot menu, or one of the +lightweight bootloaders like Gummiboot or rEFInd. + +The kernel image built with stub support remains a valid kernel image for +booting in non-UEFI environments. + +UEFI kernel support on ARM +========================== +UEFI kernel support on the ARM architectures (arm and arm64) is only available +when boot is performed through the stub. + +When booting in UEFI mode, the stub deletes any memory nodes from a provided DT. +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. +========================== ====== =========================================== diff --git a/Documentation/arm/uefi.txt b/Documentation/arm/uefi.txt deleted file mode 100644 index 6543a0adea8a..000000000000 --- a/Documentation/arm/uefi.txt +++ /dev/null @@ -1,60 +0,0 @@ -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/. - -UEFI is an evolution of its predecessor 'EFI', so the terms EFI and -UEFI are used somewhat interchangeably in this document and associated -source code. As a rule, anything new uses 'UEFI', whereas 'EFI' refers -to legacy code or specifications. - -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 - -The implementation depends on receiving information about the UEFI environment -in a Flattened Device Tree (FDT) - so is only available with CONFIG_OF. - -UEFI stub -========= -The "stub" is a feature that extends the Image/zImage into a valid UEFI -PE/COFF executable, including a loader application that makes it possible to -load the kernel directly from the UEFI shell, boot menu, or one of the -lightweight bootloaders like Gummiboot or rEFInd. - -The kernel image built with stub support remains a valid kernel image for -booting in non-UEFI environments. - -UEFI kernel support on ARM -========================== -UEFI kernel support on the ARM architectures (arm and arm64) is only available -when boot is performed through the stub. - -When booting in UEFI mode, the stub deletes any memory nodes from a provided DT. -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. --------------------------------------------------------------------------------- diff --git a/Documentation/arm/vfp/release-notes.rst b/Documentation/arm/vfp/release-notes.rst new file mode 100644 index 000000000000..c6b04937cee3 --- /dev/null +++ b/Documentation/arm/vfp/release-notes.rst @@ -0,0 +1,57 @@ +=============================================== +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 +provides support for the exceptions bounced from VFP hardware found +on ARM926EJ-S. + +This release has been validated against the SoftFloat-2b library by +John R. Hauser using the TestFloat-2a test suite. Details of this +library and test suite can be found at: + + http://www.jhauser.us/arithmetic/SoftFloat.html + +The operations which have been tested with this package are: + + - fdiv + - fsub + - fadd + - fmul + - fcmp + - fcmpe + - fcvtd + - fcvts + - fsito + - ftosi + - fsqrt + +All the above pass softfloat tests with the following exceptions: + +- fadd/fsub shows some differences in the handling of +0 / -0 results + when input operands differ in signs. +- the handling of underflow exceptions is slightly different. If a + result underflows before rounding, but becomes a normalised number + after rounding, we do not signal an underflow exception. + +Other operations which have been tested by basic assembly-only tests +are: + + - fcpy + - fabs + - fneg + - ftoui + - ftosiz + - ftouiz + +The combination operations have not been tested: + + - fmac + - fnmac + - fmsc + - fnmsc + - fnmul diff --git a/Documentation/arm/vlocks.rst b/Documentation/arm/vlocks.rst new file mode 100644 index 000000000000..a40a1742110b --- /dev/null +++ b/Documentation/arm/vlocks.rst @@ -0,0 +1,212 @@ +====================================== +vlocks for Bare-Metal Mutual Exclusion +====================================== + +Voting Locks, or "vlocks" provide a simple low-level mutual exclusion +mechanism, with reasonable but minimal requirements on the memory +system. + +These are intended to be used to coordinate critical activity among CPUs +which are otherwise non-coherent, in situations where the hardware +provides no other mechanism to support this and ordinary spinlocks +cannot be used. + + +vlocks make use of the atomicity provided by the memory system for +writes to a single memory location. To arbitrate, every CPU "votes for +itself", by storing a unique number to a common memory location. The +final value seen in that memory location when all the votes have been +cast identifies the winner. + +In order to make sure that the election produces an unambiguous result +in finite time, a CPU will only enter the election in the first place if +no winner has been chosen and the election does not appear to have +started yet. + + +Algorithm +--------- + +The easiest way to explain the vlocks algorithm is with some pseudo-code:: + + + int currently_voting[NR_CPUS] = { 0, }; + int last_vote = -1; /* no votes yet */ + + bool vlock_trylock(int this_cpu) + { + /* signal our desire to vote */ + currently_voting[this_cpu] = 1; + if (last_vote != -1) { + /* someone already volunteered himself */ + currently_voting[this_cpu] = 0; + return false; /* not ourself */ + } + + /* let's suggest ourself */ + last_vote = this_cpu; + currently_voting[this_cpu] = 0; + + /* then wait until everyone else is done voting */ + for_each_cpu(i) { + while (currently_voting[i] != 0) + /* wait */; + } + + /* result */ + if (last_vote == this_cpu) + return true; /* we won */ + return false; + } + + bool vlock_unlock(void) + { + last_vote = -1; + } + + +The currently_voting[] array provides a way for the CPUs to determine +whether an election is in progress, and plays a role analogous to the +"entering" array in Lamport's bakery algorithm [1]. + +However, once the election has started, the underlying memory system +atomicity is used to pick the winner. This avoids the need for a static +priority rule to act as a tie-breaker, or any counters which could +overflow. + +As long as the last_vote variable is globally visible to all CPUs, it +will contain only one value that won't change once every CPU has cleared +its currently_voting flag. + + +Features and limitations +------------------------ + + * vlocks are not intended to be fair. In the contended case, it is the + _last_ CPU which attempts to get the lock which will be most likely + to win. + + vlocks are therefore best suited to situations where it is necessary + to pick a unique winner, but it does not matter which CPU actually + wins. + + * Like other similar mechanisms, vlocks will not scale well to a large + 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:: + + /* first level: local election */ + my_town = towns[(this_cpu >> 4) & 0xf]; + I_won = vlock_trylock(my_town, this_cpu & 0xf); + if (I_won) { + /* we won the town election, let's go for the state */ + my_state = states[(this_cpu >> 8) & 0xf]; + I_won = vlock_lock(my_state, this_cpu & 0xf)); + if (I_won) { + /* and so on */ + I_won = vlock_lock(the_whole_country, this_cpu & 0xf]; + if (I_won) { + /* ... */ + } + vlock_unlock(the_whole_country); + } + vlock_unlock(my_state); + } + vlock_unlock(my_town); + + +ARM implementation +------------------ + +The current ARM implementation [2] contains some optimisations beyond +the basic algorithm: + + * By packing the members of the currently_voting array close together, + we can read the whole array in one transaction (providing the number + of CPUs potentially contending the lock is small enough). This + 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:: + + LDR Rt, [Rn] + CMP Rt, #0 + + ...in place of code equivalent to:: + + LDRB Rt, [Rn] + CMP Rt, #0 + LDRBEQ Rt, [Rn, #1] + CMPEQ Rt, #0 + LDRBEQ Rt, [Rn, #2] + CMPEQ Rt, #0 + LDRBEQ Rt, [Rn, #3] + CMPEQ Rt, #0 + + This cuts down on the fast-path latency, as well as potentially + reducing bus contention in contended cases. + + The optimisation relies on the fact that the ARM memory system + guarantees coherency between overlapping memory accesses of + different sizes, similarly to many other architectures. Note that + we do not care which element of currently_voting appears in which + bits of Rt, so there is no need to worry about endianness in this + optimisation. + + If there are too many CPUs to read the currently_voting array in + one transaction then multiple transations are still required. The + implementation uses a simple loop of word-sized loads for this + case. The number of transactions is still fewer than would be + required if bytes were loaded individually. + + + In principle, we could aggregate further by using LDRD or LDM, but + to keep the code simple this was not attempted in the initial + implementation. + + + * vlocks are currently only used to coordinate between CPUs which are + unable to enable their caches yet. This means that the + implementation removes many of the barriers which would be required + when executing the algorithm in cached memory. + + packing of the currently_voting array does not work with cached + memory unless all CPUs contending the lock are cache-coherent, due + to cache writebacks from one CPU clobbering values written by other + CPUs. (Though if all the CPUs are cache-coherent, you should be + probably be using proper spinlocks instead anyway). + + + * The "no votes yet" value used for the last_vote variable is 0 (not + -1 as in the pseudocode). This allows statically-allocated vlocks + to be implicitly initialised to an unlocked state simply by putting + them in .bss. + + An offset is added to each CPU's ID for the purpose of setting this + variable, so that no CPU uses the value 0 for its ID. + + +Colophon +-------- + +Originally created and documented by Dave Martin for Linaro Limited, for +use in ARM-based big.LITTLE platforms, with review and input gratefully +received from Nicolas Pitre and Achin Gupta. Thanks to Nicolas for +grabbing most of this text out of the relevant mail thread and writing +up the pseudocode. + +Copyright (C) 2012-2013 Linaro Limited +Distributed under the terms of Version 2 of the GNU General Public +License, as defined in linux/COPYING. + + +References +---------- + +[1] Lamport, L. "A New Solution of Dijkstra's Concurrent Programming + Problem", Communications of the ACM 17, 8 (August 1974), 453-455. + + https://en.wikipedia.org/wiki/Lamport%27s_bakery_algorithm + +[2] linux/arch/arm/common/vlock.S, www.kernel.org. diff --git a/Documentation/arm/vlocks.txt b/Documentation/arm/vlocks.txt deleted file mode 100644 index 45731672c564..000000000000 --- a/Documentation/arm/vlocks.txt +++ /dev/null @@ -1,211 +0,0 @@ -vlocks for Bare-Metal Mutual Exclusion -====================================== - -Voting Locks, or "vlocks" provide a simple low-level mutual exclusion -mechanism, with reasonable but minimal requirements on the memory -system. - -These are intended to be used to coordinate critical activity among CPUs -which are otherwise non-coherent, in situations where the hardware -provides no other mechanism to support this and ordinary spinlocks -cannot be used. - - -vlocks make use of the atomicity provided by the memory system for -writes to a single memory location. To arbitrate, every CPU "votes for -itself", by storing a unique number to a common memory location. The -final value seen in that memory location when all the votes have been -cast identifies the winner. - -In order to make sure that the election produces an unambiguous result -in finite time, a CPU will only enter the election in the first place if -no winner has been chosen and the election does not appear to have -started yet. - - -Algorithm ---------- - -The easiest way to explain the vlocks algorithm is with some pseudo-code: - - - int currently_voting[NR_CPUS] = { 0, }; - int last_vote = -1; /* no votes yet */ - - bool vlock_trylock(int this_cpu) - { - /* signal our desire to vote */ - currently_voting[this_cpu] = 1; - if (last_vote != -1) { - /* someone already volunteered himself */ - currently_voting[this_cpu] = 0; - return false; /* not ourself */ - } - - /* let's suggest ourself */ - last_vote = this_cpu; - currently_voting[this_cpu] = 0; - - /* then wait until everyone else is done voting */ - for_each_cpu(i) { - while (currently_voting[i] != 0) - /* wait */; - } - - /* result */ - if (last_vote == this_cpu) - return true; /* we won */ - return false; - } - - bool vlock_unlock(void) - { - last_vote = -1; - } - - -The currently_voting[] array provides a way for the CPUs to determine -whether an election is in progress, and plays a role analogous to the -"entering" array in Lamport's bakery algorithm [1]. - -However, once the election has started, the underlying memory system -atomicity is used to pick the winner. This avoids the need for a static -priority rule to act as a tie-breaker, or any counters which could -overflow. - -As long as the last_vote variable is globally visible to all CPUs, it -will contain only one value that won't change once every CPU has cleared -its currently_voting flag. - - -Features and limitations ------------------------- - - * vlocks are not intended to be fair. In the contended case, it is the - _last_ CPU which attempts to get the lock which will be most likely - to win. - - vlocks are therefore best suited to situations where it is necessary - to pick a unique winner, but it does not matter which CPU actually - wins. - - * Like other similar mechanisms, vlocks will not scale well to a large - 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: - - /* first level: local election */ - my_town = towns[(this_cpu >> 4) & 0xf]; - I_won = vlock_trylock(my_town, this_cpu & 0xf); - if (I_won) { - /* we won the town election, let's go for the state */ - my_state = states[(this_cpu >> 8) & 0xf]; - I_won = vlock_lock(my_state, this_cpu & 0xf)); - if (I_won) { - /* and so on */ - I_won = vlock_lock(the_whole_country, this_cpu & 0xf]; - if (I_won) { - /* ... */ - } - vlock_unlock(the_whole_country); - } - vlock_unlock(my_state); - } - vlock_unlock(my_town); - - -ARM implementation ------------------- - -The current ARM implementation [2] contains some optimisations beyond -the basic algorithm: - - * By packing the members of the currently_voting array close together, - we can read the whole array in one transaction (providing the number - of CPUs potentially contending the lock is small enough). This - 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: - - LDR Rt, [Rn] - CMP Rt, #0 - - ...in place of code equivalent to: - - LDRB Rt, [Rn] - CMP Rt, #0 - LDRBEQ Rt, [Rn, #1] - CMPEQ Rt, #0 - LDRBEQ Rt, [Rn, #2] - CMPEQ Rt, #0 - LDRBEQ Rt, [Rn, #3] - CMPEQ Rt, #0 - - This cuts down on the fast-path latency, as well as potentially - reducing bus contention in contended cases. - - The optimisation relies on the fact that the ARM memory system - guarantees coherency between overlapping memory accesses of - different sizes, similarly to many other architectures. Note that - we do not care which element of currently_voting appears in which - bits of Rt, so there is no need to worry about endianness in this - optimisation. - - If there are too many CPUs to read the currently_voting array in - one transaction then multiple transations are still required. The - implementation uses a simple loop of word-sized loads for this - case. The number of transactions is still fewer than would be - required if bytes were loaded individually. - - - In principle, we could aggregate further by using LDRD or LDM, but - to keep the code simple this was not attempted in the initial - implementation. - - - * vlocks are currently only used to coordinate between CPUs which are - unable to enable their caches yet. This means that the - implementation removes many of the barriers which would be required - when executing the algorithm in cached memory. - - packing of the currently_voting array does not work with cached - memory unless all CPUs contending the lock are cache-coherent, due - to cache writebacks from one CPU clobbering values written by other - CPUs. (Though if all the CPUs are cache-coherent, you should be - probably be using proper spinlocks instead anyway). - - - * The "no votes yet" value used for the last_vote variable is 0 (not - -1 as in the pseudocode). This allows statically-allocated vlocks - to be implicitly initialised to an unlocked state simply by putting - them in .bss. - - An offset is added to each CPU's ID for the purpose of setting this - variable, so that no CPU uses the value 0 for its ID. - - -Colophon --------- - -Originally created and documented by Dave Martin for Linaro Limited, for -use in ARM-based big.LITTLE platforms, with review and input gratefully -received from Nicolas Pitre and Achin Gupta. Thanks to Nicolas for -grabbing most of this text out of the relevant mail thread and writing -up the pseudocode. - -Copyright (C) 2012-2013 Linaro Limited -Distributed under the terms of Version 2 of the GNU General Public -License, as defined in linux/COPYING. - - -References ----------- - -[1] Lamport, L. "A New Solution of Dijkstra's Concurrent Programming - Problem", Communications of the ACM 17, 8 (August 1974), 453-455. - - https://en.wikipedia.org/wiki/Lamport%27s_bakery_algorithm - -[2] linux/arch/arm/common/vlock.S, www.kernel.org. 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 -- cgit v1.2.3-55-g7522 From 2bbbf827d339032dbeda62f0a5f20d2fde07b0f5 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 15 Apr 2019 18:39:27 -0300 Subject: 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 --- Documentation/memory-devices/ti-emif.rst | 64 ++++++++++++++++++++++++++++++++ Documentation/memory-devices/ti-emif.txt | 57 ---------------------------- 2 files changed, 64 insertions(+), 57 deletions(-) create mode 100644 Documentation/memory-devices/ti-emif.rst delete mode 100644 Documentation/memory-devices/ti-emif.txt diff --git a/Documentation/memory-devices/ti-emif.rst b/Documentation/memory-devices/ti-emif.rst new file mode 100644 index 000000000000..c9242294e63c --- /dev/null +++ b/Documentation/memory-devices/ti-emif.rst @@ -0,0 +1,64 @@ +: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 + +Description +=========== +This driver is for the EMIF module available in Texas Instruments +SoCs. EMIF is an SDRAM controller that, based on its revision, +supports one or more of DDR2, DDR3, and LPDDR2 SDRAM protocols. +This driver takes care of only LPDDR2 memories presently. The +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) +=========================================================== +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 + 'struct emif_custom_configs' +- IP revision +- PHY type + +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 + indicates the current temperature level of the device. diff --git a/Documentation/memory-devices/ti-emif.txt b/Documentation/memory-devices/ti-emif.txt deleted file mode 100644 index f4ad9a7d0f4b..000000000000 --- a/Documentation/memory-devices/ti-emif.txt +++ /dev/null @@ -1,57 +0,0 @@ -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 - -Description -=========== -This driver is for the EMIF module available in Texas Instruments -SoCs. EMIF is an SDRAM controller that, based on its revision, -supports one or more of DDR2, DDR3, and LPDDR2 SDRAM protocols. -This driver takes care of only LPDDR2 memories presently. The -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): -===================================================================== -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 - 'struct emif_custom_configs' -- IP revision -- PHY type - -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 - indicates the current temperature level of the device. -- cgit v1.2.3-55-g7522 From 675aaf05d8982d3d304d4652d1555714be8b4af2 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 15 Apr 2019 18:46:48 -0300 Subject: 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 --- Documentation/security/tpm/xen-tpmfront.rst | 126 ++++++++++++++++++++++++++++ Documentation/security/tpm/xen-tpmfront.txt | 113 ------------------------- 2 files changed, 126 insertions(+), 113 deletions(-) create mode 100644 Documentation/security/tpm/xen-tpmfront.rst delete mode 100644 Documentation/security/tpm/xen-tpmfront.txt diff --git a/Documentation/security/tpm/xen-tpmfront.rst b/Documentation/security/tpm/xen-tpmfront.rst new file mode 100644 index 000000000000..98a16ab87360 --- /dev/null +++ b/Documentation/security/tpm/xen-tpmfront.rst @@ -0,0 +1,126 @@ +:orphan: + +============================= +Virtual TPM interface for Xen +============================= + +Authors: Matthew Fioravante (JHUAPL), Daniel De Graaf (NSA) + +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 +------------ + +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 +a TPM in a virtual system the same way they interact with a TPM on the physical +system. Each guest gets its own unique, emulated, software TPM. However, each +of the vTPM's secrets (Keys, NVRAM, etc) are managed by a vTPM Manager domain, +which seals the secrets to the Physical TPM. If the process of creating each of +these domains (manager, vTPM, and guest) is trusted, the vTPM subsystem extends +the chain of trust rooted in the hardware TPM to virtual machines in Xen. Each +major component of vTPM is implemented as a separate domain, providing secure +separation guaranteed by the hypervisor. The vTPM domains are implemented in +mini-os to reduce memory and processor overhead. + +This mini-os vTPM subsystem was built on top of the previous vTPM work done by +IBM and Intel corporation. + + +Design Overview +--------------- + +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: + 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 + provides vTPM access to a Linux-based DomU. + +* 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 + 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 + 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 + 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) + 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. + + +Integration With Xen +-------------------- + +Support for the vTPM driver was added in Xen using the libxl toolstack in Xen +4.3. See the Xen documentation (docs/misc/vtpm.txt) for details on setting up +the vTPM and vTPM Manager stub domains. Once the stub domains are running, a +vTPM device is set up in the same manner as a disk or network device in the +domain's configuration file. + +In order to use features such as IMA that require a TPM to be loaded prior to +the initrd, the xen-tpmfront driver must be compiled in to the kernel. If not +using such features, the driver can be compiled as a module and will be loaded +as usual. diff --git a/Documentation/security/tpm/xen-tpmfront.txt b/Documentation/security/tpm/xen-tpmfront.txt deleted file mode 100644 index 69346de87ff3..000000000000 --- a/Documentation/security/tpm/xen-tpmfront.txt +++ /dev/null @@ -1,113 +0,0 @@ -Virtual TPM interface for Xen - -Authors: Matthew Fioravante (JHUAPL), Daniel De Graaf (NSA) - -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 - -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 -a TPM in a virtual system the same way they interact with a TPM on the physical -system. Each guest gets its own unique, emulated, software TPM. However, each -of the vTPM's secrets (Keys, NVRAM, etc) are managed by a vTPM Manager domain, -which seals the secrets to the Physical TPM. If the process of creating each of -these domains (manager, vTPM, and guest) is trusted, the vTPM subsystem extends -the chain of trust rooted in the hardware TPM to virtual machines in Xen. Each -major component of vTPM is implemented as a separate domain, providing secure -separation guaranteed by the hypervisor. The vTPM domains are implemented in -mini-os to reduce memory and processor overhead. - -This mini-os vTPM subsystem was built on top of the previous vTPM work done by -IBM and Intel corporation. - - -DESIGN OVERVIEW ---------------- - -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: 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 - provides vTPM access to a Linux-based DomU. - - * 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 - 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 - 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 - 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) - 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. - - -INTEGRATION WITH XEN --------------------- - -Support for the vTPM driver was added in Xen using the libxl toolstack in Xen -4.3. See the Xen documentation (docs/misc/vtpm.txt) for details on setting up -the vTPM and vTPM Manager stub domains. Once the stub domains are running, a -vTPM device is set up in the same manner as a disk or network device in the -domain's configuration file. - -In order to use features such as IMA that require a TPM to be loaded prior to -the initrd, the xen-tpmfront driver must be compiled in to the kernel. If not -using such features, the driver can be compiled as a module and will be loaded -as usual. -- cgit v1.2.3-55-g7522 From 619ba4516771bdfb96658e7a5f57e6551232549a Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 19 Apr 2019 18:49:49 -0300 Subject: 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 --- Documentation/bus-devices/ti-gpmc.rst | 179 ++++++++++++++++++++++++++++++++++ Documentation/bus-devices/ti-gpmc.txt | 122 ----------------------- 2 files changed, 179 insertions(+), 122 deletions(-) create mode 100644 Documentation/bus-devices/ti-gpmc.rst delete mode 100644 Documentation/bus-devices/ti-gpmc.txt diff --git a/Documentation/bus-devices/ti-gpmc.rst b/Documentation/bus-devices/ti-gpmc.rst new file mode 100644 index 000000000000..87c366e418be --- /dev/null +++ b/Documentation/bus-devices/ti-gpmc.rst @@ -0,0 +1,179 @@ +: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 + NAND flash + * Pseudo-SRAM devices + +GPMC is found on Texas Instruments SoC's (OMAP based) +IP details: http://www.ti.com/lit/pdf/spruh73 section 7.1 + + +GPMC generic timing calculation: +================================ + +GPMC has certain timings that has to be programmed for proper +functioning of the peripheral, while peripheral has another set of +timings. To have peripheral work with gpmc, peripheral timings has to +be translated to the form gpmc can understand. The way it has to be +translated depends on the connected peripheral. Also there is a +dependency for certain gpmc timings on gpmc clock frequency. Hence a +generic timing routine was developed to achieve above requirements. + +Generic routine provides a generic method to calculate gpmc timings +from gpmc peripheral timings. struct gpmc_device_timings fields has to +be updated with timings from the datasheet of the peripheral that is +connected to gpmc. A few of the peripheral timings can be fed either +in time or in cycles, provision to handle this scenario has been +provided (refer struct gpmc_device_timings definition). It may so +happen that timing as specified by peripheral datasheet is not present +in timing structure, in this scenario, try to correlate peripheral +timing to the one available. If that doesn't work, try to add a new +field as required by peripheral, educate generic timing routine to +handle it, make sure that it does not break any of the existing. +Then there may be cases where peripheral datasheet doesn't mention +certain fields of struct gpmc_device_timings, zero those entries. + +Generic timing routine has been verified to work properly on +multiple onenand's and tusb6010 peripherals. + +A word of caution: generic timing routine has been developed based +on understanding of gpmc timings, peripheral timings, available +custom timing routines, a kind of reverse engineering without +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 + +2. sync common + +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 + +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 + +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 + +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 + +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 + +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 + +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 + +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 + + +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). diff --git a/Documentation/bus-devices/ti-gpmc.txt b/Documentation/bus-devices/ti-gpmc.txt deleted file mode 100644 index cc9ce57e0a26..000000000000 --- a/Documentation/bus-devices/ti-gpmc.txt +++ /dev/null @@ -1,122 +0,0 @@ -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 - NAND flash - * Pseudo-SRAM devices - -GPMC is found on Texas Instruments SoC's (OMAP based) -IP details: http://www.ti.com/lit/pdf/spruh73 section 7.1 - - -GPMC generic timing calculation: -================================ - -GPMC has certain timings that has to be programmed for proper -functioning of the peripheral, while peripheral has another set of -timings. To have peripheral work with gpmc, peripheral timings has to -be translated to the form gpmc can understand. The way it has to be -translated depends on the connected peripheral. Also there is a -dependency for certain gpmc timings on gpmc clock frequency. Hence a -generic timing routine was developed to achieve above requirements. - -Generic routine provides a generic method to calculate gpmc timings -from gpmc peripheral timings. struct gpmc_device_timings fields has to -be updated with timings from the datasheet of the peripheral that is -connected to gpmc. A few of the peripheral timings can be fed either -in time or in cycles, provision to handle this scenario has been -provided (refer struct gpmc_device_timings definition). It may so -happen that timing as specified by peripheral datasheet is not present -in timing structure, in this scenario, try to correlate peripheral -timing to the one available. If that doesn't work, try to add a new -field as required by peripheral, educate generic timing routine to -handle it, make sure that it does not break any of the existing. -Then there may be cases where peripheral datasheet doesn't mention -certain fields of struct gpmc_device_timings, zero those entries. - -Generic timing routine has been verified to work properly on -multiple onenand's and tusb6010 peripherals. - -A word of caution: generic timing routine has been developed based -on understanding of gpmc timings, peripheral timings, available -custom timing routines, a kind of reverse engineering without -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 - -2. sync common -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 - -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 - -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 - -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 - -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 - -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 - -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 - -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 - - -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). -- cgit v1.2.3-55-g7522 From a278295ccc2ddd1dc0ac8423a12ff6dd74f0d502 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 15 Apr 2019 19:25:27 -0300 Subject: 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.rst | 189 ++++++++++++++++++++++++++++++++++++++++++ Documentation/nvmem/nvmem.txt | 183 ---------------------------------------- 2 files changed, 189 insertions(+), 183 deletions(-) create mode 100644 Documentation/nvmem/nvmem.rst delete mode 100644 Documentation/nvmem/nvmem.txt diff --git a/Documentation/nvmem/nvmem.rst b/Documentation/nvmem/nvmem.rst new file mode 100644 index 000000000000..3866b6e066d5 --- /dev/null +++ b/Documentation/nvmem/nvmem.rst @@ -0,0 +1,189 @@ +:orphan: + +=============== +NVMEM Subsystem +=============== + + Srinivas Kandagatla + +This document explains the NVMEM Framework along with the APIs provided, +and how to use it. + +1. Introduction +=============== +*NVMEM* is the abbreviation for Non Volatile Memory layer. It is used to +retrieve configuration of SOC or Device specific data from non volatile +memories like eeprom, efuses and so on. + +Before this framework existed, NVMEM drivers like eeprom were stored in +drivers/misc, where they all had to duplicate pretty much the same code to +register a sysfs file, allow in-kernel users to access the content of the +devices they were driving, etc. + +This was also a problem as far as other in-kernel users were involved, since +the solutions used were pretty much different from one driver to another, there +was a rather big abstraction leak. + +This framework aims at solve these problems. It also introduces DT +representation for consumer devices to go get the data they require (MAC +Addresses, SoC/Revision ID, part numbers, and so on) from the NVMEMs. This +framework is based on regmap, so that most of the abstraction available in +regmap can be reused, across multiple types of buses. + +NVMEM Providers ++++++++++++++++ + +NVMEM provider refers to an entity that implements methods to initialize, read +and write the non-volatile memory. + +2. Registering/Unregistering the NVMEM provider +=============================================== + +A NVMEM provider can register with NVMEM core by supplying relevant +nvmem configuration to nvmem_register(), on success core would return a valid +nvmem_device pointer. + +nvmem_unregister(nvmem) is used to unregister a previously registered provider. + +For example, a simple qfprom case:: + + static struct nvmem_config econfig = { + .name = "qfprom", + .owner = THIS_MODULE, + }; + + 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:: + + static struct nvmem_cell_info foo_nvmem_cells[] = { + { + .name = "macaddr", + .offset = 0x7f00, + .bytes = ETH_ALEN, + } + }; + + 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); + +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:: + + 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 Consumers ++++++++++++++++ + +NVMEM consumers are the entities which make use of the NVMEM provider to +read from and to NVMEM. + +3. NVMEM cell based consumer APIs +================================= + +NVMEM cells are the data entries/fields in the NVMEM. +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); + + 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); + +`*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. + +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:: + + 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, + size_t bytes, void *buf); + 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, + struct nvmem_cell_info *info, void *buf); + 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. + +The difference between these apis and cell based apis is that these apis always +take nvmem_device as parameter. + +5. Releasing a reference to the NVMEM +===================================== + +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:: + + 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 +with this NVMEM. + +Userspace ++++++++++ + +6. Userspace binary interface +============================== + +Userspace can read/write the raw NVMEM file located at:: + + /sys/bus/nvmem/devices/*/nvmem + +ex:: + + 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 +===================== + +See Documentation/devicetree/bindings/nvmem/nvmem.txt diff --git a/Documentation/nvmem/nvmem.txt b/Documentation/nvmem/nvmem.txt deleted file mode 100644 index fc2fe4b18655..000000000000 --- a/Documentation/nvmem/nvmem.txt +++ /dev/null @@ -1,183 +0,0 @@ - NVMEM SUBSYSTEM - Srinivas Kandagatla - -This document explains the NVMEM Framework along with the APIs provided, -and how to use it. - -1. Introduction -=============== -*NVMEM* is the abbreviation for Non Volatile Memory layer. It is used to -retrieve configuration of SOC or Device specific data from non volatile -memories like eeprom, efuses and so on. - -Before this framework existed, NVMEM drivers like eeprom were stored in -drivers/misc, where they all had to duplicate pretty much the same code to -register a sysfs file, allow in-kernel users to access the content of the -devices they were driving, etc. - -This was also a problem as far as other in-kernel users were involved, since -the solutions used were pretty much different from one driver to another, there -was a rather big abstraction leak. - -This framework aims at solve these problems. It also introduces DT -representation for consumer devices to go get the data they require (MAC -Addresses, SoC/Revision ID, part numbers, and so on) from the NVMEMs. This -framework is based on regmap, so that most of the abstraction available in -regmap can be reused, across multiple types of buses. - -NVMEM Providers -+++++++++++++++ - -NVMEM provider refers to an entity that implements methods to initialize, read -and write the non-volatile memory. - -2. Registering/Unregistering the NVMEM provider -=============================================== - -A NVMEM provider can register with NVMEM core by supplying relevant -nvmem configuration to nvmem_register(), on success core would return a valid -nvmem_device pointer. - -nvmem_unregister(nvmem) is used to unregister a previously registered provider. - -For example, a simple qfprom case: - -static struct nvmem_config econfig = { - .name = "qfprom", - .owner = THIS_MODULE, -}; - -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: - -static struct nvmem_cell_info foo_nvmem_cells[] = { - { - .name = "macaddr", - .offset = 0x7f00, - .bytes = ETH_ALEN, - } -}; - -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); - -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: - -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 Consumers -+++++++++++++++ - -NVMEM consumers are the entities which make use of the NVMEM provider to -read from and to NVMEM. - -3. NVMEM cell based consumer APIs -================================= - -NVMEM cells are the data entries/fields in the NVMEM. -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); - -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); - -*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. - -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. - -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, - size_t bytes, void *buf); -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, - struct nvmem_cell_info *info, void *buf); -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. - -The difference between these apis and cell based apis is that these apis always -take nvmem_device as parameter. - -5. Releasing a reference to the NVMEM -===================================== - -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. - -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 -with this NVMEM. - -Userspace -+++++++++ - -6. Userspace binary interface -============================== - -Userspace can read/write the raw NVMEM file located at -/sys/bus/nvmem/devices/*/nvmem - -ex: - -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 -===================== - -See Documentation/devicetree/bindings/nvmem/nvmem.txt -- cgit v1.2.3-55-g7522 From 1945a035540e2cef0362a2e7e828f8cf547e86b8 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 15 Apr 2019 19:27:55 -0300 Subject: 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 --- Documentation/phy/samsung-usb2.rst | 139 +++++++++++++++++++++++++++++++++++++ Documentation/phy/samsung-usb2.txt | 135 ----------------------------------- MAINTAINERS | 2 +- 3 files changed, 140 insertions(+), 136 deletions(-) create mode 100644 Documentation/phy/samsung-usb2.rst delete mode 100644 Documentation/phy/samsung-usb2.txt diff --git a/Documentation/phy/samsung-usb2.rst b/Documentation/phy/samsung-usb2.rst new file mode 100644 index 000000000000..98b5952fcb97 --- /dev/null +++ b/Documentation/phy/samsung-usb2.rst @@ -0,0 +1,139 @@ +:orphan: + +==================================== +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 +create a one driver that would fit all these PHY controllers. Often +the differences were minor and were found in particular bits of the +registers of the PHY. In some rare cases the order of register writes or +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 +-------------------- + +- phy-samsung-usb2.c + This is the main file of the adaptation layer. This file contains + the probe function and provides two callbacks to the Generic PHY + Framework. This two callbacks are used to power on and power off the + phy. They carry out the common work that has to be done on all version + of the PHY module. Depending on which SoC was chosen they execute SoC + specific callbacks. The specific SoC version is selected by choosing + the appropriate compatible string. In addition, this file contains + struct of_device_id definitions for particular SoCs. + +- phy-samsung-usb2.h + This is the include file. It declares the structures used by this + driver. In addition it should contain extern declarations for + structures that describe particular 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 { + 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 +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:: + + 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 *)` + + 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:: + + static const struct samsung_usb2_common_phy exynos4210_phys[] = { + { + .label = "device", + .id = EXYNOS4210_DEVICE, + .power_on = exynos4210_power_on, + .power_off = exynos4210_power_off, + }, + { + .label = "host", + .id = EXYNOS4210_HOST, + .power_on = exynos4210_power_on, + .power_off = exynos4210_power_off, + }, + { + .label = "hsic0", + .id = EXYNOS4210_HSIC0, + .power_on = exynos4210_power_on, + .power_off = exynos4210_power_off, + }, + { + .label = "hsic1", + .id = EXYNOS4210_HSIC1, + .power_on = exynos4210_power_on, + .power_off = exynos4210_power_off, + }, + {}, + }; + +- `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:: + + #ifdef CONFIG_PHY_EXYNOS4210_USB2 + { + .compatible = "samsung,exynos4210-usb2-phy", + .data = &exynos4210_usb2_phy_config, + }, + #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:: + + config PHY_EXYNOS4210_USB2 + bool "Support for Exynos 4210" + depends on PHY_SAMSUNG_USB2 + depends on CPU_EXYNOS4210 + help + Enable USB PHY support for Exynos 4210. This option requires that + Samsung USB 2.0 PHY driver is enabled and means that support for this + particular SoC is compiled in the driver. In case of Exynos 4210 four + 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:: + + 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/Documentation/phy/samsung-usb2.txt b/Documentation/phy/samsung-usb2.txt deleted file mode 100644 index ed12d437189d..000000000000 --- a/Documentation/phy/samsung-usb2.txt +++ /dev/null @@ -1,135 +0,0 @@ -.------------------------------------------------------------------------------+ -| 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 -create a one driver that would fit all these PHY controllers. Often -the differences were minor and were found in particular bits of the -registers of the PHY. In some rare cases the order of register writes or -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 -+---------------------- - -- phy-samsung-usb2.c - This is the main file of the adaptation layer. This file contains - the probe function and provides two callbacks to the Generic PHY - Framework. This two callbacks are used to power on and power off the - phy. They carry out the common work that has to be done on all version - of the PHY module. Depending on which SoC was chosen they execute SoC - specific callbacks. The specific SoC version is selected by choosing - the appropriate compatible string. In addition, this file contains - struct of_device_id definitions for particular SoCs. - -- phy-samsung-usb2.h - This is the include file. It declares the structures used by this - driver. In addition it should contain extern declarations for - structures that describe particular 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 { - 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 -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: - -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 *) - 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: - -static const struct samsung_usb2_common_phy exynos4210_phys[] = { - { - .label = "device", - .id = EXYNOS4210_DEVICE, - .power_on = exynos4210_power_on, - .power_off = exynos4210_power_off, - }, - { - .label = "host", - .id = EXYNOS4210_HOST, - .power_on = exynos4210_power_on, - .power_off = exynos4210_power_off, - }, - { - .label = "hsic0", - .id = EXYNOS4210_HSIC0, - .power_on = exynos4210_power_on, - .power_off = exynos4210_power_off, - }, - { - .label = "hsic1", - .id = EXYNOS4210_HSIC1, - .power_on = exynos4210_power_on, - .power_off = exynos4210_power_off, - }, - {}, -}; - -- 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: - -#ifdef CONFIG_PHY_EXYNOS4210_USB2 - { - .compatible = "samsung,exynos4210-usb2-phy", - .data = &exynos4210_usb2_phy_config, - }, -#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: - -config PHY_EXYNOS4210_USB2 - bool "Support for Exynos 4210" - depends on PHY_SAMSUNG_USB2 - depends on CPU_EXYNOS4210 - help - Enable USB PHY support for Exynos 4210. This option requires that - Samsung USB 2.0 PHY driver is enabled and means that support for this - particular SoC is compiled in the driver. In case of Exynos 4210 four - 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: - -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 -- cgit v1.2.3-55-g7522 From eaf5211d8c00060a3b41a031a762c906d3603098 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 15 Apr 2019 23:00:35 -0300 Subject: 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 *); -- cgit v1.2.3-55-g7522 From a36d053863a1b6cd6e79a632af01be014517f9ac Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 27 May 2019 15:59:13 -0300 Subject: 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"); -- cgit v1.2.3-55-g7522 From c3123552aad3ffd7a35e16d4402231225165e343 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 17 Apr 2019 05:46:08 -0300 Subject: 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 --- Documentation/accounting/cgroupstats.rst | 31 ++++ Documentation/accounting/cgroupstats.txt | 27 ---- Documentation/accounting/delay-accounting.rst | 126 ++++++++++++++++ Documentation/accounting/delay-accounting.txt | 117 --------------- Documentation/accounting/index.rst | 14 ++ Documentation/accounting/psi.rst | 182 +++++++++++++++++++++++ Documentation/accounting/psi.txt | 180 ----------------------- Documentation/accounting/taskstats-struct.rst | 199 ++++++++++++++++++++++++++ Documentation/accounting/taskstats-struct.txt | 180 ----------------------- Documentation/accounting/taskstats.rst | 180 +++++++++++++++++++++++ Documentation/accounting/taskstats.txt | 181 ----------------------- Documentation/admin-guide/cgroup-v2.rst | 6 +- init/Kconfig | 2 +- 13 files changed, 736 insertions(+), 689 deletions(-) create mode 100644 Documentation/accounting/cgroupstats.rst delete mode 100644 Documentation/accounting/cgroupstats.txt create mode 100644 Documentation/accounting/delay-accounting.rst delete mode 100644 Documentation/accounting/delay-accounting.txt create mode 100644 Documentation/accounting/index.rst create mode 100644 Documentation/accounting/psi.rst delete mode 100644 Documentation/accounting/psi.txt create mode 100644 Documentation/accounting/taskstats-struct.rst delete mode 100644 Documentation/accounting/taskstats-struct.txt create mode 100644 Documentation/accounting/taskstats.rst delete mode 100644 Documentation/accounting/taskstats.txt diff --git a/Documentation/accounting/cgroupstats.rst b/Documentation/accounting/cgroupstats.rst new file mode 100644 index 000000000000..b9afc48f4ea2 --- /dev/null +++ b/Documentation/accounting/cgroupstats.rst @@ -0,0 +1,31 @@ +================== +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. + +Per cgroup statistics infrastructure re-uses code from the taskstats +interface. A new set of cgroup operations are registered with commands +and attributes specific to cgroups. It should be very easy to +extend per cgroup statistics, by adding members to the cgroupstats +structure. + +The current model for cgroupstats is a pull, a push model (to post +statistics on interesting events), should be very easy to add. Currently +user space requests for statistics by passing the cgroup path. +Statistics about the state of all the tasks in the cgroup is returned to +user space. + +NOTE: We currently rely on delay accounting for extracting information +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:: + + ~/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/cgroupstats.txt b/Documentation/accounting/cgroupstats.txt deleted file mode 100644 index d16a9849e60e..000000000000 --- a/Documentation/accounting/cgroupstats.txt +++ /dev/null @@ -1,27 +0,0 @@ -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. - -Per cgroup statistics infrastructure re-uses code from the taskstats -interface. A new set of cgroup operations are registered with commands -and attributes specific to cgroups. It should be very easy to -extend per cgroup statistics, by adding members to the cgroupstats -structure. - -The current model for cgroupstats is a pull, a push model (to post -statistics on interesting events), should be very easy to add. Currently -user space requests for statistics by passing the cgroup path. -Statistics about the state of all the tasks in the cgroup is returned to -user space. - -NOTE: We currently rely on delay accounting for extracting information -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 - -~/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.rst b/Documentation/accounting/delay-accounting.rst new file mode 100644 index 000000000000..7cc7f5852da0 --- /dev/null +++ b/Documentation/accounting/delay-accounting.rst @@ -0,0 +1,126 @@ +================ +Delay accounting +================ + +Tasks encounter delays in execution when they wait +for some kernel resource to become available e.g. a +runnable task may wait for a free CPU to run on. + +The per-task delay accounting functionality measures +the delays experienced by a task while + +a) waiting for a CPU (while being runnable) +b) completion of synchronous block I/O initiated by the task +c) swapping in pages +d) memory reclaim + +and makes these statistics available to userspace through +the taskstats interface. + +Such delays provide feedback for setting a task's cpu priority, +io priority and rss limit values appropriately. Long delays for +important tasks could be a trigger for raising its corresponding priority. + +The functionality, through its use of the taskstats interface, also provides +delay statistics aggregated for all tasks (or threads) belonging to a +thread group (corresponding to a traditional Unix process). This is a commonly +needed aggregation that is more efficiently done by the kernel. + +Userspace utilities, particularly resource management applications, can also +aggregate delay statistics into arbitrary groups. To enable this, delay +statistics of a task are available both during its lifetime as well as on its +exit, ensuring continuous and complete monitoring can be done. + + +Interface +--------- + +Delay accounting uses the taskstats interface which is described +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. + +Taking the difference of two successive readings of a given +counter (say cpu_delay_total) for a task will give the delay +experienced by the task waiting for the corresponding resource +in that interval. + +When a task exits, records containing the per-task statistics +are sent to userspace without requiring a command. If it is the last exiting +task of a thread group, the per-tgid statistics are also sent. More details +are given in the taskstats interface description. + +The getdelays.c userspace utility in tools/accounting directory allows simple +commands to be run and the corresponding delay statistics to be displayed. It +also serves as an example of using the taskstats interface. + +Usage +----- + +Compile the kernel with:: + + CONFIG_TASK_DELAY_ACCT=y + CONFIG_TASKSTATS=y + +Delay accounting is enabled by default at boot up. +To disable, add:: + + nodelayacct + +to the kernel boot options. The rest of the instructions +below assume this has not been done. + +After the system has booted up, use a utility +similar to getdelays.c to access the delays +seen by a given task or a task group (tgid). +The utility also allows a given command to be +executed and the corresponding delays to be +seen. + +General format of the getdelays command:: + + getdelays [-t tgid] [-p pid] [-c cmd...] + + +Get delays, since system boot, for pid 10:: + + # ./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 + +Get delays seen in executing a given simple command:: + + # ./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 + 6 4000250 4000000 0 + IO count delay total + 0 0 + SWAP count delay total + 0 0 + RECLAIM count delay total + 0 0 diff --git a/Documentation/accounting/delay-accounting.txt b/Documentation/accounting/delay-accounting.txt deleted file mode 100644 index 042ea59b5853..000000000000 --- a/Documentation/accounting/delay-accounting.txt +++ /dev/null @@ -1,117 +0,0 @@ -Delay accounting ----------------- - -Tasks encounter delays in execution when they wait -for some kernel resource to become available e.g. a -runnable task may wait for a free CPU to run on. - -The per-task delay accounting functionality measures -the delays experienced by a task while - -a) waiting for a CPU (while being runnable) -b) completion of synchronous block I/O initiated by the task -c) swapping in pages -d) memory reclaim - -and makes these statistics available to userspace through -the taskstats interface. - -Such delays provide feedback for setting a task's cpu priority, -io priority and rss limit values appropriately. Long delays for -important tasks could be a trigger for raising its corresponding priority. - -The functionality, through its use of the taskstats interface, also provides -delay statistics aggregated for all tasks (or threads) belonging to a -thread group (corresponding to a traditional Unix process). This is a commonly -needed aggregation that is more efficiently done by the kernel. - -Userspace utilities, particularly resource management applications, can also -aggregate delay statistics into arbitrary groups. To enable this, delay -statistics of a task are available both during its lifetime as well as on its -exit, ensuring continuous and complete monitoring can be done. - - -Interface ---------- - -Delay accounting uses the taskstats interface which is described -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. - -Taking the difference of two successive readings of a given -counter (say cpu_delay_total) for a task will give the delay -experienced by the task waiting for the corresponding resource -in that interval. - -When a task exits, records containing the per-task statistics -are sent to userspace without requiring a command. If it is the last exiting -task of a thread group, the per-tgid statistics are also sent. More details -are given in the taskstats interface description. - -The getdelays.c userspace utility in tools/accounting directory allows simple -commands to be run and the corresponding delay statistics to be displayed. It -also serves as an example of using the taskstats interface. - -Usage ------ - -Compile the kernel with - CONFIG_TASK_DELAY_ACCT=y - CONFIG_TASKSTATS=y - -Delay accounting is enabled by default at boot up. -To disable, add - nodelayacct -to the kernel boot options. The rest of the instructions -below assume this has not been done. - -After the system has booted up, use a utility -similar to getdelays.c to access the delays -seen by a given task or a task group (tgid). -The utility also allows a given command to be -executed and the corresponding delays to be -seen. - -General format of the getdelays command - -getdelays [-t tgid] [-p pid] [-c cmd...] - - -Get delays, since system boot, for pid 10 -# ./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 - -Get delays seen in executing a given simple command -# ./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 - 6 4000250 4000000 0 -IO count delay total - 0 0 -SWAP count delay total - 0 0 -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.rst b/Documentation/accounting/psi.rst new file mode 100644 index 000000000000..621111ce5740 --- /dev/null +++ b/Documentation/accounting/psi.rst @@ -0,0 +1,182 @@ +================================ +PSI - Pressure Stall Information +================================ + +:Date: April, 2018 +:Author: Johannes Weiner + +When CPU, memory or IO devices are contended, workloads experience +latency spikes, throughput losses, and run the risk of OOM kills. + +Without an accurate measure of such contention, users are forced to +either play it safe and under-utilize their hardware resources, or +roll the dice and frequently suffer the disruptions resulting from +excessive overcommit. + +The psi feature identifies and quantifies the disruptions caused by +such resource crunches and the time impact it has on complex workloads +or even entire systems. + +Having an accurate measure of productivity losses caused by resource +scarcity aids users in sizing workloads to hardware--or provisioning +hardware according to workload demand. + +As psi aggregates this information in realtime, systems can be managed +dynamically using techniques such as load shedding, migrating jobs to +other systems or data centers, or strategically pausing or killing low +priority or restartable batch jobs. + +This allows maximizing hardware utilization without sacrificing +workload health or risking major disruptions such as OOM kills. + +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:: + + some avg10=0.00 avg60=0.00 avg300=0.00 total=0 + +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 + +The "some" line indicates the share of time in which at least some +tasks are stalled on a given resource. + +The "full" line indicates the share of time in which all non-idle +tasks are stalled on a given resource simultaneously. In this state +actual CPU cycles are going to waste, and a workload that spends +extended time in this state is considered to be thrashing. This has +severe impact on performance, and it's useful to distinguish this +situation from a state where some tasks are stalled but the CPU is +still doing productive work. As such, time spent in this subset of the +stall state is tracked separately and exported in the "full" averages. + +The ratios (in %) are tracked as recent trends over ten, sixty, and +three hundred second windows, which gives insight into short term events +as well as medium and long term trends. The total absolute stall time +(in us) is tracked and exported as well, to allow detection of latency +spikes which wouldn't necessarily make a dent in the time averages, +or to average trends over custom time frames. + +Monitoring for pressure thresholds +================================== + +Users can register triggers and use poll() to be woken up when resource +pressure exceeds certain thresholds. + +A trigger describes the maximum cumulative stall time over a specific +time window, e.g. 100ms of total stall time within any 500ms window to +generate a wakeup event. + +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:: + +