diff options
Diffstat (limited to 'Documentation/locking')
-rw-r--r-- | Documentation/locking/hwspinlock.rst | 68 | ||||
-rw-r--r-- | Documentation/locking/index.rst | 2 | ||||
-rw-r--r-- | Documentation/locking/lockdep-design.rst | 4 | ||||
-rw-r--r-- | Documentation/locking/locktorture.rst | 6 | ||||
-rw-r--r-- | Documentation/locking/locktypes.rst | 2 | ||||
-rw-r--r-- | Documentation/locking/mutex-design.rst | 18 | ||||
-rw-r--r-- | Documentation/locking/percpu-rw-semaphore.rst | 4 | ||||
-rw-r--r-- | Documentation/locking/seqlock.rst | 4 |
8 files changed, 41 insertions, 67 deletions
diff --git a/Documentation/locking/hwspinlock.rst b/Documentation/locking/hwspinlock.rst index 6f03713b7003..a737c702a7d1 100644 --- a/Documentation/locking/hwspinlock.rst +++ b/Documentation/locking/hwspinlock.rst @@ -40,17 +40,6 @@ User API :: - struct hwspinlock *hwspin_lock_request(void); - -Dynamically assign an hwspinlock and return its address, or NULL -in case an unused hwspinlock isn't available. Users of this -API will usually want to communicate the lock's id to the remote core -before it can be used to achieve synchronization. - -Should be called from a process context (might sleep). - -:: - struct hwspinlock *hwspin_lock_request_specific(unsigned int id); Assign a specific hwspinlock id and return its address, or NULL @@ -87,6 +76,17 @@ Should be called from a process context (might sleep). :: + int hwspin_lock_bust(struct hwspinlock *hwlock, unsigned int id); + +After verifying the owner of the hwspinlock, release a previously acquired +hwspinlock; returns 0 on success, or an appropriate error code on failure +(e.g. -EOPNOTSUPP if the bust operation is not defined for the specific +hwspinlock). + +Should be called from a process context (might sleep). + +:: + int hwspin_lock_timeout(struct hwspinlock *hwlock, unsigned int timeout); Lock a previously-assigned hwspinlock with a timeout limit (specified in @@ -301,17 +301,6 @@ The caller should **never** unlock an hwspinlock which is already unlocked. Doing so is considered a bug (there is no protection against this). This function will never sleep. -:: - - int hwspin_lock_get_id(struct hwspinlock *hwlock); - -Retrieve id number of a given hwspinlock. This is needed when an -hwspinlock is dynamically assigned: before it can be used to achieve -mutual exclusion with a remote cpu, the id number should be communicated -to the remote task with which we want to synchronize. - -Returns the hwspinlock id number, or -EINVAL if hwlock is null. - Typical usage ============= @@ -320,40 +309,7 @@ Typical usage #include <linux/hwspinlock.h> #include <linux/err.h> - int hwspinlock_example1(void) - { - struct hwspinlock *hwlock; - int ret; - - /* dynamically assign a hwspinlock */ - hwlock = hwspin_lock_request(); - if (!hwlock) - ... - - id = hwspin_lock_get_id(hwlock); - /* probably need to communicate id to a remote processor now */ - - /* take the lock, spin for 1 sec if it's already taken */ - ret = hwspin_lock_timeout(hwlock, 1000); - if (ret) - ... - - /* - * we took the lock, do our thing now, but do NOT sleep - */ - - /* release the lock */ - hwspin_unlock(hwlock); - - /* free the lock */ - ret = hwspin_lock_free(hwlock); - if (ret) - ... - - return ret; - } - - int hwspinlock_example2(void) + int hwspinlock_example(void) { struct hwspinlock *hwlock; int ret; diff --git a/Documentation/locking/index.rst b/Documentation/locking/index.rst index 7003bd5aeff4..6a9ea96c8bcb 100644 --- a/Documentation/locking/index.rst +++ b/Documentation/locking/index.rst @@ -1,7 +1,7 @@ .. SPDX-License-Identifier: GPL-2.0 ======= -locking +Locking ======= .. toctree:: diff --git a/Documentation/locking/lockdep-design.rst b/Documentation/locking/lockdep-design.rst index 82f36cab61bd..56b90eea2731 100644 --- a/Documentation/locking/lockdep-design.rst +++ b/Documentation/locking/lockdep-design.rst @@ -29,7 +29,7 @@ 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 +class and hence their usages and dependencies 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 @@ -105,7 +105,7 @@ exact case is for the lock as of the reporting time. +--------------+-------------+--------------+ The character '-' suggests irq is disabled because if otherwise the -charactor '?' would have been shown instead. Similar deduction can be +character '?' 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. diff --git a/Documentation/locking/locktorture.rst b/Documentation/locking/locktorture.rst index dfaf9fc883f4..3e763f77a620 100644 --- a/Documentation/locking/locktorture.rst +++ b/Documentation/locking/locktorture.rst @@ -5,7 +5,7 @@ Kernel Lock Torture Test Operation CONFIG_LOCK_TORTURE_TEST ======================== -The CONFIG LOCK_TORTURE_TEST config option provides a kernel module +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 @@ -67,7 +67,7 @@ torture_type - "rtmutex_lock": rtmutex_lock() and rtmutex_unlock() pairs. - Kernel must have CONFIG_RT_MUTEX=y. + Kernel must have CONFIG_RT_MUTEXES=y. - "rwsem_lock": read/write down() and up() semaphore pairs. @@ -113,7 +113,7 @@ stutter without pausing. shuffle_interval - The number of seconds to keep the test threads affinitied + The number of seconds to keep the test threads affinitized to a particular subset of the CPUs, defaults to 3 seconds. Used in conjunction with test_no_idle_hz. diff --git a/Documentation/locking/locktypes.rst b/Documentation/locking/locktypes.rst index 9933faad4771..80c914f6eae7 100644 --- a/Documentation/locking/locktypes.rst +++ b/Documentation/locking/locktypes.rst @@ -500,7 +500,7 @@ caveats also apply to bit spinlocks. Some bit spinlocks are replaced with regular spinlock_t for PREEMPT_RT using conditional (#ifdef'ed) code changes at the usage site. In contrast, usage-site changes are not needed for the spinlock_t substitution. -Instead, conditionals in header files and the core locking implemementation +Instead, conditionals in header files and the core locking implementation enable the compiler to do the substitution transparently. diff --git a/Documentation/locking/mutex-design.rst b/Documentation/locking/mutex-design.rst index 78540cd7f54b..7c30b4aa5e28 100644 --- a/Documentation/locking/mutex-design.rst +++ b/Documentation/locking/mutex-design.rst @@ -101,6 +101,24 @@ features that make lock debugging easier and faster: - Detects multi-task circular deadlocks and prints out all affected locks and tasks (and only those tasks). +Mutexes - and most other sleeping locks like rwsems - do not provide an +implicit reference for the memory they occupy, which reference is released +with mutex_unlock(). + +[ This is in contrast with spin_unlock() [or completion_done()], which + APIs can be used to guarantee that the memory is not touched by the + lock implementation after spin_unlock()/completion_done() releases + the lock. ] + +mutex_unlock() may access the mutex structure even after it has internally +released the lock already - so it's not safe for another context to +acquire the mutex and assume that the mutex_unlock() context is not using +the structure anymore. + +The mutex user must ensure that the mutex is not destroyed while a +release operation is still in progress - in other words, callers of +mutex_unlock() must ensure that the mutex stays alive until mutex_unlock() +has returned. Interfaces ---------- diff --git a/Documentation/locking/percpu-rw-semaphore.rst b/Documentation/locking/percpu-rw-semaphore.rst index 247de6410855..a105bf2dd812 100644 --- a/Documentation/locking/percpu-rw-semaphore.rst +++ b/Documentation/locking/percpu-rw-semaphore.rst @@ -16,8 +16,8 @@ writing is very expensive, it calls synchronize_rcu() that can take hundreds of milliseconds. The lock is declared with "struct percpu_rw_semaphore" type. -The lock is initialized percpu_init_rwsem, it returns 0 on success and --ENOMEM on allocation failure. +The lock is initialized with percpu_init_rwsem, it returns 0 on success +and -ENOMEM on allocation failure. The lock must be freed with percpu_free_rwsem to avoid memory leak. The lock is locked for read with percpu_down_read, percpu_up_read and diff --git a/Documentation/locking/seqlock.rst b/Documentation/locking/seqlock.rst index 64405e5da63e..ec6411d02ac8 100644 --- a/Documentation/locking/seqlock.rst +++ b/Documentation/locking/seqlock.rst @@ -39,7 +39,7 @@ as the writer can invalidate a pointer that the reader is following. Sequence counters (``seqcount_t``) ================================== -This is the the raw counting mechanism, which does not protect against +This is the raw counting mechanism, which does not protect against multiple writers. Write side critical sections must thus be serialized by an external lock. @@ -153,7 +153,7 @@ Use seqcount_latch_t when the write side sections cannot be protected from interruption by readers. This is typically the case when the read side can be invoked from NMI handlers. -Check `raw_write_seqcount_latch()` for more information. +Check `write_seqcount_latch()` for more information. .. _seqlock_t: |