+sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget*/translations/zh_CN/kernel-hacking/lockingmodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget*/translations/zh_TW/kernel-hacking/lockingmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget*/translations/it_IT/kernel-hacking/lockingmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget*/translations/ja_JP/kernel-hacking/lockingmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget*/translations/ko_KR/kernel-hacking/lockingmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hPortuguese (Brazilian)}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget*/translations/pt_BR/kernel-hacking/lockingmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget*/translations/sp_SP/kernel-hacking/lockingmodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhtarget)}(h.. _kernel_hacking_lock:h]h}(h]h ]h"]h$]h&]refidkernel-hacking-lockuh1hhKhhhhhD/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking.rstubhsection)}(hhh](htitle)}(hUnreliable Guide To Lockingh]hUnreliable Guide To Locking}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh field_list)}(hhh]hfield)}(hhh](h field_name)}(hAuthorh]hAuthor}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhKubh field_body)}(hRusty Russell h]h paragraph)}(h Rusty Russellh]h Rusty Russell}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhubah}(h]h ]h"]h$]h&]uh1hhhubeh}(h]h ]h"]h$]h&]uh1hhhhKhhhhubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h Introductionh]h Introduction}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhK ubh)}(hWelcome, to Rusty's Remarkably Unreliable Guide to Kernel Locking issues. This document describes the locking systems in the Linux Kernel in 2.6.h]hWelcome, to Rusty’s Remarkably Unreliable Guide to Kernel Locking issues. This document describes the locking systems in the Linux Kernel in 2.6.}(hj,hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hjhhubh)}(hWith the wide availability of HyperThreading, and preemption in the Linux Kernel, everyone hacking on the kernel needs to know the fundamentals of concurrency and locking for SMP.h]hWith the wide availability of HyperThreading, and preemption in the Linux Kernel, everyone hacking on the kernel needs to know the fundamentals of concurrency and locking for SMP.}(hj:hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h] introductionah ]h"] introductionah$]h&]uh1hhhhhhhhK ubh)}(hhh](h)}(hThe Problem With Concurrencyh]hThe Problem With Concurrency}(hjShhhNhNubah}(h]h ]h"]h$]h&]uh1hhjPhhhhhKubh)}(h1(Skip this if you know what a Race Condition is).h]h1(Skip this if you know what a Race Condition is).}(hjahhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjPhhubh)}(h9In a normal program, you can increment a counter like so:h]h9In a normal program, you can increment a counter like so:}(hjohhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjPhhubh literal_block)}(hvery_important_count++;h]hvery_important_count++;}hjsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1j}hhhKhjPhhubh)}(h)This is what they would expect to happen:h]h)This is what they would expect to happen:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hjPhhubhtable)}(hhh](h)}(hExpected Resultsh]hExpected Results}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK#hjubhtgroup)}(hhh](hcolspec)}(hhh]h}(h]h ]h"]h$]h&]colwidthK$uh1jhjubj)}(hhh]h}(h]h ]h"]h$]h&]colwidthK$uh1jhjubhthead)}(hhh]hrow)}(hhh](hentry)}(hhh]h)}(h Instance 1h]h Instance 1}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK&hjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(h Instance 2h]h Instance 2}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK&hjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jhjubhtbody)}(hhh](j)}(hhh](j)}(hhh]h)}(hread very_important_count (5)h]hread very_important_count (5)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK(hjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh](j)}(hhh]h)}(h add 1 (6)h]h add 1 (6)}(hjEhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK*hjBubah}(h]h ]h"]h$]h&]uh1jhj?ubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhj?ubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh](j)}(hhh]h)}(hwrite very_important_count (6)h]hwrite very_important_count (6)}(hjnhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK,hjkubah}(h]h ]h"]h$]h&]uh1jhjhubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhjhubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh](j)}(hhh]h}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hread very_important_count (6)h]hread very_important_count (6)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK.hjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh](j)}(hhh]h}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(h add 1 (7)h]h add 1 (7)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK0hjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh](j)}(hhh]h}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hwrite very_important_count (7)h]hwrite very_important_count (7)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK2hjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]colsKuh1jhjubeh}(h]id1ah ]h"]h$]h&]uh1jhjPhhhhhNubh)}(hThis is what might happen:h]hThis is what might happen:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK5hjPhhubj)}(hhh](h)}(hPossible Resultsh]hPossible Results}(hj1hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK7hj.ubj)}(hhh](j)}(hhh]h}(h]h ]h"]h$]h&]colwidthK$uh1jhj?ubj)}(hhh]h}(h]h ]h"]h$]h&]colwidthK$uh1jhj?ubj)}(hhh]j)}(hhh](j)}(hhh]h)}(h Instance 1h]h Instance 1}(hj_hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK:hj\ubah}(h]h ]h"]h$]h&]uh1jhjYubj)}(hhh]h)}(h Instance 2h]h Instance 2}(hjvhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK:hjsubah}(h]h ]h"]h$]h&]uh1jhjYubeh}(h]h ]h"]h$]h&]uh1jhjVubah}(h]h ]h"]h$]h&]uh1jhj?ubj)}(hhh](j)}(hhh](j)}(hhh]h)}(hread very_important_count (5)h]hread very_important_count (5)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh](j)}(hhh]h)}(h add 1 (6)h]h add 1 (6)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK@hjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh](j)}(hhh]h}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(h add 1 (6)h]h add 1 (6)}(hj#hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKBhj ubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh](j)}(hhh]h)}(hwrite very_important_count (6)h]hwrite very_important_count (6)}(hjChhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKDhj@ubah}(h]h ]h"]h$]h&]uh1jhj=ubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhj=ubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh](j)}(hhh]h}(h]h ]h"]h$]h&]uh1jhjfubj)}(hhh]h)}(hwrite very_important_count (6)h]hwrite very_important_count (6)}(hjuhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKFhjrubah}(h]h ]h"]h$]h&]uh1jhjfubeh}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhj?ubeh}(h]h ]h"]h$]h&]colsKuh1jhj.ubeh}(h]id2ah ]h"]h$]h&]uh1jhjPhhhhhNubh)}(hhh](h)}(h$Race Conditions and Critical Regionsh]h$Race Conditions and Critical Regions}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKKubh)}(hXBThis overlap, where the result depends on the relative timing of multiple tasks, is called a race condition. The piece of code containing the concurrency issue is called a critical region. And especially since Linux starting running on SMP machines, they became one of the major issues in kernel design and implementation.h]hXBThis overlap, where the result depends on the relative timing of multiple tasks, is called a race condition. The piece of code containing the concurrency issue is called a critical region. And especially since Linux starting running on SMP machines, they became one of the major issues in kernel design and implementation.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKMhjhhubh)}(hPreemption can have the same effect, even if there is only one CPU: by preempting one task during the critical region, we have exactly the same race condition. In this case the thread which preempts might run the critical region itself.h]hPreemption can have the same effect, even if there is only one CPU: by preempting one task during the critical region, we have exactly the same race condition. In this case the thread which preempts might run the critical region itself.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKShjhhubh)}(hX>The solution is to recognize when these simultaneous accesses occur, and use locks to make sure that only one instance can enter the critical region at any time. There are many friendly primitives in the Linux kernel to help you do this. And then there are the unfriendly primitives, but I'll pretend they don't exist.h]hXBThe solution is to recognize when these simultaneous accesses occur, and use locks to make sure that only one instance can enter the critical region at any time. There are many friendly primitives in the Linux kernel to help you do this. And then there are the unfriendly primitives, but I’ll pretend they don’t exist.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKXhjhhubeh}(h]$race-conditions-and-critical-regionsah ]h"]$race conditions and critical regionsah$]h&]uh1hhjPhhhhhKKubeh}(h]the-problem-with-concurrencyah ]h"]the problem with concurrencyah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hLocking in the Linux Kernelh]hLocking in the Linux Kernel}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhK_ubh)}(hGIf I could give you one piece of advice on locking: **keep it simple**.h](h4If I could give you one piece of advice on locking: }(hjhhhNhNubhstrong)}(h**keep it simple**h]hkeep it simple}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKahjhhubh)}(h$Be reluctant to introduce new locks.h]h$Be reluctant to introduce new locks.}(hj!hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKchjhhubh)}(hhh](h)}(h5Two Main Types of Kernel Locks: Spinlocks and Mutexesh]h5Two Main Types of Kernel Locks: Spinlocks and Mutexes}(hj2hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj/hhhhhKfubh)}(hXThere are two main types of kernel locks. The fundamental type is the spinlock (``include/asm/spinlock.h``), which is a very simple single-holder lock: if you can't get the spinlock, you keep trying (spinning) until you can. Spinlocks are very small and fast, and can be used anywhere.h](hPThere are two main types of kernel locks. The fundamental type is the spinlock (}(hj@hhhNhNubhliteral)}(h``include/asm/spinlock.h``h]hinclude/asm/spinlock.h}(hjJhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj@ubh), which is a very simple single-holder lock: if you can’t get the spinlock, you keep trying (spinning) until you can. Spinlocks are very small and fast, and can be used anywhere.}(hj@hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhhj/hhubh)}(hXThe second type is a mutex (``include/linux/mutex.h``): it is like a spinlock, but you may block holding a mutex. If you can't lock a mutex, your task will suspend itself, and be woken up when the mutex is released. This means the CPU can do something else while you are waiting. There are many cases when you simply can't sleep (see `What Functions Are Safe To Call From Interrupts?`_), and so have to use a spinlock instead.h](hThe second type is a mutex (}(hjbhhhNhNubjI)}(h``include/linux/mutex.h``h]hinclude/linux/mutex.h}(hjjhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjbubhX): it is like a spinlock, but you may block holding a mutex. If you can’t lock a mutex, your task will suspend itself, and be woken up when the mutex is released. This means the CPU can do something else while you are waiting. There are many cases when you simply can’t sleep (see }(hjbhhhNhNubh reference)}(h3`What Functions Are Safe To Call From Interrupts?`_h]h0What Functions Are Safe To Call From Interrupts?}(hj~hhhNhNubah}(h]h ]h"]h$]h&]name0What Functions Are Safe To Call From Interrupts?h/what-functions-are-safe-to-call-from-interruptsuh1j|hjbresolvedKubh)), and so have to use a spinlock instead.}(hjbhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKnhj/hhubh)}(hHNeither type of lock is recursive: see `Deadlock: Simple and Advanced`_.h](h'Neither type of lock is recursive: see }(hjhhhNhNubj})}(h `Deadlock: Simple and Advanced`_h]hDeadlock: Simple and Advanced}(hjhhhNhNubah}(h]h ]h"]h$]h&]nameDeadlock: Simple and Advancedhdeadlock-simple-and-advanceduh1j|hjjKubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKvhj/hhubeh}(h]4two-main-types-of-kernel-locks-spinlocks-and-mutexesah ]h"]5two main types of kernel locks: spinlocks and mutexesah$]h&]uh1hhjhhhhhKfubh)}(hhh](h)}(hLocks and Uniprocessor Kernelsh]hLocks and Uniprocessor Kernels}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKzubh)}(hFor kernels compiled without ``CONFIG_SMP``, and without ``CONFIG_PREEMPT`` spinlocks do not exist at all. This is an excellent design decision: when no-one else can run at the same time, there is no reason to have a lock.h](hFor kernels compiled without }(hjhhhNhNubjI)}(h``CONFIG_SMP``h]h CONFIG_SMP}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjubh, and without }(hjhhhNhNubjI)}(h``CONFIG_PREEMPT``h]hCONFIG_PREEMPT}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjubh spinlocks do not exist at all. This is an excellent design decision: when no-one else can run at the same time, there is no reason to have a lock.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK|hjhhubh)}(hX If the kernel is compiled without ``CONFIG_SMP``, but ``CONFIG_PREEMPT`` is set, then spinlocks simply disable preemption, which is sufficient to prevent any races. For most purposes, we can think of preemption as equivalent to SMP, and not worry about it separately.h](h"If the kernel is compiled without }(hjhhhNhNubjI)}(h``CONFIG_SMP``h]h CONFIG_SMP}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjubh, but }(hjhhhNhNubjI)}(h``CONFIG_PREEMPT``h]hCONFIG_PREEMPT}(hj"hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjubh is set, then spinlocks simply disable preemption, which is sufficient to prevent any races. For most purposes, we can think of preemption as equivalent to SMP, and not worry about it separately.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hYou should always test your locking code with ``CONFIG_SMP`` and ``CONFIG_PREEMPT`` enabled, even if you don't have an SMP test box, because it will still catch some kinds of locking bugs.h](h.You should always test your locking code with }(hj:hhhNhNubjI)}(h``CONFIG_SMP``h]h CONFIG_SMP}(hjBhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj:ubh and }(hj:hhhNhNubjI)}(h``CONFIG_PREEMPT``h]hCONFIG_PREEMPT}(hjThhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj:ubhk enabled, even if you don’t have an SMP test box, because it will still catch some kinds of locking bugs.}(hj:hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hoMutexes still exist, because they are required for synchronization between user contexts, as we will see below.h]hoMutexes still exist, because they are required for synchronization between user contexts, as we will see below.}(hjlhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]locks-and-uniprocessor-kernelsah ]h"]locks and uniprocessor kernelsah$]h&]uh1hhjhhhhhKzubh)}(hhh](h)}(hLocking Only In User Contexth]hLocking Only In User Context}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hXIf you have a data structure which is only ever accessed from user context, then you can use a simple mutex (``include/linux/mutex.h``) to protect it. This is the most trivial case: you initialize the mutex. Then you can call mutex_lock_interruptible() to grab the mutex, and mutex_unlock() to release it. There is also a mutex_lock(), which should be avoided, because it will not return if a signal is received.h](hmIf you have a data structure which is only ever accessed from user context, then you can use a simple mutex (}(hjhhhNhNubjI)}(h``include/linux/mutex.h``h]hinclude/linux/mutex.h}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjubhX) to protect it. This is the most trivial case: you initialize the mutex. Then you can call mutex_lock_interruptible() to grab the mutex, and mutex_unlock() to release it. There is also a mutex_lock(), which should be avoided, because it will not return if a signal is received.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXExample: ``net/netfilter/nf_sockopt.c`` allows registration of new setsockopt() and getsockopt() calls, with nf_register_sockopt(). Registration and de-registration are only done on module load and unload (and boot time, where there is no concurrency), and the list of registrations is only consulted for an unknown setsockopt() or getsockopt() system call. The ``nf_sockopt_mutex`` is perfect to protect this, especially since the setsockopt and getsockopt calls may well sleep.h](h Example: }(hjhhhNhNubjI)}(h``net/netfilter/nf_sockopt.c``h]hnet/netfilter/nf_sockopt.c}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjubhXC allows registration of new setsockopt() and getsockopt() calls, with nf_register_sockopt(). Registration and de-registration are only done on module load and unload (and boot time, where there is no concurrency), and the list of registrations is only consulted for an unknown setsockopt() or getsockopt() system call. The }(hjhhhNhNubjI)}(h``nf_sockopt_mutex``h]hnf_sockopt_mutex}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjubha is perfect to protect this, especially since the setsockopt and getsockopt calls may well sleep.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]locking-only-in-user-contextah ]h"]locking only in user contextah$]h&]uh1hhjhhhhhKubh)}(hhh](h)}(h)Locking Between User Context and Softirqsh]h)Locking Between User Context and Softirqs}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hXIf a softirq shares data with user context, you have two problems. Firstly, the current user context can be interrupted by a softirq, and secondly, the critical region could be entered from another CPU. This is where spin_lock_bh() (``include/linux/spinlock.h``) is used. It disables softirqs on that CPU, then grabs the lock. spin_unlock_bh() does the reverse. (The '_bh' suffix is a historical reference to "Bottom Halves", the old name for software interrupts. It should really be called spin_lock_softirq()' in a perfect world).h](hIf a softirq shares data with user context, you have two problems. Firstly, the current user context can be interrupted by a softirq, and secondly, the critical region could be entered from another CPU. This is where spin_lock_bh() (}(hjhhhNhNubjI)}(h``include/linux/spinlock.h``h]hinclude/linux/spinlock.h}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjubhX) is used. It disables softirqs on that CPU, then grabs the lock. spin_unlock_bh() does the reverse. (The ‘_bh’ suffix is a historical reference to “Bottom Halves”, the old name for software interrupts. It should really be called spin_lock_softirq()’ in a perfect world).}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hNote that you can also use spin_lock_irq() or spin_lock_irqsave() here, which stop hardware interrupts as well: see `Hard IRQ Context`_.h](htNote that you can also use spin_lock_irq() or spin_lock_irqsave() here, which stop hardware interrupts as well: see }(hjhhhNhNubj})}(h`Hard IRQ Context`_h]hHard IRQ Context}(hj&hhhNhNubah}(h]h ]h"]h$]h&]nameHard IRQ Contexthhard-irq-contextuh1j|hjjKubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hThis works perfectly for UP as well: the spin lock vanishes, and this macro simply becomes local_bh_disable() (``include/linux/interrupt.h``), which protects you from the softirq being run.h](hoThis works perfectly for UP as well: the spin lock vanishes, and this macro simply becomes local_bh_disable() (}(hjAhhhNhNubjI)}(h``include/linux/interrupt.h``h]hinclude/linux/interrupt.h}(hjIhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjAubh1), which protects you from the softirq being run.}(hjAhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h])locking-between-user-context-and-softirqsah ]h"])locking between user context and softirqsah$]h&]uh1hhjhhhhhKubh)}(hhh](h)}(h)Locking Between User Context and Taskletsh]h)Locking Between User Context and Tasklets}(hjlhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjihhhhhKubh)}(hTThis is exactly the same as above, because tasklets are actually run from a softirq.h]hTThis is exactly the same as above, because tasklets are actually run from a softirq.}(hjzhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjihhubeh}(h])locking-between-user-context-and-taskletsah ]h"])locking between user context and taskletsah$]h&]uh1hhjhhhhhKubh)}(hhh](h)}(h'Locking Between User Context and Timersh]h'Locking Between User Context and Timers}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hThis, too, is exactly the same as above, because timers are actually run from a softirq. From a locking point of view, tasklets and timers are identical.h]hThis, too, is exactly the same as above, because timers are actually run from a softirq. From a locking point of view, tasklets and timers are identical.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]'locking-between-user-context-and-timersah ]h"]'locking between user context and timersah$]h&]uh1hhjhhhhhKubh)}(hhh](h)}(hLocking Between Tasklets/Timersh]hLocking Between Tasklets/Timers}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hTSometimes a tasklet or timer might want to share data with another tasklet or timer.h]hTSometimes a tasklet or timer might want to share data with another tasklet or timer.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hhh](h)}(hThe Same Tasklet/Timerh]hThe Same Tasklet/Timer}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hSince a tasklet is never run on two CPUs at once, you don't need to worry about your tasklet being reentrant (running twice at once), even on SMP.h]hSince a tasklet is never run on two CPUs at once, you don’t need to worry about your tasklet being reentrant (running twice at once), even on SMP.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]the-same-tasklet-timerah ]h"]the same tasklet/timerah$]h&]uh1hhjhhhhhKubh)}(hhh](h)}(hDifferent Tasklets/Timersh]hDifferent Tasklets/Timers}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hIf another tasklet/timer wants to share data with your tasklet or timer , you will both need to use spin_lock() and spin_unlock() calls. spin_lock_bh() is unnecessary here, as you are already in a tasklet, and none will be run on the same CPU.h]hIf another tasklet/timer wants to share data with your tasklet or timer , you will both need to use spin_lock() and spin_unlock() calls. spin_lock_bh() is unnecessary here, as you are already in a tasklet, and none will be run on the same CPU.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]different-tasklets-timersah ]h"]different tasklets/timersah$]h&]uh1hhjhhhhhKubeh}(h]locking-between-tasklets-timersah ]h"]locking between tasklets/timersah$]h&]uh1hhjhhhhhKubh)}(hhh](h)}(hLocking Between Softirqsh]hLocking Between Softirqs}(hj/hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj,hhhhhKubh)}(hHOften a softirq might want to share data with itself or a tasklet/timer.h]hHOften a softirq might want to share data with itself or a tasklet/timer.}(hj=hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj,hhubh)}(hhh](h)}(hThe Same Softirqh]hThe Same Softirq}(hjNhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjKhhhhhKubh)}(hThe same softirq can run on the other CPUs: you can use a per-CPU array (see `Per-CPU Data`_) for better performance. If you're going so far as to use a softirq, you probably care about scalable performance enough to justify the extra complexity.h](hMThe same softirq can run on the other CPUs: you can use a per-CPU array (see }(hj\hhhNhNubj})}(h`Per-CPU Data`_h]h Per-CPU Data}(hjdhhhNhNubah}(h]h ]h"]h$]h&]name Per-CPU Datah per-cpu-datauh1j|hj\jKubh) for better performance. If you’re going so far as to use a softirq, you probably care about scalable performance enough to justify the extra complexity.}(hj\hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjKhhubh)}(hAYou'll need to use spin_lock() and spin_unlock() for shared data.h]hCYou’ll need to use spin_lock() and spin_unlock() for shared data.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjKhhubeh}(h]the-same-softirqah ]h"]the same softirqah$]h&]uh1hhj,hhhhhKubh)}(hhh](h)}(hDifferent Softirqsh]hDifferent Softirqs}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hYou'll need to use spin_lock() and spin_unlock() for shared data, whether it be a timer, tasklet, different softirq or the same or another softirq: any of them could be running on a different CPU.h]hYou’ll need to use spin_lock() and spin_unlock() for shared data, whether it be a timer, tasklet, different softirq or the same or another softirq: any of them could be running on a different CPU.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]different-softirqsah ]h"]different softirqsah$]h&]uh1hhj,hhhhhKubeh}(h]locking-between-softirqsah ]h"]locking between softirqsah$]h&]uh1hhjhhhhhKubeh}(h]locking-in-the-linux-kernelah ]h"]locking in the linux kernelah$]h&]uh1hhhhhhhhK_ubh)}(hhh](h)}(hHard IRQ Contexth]hHard IRQ Context}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hHardware interrupts usually communicate with a tasklet or softirq. Frequently this involves putting work in a queue, which the softirq will take out.h]hHardware interrupts usually communicate with a tasklet or softirq. Frequently this involves putting work in a queue, which the softirq will take out.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hhh](h)}(h.Locking Between Hard IRQ and Softirqs/Taskletsh]h.Locking Between Hard IRQ and Softirqs/Tasklets}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hXIf a hardware irq handler shares data with a softirq, you have two concerns. Firstly, the softirq processing can be interrupted by a hardware interrupt, and secondly, the critical region could be entered by a hardware interrupt on another CPU. This is where spin_lock_irq() is used. It is defined to disable interrupts on that cpu, then grab the lock. spin_unlock_irq() does the reverse.h]hXIf a hardware irq handler shares data with a softirq, you have two concerns. Firstly, the softirq processing can be interrupted by a hardware interrupt, and secondly, the critical region could be entered by a hardware interrupt on another CPU. This is where spin_lock_irq() is used. It is defined to disable interrupts on that cpu, then grab the lock. spin_unlock_irq() does the reverse.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hX1The irq handler does not need to use spin_lock_irq(), because the softirq cannot run while the irq handler is running: it can use spin_lock(), which is slightly faster. The only exception would be if a different hardware irq handler uses the same lock: spin_lock_irq() will stop that from interrupting us.h]hX1The irq handler does not need to use spin_lock_irq(), because the softirq cannot run while the irq handler is running: it can use spin_lock(), which is slightly faster. The only exception would be if a different hardware irq handler uses the same lock: spin_lock_irq() will stop that from interrupting us.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hThis works perfectly for UP as well: the spin lock vanishes, and this macro simply becomes local_irq_disable() (``include/asm/smp.h``), which protects you from the softirq/tasklet/BH being run.h](hpThis works perfectly for UP as well: the spin lock vanishes, and this macro simply becomes local_irq_disable() (}(hj hhhNhNubjI)}(h``include/asm/smp.h``h]hinclude/asm/smp.h}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj ubh<), which protects you from the softirq/tasklet/BH being run.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM hjhhubh)}(hXJspin_lock_irqsave() (``include/linux/spinlock.h``) is a variant which saves whether interrupts were on or off in a flags word, which is passed to spin_unlock_irqrestore(). This means that the same code can be used inside an hard irq handler (where interrupts are already off) and in softirqs (where the irq disabling is required).h](hspin_lock_irqsave() (}(hj8 hhhNhNubjI)}(h``include/linux/spinlock.h``h]hinclude/linux/spinlock.h}(hj@ hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj8 ubhX) is a variant which saves whether interrupts were on or off in a flags word, which is passed to spin_unlock_irqrestore(). This means that the same code can be used inside an hard irq handler (where interrupts are already off) and in softirqs (where the irq disabling is required).}(hj8 hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hNote that softirqs (and hence tasklets and timers) are run on return from hardware interrupts, so spin_lock_irq() also stops these. In that sense, spin_lock_irqsave() is the most general and powerful locking function.h]hNote that softirqs (and hence tasklets and timers) are run on return from hardware interrupts, so spin_lock_irq() also stops these. In that sense, spin_lock_irqsave() is the most general and powerful locking function.}(hjX hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubeh}(h].locking-between-hard-irq-and-softirqs-taskletsah ]h"].locking between hard irq and softirqs/taskletsah$]h&]uh1hhjhhhhhKubh)}(hhh](h)}(h%Locking Between Two Hard IRQ Handlersh]h%Locking Between Two Hard IRQ Handlers}(hjq hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjn hhhhhMubh)}(hIt is rare to have to share data between two IRQ handlers, but if you do, spin_lock_irqsave() should be used: it is architecture-specific whether all interrupts are disabled inside irq handlers themselves.h]hIt is rare to have to share data between two IRQ handlers, but if you do, spin_lock_irqsave() should be used: it is architecture-specific whether all interrupts are disabled inside irq handlers themselves.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjn hhubeh}(h]%locking-between-two-hard-irq-handlersah ]h"]%locking between two hard irq handlersah$]h&]uh1hhjhhhhhMubeh}(h]j6ah ]h"]hard irq contextah$]h&]uh1hhhhhhhhK referencedKubh)}(hhh](h)}(hCheat Sheet For Lockingh]hCheat Sheet For Locking}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhM$ubh)}(h)Pete Zaitcev gives the following summary:h]h)Pete Zaitcev gives the following summary:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM&hj hhubh bullet_list)}(hhh](h list_item)}(hIf you are in a process context (any syscall) and want to lock other process out, use a mutex. You can take a mutex and sleep (``copy_from_user()`` or ``kmalloc(x,GFP_KERNEL)``). h]h)}(hIf you are in a process context (any syscall) and want to lock other process out, use a mutex. You can take a mutex and sleep (``copy_from_user()`` or ``kmalloc(x,GFP_KERNEL)``).h](hIf you are in a process context (any syscall) and want to lock other process out, use a mutex. You can take a mutex and sleep (}(hj hhhNhNubjI)}(h``copy_from_user()``h]hcopy_from_user()}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj ubh or }(hj hhhNhNubjI)}(h``kmalloc(x,GFP_KERNEL)``h]hkmalloc(x,GFP_KERNEL)}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj ubh).}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM(hj ubah}(h]h ]h"]h$]h&]uh1j hj hhhhhNubj )}(hjOtherwise (== data can be touched in an interrupt), use spin_lock_irqsave() and spin_unlock_irqrestore(). h]h)}(hiOtherwise (== data can be touched in an interrupt), use spin_lock_irqsave() and spin_unlock_irqrestore().h]hiOtherwise (== data can be touched in an interrupt), use spin_lock_irqsave() and spin_unlock_irqrestore().}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM,hj ubah}(h]h ]h"]h$]h&]uh1j hj hhhhhNubj )}(hsAvoid holding spinlock for more than 5 lines of code and across any function call (except accessors like readb()). h]h)}(hrAvoid holding spinlock for more than 5 lines of code and across any function call (except accessors like readb()).h]hrAvoid holding spinlock for more than 5 lines of code and across any function call (except accessors like readb()).}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM0hj ubah}(h]h ]h"]h$]h&]uh1j hj hhhhhNubeh}(h]h ]h"]h$]h&]bullet-uh1j hhhM(hj hhubh)}(hhh](h)}(hTable of Minimum Requirementsh]hTable of Minimum Requirements}(hj: hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj7 hhhhhM4ubh)}(hXPThe following table lists the **minimum** locking requirements between various contexts. In some cases, the same context can only be running on one CPU at a time, so no locking is required for that context (eg. a particular thread can only run on one CPU at a time, but if it needs shares data with another thread, locking is required).h](hThe following table lists the }(hjH hhhNhNubj)}(h **minimum**h]hminimum}(hjP hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjH ubhX' locking requirements between various contexts. In some cases, the same context can only be running on one CPU at a time, so no locking is required for that context (eg. a particular thread can only run on one CPU at a time, but if it needs shares data with another thread, locking is required).}(hjH hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM6hj7 hhubh)}(hxRemember the advice above: you can always use spin_lock_irqsave(), which is a superset of all other spinlock primitives.h]hxRemember the advice above: you can always use spin_lock_irqsave(), which is a superset of all other spinlock primitives.}(hjh hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM<hj7 hhubj)}(hhh]j)}(hhh](j)}(hhh]h}(h]h ]h"]h$]h&]colwidthKuh1jhjy ubj)}(hhh]h}(h]h ]h"]h$]h&]colwidthK uh1jhjy ubj)}(hhh]h}(h]h ]h"]h$]h&]colwidthK uh1jhjy ubj)}(hhh]h}(h]h ]h"]h$]h&]colwidthK uh1jhjy ubj)}(hhh]h}(h]h ]h"]h$]h&]colwidthK uh1jhjy ubj)}(hhh]h}(h]h ]h"]h$]h&]colwidthK uh1jhjy ubj)}(hhh]h}(h]h ]h"]h$]h&]colwidthK uh1jhjy ubj)}(hhh]h}(h]h ]h"]h$]h&]colwidthKuh1jhjy ubj)}(hhh]h}(h]h ]h"]h$]h&]colwidthKuh1jhjy ubj)}(hhh]h}(h]h ]h"]h$]h&]colwidthKuh1jhjy ubj)}(hhh]h}(h]h ]h"]h$]h&]colwidthKuh1jhjy ubj)}(hhh]j)}(hhh](j)}(hhh]h)}(h.h]h.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMAhj ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h)}(h IRQ Handler Ah]h IRQ Handler A}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMAhj ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h)}(h IRQ Handler Bh]h IRQ Handler B}(hj! hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMAhj ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h)}(h Softirq Ah]h Softirq A}(hj8 hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMAhj5 ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h)}(h Softirq Bh]h Softirq B}(hjO hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMAhjL ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h)}(h Tasklet Ah]h Tasklet A}(hjf hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMAhjc ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h)}(h Tasklet Bh]h Tasklet B}(hj} hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMAhjz ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h)}(hTimer Ah]hTimer A}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMAhj ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h)}(hTimer Bh]hTimer B}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMAhj ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h)}(hUser Context Ah]hUser Context A}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMAhj ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h)}(hUser Context Bh]hUser Context B}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMAhj ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1jhj ubah}(h]h ]h"]h$]h&]uh1jhjy ubj)}(hhh](j)}(hhh](j)}(hhh]h)}(h IRQ Handler Ah]h IRQ Handler A}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMChj ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h)}(hNoneh]hNone}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMChj ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh](j)}(hhh]h)}(h IRQ Handler Bh]h IRQ Handler B}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMDhj ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h)}(hSLISh]hSLIS}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMDhj ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h)}(hNoneh]hNone}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMDhj ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh](j)}(hhh]h)}(h Softirq Ah]h Softirq A}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMEhj ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h)}(hSLIh]hSLI}(hj7 hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMEhj4 ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h)}(hSLIh]hSLI}(hjN hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMEhjK ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h)}(hSLh]hSL}(hje hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMEhjb ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh](j)}(hhh]h)}(h Softirq Bh]h Softirq B}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMFhj ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h)}(hSLIh]hSLI}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMFhj ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h)}(hSLIh]hSLI}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMFhj ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h)}(hSLh]hSL}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMFhjubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h)}(hSLh]hSL}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMFhjubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh](j)}(hhh]h)}(h Tasklet Ah]h Tasklet A}(hjvhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMGhjsubah}(h]h ]h"]h$]h&]uh1jhjpubj)}(hhh]h)}(hSLIh]hSLI}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMGhjubah}(h]h ]h"]h$]h&]uh1jhjpubj)}(hhh]h)}(hSLIh]hSLI}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMGhjubah}(h]h ]h"]h$]h&]uh1jhjpubj)}(hhh]h)}(hSLh]hSL}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMGhjubah}(h]h ]h"]h$]h&]uh1jhjpubj)}(hhh]h)}(hSLh]hSL}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMGhjubah}(h]h ]h"]h$]h&]uh1jhjpubj)}(hhh]h)}(hNoneh]hNone}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMGhjubah}(h]h ]h"]h$]h&]uh1jhjpubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhjpubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhjpubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhjpubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhjpubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhjpubeh}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh](j)}(hhh]h)}(h Tasklet Bh]h Tasklet B}(hj6hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMHhj3ubah}(h]h ]h"]h$]h&]uh1jhj0ubj)}(hhh]h)}(hSLIh]hSLI}(hjMhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMHhjJubah}(h]h ]h"]h$]h&]uh1jhj0ubj)}(hhh]h)}(hSLIh]hSLI}(hjdhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMHhjaubah}(h]h ]h"]h$]h&]uh1jhj0ubj)}(hhh]h)}(hSLh]hSL}(hj{hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMHhjxubah}(h]h ]h"]h$]h&]uh1jhj0ubj)}(hhh]h)}(hSLh]hSL}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMHhjubah}(h]h ]h"]h$]h&]uh1jhj0ubj)}(hhh]h)}(hSLh]hSL}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMHhjubah}(h]h ]h"]h$]h&]uh1jhj0ubj)}(hhh]h)}(hNoneh]hNone}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMHhjubah}(h]h ]h"]h$]h&]uh1jhj0ubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhj0ubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhj0ubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhj0ubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhj0ubeh}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh](j)}(hhh]h)}(hTimer Ah]hTimer A}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMIhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hSLIh]hSLI}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMIhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hSLIh]hSLI}(hj2hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMIhj/ubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hSLh]hSL}(hjIhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMIhjFubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hSLh]hSL}(hj`hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMIhj]ubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hSLh]hSL}(hjwhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMIhjtubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hSLh]hSL}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMIhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hNoneh]hNone}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMIhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh](j)}(hhh]h)}(hTimer Bh]hTimer B}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMJhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hSLIh]hSLI}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMJhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hSLIh]hSLI}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMJhj ubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hSLh]hSL}(hj%hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMJhj"ubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hSLh]hSL}(hj<hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMJhj9ubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hSLh]hSL}(hjShhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMJhjPubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hSLh]hSL}(hjjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMJhjgubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hSLh]hSL}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMJhj~ubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hNoneh]hNone}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMJhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh](j)}(hhh]h)}(hUser Context Ah]hUser Context A}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hSLIh]hSLI}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hSLIh]hSLI}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hSLBHh]hSLBH}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMKhj ubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hSLBHh]hSLBH}(hj&hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMKhj#ubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hSLBHh]hSLBH}(hj=hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMKhj:ubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hSLBHh]hSLBH}(hjThhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMKhjQubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hSLBHh]hSLBH}(hjkhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMKhjhubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hSLBHh]hSLBH}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hNoneh]hNone}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh](j)}(hhh]h)}(hUser Context Bh]hUser Context B}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMLhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hSLIh]hSLI}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMLhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hSLIh]hSLI}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMLhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hSLBHh]hSLBH}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMLhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hSLBHh]hSLBH}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMLhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hSLBHh]hSLBH}(hj5hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMLhj2ubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hSLBHh]hSLBH}(hjLhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMLhjIubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hSLBHh]hSLBH}(hjchhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMLhj`ubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hSLBHh]hSLBH}(hjzhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMLhjwubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hMLIh]hMLI}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMLhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hNoneh]hNone}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMLhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1jhjy ubeh}(h]h ]h"]h$]h&]colsK uh1jhjv ubah}(h]h ]h"]h$]h&]uh1jhj7 hhhhhNubh)}(h$Table: Table of Locking Requirementsh]h$Table: Table of Locking Requirements}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMOhj7 hhubj)}(hhh]j)}(hhh](j)}(hhh]h}(h]h ]h"]h$]h&]colwidthKuh1jhjubj)}(hhh]h}(h]h ]h"]h$]h&]colwidthKuh1jhjubj)}(hhh](j)}(hhh](j)}(hhh]h)}(hSLISh]hSLIS}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMRhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hspin_lock_irqsaveh]hspin_lock_irqsave}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMRhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh](j)}(hhh]h)}(hSLIh]hSLI}(hj=hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMThj:ubah}(h]h ]h"]h$]h&]uh1jhj7ubj)}(hhh]h)}(h spin_lock_irqh]h spin_lock_irq}(hjThhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMThjQubah}(h]h ]h"]h$]h&]uh1jhj7ubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh](j)}(hhh]h)}(hSLh]hSL}(hjthhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMVhjqubah}(h]h ]h"]h$]h&]uh1jhjnubj)}(hhh]h)}(h spin_lockh]h spin_lock}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMVhjubah}(h]h ]h"]h$]h&]uh1jhjnubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh](j)}(hhh]h)}(hSLBHh]hSLBH}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMXhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(h spin_lock_bhh]h spin_lock_bh}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMXhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh](j)}(hhh]h)}(hMLIh]hMLI}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMZhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hmutex_lock_interruptibleh]hmutex_lock_interruptible}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMZhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]colsKuh1jhjubah}(h]h ]h"]h$]h&]uh1jhj7 hhhhhNubh)}(h,Table: Legend for Locking Requirements Tableh]h,Table: Legend for Locking Requirements Table}(hj&hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM]hj7 hhubeh}(h]table-of-minimum-requirementsah ]h"]table of minimum requirementsah$]h&]uh1hhj hhhhhM4ubeh}(h]cheat-sheet-for-lockingah ]h"]cheat sheet for lockingah$]h&]uh1hhhhhhhhM$ubh)}(hhh](h)}(hThe trylock Functionsh]hThe trylock Functions}(hjGhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjDhhhhhM`ubh)}(hXcThere are functions that try to acquire a lock only once and immediately return a value telling about success or failure to acquire the lock. They can be used if you need no access to the data protected with the lock when some other thread is holding the lock. You should acquire the lock later if you then need access to the data protected with the lock.h]hXcThere are functions that try to acquire a lock only once and immediately return a value telling about success or failure to acquire the lock. They can be used if you need no access to the data protected with the lock when some other thread is holding the lock. You should acquire the lock later if you then need access to the data protected with the lock.}(hjUhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMbhjDhhubh)}(hspin_trylock() does not spin but returns non-zero if it acquires the spinlock on the first try or 0 if not. This function can be used in all contexts like spin_lock(): you must have disabled the contexts that might interrupt you and acquire the spin lock.h]hspin_trylock() does not spin but returns non-zero if it acquires the spinlock on the first try or 0 if not. This function can be used in all contexts like spin_lock(): you must have disabled the contexts that might interrupt you and acquire the spin lock.}(hjchhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhhjDhhubh)}(hmutex_trylock() does not suspend your task but returns non-zero if it could lock the mutex on the first try or 0 if not. This function cannot be safely used in hardware or software interrupt contexts despite not sleeping.h]hmutex_trylock() does not suspend your task but returns non-zero if it could lock the mutex on the first try or 0 if not. This function cannot be safely used in hardware or software interrupt contexts despite not sleeping.}(hjqhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMnhjDhhubeh}(h]the-trylock-functionsah ]h"]the trylock functionsah$]h&]uh1hhhhhhhhM`ubh)}(hhh](h)}(hCommon Examplesh]hCommon Examples}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMtubh)}(hLet's step through a simple example: a cache of number to name mappings. The cache keeps a count of how often each of the objects is used, and when it gets full, throws out the least used one.h]hLet’s step through a simple example: a cache of number to name mappings. The cache keeps a count of how often each of the objects is used, and when it gets full, throws out the least used one.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMvhjhhubh)}(hhh](h)}(hAll In User Contexth]hAll In User Context}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhM{ubh)}(hFor our first example, we assume that all operations are in user context (ie. from system calls), so we can sleep. This means we can use a mutex to protect the cache and all the objects within it. Here's the code::h]hFor our first example, we assume that all operations are in user context (ie. from system calls), so we can sleep. This means we can use a mutex to protect the cache and all the objects within it. Here’s the code:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM}hjhhubj~)}(hX#include #include #include #include #include struct object { struct list_head list; int id; char name[32]; int popularity; }; /* Protects the cache, cache_num, and the objects within it */ static DEFINE_MUTEX(cache_lock); static LIST_HEAD(cache); static unsigned int cache_num = 0; #define MAX_CACHE_SIZE 10 /* Must be holding cache_lock */ static struct object *__cache_find(int id) { struct object *i; list_for_each_entry(i, &cache, list) if (i->id == id) { i->popularity++; return i; } return NULL; } /* Must be holding cache_lock */ static void __cache_delete(struct object *obj) { BUG_ON(!obj); list_del(&obj->list); kfree(obj); cache_num--; } /* Must be holding cache_lock */ static void __cache_add(struct object *obj) { list_add(&obj->list, &cache); if (++cache_num > MAX_CACHE_SIZE) { struct object *i, *outcast = NULL; list_for_each_entry(i, &cache, list) { if (!outcast || i->popularity < outcast->popularity) outcast = i; } __cache_delete(outcast); } } int cache_add(int id, const char *name) { struct object *obj; if ((obj = kmalloc_obj(*obj)) == NULL) return -ENOMEM; strscpy(obj->name, name, sizeof(obj->name)); obj->id = id; obj->popularity = 0; mutex_lock(&cache_lock); __cache_add(obj); mutex_unlock(&cache_lock); return 0; } void cache_delete(int id) { mutex_lock(&cache_lock); __cache_delete(__cache_find(id)); mutex_unlock(&cache_lock); } int cache_find(int id, char *name) { struct object *obj; int ret = -ENOENT; mutex_lock(&cache_lock); obj = __cache_find(id); if (obj) { ret = 0; strscpy(name, obj->name); } mutex_unlock(&cache_lock); return ret; }h]hX#include #include #include #include #include struct object { struct list_head list; int id; char name[32]; int popularity; }; /* Protects the cache, cache_num, and the objects within it */ static DEFINE_MUTEX(cache_lock); static LIST_HEAD(cache); static unsigned int cache_num = 0; #define MAX_CACHE_SIZE 10 /* Must be holding cache_lock */ static struct object *__cache_find(int id) { struct object *i; list_for_each_entry(i, &cache, list) if (i->id == id) { i->popularity++; return i; } return NULL; } /* Must be holding cache_lock */ static void __cache_delete(struct object *obj) { BUG_ON(!obj); list_del(&obj->list); kfree(obj); cache_num--; } /* Must be holding cache_lock */ static void __cache_add(struct object *obj) { list_add(&obj->list, &cache); if (++cache_num > MAX_CACHE_SIZE) { struct object *i, *outcast = NULL; list_for_each_entry(i, &cache, list) { if (!outcast || i->popularity < outcast->popularity) outcast = i; } __cache_delete(outcast); } } int cache_add(int id, const char *name) { struct object *obj; if ((obj = kmalloc_obj(*obj)) == NULL) return -ENOMEM; strscpy(obj->name, name, sizeof(obj->name)); obj->id = id; obj->popularity = 0; mutex_lock(&cache_lock); __cache_add(obj); mutex_unlock(&cache_lock); return 0; } void cache_delete(int id) { mutex_lock(&cache_lock); __cache_delete(__cache_find(id)); mutex_unlock(&cache_lock); } int cache_find(int id, char *name) { struct object *obj; int ret = -ENOENT; mutex_lock(&cache_lock); obj = __cache_find(id); if (obj) { ret = 0; strscpy(name, obj->name); } mutex_unlock(&cache_lock); return ret; }}hjsbah}(h]h ]h"]h$]h&]jjuh1j}hhhMhjhhubh)}(hX,Note that we always make sure we have the cache_lock when we add, delete, or look up the cache: both the cache infrastructure itself and the contents of the objects are protected by the lock. In this case it's easy, since we copy the data for the user, and never let them access the objects directly.h]hX.Note that we always make sure we have the cache_lock when we add, delete, or look up the cache: both the cache infrastructure itself and the contents of the objects are protected by the lock. In this case it’s easy, since we copy the data for the user, and never let them access the objects directly.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hThere is a slight (and common) optimization here: in cache_add() we set up the fields of the object before grabbing the lock. This is safe, as no-one else can access it until we put it in cache.h]hThere is a slight (and common) optimization here: in cache_add() we set up the fields of the object before grabbing the lock. This is safe, as no-one else can access it until we put it in cache.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubeh}(h]all-in-user-contextah ]h"]all in user contextah$]h&]uh1hhjhhhhhM{ubh)}(hhh](h)}(h Accessing From Interrupt Contexth]h Accessing From Interrupt Context}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hNow consider the case where cache_find() can be called from interrupt context: either a hardware interrupt or a softirq. An example would be a timer which deletes object from the cache.h]hNow consider the case where cache_find() can be called from interrupt context: either a hardware interrupt or a softirq. An example would be a timer which deletes object from the cache.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hThe change is shown below, in standard patch format: the ``-`` are lines which are taken away, and the ``+`` are lines which are added.h](h9The change is shown below, in standard patch format: the }(hjhhhNhNubjI)}(h``-``h]h-}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjubh) are lines which are taken away, and the }(hjhhhNhNubjI)}(h``+``h]h+}(hj0hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjubh are lines which are added.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj~)}(hX--- cache.c.usercontext 2003-12-09 13:58:54.000000000 +1100 +++ cache.c.interrupt 2003-12-09 14:07:49.000000000 +1100 @@ -12,7 +12,7 @@ int popularity; }; -static DEFINE_MUTEX(cache_lock); +static DEFINE_SPINLOCK(cache_lock); static LIST_HEAD(cache); static unsigned int cache_num = 0; #define MAX_CACHE_SIZE 10 @@ -55,6 +55,7 @@ int cache_add(int id, const char *name) { struct object *obj; + unsigned long flags; if ((obj = kmalloc_obj(*obj)) == NULL) return -ENOMEM; @@ -63,30 +64,33 @@ obj->id = id; obj->popularity = 0; - mutex_lock(&cache_lock); + spin_lock_irqsave(&cache_lock, flags); __cache_add(obj); - mutex_unlock(&cache_lock); + spin_unlock_irqrestore(&cache_lock, flags); return 0; } void cache_delete(int id) { - mutex_lock(&cache_lock); + unsigned long flags; + + spin_lock_irqsave(&cache_lock, flags); __cache_delete(__cache_find(id)); - mutex_unlock(&cache_lock); + spin_unlock_irqrestore(&cache_lock, flags); } int cache_find(int id, char *name) { struct object *obj; int ret = -ENOENT; + unsigned long flags; - mutex_lock(&cache_lock); + spin_lock_irqsave(&cache_lock, flags); obj = __cache_find(id); if (obj) { ret = 0; strscpy(name, obj->name); } - mutex_unlock(&cache_lock); + spin_unlock_irqrestore(&cache_lock, flags); return ret; }h]hX--- cache.c.usercontext 2003-12-09 13:58:54.000000000 +1100 +++ cache.c.interrupt 2003-12-09 14:07:49.000000000 +1100 @@ -12,7 +12,7 @@ int popularity; }; -static DEFINE_MUTEX(cache_lock); +static DEFINE_SPINLOCK(cache_lock); static LIST_HEAD(cache); static unsigned int cache_num = 0; #define MAX_CACHE_SIZE 10 @@ -55,6 +55,7 @@ int cache_add(int id, const char *name) { struct object *obj; + unsigned long flags; if ((obj = kmalloc_obj(*obj)) == NULL) return -ENOMEM; @@ -63,30 +64,33 @@ obj->id = id; obj->popularity = 0; - mutex_lock(&cache_lock); + spin_lock_irqsave(&cache_lock, flags); __cache_add(obj); - mutex_unlock(&cache_lock); + spin_unlock_irqrestore(&cache_lock, flags); return 0; } void cache_delete(int id) { - mutex_lock(&cache_lock); + unsigned long flags; + + spin_lock_irqsave(&cache_lock, flags); __cache_delete(__cache_find(id)); - mutex_unlock(&cache_lock); + spin_unlock_irqrestore(&cache_lock, flags); } int cache_find(int id, char *name) { struct object *obj; int ret = -ENOENT; + unsigned long flags; - mutex_lock(&cache_lock); + spin_lock_irqsave(&cache_lock, flags); obj = __cache_find(id); if (obj) { ret = 0; strscpy(name, obj->name); } - mutex_unlock(&cache_lock); + spin_unlock_irqrestore(&cache_lock, flags); return ret; }}hjHsbah}(h]h ]h"]h$]h&]jjuh1j}hhhMhjhhubh)}(hNote that the spin_lock_irqsave() will turn off interrupts if they are on, otherwise does nothing (if we are already in an interrupt handler), hence these functions are safe to call from any context.h]hNote that the spin_lock_irqsave() will turn off interrupts if they are on, otherwise does nothing (if we are already in an interrupt handler), hence these functions are safe to call from any context.}(hjVhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM3hjhhubh)}(hUnfortunately, cache_add() calls kmalloc() with the ``GFP_KERNEL`` flag, which is only legal in user context. I have assumed that cache_add() is still only called in user context, otherwise this should become a parameter to cache_add().h](h4Unfortunately, cache_add() calls kmalloc() with the }(hjdhhhNhNubjI)}(h``GFP_KERNEL``h]h GFP_KERNEL}(hjlhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjdubh flag, which is only legal in user context. I have assumed that cache_add() is still only called in user context, otherwise this should become a parameter to cache_add().}(hjdhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM8hjhhubeh}(h] accessing-from-interrupt-contextah ]h"] accessing from interrupt contextah$]h&]uh1hhjhhhhhMubh)}(hhh](h)}(h"Exposing Objects Outside This Fileh]h"Exposing Objects Outside This File}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhM?ubh)}(hXIf our objects contained more information, it might not be sufficient to copy the information in and out: other parts of the code might want to keep pointers to these objects, for example, rather than looking up the id every time. This produces two problems.h]hXIf our objects contained more information, it might not be sufficient to copy the information in and out: other parts of the code might want to keep pointers to these objects, for example, rather than looking up the id every time. This produces two problems.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMAhjhhubh)}(hThe first problem is that we use the ``cache_lock`` to protect objects: we'd need to make this non-static so the rest of the code can use it. This makes locking trickier, as it is no longer all in one place.h](h%The first problem is that we use the }(hjhhhNhNubjI)}(h``cache_lock``h]h cache_lock}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjubh to protect objects: we’d need to make this non-static so the rest of the code can use it. This makes locking trickier, as it is no longer all in one place.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMFhjhhubh)}(hX=The second problem is the lifetime problem: if another structure keeps a pointer to an object, it presumably expects that pointer to remain valid. Unfortunately, this is only guaranteed while you hold the lock, otherwise someone might call cache_delete() and even worse, add another object, re-using the same address.h]hX=The second problem is the lifetime problem: if another structure keeps a pointer to an object, it presumably expects that pointer to remain valid. Unfortunately, this is only guaranteed while you hold the lock, otherwise someone might call cache_delete() and even worse, add another object, re-using the same address.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMJhjhhubh)}(hZAs there is only one lock, you can't hold it forever: no-one else would get any work done.h]h\As there is only one lock, you can’t hold it forever: no-one else would get any work done.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMPhjhhubh)}(hXThe solution to this problem is to use a reference count: everyone who has a pointer to the object increases it when they first get the object, and drops the reference count when they're finished with it. Whoever drops it to zero knows it is unused, and can actually delete it.h]hXThe solution to this problem is to use a reference count: everyone who has a pointer to the object increases it when they first get the object, and drops the reference count when they’re finished with it. Whoever drops it to zero knows it is unused, and can actually delete it.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMShjhhubh)}(hHere is the code::h]hHere is the code:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMXhjhhubj~)}(hX--- cache.c.interrupt 2003-12-09 14:25:43.000000000 +1100 +++ cache.c.refcnt 2003-12-09 14:33:05.000000000 +1100 @@ -7,6 +7,7 @@ struct object { struct list_head list; + unsigned int refcnt; int id; char name[32]; int popularity; @@ -17,6 +18,35 @@ static unsigned int cache_num = 0; #define MAX_CACHE_SIZE 10 +static void __object_put(struct object *obj) +{ + if (--obj->refcnt == 0) + kfree(obj); +} + +static void __object_get(struct object *obj) +{ + obj->refcnt++; +} + +void object_put(struct object *obj) +{ + unsigned long flags; + + spin_lock_irqsave(&cache_lock, flags); + __object_put(obj); + spin_unlock_irqrestore(&cache_lock, flags); +} + +void object_get(struct object *obj) +{ + unsigned long flags; + + spin_lock_irqsave(&cache_lock, flags); + __object_get(obj); + spin_unlock_irqrestore(&cache_lock, flags); +} + /* Must be holding cache_lock */ static struct object *__cache_find(int id) { @@ -35,6 +65,7 @@ { BUG_ON(!obj); list_del(&obj->list); + __object_put(obj); cache_num--; } @@ -63,6 +94,7 @@ strscpy(obj->name, name, sizeof(obj->name)); obj->id = id; obj->popularity = 0; + obj->refcnt = 1; /* The cache holds a reference */ spin_lock_irqsave(&cache_lock, flags); __cache_add(obj); @@ -79,18 +111,15 @@ spin_unlock_irqrestore(&cache_lock, flags); } -int cache_find(int id, char *name) +struct object *cache_find(int id) { struct object *obj; - int ret = -ENOENT; unsigned long flags; spin_lock_irqsave(&cache_lock, flags); obj = __cache_find(id); - if (obj) { - ret = 0; - strscpy(name, obj->name); - } + if (obj) + __object_get(obj); spin_unlock_irqrestore(&cache_lock, flags); - return ret; + return obj; }h]hX--- cache.c.interrupt 2003-12-09 14:25:43.000000000 +1100 +++ cache.c.refcnt 2003-12-09 14:33:05.000000000 +1100 @@ -7,6 +7,7 @@ struct object { struct list_head list; + unsigned int refcnt; int id; char name[32]; int popularity; @@ -17,6 +18,35 @@ static unsigned int cache_num = 0; #define MAX_CACHE_SIZE 10 +static void __object_put(struct object *obj) +{ + if (--obj->refcnt == 0) + kfree(obj); +} + +static void __object_get(struct object *obj) +{ + obj->refcnt++; +} + +void object_put(struct object *obj) +{ + unsigned long flags; + + spin_lock_irqsave(&cache_lock, flags); + __object_put(obj); + spin_unlock_irqrestore(&cache_lock, flags); +} + +void object_get(struct object *obj) +{ + unsigned long flags; + + spin_lock_irqsave(&cache_lock, flags); + __object_get(obj); + spin_unlock_irqrestore(&cache_lock, flags); +} + /* Must be holding cache_lock */ static struct object *__cache_find(int id) { @@ -35,6 +65,7 @@ { BUG_ON(!obj); list_del(&obj->list); + __object_put(obj); cache_num--; } @@ -63,6 +94,7 @@ strscpy(obj->name, name, sizeof(obj->name)); obj->id = id; obj->popularity = 0; + obj->refcnt = 1; /* The cache holds a reference */ spin_lock_irqsave(&cache_lock, flags); __cache_add(obj); @@ -79,18 +111,15 @@ spin_unlock_irqrestore(&cache_lock, flags); } -int cache_find(int id, char *name) +struct object *cache_find(int id) { struct object *obj; - int ret = -ENOENT; unsigned long flags; spin_lock_irqsave(&cache_lock, flags); obj = __cache_find(id); - if (obj) { - ret = 0; - strscpy(name, obj->name); - } + if (obj) + __object_get(obj); spin_unlock_irqrestore(&cache_lock, flags); - return ret; + return obj; }}hjsbah}(h]h ]h"]h$]h&]jjuh1j}hhhMZhjhhubh)}(hWe encapsulate the reference counting in the standard 'get' and 'put' functions. Now we can return the object itself from cache_find() which has the advantage that the user can now sleep holding the object (eg. to copy_to_user() to name to userspace).h]hXWe encapsulate the reference counting in the standard ‘get’ and ‘put’ functions. Now we can return the object itself from cache_find() which has the advantage that the user can now sleep holding the object (eg. to copy_to_user() to name to userspace).}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hXThe other point to note is that I said a reference should be held for every pointer to the object: thus the reference count is 1 when first inserted into the cache. In some versions the framework does not hold a reference count, but they are more complicated.h]hXThe other point to note is that I said a reference should be held for every pointer to the object: thus the reference count is 1 when first inserted into the cache. In some versions the framework does not hold a reference count, but they are more complicated.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hhh](h)}(h/Using Atomic Operations For The Reference Counth]h/Using Atomic Operations For The Reference Count}(hj0hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj-hhhhhMubh)}(hXIn practice, :c:type:`atomic_t` would usually be used for refcnt. There are a number of atomic operations defined in ``include/asm/atomic.h``: these are guaranteed to be seen atomically from all CPUs in the system, so no lock is required. In this case, it is simpler than using spinlocks, although for anything non-trivial using spinlocks is clearer. The atomic_inc() and atomic_dec_and_test() are used instead of the standard increment and decrement operators, and the lock is no longer used to protect the reference count itself.h](h In practice, }(hj>hhhNhNubh)}(h:c:type:`atomic_t`h]jI)}(hjHh]hatomic_t}(hjJhhhNhNubah}(h]h ](xrefcc-typeeh"]h$]h&]uh1jHhjFubah}(h]h ]h"]h$]h&]refdockernel-hacking/locking refdomainjUreftypetype refexplicitrefwarn reftargetatomic_tuh1hhhhMhj>ubhV would usually be used for refcnt. There are a number of atomic operations defined in }(hj>hhhNhNubjI)}(h``include/asm/atomic.h``h]hinclude/asm/atomic.h}(hjmhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj>ubhX: these are guaranteed to be seen atomically from all CPUs in the system, so no lock is required. In this case, it is simpler than using spinlocks, although for anything non-trivial using spinlocks is clearer. The atomic_inc() and atomic_dec_and_test() are used instead of the standard increment and decrement operators, and the lock is no longer used to protect the reference count itself.}(hj>hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj-hhubj~)}(hXg--- cache.c.refcnt 2003-12-09 15:00:35.000000000 +1100 +++ cache.c.refcnt-atomic 2003-12-11 15:49:42.000000000 +1100 @@ -7,7 +7,7 @@ struct object { struct list_head list; - unsigned int refcnt; + atomic_t refcnt; int id; char name[32]; int popularity; @@ -18,33 +18,15 @@ static unsigned int cache_num = 0; #define MAX_CACHE_SIZE 10 -static void __object_put(struct object *obj) -{ - if (--obj->refcnt == 0) - kfree(obj); -} - -static void __object_get(struct object *obj) -{ - obj->refcnt++; -} - void object_put(struct object *obj) { - unsigned long flags; - - spin_lock_irqsave(&cache_lock, flags); - __object_put(obj); - spin_unlock_irqrestore(&cache_lock, flags); + if (atomic_dec_and_test(&obj->refcnt)) + kfree(obj); } void object_get(struct object *obj) { - unsigned long flags; - - spin_lock_irqsave(&cache_lock, flags); - __object_get(obj); - spin_unlock_irqrestore(&cache_lock, flags); + atomic_inc(&obj->refcnt); } /* Must be holding cache_lock */ @@ -65,7 +47,7 @@ { BUG_ON(!obj); list_del(&obj->list); - __object_put(obj); + object_put(obj); cache_num--; } @@ -94,7 +76,7 @@ strscpy(obj->name, name, sizeof(obj->name)); obj->id = id; obj->popularity = 0; - obj->refcnt = 1; /* The cache holds a reference */ + atomic_set(&obj->refcnt, 1); /* The cache holds a reference */ spin_lock_irqsave(&cache_lock, flags); __cache_add(obj); @@ -119,7 +101,7 @@ spin_lock_irqsave(&cache_lock, flags); obj = __cache_find(id); if (obj) - __object_get(obj); + object_get(obj); spin_unlock_irqrestore(&cache_lock, flags); return obj; }h]hXg--- cache.c.refcnt 2003-12-09 15:00:35.000000000 +1100 +++ cache.c.refcnt-atomic 2003-12-11 15:49:42.000000000 +1100 @@ -7,7 +7,7 @@ struct object { struct list_head list; - unsigned int refcnt; + atomic_t refcnt; int id; char name[32]; int popularity; @@ -18,33 +18,15 @@ static unsigned int cache_num = 0; #define MAX_CACHE_SIZE 10 -static void __object_put(struct object *obj) -{ - if (--obj->refcnt == 0) - kfree(obj); -} - -static void __object_get(struct object *obj) -{ - obj->refcnt++; -} - void object_put(struct object *obj) { - unsigned long flags; - - spin_lock_irqsave(&cache_lock, flags); - __object_put(obj); - spin_unlock_irqrestore(&cache_lock, flags); + if (atomic_dec_and_test(&obj->refcnt)) + kfree(obj); } void object_get(struct object *obj) { - unsigned long flags; - - spin_lock_irqsave(&cache_lock, flags); - __object_get(obj); - spin_unlock_irqrestore(&cache_lock, flags); + atomic_inc(&obj->refcnt); } /* Must be holding cache_lock */ @@ -65,7 +47,7 @@ { BUG_ON(!obj); list_del(&obj->list); - __object_put(obj); + object_put(obj); cache_num--; } @@ -94,7 +76,7 @@ strscpy(obj->name, name, sizeof(obj->name)); obj->id = id; obj->popularity = 0; - obj->refcnt = 1; /* The cache holds a reference */ + atomic_set(&obj->refcnt, 1); /* The cache holds a reference */ spin_lock_irqsave(&cache_lock, flags); __cache_add(obj); @@ -119,7 +101,7 @@ spin_lock_irqsave(&cache_lock, flags); obj = __cache_find(id); if (obj) - __object_get(obj); + object_get(obj); spin_unlock_irqrestore(&cache_lock, flags); return obj; }}hjsbah}(h]h ]h"]h$]h&]jjuh1j}hhhMhj-hhubeh}(h]/using-atomic-operations-for-the-reference-countah ]h"]/using atomic operations for the reference countah$]h&]uh1hhjhhhhhMubeh}(h]"exposing-objects-outside-this-fileah ]h"]"exposing objects outside this fileah$]h&]uh1hhjhhhhhM?ubh)}(hhh](h)}(h!Protecting The Objects Themselvesh]h!Protecting The Objects Themselves}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hIn these examples, we assumed that the objects (except the reference counts) never changed once they are created. If we wanted to allow the name to change, there are three possibilities:h]hIn these examples, we assumed that the objects (except the reference counts) never changed once they are created. If we wanted to allow the name to change, there are three possibilities:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj )}(hhh](j )}(hrYou can make ``cache_lock`` non-static, and tell people to grab that lock before changing the name in any object. h]h)}(hqYou can make ``cache_lock`` non-static, and tell people to grab that lock before changing the name in any object.h](h You can make }(hjhhhNhNubjI)}(h``cache_lock``h]h cache_lock}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjubhV non-static, and tell people to grab that lock before changing the name in any object.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1j hjhhhhhNubj )}(hYou can provide a cache_obj_rename() which grabs this lock and changes the name for the caller, and tell everyone to use that function. h]h)}(hYou can provide a cache_obj_rename() which grabs this lock and changes the name for the caller, and tell everyone to use that function.h]hYou can provide a cache_obj_rename() which grabs this lock and changes the name for the caller, and tell everyone to use that function.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1j hjhhhhhNubj )}(hiYou can make the ``cache_lock`` protect only the cache itself, and use another lock to protect the name. h]h)}(hhYou can make the ``cache_lock`` protect only the cache itself, and use another lock to protect the name.h](hYou can make the }(hj hhhNhNubjI)}(h``cache_lock``h]h cache_lock}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj ubhI protect only the cache itself, and use another lock to protect the name.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM#hjubah}(h]h ]h"]h$]h&]uh1j hjhhhhhNubeh}(h]h ]h"]h$]h&]j5 j6 uh1j hhhMhjhhubh)}(hTheoretically, you can make the locks as fine-grained as one lock for every field, for every object. In practice, the most common variants are:h]hTheoretically, you can make the locks as fine-grained as one lock for every field, for every object. In practice, the most common variants are:}(hj7hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM&hjhhubj )}(hhh](j )}(hOne lock which protects the infrastructure (the ``cache`` list in this example) and all the objects. This is what we have done so far. h]h)}(hOne lock which protects the infrastructure (the ``cache`` list in this example) and all the objects. This is what we have done so far.h](h0One lock which protects the infrastructure (the }(hjLhhhNhNubjI)}(h ``cache``h]hcache}(hjThhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjLubhM list in this example) and all the objects. This is what we have done so far.}(hjLhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM*hjHubah}(h]h ]h"]h$]h&]uh1j hjEhhhhhNubj )}(hOne lock which protects the infrastructure (including the list pointers inside the objects), and one lock inside the object which protects the rest of that object. h]h)}(hOne lock which protects the infrastructure (including the list pointers inside the objects), and one lock inside the object which protects the rest of that object.h]hOne lock which protects the infrastructure (including the list pointers inside the objects), and one lock inside the object which protects the rest of that object.}(hjvhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM-hjrubah}(h]h ]h"]h$]h&]uh1j hjEhhhhhNubj )}(hvMultiple locks to protect the infrastructure (eg. one lock per hash chain), possibly with a separate per-object lock. h]h)}(huMultiple locks to protect the infrastructure (eg. one lock per hash chain), possibly with a separate per-object lock.h]huMultiple locks to protect the infrastructure (eg. one lock per hash chain), possibly with a separate per-object lock.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM1hjubah}(h]h ]h"]h$]h&]uh1j hjEhhhhhNubeh}(h]h ]h"]h$]h&]j5 j6 uh1j hhhM*hjhhubh)}(h-Here is the "lock-per-object" implementation:h]h1Here is the “lock-per-object” implementation:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM4hjhhubj~)}(hX--- cache.c.refcnt-atomic 2003-12-11 15:50:54.000000000 +1100 +++ cache.c.perobjectlock 2003-12-11 17:15:03.000000000 +1100 @@ -6,11 +6,17 @@ struct object { + /* These two protected by cache_lock. */ struct list_head list; + int popularity; + atomic_t refcnt; + + /* Doesn't change once created. */ int id; + + spinlock_t lock; /* Protects the name */ char name[32]; - int popularity; }; static DEFINE_SPINLOCK(cache_lock); @@ -77,6 +84,7 @@ obj->id = id; obj->popularity = 0; atomic_set(&obj->refcnt, 1); /* The cache holds a reference */ + spin_lock_init(&obj->lock); spin_lock_irqsave(&cache_lock, flags); __cache_add(obj);h]hX--- cache.c.refcnt-atomic 2003-12-11 15:50:54.000000000 +1100 +++ cache.c.perobjectlock 2003-12-11 17:15:03.000000000 +1100 @@ -6,11 +6,17 @@ struct object { + /* These two protected by cache_lock. */ struct list_head list; + int popularity; + atomic_t refcnt; + + /* Doesn't change once created. */ int id; + + spinlock_t lock; /* Protects the name */ char name[32]; - int popularity; }; static DEFINE_SPINLOCK(cache_lock); @@ -77,6 +84,7 @@ obj->id = id; obj->popularity = 0; atomic_set(&obj->refcnt, 1); /* The cache holds a reference */ + spin_lock_init(&obj->lock); spin_lock_irqsave(&cache_lock, flags); __cache_add(obj);}hjsbah}(h]h ]h"]h$]h&]jjuh1j}hhhM8hjhhubh)}(hX`Note that I decide that the popularity count should be protected by the ``cache_lock`` rather than the per-object lock: this is because it (like the :c:type:`struct list_head ` inside the object) is logically part of the infrastructure. This way, I don't need to grab the lock of every object in __cache_add() when seeking the least popular.h](hHNote that I decide that the popularity count should be protected by the }(hjhhhNhNubjI)}(h``cache_lock``h]h cache_lock}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjubh? rather than the per-object lock: this is because it (like the }(hjhhhNhNubh)}(h&:c:type:`struct list_head `h]jI)}(hjh]hstruct list_head}(hjhhhNhNubah}(h]h ](jTjUc-typeeh"]h$]h&]uh1jHhjubah}(h]h ]h"]h$]h&]refdocja refdomainjUreftypetype refexplicitrefwarnjg list_headuh1hhhhMVhjubh inside the object) is logically part of the infrastructure. This way, I don’t need to grab the lock of every object in __cache_add() when seeking the least popular.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMVhjhhubh)}(hI also decided that the id member is unchangeable, so I don't need to grab each object lock in __cache_find() to examine the id: the object lock is only used by a caller who wants to read or write the name field.h]hI also decided that the id member is unchangeable, so I don’t need to grab each object lock in __cache_find() to examine the id: the object lock is only used by a caller who wants to read or write the name field.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM]hjhhubh)}(hNote also that I added a comment describing what data was protected by which locks. This is extremely important, as it describes the runtime behavior of the code, and can be hard to gain from just reading. And as Alan Cox says, “Lock data, not code”.h]hNote also that I added a comment describing what data was protected by which locks. This is extremely important, as it describes the runtime behavior of the code, and can be hard to gain from just reading. And as Alan Cox says, “Lock data, not code”.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMbhjhhubeh}(h]!protecting-the-objects-themselvesah ]h"]!protecting the objects themselvesah$]h&]uh1hhjhhhhhMubeh}(h]common-examplesah ]h"]common examplesah$]h&]uh1hhhhhhhhMtubh)}(hhh](h)}(hCommon Problemsh]hCommon Problems}(hj6hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj3hhhhhMhubh)}(hhh](h)}(hDeadlock: Simple and Advancedh]hDeadlock: Simple and Advanced}(hjGhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjDhhhhhMkubh)}(hX&There is a coding bug where a piece of code tries to grab a spinlock twice: it will spin forever, waiting for the lock to be released (spinlocks, rwlocks and mutexes are not recursive in Linux). This is trivial to diagnose: not a stay-up-five-nights-talk-to-fluffy-code-bunnies kind of problem.h]hX&There is a coding bug where a piece of code tries to grab a spinlock twice: it will spin forever, waiting for the lock to be released (spinlocks, rwlocks and mutexes are not recursive in Linux). This is trivial to diagnose: not a stay-up-five-nights-talk-to-fluffy-code-bunnies kind of problem.}(hjUhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMmhjDhhubh)}(hX3For a slightly more complex case, imagine you have a region shared by a softirq and user context. If you use a spin_lock() call to protect it, it is possible that the user context will be interrupted by the softirq while it holds the lock, and the softirq will then spin forever trying to get the same lock.h]hX3For a slightly more complex case, imagine you have a region shared by a softirq and user context. If you use a spin_lock() call to protect it, it is possible that the user context will be interrupted by the softirq while it holds the lock, and the softirq will then spin forever trying to get the same lock.}(hjchhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMshjDhhubh)}(hBoth of these are called deadlock, and as shown above, it can occur even with a single CPU (although not on UP compiles, since spinlocks vanish on kernel compiles with ``CONFIG_SMP``\ =n. You'll still get data corruption in the second example).h](hBoth of these are called deadlock, and as shown above, it can occur even with a single CPU (although not on UP compiles, since spinlocks vanish on kernel compiles with }(hjqhhhNhNubjI)}(h``CONFIG_SMP``h]h CONFIG_SMP}(hjyhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjqubh@ =n. You’ll still get data corruption in the second example).}(hjqhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMyhjDhhubh)}(hThis complete lockup is easy to diagnose: on SMP boxes the watchdog timer or compiling with ``DEBUG_SPINLOCK`` set (``include/linux/spinlock.h``) will show this up immediately when it happens.h](h\This complete lockup is easy to diagnose: on SMP boxes the watchdog timer or compiling with }(hjhhhNhNubjI)}(h``DEBUG_SPINLOCK``h]hDEBUG_SPINLOCK}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjubh set (}(hjhhhNhNubjI)}(h``include/linux/spinlock.h``h]hinclude/linux/spinlock.h}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjubh0) will show this up immediately when it happens.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM~hjDhhubh)}(hXA more complex problem is the so-called 'deadly embrace', involving two or more locks. Say you have a hash table: each entry in the table is a spinlock, and a chain of hashed objects. Inside a softirq handler, you sometimes want to alter an object from one place in the hash to another: you grab the spinlock of the old hash chain and the spinlock of the new hash chain, and delete the object from the old one, and insert it in the new one.h]hXA more complex problem is the so-called ‘deadly embrace’, involving two or more locks. Say you have a hash table: each entry in the table is a spinlock, and a chain of hashed objects. Inside a softirq handler, you sometimes want to alter an object from one place in the hash to another: you grab the spinlock of the old hash chain and the spinlock of the new hash chain, and delete the object from the old one, and insert it in the new one.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjDhhubh)}(hX There are two problems here. First, if your code ever tries to move the object to the same chain, it will deadlock with itself as it tries to lock it twice. Secondly, if the same softirq on another CPU is trying to move another object in the reverse direction, the following could happen:h]hX There are two problems here. First, if your code ever tries to move the object to the same chain, it will deadlock with itself as it tries to lock it twice. Secondly, if the same softirq on another CPU is trying to move another object in the reverse direction, the following could happen:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjDhhubj)}(hhh]j)}(hhh](j)}(hhh]h}(h]h ]h"]h$]h&]colwidthKuh1jhjubj)}(hhh]h}(h]h ]h"]h$]h&]colwidthKuh1jhjubj)}(hhh]j)}(hhh](j)}(hhh]h)}(hCPU 1h]hCPU 1}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hCPU 2h]hCPU 2}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh](j)}(hhh](j)}(hhh]h)}(hGrab lock A -> OKh]hGrab lock A -> OK}(hjBhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj?ubah}(h]h ]h"]h$]h&]uh1jhj<ubj)}(hhh]h)}(hGrab lock B -> OKh]hGrab lock B -> OK}(hjYhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjVubah}(h]h ]h"]h$]h&]uh1jhj<ubeh}(h]h ]h"]h$]h&]uh1jhj9ubj)}(hhh](j)}(hhh]h)}(hGrab lock B -> spinh]hGrab lock B -> spin}(hjyhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjvubah}(h]h ]h"]h$]h&]uh1jhjsubj)}(hhh]h)}(hGrab lock A -> spinh]hGrab lock A -> spin}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1jhjsubeh}(h]h ]h"]h$]h&]uh1jhj9ubeh}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]colsKuh1jhjubah}(h]h ]h"]h$]h&]uh1jhjDhhhhhNubh)}(hTable: Consequencesh]hTable: Consequences}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjDhhubh)}(hxThe two CPUs will spin forever, waiting for the other to give up their lock. It will look, smell, and feel like a crash.h]hxThe two CPUs will spin forever, waiting for the other to give up their lock. It will look, smell, and feel like a crash.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjDhhubeh}(h]jah ]h"]deadlock: simple and advancedah$]h&]uh1hhj3hhhhhMkj Kubh)}(hhh](h)}(hPreventing Deadlockh]hPreventing Deadlock}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hX#Textbooks will tell you that if you always lock in the same order, you will never get this kind of deadlock. Practice will tell you that this approach doesn't scale: when I create a new lock, I don't understand enough of the kernel to figure out where in the 5000 lock hierarchy it will fit.h]hX'Textbooks will tell you that if you always lock in the same order, you will never get this kind of deadlock. Practice will tell you that this approach doesn’t scale: when I create a new lock, I don’t understand enough of the kernel to figure out where in the 5000 lock hierarchy it will fit.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hX_The best locks are encapsulated: they never get exposed in headers, and are never held around calls to non-trivial functions outside the same file. You can read through this code and see that it will never deadlock, because it never tries to grab another lock while it has that one. People using your code don't even need to know you are using a lock.h]hXaThe best locks are encapsulated: they never get exposed in headers, and are never held around calls to non-trivial functions outside the same file. You can read through this code and see that it will never deadlock, because it never tries to grab another lock while it has that one. People using your code don’t even need to know you are using a lock.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hA classic problem here is when you provide callbacks or hooks: if you call these with the lock held, you risk simple deadlock, or a deadly embrace (who knows what the callback will do?).h]hA classic problem here is when you provide callbacks or hooks: if you call these with the lock held, you risk simple deadlock, or a deadly embrace (who knows what the callback will do?).}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hhh](h)}(h#Overzealous Prevention Of Deadlocksh]h#Overzealous Prevention Of Deadlocks}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hDeadlocks are problematic, but not as bad as data corruption. Code which grabs a read lock, searches a list, fails to find what it wants, drops the read lock, grabs a write lock and inserts the object has a race condition.h]hDeadlocks are problematic, but not as bad as data corruption. Code which grabs a read lock, searches a list, fails to find what it wants, drops the read lock, grabs a write lock and inserts the object has a race condition.}(hj,hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubeh}(h]#overzealous-prevention-of-deadlocksah ]h"]#overzealous prevention of deadlocksah$]h&]uh1hhjhhhhhMubeh}(h]preventing-deadlockah ]h"]preventing deadlockah$]h&]uh1hhj3hhhhhMubh)}(hhh](h)}(hRacing Timers: A Kernel Pastimeh]hRacing Timers: A Kernel Pastime}(hjMhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjJhhhhhMubh)}(hTimers can produce their own special problems with races. Consider a collection of objects (list, hash, etc) where each object has a timer which is due to destroy it.h]hTimers can produce their own special problems with races. Consider a collection of objects (list, hash, etc) where each object has a timer which is due to destroy it.}(hj[hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjJhhubh)}(hbIf you want to destroy the entire collection (say on module removal), you might do the following::h]haIf you want to destroy the entire collection (say on module removal), you might do the following:}(hjihhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjJhhubj~)}(hX/* THIS CODE BAD BAD BAD BAD: IF IT WAS ANY WORSE IT WOULD USE HUNGARIAN NOTATION */ spin_lock_bh(&list_lock); while (list) { struct foo *next = list->next; timer_delete(&list->timer); kfree(list); list = next; } spin_unlock_bh(&list_lock);h]hX/* THIS CODE BAD BAD BAD BAD: IF IT WAS ANY WORSE IT WOULD USE HUNGARIAN NOTATION */ spin_lock_bh(&list_lock); while (list) { struct foo *next = list->next; timer_delete(&list->timer); kfree(list); list = next; } spin_unlock_bh(&list_lock);}hjwsbah}(h]h ]h"]h$]h&]jjuh1j}hhhMhjJhhubh)}(hSooner or later, this will crash on SMP, because a timer can have just gone off before the spin_lock_bh(), and it will only get the lock after we spin_unlock_bh(), and then try to free the element (which has already been freed!).h]hSooner or later, this will crash on SMP, because a timer can have just gone off before the spin_lock_bh(), and it will only get the lock after we spin_unlock_bh(), and then try to free the element (which has already been freed!).}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjJhhubh)}(hThis can be avoided by checking the result of timer_delete(): if it returns 1, the timer has been deleted. If 0, it means (in this case) that it is currently running, so we can do::h]hThis can be avoided by checking the result of timer_delete(): if it returns 1, the timer has been deleted. If 0, it means (in this case) that it is currently running, so we can do:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjJhhubj~)}(hXretry: spin_lock_bh(&list_lock); while (list) { struct foo *next = list->next; if (!timer_delete(&list->timer)) { /* Give timer a chance to delete this */ spin_unlock_bh(&list_lock); goto retry; } kfree(list); list = next; } spin_unlock_bh(&list_lock);h]hXretry: spin_lock_bh(&list_lock); while (list) { struct foo *next = list->next; if (!timer_delete(&list->timer)) { /* Give timer a chance to delete this */ spin_unlock_bh(&list_lock); goto retry; } kfree(list); list = next; } spin_unlock_bh(&list_lock);}hjsbah}(h]h ]h"]h$]h&]jjuh1j}hhhMhjJhhubh)}(hXAnother common problem is deleting timers which restart themselves (by calling add_timer() at the end of their timer function). Because this is a fairly common case which is prone to races, you should use timer_delete_sync() (``include/linux/timer.h``) to handle this case.h](hAnother common problem is deleting timers which restart themselves (by calling add_timer() at the end of their timer function). Because this is a fairly common case which is prone to races, you should use timer_delete_sync() (}(hjhhhNhNubjI)}(h``include/linux/timer.h``h]hinclude/linux/timer.h}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjubh) to handle this case.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjJhhubh)}(hBefore freeing a timer, timer_shutdown() or timer_shutdown_sync() should be called which will keep it from being rearmed. Any subsequent attempt to rearm the timer will be silently ignored by the core code.h]hBefore freeing a timer, timer_shutdown() or timer_shutdown_sync() should be called which will keep it from being rearmed. Any subsequent attempt to rearm the timer will be silently ignored by the core code.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjJhhubeh}(h]racing-timers-a-kernel-pastimeah ]h"]racing timers: a kernel pastimeah$]h&]uh1hhj3hhhhhMubeh}(h]common-problemsah ]h"]common problemsah$]h&]uh1hhhhhhhhMhubh)}(hhh](h)}(h Locking Speedh]h Locking Speed}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hXThere are three main things to worry about when considering speed of some code which does locking. First is concurrency: how many things are going to be waiting while someone else is holding a lock. Second is the time taken to actually acquire and release an uncontended lock. Third is using fewer, or smarter locks. I'm assuming that the lock is used fairly often: otherwise, you wouldn't be concerned about efficiency.h]hXThere are three main things to worry about when considering speed of some code which does locking. First is concurrency: how many things are going to be waiting while someone else is holding a lock. Second is the time taken to actually acquire and release an uncontended lock. Third is using fewer, or smarter locks. I’m assuming that the lock is used fairly often: otherwise, you wouldn’t be concerned about efficiency.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hX Concurrency depends on how long the lock is usually held: you should hold the lock for as long as needed, but no longer. In the cache example, we always create the object without the lock held, and then grab the lock only when we are ready to insert it in the list.h]hX Concurrency depends on how long the lock is usually held: you should hold the lock for as long as needed, but no longer. In the cache example, we always create the object without the lock held, and then grab the lock only when we are ready to insert it in the list.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hXoAcquisition times depend on how much damage the lock operations do to the pipeline (pipeline stalls) and how likely it is that this CPU was the last one to grab the lock (ie. is the lock cache-hot for this CPU): on a machine with more CPUs, this likelihood drops fast. Consider a 700MHz Intel Pentium III: an instruction takes about 0.7ns, an atomic increment takes about 58ns, a lock which is cache-hot on this CPU takes 160ns, and a cacheline transfer from another CPU takes an additional 170 to 360ns. (These figures from Paul McKenney's `Linux Journal RCU article `__).h](hXAcquisition times depend on how much damage the lock operations do to the pipeline (pipeline stalls) and how likely it is that this CPU was the last one to grab the lock (ie. is the lock cache-hot for this CPU): on a machine with more CPUs, this likelihood drops fast. Consider a 700MHz Intel Pentium III: an instruction takes about 0.7ns, an atomic increment takes about 58ns, a lock which is cache-hot on this CPU takes 160ns, and a cacheline transfer from another CPU takes an additional 170 to 360ns. (These figures from Paul McKenney’s }(hjhhhNhNubj})}(hP`Linux Journal RCU article `__h]hLinux Journal RCU article}(hj"hhhNhNubah}(h]h ]h"]h$]h&]nameLinux Journal RCU articlerefuri0http://www.linuxjournal.com/article.php?sid=6993uh1j|hjubh).}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hX;These two aims conflict: holding a lock for a short time might be done by splitting locks into parts (such as in our final per-object-lock example), but this increases the number of lock acquisitions, and the results are often slower than having a single lock. This is another reason to advocate locking simplicity.h]hX;These two aims conflict: holding a lock for a short time might be done by splitting locks into parts (such as in our final per-object-lock example), but this increases the number of lock acquisitions, and the results are often slower than having a single lock. This is another reason to advocate locking simplicity.}(hj>hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(htThe third concern is addressed below: there are some methods to reduce the amount of locking which needs to be done.h]htThe third concern is addressed below: there are some methods to reduce the amount of locking which needs to be done.}(hjLhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hhh](h)}(hRead/Write Lock Variantsh]hRead/Write Lock Variants}(hj]hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjZhhhhhMubh)}(hXfBoth spinlocks and mutexes have read/write variants: ``rwlock_t`` and :c:type:`struct rw_semaphore `. These divide users into two classes: the readers and the writers. If you are only reading the data, you can get a read lock, but to write to the data you need the write lock. Many people can hold a read lock, but a writer must be sole holder.h](h5Both spinlocks and mutexes have read/write variants: }(hjkhhhNhNubjI)}(h ``rwlock_t``h]hrwlock_t}(hjshhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjkubh and }(hjkhhhNhNubh)}(h,:c:type:`struct rw_semaphore `h]jI)}(hjh]hstruct rw_semaphore}(hjhhhNhNubah}(h]h ](jTjUc-typeeh"]h$]h&]uh1jHhjubah}(h]h ]h"]h$]h&]refdocja refdomainjUreftypetype refexplicitrefwarnjg rw_semaphoreuh1hhhhMhjkubh. These divide users into two classes: the readers and the writers. If you are only reading the data, you can get a read lock, but to write to the data you need the write lock. Many people can hold a read lock, but a writer must be sole holder.}(hjkhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjZhhubh)}(hXIf your code divides neatly along reader/writer lines (as our cache code does), and the lock is held by readers for significant lengths of time, using these locks can help. They are slightly slower than the normal locks though, so in practice ``rwlock_t`` is not usually worthwhile.h](hIf your code divides neatly along reader/writer lines (as our cache code does), and the lock is held by readers for significant lengths of time, using these locks can help. They are slightly slower than the normal locks though, so in practice }(hjhhhNhNubjI)}(h ``rwlock_t``h]hrwlock_t}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjubh is not usually worthwhile.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM#hjZhhubeh}(h]read-write-lock-variantsah ]h"]read/write lock variantsah$]h&]uh1hhjhhhhhMubh)}(hhh](h)}(h Avoiding Locks: Read Copy Updateh]h Avoiding Locks: Read Copy Update}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhM)ubh)}(hXThere is a special method of read/write locking called Read Copy Update. Using RCU, the readers can avoid taking a lock altogether: as we expect our cache to be read more often than updated (otherwise the cache is a waste of time), it is a candidate for this optimization.h]hXThere is a special method of read/write locking called Read Copy Update. Using RCU, the readers can avoid taking a lock altogether: as we expect our cache to be read more often than updated (otherwise the cache is a waste of time), it is a candidate for this optimization.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM+hjhhubh)}(hXLHow do we get rid of read locks? Getting rid of read locks means that writers may be changing the list underneath the readers. That is actually quite simple: we can read a linked list while an element is being added if the writer adds the element very carefully. For example, adding ``new`` to a single linked list called ``list``::h](hXHow do we get rid of read locks? Getting rid of read locks means that writers may be changing the list underneath the readers. That is actually quite simple: we can read a linked list while an element is being added if the writer adds the element very carefully. For example, adding }(hjhhhNhNubjI)}(h``new``h]hnew}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjubh to a single linked list called }(hjhhhNhNubjI)}(h``list``h]hlist}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjubh:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM0hjhhubj~)}(h0new->next = list->next; wmb(); list->next = new;h]h0new->next = list->next; wmb(); list->next = new;}hj'sbah}(h]h ]h"]h$]h&]jjuh1j}hhhM6hjhhubh)}(hXThe wmb() is a write memory barrier. It ensures that the first operation (setting the new element's ``next`` pointer) is complete and will be seen by all CPUs, before the second operation is (putting the new element into the list). This is important, since modern compilers and modern CPUs can both reorder instructions unless told otherwise: we want a reader to either not see the new element at all, or see the new element with the ``next`` pointer correctly pointing at the rest of the list.h](hfThe wmb() is a write memory barrier. It ensures that the first operation (setting the new element’s }(hj5hhhNhNubjI)}(h``next``h]hnext}(hj=hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj5ubhXF pointer) is complete and will be seen by all CPUs, before the second operation is (putting the new element into the list). This is important, since modern compilers and modern CPUs can both reorder instructions unless told otherwise: we want a reader to either not see the new element at all, or see the new element with the }(hj5hhhNhNubjI)}(h``next``h]hnext}(hjOhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj5ubh4 pointer correctly pointing at the rest of the list.}(hj5hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM;hjhhubh)}(hFortunately, there is a function to do this for standard :c:type:`struct list_head ` lists: list_add_rcu() (``include/linux/list.h``).h](h9Fortunately, there is a function to do this for standard }(hjghhhNhNubh)}(h&:c:type:`struct list_head `h]jI)}(hjqh]hstruct list_head}(hjshhhNhNubah}(h]h ](jTjUc-typeeh"]h$]h&]uh1jHhjoubah}(h]h ]h"]h$]h&]refdocja refdomainjUreftypetype refexplicitrefwarnjg list_headuh1hhhhMDhjgubh lists: list_add_rcu() (}(hjghhhNhNubjI)}(h``include/linux/list.h``h]hinclude/linux/list.h}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjgubh).}(hjghhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMDhjhhubh)}(hRemoving an element from the list is even simpler: we replace the pointer to the old element with a pointer to its successor, and readers will either see it, or skip over it.h]hRemoving an element from the list is even simpler: we replace the pointer to the old element with a pointer to its successor, and readers will either see it, or skip over it.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMHhjhhubj~)}(hlist->next = old->next;h]hlist->next = old->next;}hjsbah}(h]h ]h"]h$]h&]jjuh1j}hhhMNhjhhubh)}(hThere is list_del_rcu() (``include/linux/list.h``) which does this (the normal version poisons the old object, which we don't want).h](hThere is list_del_rcu() (}(hjhhhNhNubjI)}(h``include/linux/list.h``h]hinclude/linux/list.h}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjubhU) which does this (the normal version poisons the old object, which we don’t want).}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMQhjhhubh)}(hXThe reader must also be careful: some CPUs can look through the ``next`` pointer to start reading the contents of the next element early, but don't realize that the pre-fetched contents is wrong when the ``next`` pointer changes underneath them. Once again, there is a list_for_each_entry_rcu() (``include/linux/list.h``) to help you. Of course, writers can just use list_for_each_entry(), since there cannot be two simultaneous writers.h](h@The reader must also be careful: some CPUs can look through the }(hjhhhNhNubjI)}(h``next``h]hnext}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjubh pointer to start reading the contents of the next element early, but don’t realize that the pre-fetched contents is wrong when the }(hjhhhNhNubjI)}(h``next``h]hnext}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjubhT pointer changes underneath them. Once again, there is a list_for_each_entry_rcu() (}(hjhhhNhNubjI)}(h``include/linux/list.h``h]hinclude/linux/list.h}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjubhu) to help you. Of course, writers can just use list_for_each_entry(), since there cannot be two simultaneous writers.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMUhjhhubh)}(hXYOur final dilemma is this: when can we actually destroy the removed element? Remember, a reader might be stepping through this element in the list right now: if we free this element and the ``next`` pointer changes, the reader will jump off into garbage and crash. We need to wait until we know that all the readers who were traversing the list when we deleted the element are finished. We use call_rcu() to register a callback which will actually destroy the object once all pre-existing readers are finished. Alternatively, synchronize_rcu() may be used to block until all pre-existing are finished.h](hOur final dilemma is this: when can we actually destroy the removed element? Remember, a reader might be stepping through this element in the list right now: if we free this element and the }(hj*hhhNhNubjI)}(h``next``h]hnext}(hj2hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj*ubhX pointer changes, the reader will jump off into garbage and crash. We need to wait until we know that all the readers who were traversing the list when we deleted the element are finished. We use call_rcu() to register a callback which will actually destroy the object once all pre-existing readers are finished. Alternatively, synchronize_rcu() may be used to block until all pre-existing are finished.}(hj*hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM^hjhhubh)}(hX But how does Read Copy Update know when the readers are finished? The method is this: firstly, the readers always traverse the list inside rcu_read_lock()/rcu_read_unlock() pairs: these simply disable preemption so the reader won't go to sleep while reading the list.h]hX But how does Read Copy Update know when the readers are finished? The method is this: firstly, the readers always traverse the list inside rcu_read_lock()/rcu_read_unlock() pairs: these simply disable preemption so the reader won’t go to sleep while reading the list.}(hjJhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMihjhhubh)}(hX9RCU then waits until every other CPU has slept at least once: since readers cannot sleep, we know that any readers which were traversing the list during the deletion are finished, and the callback is triggered. The real Read Copy Update code is a little more optimized than this, but this is the fundamental idea.h]hX9RCU then waits until every other CPU has slept at least once: since readers cannot sleep, we know that any readers which were traversing the list during the deletion are finished, and the callback is triggered. The real Read Copy Update code is a little more optimized than this, but this is the fundamental idea.}(hjXhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMohjhhubj~)}(hX--- cache.c.perobjectlock 2003-12-11 17:15:03.000000000 +1100 +++ cache.c.rcupdate 2003-12-11 17:55:14.000000000 +1100 @@ -1,15 +1,18 @@ #include #include #include +#include #include #include struct object { - /* These two protected by cache_lock. */ + /* This is protected by RCU */ struct list_head list; int popularity; + struct rcu_head rcu; + atomic_t refcnt; /* Doesn't change once created. */ @@ -40,7 +43,7 @@ { struct object *i; - list_for_each_entry(i, &cache, list) { + list_for_each_entry_rcu(i, &cache, list) { if (i->id == id) { i->popularity++; return i; @@ -49,19 +52,25 @@ return NULL; } +/* Final discard done once we know no readers are looking. */ +static void cache_delete_rcu(void *arg) +{ + object_put(arg); +} + /* Must be holding cache_lock */ static void __cache_delete(struct object *obj) { BUG_ON(!obj); - list_del(&obj->list); - object_put(obj); + list_del_rcu(&obj->list); cache_num--; + call_rcu(&obj->rcu, cache_delete_rcu); } /* Must be holding cache_lock */ static void __cache_add(struct object *obj) { - list_add(&obj->list, &cache); + list_add_rcu(&obj->list, &cache); if (++cache_num > MAX_CACHE_SIZE) { struct object *i, *outcast = NULL; list_for_each_entry(i, &cache, list) { @@ -104,12 +114,11 @@ struct object *cache_find(int id) { struct object *obj; - unsigned long flags; - spin_lock_irqsave(&cache_lock, flags); + rcu_read_lock(); obj = __cache_find(id); if (obj) object_get(obj); - spin_unlock_irqrestore(&cache_lock, flags); + rcu_read_unlock(); return obj; }h]hX--- cache.c.perobjectlock 2003-12-11 17:15:03.000000000 +1100 +++ cache.c.rcupdate 2003-12-11 17:55:14.000000000 +1100 @@ -1,15 +1,18 @@ #include #include #include +#include #include #include struct object { - /* These two protected by cache_lock. */ + /* This is protected by RCU */ struct list_head list; int popularity; + struct rcu_head rcu; + atomic_t refcnt; /* Doesn't change once created. */ @@ -40,7 +43,7 @@ { struct object *i; - list_for_each_entry(i, &cache, list) { + list_for_each_entry_rcu(i, &cache, list) { if (i->id == id) { i->popularity++; return i; @@ -49,19 +52,25 @@ return NULL; } +/* Final discard done once we know no readers are looking. */ +static void cache_delete_rcu(void *arg) +{ + object_put(arg); +} + /* Must be holding cache_lock */ static void __cache_delete(struct object *obj) { BUG_ON(!obj); - list_del(&obj->list); - object_put(obj); + list_del_rcu(&obj->list); cache_num--; + call_rcu(&obj->rcu, cache_delete_rcu); } /* Must be holding cache_lock */ static void __cache_add(struct object *obj) { - list_add(&obj->list, &cache); + list_add_rcu(&obj->list, &cache); if (++cache_num > MAX_CACHE_SIZE) { struct object *i, *outcast = NULL; list_for_each_entry(i, &cache, list) { @@ -104,12 +114,11 @@ struct object *cache_find(int id) { struct object *obj; - unsigned long flags; - spin_lock_irqsave(&cache_lock, flags); + rcu_read_lock(); obj = __cache_find(id); if (obj) object_get(obj); - spin_unlock_irqrestore(&cache_lock, flags); + rcu_read_unlock(); return obj; }}hjfsbah}(h]h ]h"]h$]h&]jjuh1j}hhhMwhjhhubh)}(hX Note that the reader will alter the popularity member in __cache_find(), and now it doesn't hold a lock. One solution would be to make it an ``atomic_t``, but for this usage, we don't really care about races: an approximate result is good enough, so I didn't change it.h](hNote that the reader will alter the popularity member in __cache_find(), and now it doesn’t hold a lock. One solution would be to make it an }(hjthhhNhNubjI)}(h ``atomic_t``h]hatomic_t}(hj|hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjtubhx, but for this usage, we don’t really care about races: an approximate result is good enough, so I didn’t change it.}(hjthhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hThe result is that cache_find() requires no synchronization with any other functions, so is almost as fast on SMP as it would be on UP.h]hThe result is that cache_find() requires no synchronization with any other functions, so is almost as fast on SMP as it would be on UP.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hX6There is a further optimization possible here: remember our original cache code, where there were no reference counts and the caller simply held the lock whenever using the object? This is still possible: if you hold the lock, no one can delete the object, so you don't need to get and put the reference count.h]hX8There is a further optimization possible here: remember our original cache code, where there were no reference counts and the caller simply held the lock whenever using the object? This is still possible: if you hold the lock, no one can delete the object, so you don’t need to get and put the reference count.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hX;Now, because the 'read lock' in RCU is simply disabling preemption, a caller which always has preemption disabled between calling cache_find() and object_put() does not need to actually get and put the reference count: we could expose __cache_find() by making it non-static, and such callers could simply call that.h]hX?Now, because the ‘read lock’ in RCU is simply disabling preemption, a caller which always has preemption disabled between calling cache_find() and object_put() does not need to actually get and put the reference count: we could expose __cache_find() by making it non-static, and such callers could simply call that.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hThe benefit here is that the reference count is not written to: the object is not altered in any way, which is much faster on SMP machines due to caching.h]hThe benefit here is that the reference count is not written to: the object is not altered in any way, which is much faster on SMP machines due to caching.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubeh}(h]avoiding-locks-read-copy-updateah ]h"] avoiding locks: read copy updateah$]h&]uh1hhjhhhhhM)ubh)}(hhh](h)}(h Per-CPU Datah]h Per-CPU Data}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hAnother technique for avoiding locking which is used fairly widely is to duplicate information for each CPU. For example, if you wanted to keep a count of a common condition, you could use a spin lock and a single counter. Nice and simple.h]hAnother technique for avoiding locking which is used fairly widely is to duplicate information for each CPU. For example, if you wanted to keep a count of a common condition, you could use a spin lock and a single counter. Nice and simple.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hXIf that was too slow (it's usually not, but if you've got a really big machine to test on and can show that it is), you could instead use a counter for each CPU, then none of them need an exclusive lock. See DEFINE_PER_CPU(), get_cpu_var() and put_cpu_var() (``include/linux/percpu.h``).h](hXIf that was too slow (it’s usually not, but if you’ve got a really big machine to test on and can show that it is), you could instead use a counter for each CPU, then none of them need an exclusive lock. See DEFINE_PER_CPU(), get_cpu_var() and put_cpu_var() (}(hjhhhNhNubjI)}(h``include/linux/percpu.h``h]hinclude/linux/percpu.h}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjubh).}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hOf particular use for simple per-cpu counters is the ``local_t`` type, and the cpu_local_inc() and related functions, which are more efficient than simple code on some architectures (``include/asm/local.h``).h](h5Of particular use for simple per-cpu counters is the }(hjhhhNhNubjI)}(h ``local_t``h]hlocal_t}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjubhw type, and the cpu_local_inc() and related functions, which are more efficient than simple code on some architectures (}(hjhhhNhNubjI)}(h``include/asm/local.h``h]hinclude/asm/local.h}(hj-hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjubh).}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hNote that there is no simple, reliable way of getting an exact value of such a counter, without introducing more locks. This is not a problem for some uses.h]hNote that there is no simple, reliable way of getting an exact value of such a counter, without introducing more locks. This is not a problem for some uses.}(hjEhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubeh}(h]jtah ]h"] per-cpu dataah$]h&]uh1hhjhhhhhMj Kubh)}(hhh](h)}(h(Data Which Mostly Used By An IRQ Handlerh]h(Data Which Mostly Used By An IRQ Handler}(hj]hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjZhhhhhMubh)}(hIf data is always accessed from within the same IRQ handler, you don't need a lock at all: the kernel already guarantees that the irq handler will not run simultaneously on multiple CPUs.h]hIf data is always accessed from within the same IRQ handler, you don’t need a lock at all: the kernel already guarantees that the irq handler will not run simultaneously on multiple CPUs.}(hjkhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjZhhubh)}(hManfred Spraul points out that you can still do this, even if the data is very occasionally accessed in user context or softirqs/tasklets. The irq handler doesn't use a lock, and all other accesses are done as so::h]hManfred Spraul points out that you can still do this, even if the data is very occasionally accessed in user context or softirqs/tasklets. The irq handler doesn’t use a lock, and all other accesses are done as so:}(hjyhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjZhhubj~)}(hNmutex_lock(&lock); disable_irq(irq); ... enable_irq(irq); mutex_unlock(&lock);h]hNmutex_lock(&lock); disable_irq(irq); ... enable_irq(irq); mutex_unlock(&lock);}hjsbah}(h]h ]h"]h$]h&]jjuh1j}hhhMhjZhhubh)}(hXFThe disable_irq() prevents the irq handler from running (and waits for it to finish if it's currently running on other CPUs). The spinlock prevents any other accesses happening at the same time. Naturally, this is slower than just a spin_lock_irq() call, so it only makes sense if this type of access happens extremely rarely.h]hXHThe disable_irq() prevents the irq handler from running (and waits for it to finish if it’s currently running on other CPUs). The spinlock prevents any other accesses happening at the same time. Naturally, this is slower than just a spin_lock_irq() call, so it only makes sense if this type of access happens extremely rarely.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjZhhubeh}(h](data-which-mostly-used-by-an-irq-handlerah ]h"](data which mostly used by an irq handlerah$]h&]uh1hhjhhhhhMubeh}(h] locking-speedah ]h"] locking speedah$]h&]uh1hhhhhhhhMubh)}(hhh](h)}(h0What Functions Are Safe To Call From Interrupts?h]h0What Functions Are Safe To Call From Interrupts?}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hMany functions in the kernel sleep (ie. call schedule()) directly or indirectly: you can never call them while holding a spinlock, or with preemption disabled. This also means you need to be in user context: calling them from an interrupt is illegal.h]hMany functions in the kernel sleep (ie. call schedule()) directly or indirectly: you can never call them while holding a spinlock, or with preemption disabled. This also means you need to be in user context: calling them from an interrupt is illegal.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hhh](h)}(hSome Functions Which Sleeph]hSome Functions Which Sleep}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hX=The most common ones are listed below, but you usually have to read the code to find out if other calls are safe. If everyone else who calls it can sleep, you probably need to be able to sleep, too. In particular, registration and deregistration functions usually expect to be called from user context, and can sleep.h]hX=The most common ones are listed below, but you usually have to read the code to find out if other calls are safe. If everyone else who calls it can sleep, you probably need to be able to sleep, too. In particular, registration and deregistration functions usually expect to be called from user context, and can sleep.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj )}(hhh](j )}(h]Accesses to userspace: - copy_from_user() - copy_to_user() - get_user() - put_user() h](h)}(hAccesses to userspace:h]hAccesses to userspace:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubj )}(hhh](j )}(hcopy_from_user() h]h)}(hcopy_from_user()h]hcopy_from_user()}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hj ubah}(h]h ]h"]h$]h&]uh1j hj ubj )}(hcopy_to_user() h]h)}(hcopy_to_user()h]hcopy_to_user()}(hj% hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM"hj! ubah}(h]h ]h"]h$]h&]uh1j hj ubj )}(h get_user() h]h)}(h get_user()h]h get_user()}(hj= hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM$hj9 ubah}(h]h ]h"]h$]h&]uh1j hj ubj )}(h put_user() h]h)}(h put_user()h]h put_user()}(hjU hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM&hjQ ubah}(h]h ]h"]h$]h&]uh1j hj ubeh}(h]h ]h"]h$]h&]j5 j6 uh1j hhhM hjubeh}(h]h ]h"]h$]h&]uh1j hjhhhNhNubj )}(hkmalloc(GFP_KERNEL) h]h)}(hkmalloc(GFP_KERNEL) h]hkmalloc(GFP_KERNEL) }(hjy hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM(hju ubah}(h]h ]h"]h$]h&]uh1j hjhhhhhNubj )}(hXWmutex_lock_interruptible() and mutex_lock() There is a mutex_trylock() which does not sleep. Still, it must not be used inside interrupt context since its implementation is not safe for that. mutex_unlock() will also never sleep. It cannot be used in interrupt context either since a mutex must be released by the same task that acquired it. h](h)}(h+mutex_lock_interruptible() and mutex_lock()h]h+mutex_lock_interruptible() and mutex_lock()}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM*hj ubh)}(hX)There is a mutex_trylock() which does not sleep. Still, it must not be used inside interrupt context since its implementation is not safe for that. mutex_unlock() will also never sleep. It cannot be used in interrupt context either since a mutex must be released by the same task that acquired it.h]hX)There is a mutex_trylock() which does not sleep. Still, it must not be used inside interrupt context since its implementation is not safe for that. mutex_unlock() will also never sleep. It cannot be used in interrupt context either since a mutex must be released by the same task that acquired it.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM-hj ubeh}(h]h ]h"]h$]h&]uh1j hjhhhhhNubeh}(h]h ]h"]h$]h&]j5 j6 uh1j hhhMhjhhubeh}(h]some-functions-which-sleepah ]h"]some functions which sleepah$]h&]uh1hhjhhhhhMubh)}(hhh](h)}(h Some Functions Which Don't Sleeph]h"Some Functions Which Don’t Sleep}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhM4ubh)}(hMSome functions are safe to call from any context, or holding almost any lock.h]hMSome functions are safe to call from any context, or holding almost any lock.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM6hj hhubj )}(hhh](j )}(h printk() h]h)}(hprintk()h]hprintk()}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM9hj ubah}(h]h ]h"]h$]h&]uh1j hj hhhhhNubj )}(hkfree() h]h)}(hkfree()h]hkfree()}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM;hj ubah}(h]h ]h"]h$]h&]uh1j hj hhhhhNubj )}(hadd_timer() and timer_delete() h]h)}(hadd_timer() and timer_delete()h]hadd_timer() and timer_delete()}(hj!hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM=hj!ubah}(h]h ]h"]h$]h&]uh1j hj hhhhhNubeh}(h]h ]h"]h$]h&]j5 j6 uh1j hhhM9hj hhubeh}(h] some-functions-which-don-t-sleepah ]h"] some functions which don't sleepah$]h&]uh1hhjhhhhhM4ubeh}(h]jah ]h"]0what functions are safe to call from interrupts?ah$]h&]uh1hhhhhhhhMj Kubh)}(hhh](h)}(hMutex API referenceh]hMutex API reference}(hjC!hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj@!hhhhhM@ubhindex)}(hhh]h}(h]h ]h"]h$]h&]entries](singlemutex_init (C macro) c.mutex_inithNtauh1jQ!hj@!hhhNhNubhdesc)}(hhh](hdesc_signature)}(h mutex_inith]hdesc_signature_line)}(h mutex_inith]h desc_name)}(h mutex_inith]h desc_sig_name)}(hjk!h]h mutex_init}(hj{!hhhNhNubah}(h]h ]nah"]h$]h&]uh1jy!hju!ubah}(h]h ](sig-namedescnameeh"]h$]h&]jjuh1js!hjo!hhh^/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1346: ./include/linux/mutex.hhK5ubah}(h]h ]h"]h$]h&]jj add_permalinkuh1jm!sphinx_line_type declaratorhji!hhhj!hK5ubah}(h]j`!ah ](sig sig-objecteh"]h$]h&] is_multiline _toc_parts) _toc_namehuh1jg!hj!hK5hjd!hhubh desc_content)}(hhh]h}(h]h ]h"]h$]h&]uh1j!hjd!hhhj!hK5ubeh}(h]h ](jUmacroeh"]h$]h&]domainjUobjtypej!desctypej!noindex noindexentrynocontentsentryuh1jb!hhhj@!hNhNubh)}(h``mutex_init (mutex)``h]jI)}(hj!h]hmutex_init (mutex)}(hj!hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj!ubah}(h]h ]h"]h$]h&]uh1hh^/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1346: ./include/linux/mutex.hhK7hj@!hhubh block_quote)}(hinitialize the mutex h]h)}(hinitialize the mutexh]hinitialize the mutex}(hj!hhhNhNubah}(h]h ]h"]h$]h&]uh1hh^/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1346: ./include/linux/mutex.hhK5hj!ubah}(h]h ]h"]h$]h&]uh1j!hj!hK5hj@!hhubh container)}(h**Parameters** ``mutex`` the mutex to be initialized **Description** Initialize the mutex to unlocked state. It is not allowed to initialize an already locked mutex.h](h)}(h**Parameters**h]j)}(hj!h]h Parameters}(hj!hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj!ubah}(h]h ]h"]h$]h&]uh1hh^/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1346: ./include/linux/mutex.hhK9hj!ubhdefinition_list)}(hhh]hdefinition_list_item)}(h&``mutex`` the mutex to be initialized h](hterm)}(h ``mutex``h]jI)}(hj"h]hmutex}(hj "hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj"ubah}(h]h ]h"]h$]h&]uh1j"h^/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1346: ./include/linux/mutex.hhK6hj"ubh definition)}(hhh]h)}(hthe mutex to be initializedh]hthe mutex to be initialized}(hj9"hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj3"hK6hj6"ubah}(h]h ]h"]h$]h&]uh1j4"hj"ubeh}(h]h ]h"]h$]h&]uh1j"hj3"hK6hj"ubah}(h]h ]h"]h$]h&]uh1j"hj!ubh)}(h**Description**h]j)}(hj["h]h Description}(hj]"hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjY"ubah}(h]h ]h"]h$]h&]uh1hh^/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1346: ./include/linux/mutex.hhK8hj!ubh)}(h'Initialize the mutex to unlocked state.h]h'Initialize the mutex to unlocked state.}(hjq"hhhNhNubah}(h]h ]h"]h$]h&]uh1hh^/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1346: ./include/linux/mutex.hhK7hj!ubh)}(h8It is not allowed to initialize an already locked mutex.h]h8It is not allowed to initialize an already locked mutex.}(hj"hhhNhNubah}(h]h ]h"]h$]h&]uh1hh^/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1346: ./include/linux/mutex.hhK9hj!ubeh}(h]h ] kernelindentah"]h$]h&]uh1j!hj@!hhhNhNubjR!)}(hhh]h}(h]h ]h"]h$]h&]entries](j^!mutex_init_with_key (C macro)c.mutex_init_with_keyhNtauh1jQ!hj@!hhhNhNubjc!)}(hhh](jh!)}(hmutex_init_with_keyh]jn!)}(hmutex_init_with_keyh]jt!)}(hmutex_init_with_keyh]jz!)}(hj"h]hmutex_init_with_key}(hj"hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj"ubah}(h]h ](j!j!eh"]h$]h&]jjuh1js!hj"hhh^/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1346: ./include/linux/mutex.hhKDubah}(h]h ]h"]h$]h&]jjj!uh1jm!j!j!hj"hhhj"hKDubah}(h]j"ah ](j!j!eh"]h$]h&]j!j!)j!huh1jg!hj"hKDhj"hhubj!)}(hhh]h}(h]h ]h"]h$]h&]uh1j!hj"hhhj"hKDubeh}(h]h ](jUmacroeh"]h$]h&]j!jUj!j"j!j"j!j!j!uh1jb!hhhj@!hNhNubh)}(h$``mutex_init_with_key (mutex, key)``h]jI)}(hj"h]h mutex_init_with_key (mutex, key)}(hj"hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj"ubah}(h]h ]h"]h$]h&]uh1hh^/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1346: ./include/linux/mutex.hhKFhj@!hhubj!)}(h,initialize a mutex with a given lockdep key h]h)}(h+initialize a mutex with a given lockdep keyh]h+initialize a mutex with a given lockdep key}(hj"hhhNhNubah}(h]h ]h"]h$]h&]uh1hh^/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1346: ./include/linux/mutex.hhKDhj"ubah}(h]h ]h"]h$]h&]uh1j!hj #hKDhj@!hhubj!)}(h**Parameters** ``mutex`` the mutex to be initialized ``key`` the lockdep key to be associated with the mutex **Description** Initialize the mutex to the unlocked state. It is not allowed to initialize an already locked mutex.h](h)}(h**Parameters**h]j)}(hj#h]h Parameters}(hj#hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj#ubah}(h]h ]h"]h$]h&]uh1hh^/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1346: ./include/linux/mutex.hhKHhj#ubj")}(hhh](j")}(h&``mutex`` the mutex to be initialized h](j")}(h ``mutex``h]jI)}(hj9#h]hmutex}(hj;#hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj7#ubah}(h]h ]h"]h$]h&]uh1j"h^/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1346: ./include/linux/mutex.hhKEhj3#ubj5")}(hhh]h)}(hthe mutex to be initializedh]hthe mutex to be initialized}(hjR#hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjN#hKEhjO#ubah}(h]h ]h"]h$]h&]uh1j4"hj3#ubeh}(h]h ]h"]h$]h&]uh1j"hjN#hKEhj0#ubj")}(h8``key`` the lockdep key to be associated with the mutex h](j")}(h``key``h]jI)}(hjr#h]hkey}(hjt#hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjp#ubah}(h]h ]h"]h$]h&]uh1j"h^/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1346: ./include/linux/mutex.hhKFhjl#ubj5")}(hhh]h)}(h/the lockdep key to be associated with the mutexh]h/the lockdep key to be associated with the mutex}(hj#hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj#hKFhj#ubah}(h]h ]h"]h$]h&]uh1j4"hjl#ubeh}(h]h ]h"]h$]h&]uh1j"hj#hKFhj0#ubeh}(h]h ]h"]h$]h&]uh1j"hj#ubh)}(h**Description**h]j)}(hj#h]h Description}(hj#hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj#ubah}(h]h ]h"]h$]h&]uh1hh^/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1346: ./include/linux/mutex.hhKHhj#ubh)}(h+Initialize the mutex to the unlocked state.h]h+Initialize the mutex to the unlocked state.}(hj#hhhNhNubah}(h]h ]h"]h$]h&]uh1hh^/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1346: ./include/linux/mutex.hhKGhj#ubh)}(h8It is not allowed to initialize an already locked mutex.h]h8It is not allowed to initialize an already locked mutex.}(hj#hhhNhNubah}(h]h ]h"]h$]h&]uh1hh^/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1346: ./include/linux/mutex.hhKIhj#ubeh}(h]h ] kernelindentah"]h$]h&]uh1j!hj@!hhhNhNubjR!)}(hhh]h}(h]h ]h"]h$]h&]entries](j^!mutex_is_locked (C function)c.mutex_is_lockedhNtauh1jQ!hj@!hhhNhNubjc!)}(hhh](jh!)}(h)bool mutex_is_locked (struct mutex *lock)h]jn!)}(h(bool mutex_is_locked(struct mutex *lock)h](hdesc_sig_keyword_type)}(hboolh]hbool}(hj$hhhNhNubah}(h]h ]ktah"]h$]h&]uh1j$hj#hhh^/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1346: ./include/linux/mutex.hhKlubhdesc_sig_space)}(h h]h }(hj$hhhNhNubah}(h]h ]wah"]h$]h&]uh1j$hj#hhhj$hKlubjt!)}(hmutex_is_lockedh]jz!)}(hmutex_is_lockedh]hmutex_is_locked}(hj($hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj$$ubah}(h]h ](j!j!eh"]h$]h&]jjuh1js!hj#hhhj$hKlubhdesc_parameterlist)}(h(struct mutex *lock)h]hdesc_parameter)}(hstruct mutex *lockh](hdesc_sig_keyword)}(hstructh]hstruct}(hjJ$hhhNhNubah}(h]h ]kah"]h$]h&]uh1jH$hjD$ubj$)}(h h]h }(hjY$hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjD$ubh)}(hhh]jz!)}(hmutexh]hmutex}(hjj$hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjg$ubah}(h]h ]h"]h$]h&] refdomainjUreftype identifier reftargetjl$modnameN classnameN c:parent_keysphinx.domains.c LookupKey)}data]j$ ASTIdentifier)}j$j*$sbc.mutex_is_lockedasbuh1hhjD$ubj$)}(h h]h }(hj$hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjD$ubhdesc_sig_punctuation)}(h*h]h*}(hj$hhhNhNubah}(h]h ]pah"]h$]h&]uh1j$hjD$ubjz!)}(hlockh]hlock}(hj$hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjD$ubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hj>$ubah}(h]h ]h"]h$]h&]jjuh1j<$hj#hhhj$hKlubeh}(h]h ]h"]h$]h&]jjj!uh1jm!j!j!hj#hhhj$hKlubah}(h]j#ah ](j!j!eh"]h$]h&]j!j!)j!huh1jg!hj$hKlhj#hhubj!)}(hhh]h)}(his the mutex lockedh]his the mutex locked}(hj$hhhNhNubah}(h]h ]h"]h$]h&]uh1hh^/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1346: ./include/linux/mutex.hhKlhj$hhubah}(h]h ]h"]h$]h&]uh1j!hj#hhhj$hKlubeh}(h]h ](jUfunctioneh"]h$]h&]j!jUj!j$j!j$j!j!j!uh1jb!hhhj@!hNhNubj!)}(h**Parameters** ``struct mutex *lock`` the mutex to be queried **Description** Returns true if the mutex is locked, false if unlocked.h](h)}(h**Parameters**h]j)}(hj$h]h Parameters}(hj$hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj$ubah}(h]h ]h"]h$]h&]uh1hh^/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1346: ./include/linux/mutex.hhKphj$ubj")}(hhh]j")}(h/``struct mutex *lock`` the mutex to be queried h](j")}(h``struct mutex *lock``h]jI)}(hj%h]hstruct mutex *lock}(hj%hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj%ubah}(h]h ]h"]h$]h&]uh1j"h^/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1346: ./include/linux/mutex.hhKmhj%ubj5")}(hhh]h)}(hthe mutex to be queriedh]hthe mutex to be queried}(hj5%hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj1%hKmhj2%ubah}(h]h ]h"]h$]h&]uh1j4"hj%ubeh}(h]h ]h"]h$]h&]uh1j"hj1%hKmhj%ubah}(h]h ]h"]h$]h&]uh1j"hj$ubh)}(h**Description**h]j)}(hjW%h]h Description}(hjY%hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjU%ubah}(h]h ]h"]h$]h&]uh1hh^/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1346: ./include/linux/mutex.hhKohj$ubh)}(h7Returns true if the mutex is locked, false if unlocked.h]h7Returns true if the mutex is locked, false if unlocked.}(hjm%hhhNhNubah}(h]h ]h"]h$]h&]uh1hh^/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1346: ./include/linux/mutex.hhKnhj$ubeh}(h]h ] kernelindentah"]h$]h&]uh1j!hj@!hhhNhNubjR!)}(hhh]h}(h]h ]h"]h$]h&]entries](j^!mutex_lock (C function) c.mutex_lockhNtauh1jQ!hj@!hhhNhNubjc!)}(hhh](jh!)}(h$void mutex_lock (struct mutex *lock)h]jn!)}(h#void mutex_lock(struct mutex *lock)h](j$)}(hvoidh]hvoid}(hj%hhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj%hhh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chM&ubj$)}(h h]h }(hj%hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj%hhhj%hM&ubjt!)}(h mutex_lockh]jz!)}(h mutex_lockh]h mutex_lock}(hj%hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj%ubah}(h]h ](j!j!eh"]h$]h&]jjuh1js!hj%hhhj%hM&ubj=$)}(h(struct mutex *lock)h]jC$)}(hstruct mutex *lockh](jI$)}(hjL$h]hstruct}(hj%hhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hj%ubj$)}(h h]h }(hj%hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj%ubh)}(hhh]jz!)}(hmutexh]hmutex}(hj%hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj%ubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetj%modnameN classnameNj$j$)}j$]j$)}j$j%sb c.mutex_lockasbuh1hhj%ubj$)}(h h]h }(hj&hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj%ubj$)}(hj$h]h*}(hj%&hhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj%ubjz!)}(hlockh]hlock}(hj2&hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj%ubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hj%ubah}(h]h ]h"]h$]h&]jjuh1j<$hj%hhhj%hM&ubeh}(h]h ]h"]h$]h&]jjj!uh1jm!j!j!hj%hhhj%hM&ubah}(h]j%ah ](j!j!eh"]h$]h&]j!j!)j!huh1jg!hj%hM&hj%hhubj!)}(hhh]h)}(hacquire the mutexh]hacquire the mutex}(hj\&hhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chM&hjY&hhubah}(h]h ]h"]h$]h&]uh1j!hj%hhhj%hM&ubeh}(h]h ](jUfunctioneh"]h$]h&]j!jUj!jt&j!jt&j!j!j!uh1jb!hhhj@!hNhNubj!)}(hX**Parameters** ``struct mutex *lock`` the mutex to be acquired **Description** Lock the mutex exclusively for this task. If the mutex is not available right now, it will sleep until it can get it. The mutex must later on be released by the same task that acquired it. Recursive locking is not allowed. The task may not exit without first unlocking the mutex. Also, kernel memory where the mutex resides must not be freed with the mutex still locked. The mutex must first be initialized (or statically defined) before it can be locked. memset()-ing the mutex to 0 is not allowed. (The CONFIG_DEBUG_MUTEXES .config option turns on debugging checks that will enforce the restrictions and will also do deadlock debugging) This function is similar to (but not equivalent to) down().h](h)}(h**Parameters**h]j)}(hj~&h]h Parameters}(hj&hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj|&ubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chM*hjx&ubj")}(hhh]j")}(h0``struct mutex *lock`` the mutex to be acquired h](j")}(h``struct mutex *lock``h]jI)}(hj&h]hstruct mutex *lock}(hj&hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj&ubah}(h]h ]h"]h$]h&]uh1j"h_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chM'hj&ubj5")}(hhh]h)}(hthe mutex to be acquiredh]hthe mutex to be acquired}(hj&hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj&hM'hj&ubah}(h]h ]h"]h$]h&]uh1j4"hj&ubeh}(h]h ]h"]h$]h&]uh1j"hj&hM'hj&ubah}(h]h ]h"]h$]h&]uh1j"hjx&ubh)}(h**Description**h]j)}(hj&h]h Description}(hj&hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj&ubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chM)hjx&ubh)}(huLock the mutex exclusively for this task. If the mutex is not available right now, it will sleep until it can get it.h]huLock the mutex exclusively for this task. If the mutex is not available right now, it will sleep until it can get it.}(hj&hhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chM(hjx&ubh)}(hX}The mutex must later on be released by the same task that acquired it. Recursive locking is not allowed. The task may not exit without first unlocking the mutex. Also, kernel memory where the mutex resides must not be freed with the mutex still locked. The mutex must first be initialized (or statically defined) before it can be locked. memset()-ing the mutex to 0 is not allowed.h]hX}The mutex must later on be released by the same task that acquired it. Recursive locking is not allowed. The task may not exit without first unlocking the mutex. Also, kernel memory where the mutex resides must not be freed with the mutex still locked. The mutex must first be initialized (or statically defined) before it can be locked. memset()-ing the mutex to 0 is not allowed.}(hj&hhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chM+hjx&ubh)}(h(The CONFIG_DEBUG_MUTEXES .config option turns on debugging checks that will enforce the restrictions and will also do deadlock debugging)h]h(The CONFIG_DEBUG_MUTEXES .config option turns on debugging checks that will enforce the restrictions and will also do deadlock debugging)}(hj 'hhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chM3hjx&ubh)}(h;This function is similar to (but not equivalent to) down().h]h;This function is similar to (but not equivalent to) down().}(hj'hhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chM7hjx&ubeh}(h]h ] kernelindentah"]h$]h&]uh1j!hj@!hhhNhNubjR!)}(hhh]h}(h]h ]h"]h$]h&]entries](j^!mutex_unlock (C function)c.mutex_unlockhNtauh1jQ!hj@!hhhNhNubjc!)}(hhh](jh!)}(h&void mutex_unlock (struct mutex *lock)h]jn!)}(h%void mutex_unlock(struct mutex *lock)h](j$)}(hvoidh]hvoid}(hjJ'hhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjF'hhh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chM1ubj$)}(h h]h }(hjY'hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjF'hhhjX'hM1ubjt!)}(h mutex_unlockh]jz!)}(h mutex_unlockh]h mutex_unlock}(hjk'hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjg'ubah}(h]h ](j!j!eh"]h$]h&]jjuh1js!hjF'hhhjX'hM1ubj=$)}(h(struct mutex *lock)h]jC$)}(hstruct mutex *lockh](jI$)}(hjL$h]hstruct}(hj'hhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hj'ubj$)}(h h]h }(hj'hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj'ubh)}(hhh]jz!)}(hmutexh]hmutex}(hj'hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj'ubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetj'modnameN classnameNj$j$)}j$]j$)}j$jm'sbc.mutex_unlockasbuh1hhj'ubj$)}(h h]h }(hj'hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj'ubj$)}(hj$h]h*}(hj'hhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj'ubjz!)}(hlockh]hlock}(hj'hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj'ubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hj'ubah}(h]h ]h"]h$]h&]jjuh1j<$hjF'hhhjX'hM1ubeh}(h]h ]h"]h$]h&]jjj!uh1jm!j!j!hjB'hhhjX'hM1ubah}(h]j='ah ](j!j!eh"]h$]h&]j!j!)j!huh1jg!hjX'hM1hj?'hhubj!)}(hhh]h)}(hrelease the mutexh]hrelease the mutex}(hj (hhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chM1hj(hhubah}(h]h ]h"]h$]h&]uh1j!hj?'hhhjX'hM1ubeh}(h]h ](jUfunctioneh"]h$]h&]j!jUj!j"(j!j"(j!j!j!uh1jb!hhhj@!hNhNubj!)}(hX4**Parameters** ``struct mutex *lock`` the mutex to be released **Description** Unlock a mutex that has been locked by this task previously. This function must not be used in interrupt context. Unlocking of a not locked mutex is not allowed. The caller must ensure that the mutex stays alive until this function has returned - mutex_unlock() can NOT directly be used to release an object such that another concurrent task can free it. Mutexes are different from spinlocks & refcounts in this aspect. This function is similar to (but not equivalent to) up().h](h)}(h**Parameters**h]j)}(hj,(h]h Parameters}(hj.(hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj*(ubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chM5hj&(ubj")}(hhh]j")}(h0``struct mutex *lock`` the mutex to be released h](j")}(h``struct mutex *lock``h]jI)}(hjK(h]hstruct mutex *lock}(hjM(hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjI(ubah}(h]h ]h"]h$]h&]uh1j"h_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chM2hjE(ubj5")}(hhh]h)}(hthe mutex to be releasedh]hthe mutex to be released}(hjd(hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj`(hM2hja(ubah}(h]h ]h"]h$]h&]uh1j4"hjE(ubeh}(h]h ]h"]h$]h&]uh1j"hj`(hM2hjB(ubah}(h]h ]h"]h$]h&]uh1j"hj&(ubh)}(h**Description**h]j)}(hj(h]h Description}(hj(hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj(ubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chM4hj&(ubh)}(h/hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj.ubj$)}(hj$h]h*}(hjL/hhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj.ubjz!)}(hlockh]hlock}(hjY/hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj.ubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hj.ubah}(h]h ]h"]h$]h&]jjuh1j<$hj.hhhj.hM^ubeh}(h]h ]h"]h$]h&]jjj!uh1jm!j!j!hj.hhhj.hM^ubah}(h]j.ah ](j!j!eh"]h$]h&]j!j!)j!huh1jg!hj.hM^hj.hhubj!)}(hhh]h)}(h2Acquire the mutex, interruptible by fatal signals.h]h2Acquire the mutex, interruptible by fatal signals.}(hj/hhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chM^hj/hhubah}(h]h ]h"]h$]h&]uh1j!hj.hhhj.hM^ubeh}(h]h ](jUfunctioneh"]h$]h&]j!jUj!j/j!j/j!j!j!uh1jb!hhhj@!hNhNubj!)}(hX**Parameters** ``struct mutex *lock`` The mutex to be acquired. **Description** Lock the mutex like mutex_lock(). If a signal which will be fatal to the current process is delivered while the process is sleeping, this function will return without acquiring the mutex. **Context** Process context. **Return** 0 if the lock was successfully acquired or ``-EINTR`` if a fatal signal arrived.h](h)}(h**Parameters**h]j)}(hj/h]h Parameters}(hj/hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj/ubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chMbhj/ubj")}(hhh]j")}(h1``struct mutex *lock`` The mutex to be acquired. h](j")}(h``struct mutex *lock``h]jI)}(hj/h]hstruct mutex *lock}(hj/hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj/ubah}(h]h ]h"]h$]h&]uh1j"h_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chM_hj/ubj5")}(hhh]h)}(hThe mutex to be acquired.h]hThe mutex to be acquired.}(hj/hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj/hM_hj/ubah}(h]h ]h"]h$]h&]uh1j4"hj/ubeh}(h]h ]h"]h$]h&]uh1j"hj/hM_hj/ubah}(h]h ]h"]h$]h&]uh1j"hj/ubh)}(h**Description**h]j)}(hj/h]h Description}(hj0hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj/ubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chMahj/ubh)}(hLock the mutex like mutex_lock(). If a signal which will be fatal to the current process is delivered while the process is sleeping, this function will return without acquiring the mutex.h]hLock the mutex like mutex_lock(). If a signal which will be fatal to the current process is delivered while the process is sleeping, this function will return without acquiring the mutex.}(hj0hhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chM`hj/ubh)}(h **Context**h]j)}(hj&0h]hContext}(hj(0hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj$0ubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chMdhj/ubh)}(hProcess context.h]hProcess context.}(hj<0hhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chMehj/ubh)}(h **Return**h]j)}(hjM0h]hReturn}(hjO0hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjK0ubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chMghj/ubh)}(hP0 if the lock was successfully acquired or ``-EINTR`` if a fatal signal arrived.h](h+0 if the lock was successfully acquired or }(hjc0hhhNhNubjI)}(h ``-EINTR``h]h-EINTR}(hjk0hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjc0ubh if a fatal signal arrived.}(hjc0hhhNhNubeh}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chMfhj/ubeh}(h]h ] kernelindentah"]h$]h&]uh1j!hj@!hhhNhNubjR!)}(hhh]h}(h]h ]h"]h$]h&]entries](j^!mutex_lock_io (C function)c.mutex_lock_iohNtauh1jQ!hj@!hhhNhNubjc!)}(hhh](jh!)}(h'void mutex_lock_io (struct mutex *lock)h]jn!)}(h&void mutex_lock_io(struct mutex *lock)h](j$)}(hvoidh]hvoid}(hj0hhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj0hhh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chMuubj$)}(h h]h }(hj0hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj0hhhj0hMuubjt!)}(h mutex_lock_ioh]jz!)}(h mutex_lock_ioh]h mutex_lock_io}(hj0hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj0ubah}(h]h ](j!j!eh"]h$]h&]jjuh1js!hj0hhhj0hMuubj=$)}(h(struct mutex *lock)h]jC$)}(hstruct mutex *lockh](jI$)}(hjL$h]hstruct}(hj0hhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hj0ubj$)}(h h]h }(hj0hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj0ubh)}(hhh]jz!)}(hmutexh]hmutex}(hj0hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj0ubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetj1modnameN classnameNj$j$)}j$]j$)}j$j0sbc.mutex_lock_ioasbuh1hhj0ubj$)}(h h]h }(hj1hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj0ubj$)}(hj$h]h*}(hj-1hhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj0ubjz!)}(hlockh]hlock}(hj:1hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj0ubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hj0ubah}(h]h ]h"]h$]h&]jjuh1j<$hj0hhhj0hMuubeh}(h]h ]h"]h$]h&]jjj!uh1jm!j!j!hj0hhhj0hMuubah}(h]j0ah ](j!j!eh"]h$]h&]j!j!)j!huh1jg!hj0hMuhj0hhubj!)}(hhh]h)}(h9Acquire the mutex and mark the process as waiting for I/Oh]h9Acquire the mutex and mark the process as waiting for I/O}(hjd1hhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chMuhja1hhubah}(h]h ]h"]h$]h&]uh1j!hj0hhhj0hMuubeh}(h]h ](jUfunctioneh"]h$]h&]j!jUj!j|1j!j|1j!j!j!uh1jb!hhhj@!hNhNubj!)}(hX**Parameters** ``struct mutex *lock`` The mutex to be acquired. **Description** Lock the mutex like mutex_lock(). While the task is waiting for this mutex, it will be accounted as being in the IO wait state by the scheduler. **Context** Process context.h](h)}(h**Parameters**h]j)}(hj1h]h Parameters}(hj1hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj1ubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chMyhj1ubj")}(hhh]j")}(h1``struct mutex *lock`` The mutex to be acquired. h](j")}(h``struct mutex *lock``h]jI)}(hj1h]hstruct mutex *lock}(hj1hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj1ubah}(h]h ]h"]h$]h&]uh1j"h_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chMvhj1ubj5")}(hhh]h)}(hThe mutex to be acquired.h]hThe mutex to be acquired.}(hj1hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj1hMvhj1ubah}(h]h ]h"]h$]h&]uh1j4"hj1ubeh}(h]h ]h"]h$]h&]uh1j"hj1hMvhj1ubah}(h]h ]h"]h$]h&]uh1j"hj1ubh)}(h**Description**h]j)}(hj1h]h Description}(hj1hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj1ubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chMxhj1ubh)}(hLock the mutex like mutex_lock(). While the task is waiting for this mutex, it will be accounted as being in the IO wait state by the scheduler.h]hLock the mutex like mutex_lock(). While the task is waiting for this mutex, it will be accounted as being in the IO wait state by the scheduler.}(hj1hhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chMwhj1ubh)}(h **Context**h]j)}(hj2h]hContext}(hj 2hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj2ubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chM{hj1ubh)}(hProcess context.h]hProcess context.}(hj2hhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chM|hj1ubeh}(h]h ] kernelindentah"]h$]h&]uh1j!hj@!hhhNhNubjR!)}(hhh]h}(h]h ]h"]h$]h&]entries](j^!mutex_trylock (C function)c.mutex_trylockhNtauh1jQ!hj@!hhhNhNubjc!)}(hhh](jh!)}(h&int mutex_trylock (struct mutex *lock)h]jn!)}(h%int mutex_trylock(struct mutex *lock)h](j$)}(hinth]hint}(hjL2hhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjH2hhh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chMubj$)}(h h]h }(hj[2hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjH2hhhjZ2hMubjt!)}(h mutex_trylockh]jz!)}(h mutex_trylockh]h mutex_trylock}(hjm2hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hji2ubah}(h]h ](j!j!eh"]h$]h&]jjuh1js!hjH2hhhjZ2hMubj=$)}(h(struct mutex *lock)h]jC$)}(hstruct mutex *lockh](jI$)}(hjL$h]hstruct}(hj2hhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hj2ubj$)}(h h]h }(hj2hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj2ubh)}(hhh]jz!)}(hmutexh]hmutex}(hj2hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj2ubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetj2modnameN classnameNj$j$)}j$]j$)}j$jo2sbc.mutex_trylockasbuh1hhj2ubj$)}(h h]h }(hj2hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj2ubj$)}(hj$h]h*}(hj2hhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj2ubjz!)}(hlockh]hlock}(hj2hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj2ubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hj2ubah}(h]h ]h"]h$]h&]jjuh1j<$hjH2hhhjZ2hMubeh}(h]h ]h"]h$]h&]jjj!uh1jm!j!j!hjD2hhhjZ2hMubah}(h]j?2ah ](j!j!eh"]h$]h&]j!j!)j!huh1jg!hjZ2hMhjA2hhubj!)}(hhh]h)}(h)try to acquire the mutex, without waitingh]h)try to acquire the mutex, without waiting}(hj 3hhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chMhj 3hhubah}(h]h ]h"]h$]h&]uh1j!hjA2hhhjZ2hMubeh}(h]h ](jUfunctioneh"]h$]h&]j!jUj!j$3j!j$3j!j!j!uh1jb!hhhj@!hNhNubj!)}(hX**Parameters** ``struct mutex *lock`` the mutex to be acquired **Description** Try to acquire the mutex atomically. Returns 1 if the mutex has been acquired successfully, and 0 on contention. **NOTE** this function follows the spin_trylock() convention, so it is negated from the down_trylock() return values! Be careful about this when converting semaphore users to mutexes. This function must not be used in interrupt context. The mutex must be released by the same task that acquired it.h](h)}(h**Parameters**h]j)}(hj.3h]h Parameters}(hj03hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj,3ubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chMhj(3ubj")}(hhh]j")}(h0``struct mutex *lock`` the mutex to be acquired h](j")}(h``struct mutex *lock``h]jI)}(hjM3h]hstruct mutex *lock}(hjO3hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjK3ubah}(h]h ]h"]h$]h&]uh1j"h_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chMhjG3ubj5")}(hhh]h)}(hthe mutex to be acquiredh]hthe mutex to be acquired}(hjf3hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjb3hMhjc3ubah}(h]h ]h"]h$]h&]uh1j4"hjG3ubeh}(h]h ]h"]h$]h&]uh1j"hjb3hMhjD3ubah}(h]h ]h"]h$]h&]uh1j"hj(3ubh)}(h**Description**h]j)}(hj3h]h Description}(hj3hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj3ubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chMhj(3ubh)}(hpTry to acquire the mutex atomically. Returns 1 if the mutex has been acquired successfully, and 0 on contention.h]hpTry to acquire the mutex atomically. Returns 1 if the mutex has been acquired successfully, and 0 on contention.}(hj3hhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chMhj(3ubh)}(h**NOTE**h]j)}(hj3h]hNOTE}(hj3hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj3ubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chMhj(3ubh)}(hthis function follows the spin_trylock() convention, so it is negated from the down_trylock() return values! Be careful about this when converting semaphore users to mutexes.h]hthis function follows the spin_trylock() convention, so it is negated from the down_trylock() return values! Be careful about this when converting semaphore users to mutexes.}(hj3hhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chMhj(3ubh)}(hrThis function must not be used in interrupt context. The mutex must be released by the same task that acquired it.h]hrThis function must not be used in interrupt context. The mutex must be released by the same task that acquired it.}(hj3hhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chMhj(3ubeh}(h]h ] kernelindentah"]h$]h&]uh1j!hj@!hhhNhNubjR!)}(hhh]h}(h]h ]h"]h$]h&]entries](j^!&atomic_dec_and_mutex_lock (C function)c.atomic_dec_and_mutex_lockhNtauh1jQ!hj@!hhhNhNubjc!)}(hhh](jh!)}(hAint atomic_dec_and_mutex_lock (atomic_t *cnt, struct mutex *lock)h]jn!)}(h@int atomic_dec_and_mutex_lock(atomic_t *cnt, struct mutex *lock)h](j$)}(hinth]hint}(hj4hhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj3hhh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chMubj$)}(h h]h }(hj4hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj3hhhj4hMubjt!)}(hatomic_dec_and_mutex_lockh]jz!)}(hatomic_dec_and_mutex_lockh]hatomic_dec_and_mutex_lock}(hj$4hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj 4ubah}(h]h ](j!j!eh"]h$]h&]jjuh1js!hj3hhhj4hMubj=$)}(h#(atomic_t *cnt, struct mutex *lock)h](jC$)}(h atomic_t *cnth](h)}(hhh]jz!)}(hatomic_th]hatomic_t}(hjC4hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj@4ubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetjE4modnameN classnameNj$j$)}j$]j$)}j$j&4sbc.atomic_dec_and_mutex_lockasbuh1hhj<4ubj$)}(h h]h }(hjc4hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj<4ubj$)}(hj$h]h*}(hjq4hhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj<4ubjz!)}(hcnth]hcnt}(hj~4hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj<4ubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hj84ubjC$)}(hstruct mutex *lockh](jI$)}(hjL$h]hstruct}(hj4hhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hj4ubj$)}(h h]h }(hj4hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj4ubh)}(hhh]jz!)}(hmutexh]hmutex}(hj4hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj4ubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetj4modnameN classnameNj$j$)}j$]j_4c.atomic_dec_and_mutex_lockasbuh1hhj4ubj$)}(h h]h }(hj4hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj4ubj$)}(hj$h]h*}(hj4hhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj4ubjz!)}(hlockh]hlock}(hj4hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj4ubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hj84ubeh}(h]h ]h"]h$]h&]jjuh1j<$hj3hhhj4hMubeh}(h]h ]h"]h$]h&]jjj!uh1jm!j!j!hj3hhhj4hMubah}(h]j3ah ](j!j!eh"]h$]h&]j!j!)j!huh1jg!hj4hMhj3hhubj!)}(hhh]h)}(h#return holding mutex if we dec to 0h]h#return holding mutex if we dec to 0}(hj5hhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chMhj5hhubah}(h]h ]h"]h$]h&]uh1j!hj3hhhj4hMubeh}(h]h ](jUfunctioneh"]h$]h&]j!jUj!j05j!j05j!j!j!uh1jb!hhhj@!hNhNubj!)}(h**Parameters** ``atomic_t *cnt`` the atomic which we are to dec ``struct mutex *lock`` the mutex to return holding if we dec to 0 **Description** return true and hold lock if we dec to 0, return false otherwiseh](h)}(h**Parameters**h]j)}(hj:5h]h Parameters}(hj<5hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj85ubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chMhj45ubj")}(hhh](j")}(h1``atomic_t *cnt`` the atomic which we are to dec h](j")}(h``atomic_t *cnt``h]jI)}(hjY5h]h atomic_t *cnt}(hj[5hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjW5ubah}(h]h ]h"]h$]h&]uh1j"h_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chMhjS5ubj5")}(hhh]h)}(hthe atomic which we are to dech]hthe atomic which we are to dec}(hjr5hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjn5hMhjo5ubah}(h]h ]h"]h$]h&]uh1j4"hjS5ubeh}(h]h ]h"]h$]h&]uh1j"hjn5hMhjP5ubj")}(hB``struct mutex *lock`` the mutex to return holding if we dec to 0 h](j")}(h``struct mutex *lock``h]jI)}(hj5h]hstruct mutex *lock}(hj5hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj5ubah}(h]h ]h"]h$]h&]uh1j"h_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chMhj5ubj5")}(hhh]h)}(h*the mutex to return holding if we dec to 0h]h*the mutex to return holding if we dec to 0}(hj5hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj5hMhj5ubah}(h]h ]h"]h$]h&]uh1j4"hj5ubeh}(h]h ]h"]h$]h&]uh1j"hj5hMhjP5ubeh}(h]h ]h"]h$]h&]uh1j"hj45ubh)}(h**Description**h]j)}(hj5h]h Description}(hj5hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj5ubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chMhj45ubh)}(h@return true and hold lock if we dec to 0, return false otherwiseh]h@return true and hold lock if we dec to 0, return false otherwise}(hj5hhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1349: ./kernel/locking/mutex.chMhj45ubeh}(h]h ] kernelindentah"]h$]h&]uh1j!hj@!hhhNhNubeh}(h]mutex-api-referenceah ]h"]mutex api referenceah$]h&]uh1hhhhhhhhM@ubh)}(hhh](h)}(hFutex API referenceh]hFutex API reference}(hj6hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj6hhhhhMIubjR!)}(hhh]h}(h]h ]h"]h$]h&]entries](j^!__futex_hash (C function)c.__futex_hashhNtauh1jQ!hj6hhhNhNubjc!)}(hhh](jh!)}(hstruct futex_hash_bucket * __futex_hash (union futex_key *key, struct futex_private_hash *fph, struct futex_private_hash **fph_p)h]jn!)}(hstruct futex_hash_bucket *__futex_hash(union futex_key *key, struct futex_private_hash *fph, struct futex_private_hash **fph_p)h](jI$)}(hjL$h]hstruct}(hj+6hhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hj'6hhh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMiubj$)}(h h]h }(hj96hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj'6hhhj86hMiubh)}(hhh]jz!)}(hfutex_hash_bucketh]hfutex_hash_bucket}(hjJ6hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjG6ubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetjL6modnameN classnameNj$j$)}j$]j$)}j$ __futex_hashsbc.__futex_hashasbuh1hhj'6hhhj86hMiubj$)}(h h]h }(hjk6hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj'6hhhj86hMiubj$)}(hj$h]h*}(hjy6hhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj'6hhhj86hMiubjt!)}(h __futex_hashh]jz!)}(hjh6h]h __futex_hash}(hj6hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj6ubah}(h]h ](j!j!eh"]h$]h&]jjuh1js!hj'6hhhj86hMiubj=$)}(hY(union futex_key *key, struct futex_private_hash *fph, struct futex_private_hash **fph_p)h](jC$)}(hunion futex_key *keyh](jI$)}(hunionh]hunion}(hj6hhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hj6ubj$)}(h h]h }(hj6hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj6ubh)}(hhh]jz!)}(h futex_keyh]h futex_key}(hj6hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj6ubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetj6modnameN classnameNj$j$)}j$]jf6c.__futex_hashasbuh1hhj6ubj$)}(h h]h }(hj6hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj6ubj$)}(hj$h]h*}(hj6hhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj6ubjz!)}(hkeyh]hkey}(hj6hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj6ubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hj6ubjC$)}(hstruct futex_private_hash *fphh](jI$)}(hjL$h]hstruct}(hj7hhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hj7ubj$)}(h h]h }(hj#7hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj7ubh)}(hhh]jz!)}(hfutex_private_hashh]hfutex_private_hash}(hj47hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj17ubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetj67modnameN classnameNj$j$)}j$]jf6c.__futex_hashasbuh1hhj7ubj$)}(h h]h }(hjR7hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj7ubj$)}(hj$h]h*}(hj`7hhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj7ubjz!)}(hfphh]hfph}(hjm7hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj7ubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hj6ubjC$)}(h!struct futex_private_hash **fph_ph](jI$)}(hjL$h]hstruct}(hj7hhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hj7ubj$)}(h h]h }(hj7hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj7ubh)}(hhh]jz!)}(hfutex_private_hashh]hfutex_private_hash}(hj7hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj7ubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetj7modnameN classnameNj$j$)}j$]jf6c.__futex_hashasbuh1hhj7ubj$)}(h h]h }(hj7hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj7ubj$)}(hj$h]h*}(hj7hhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj7ubj$)}(hj$h]h*}(hj7hhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj7ubjz!)}(hfph_ph]hfph_p}(hj7hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj7ubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hj6ubeh}(h]h ]h"]h$]h&]jjuh1j<$hj'6hhhj86hMiubeh}(h]h ]h"]h$]h&]jjj!uh1jm!j!j!hj#6hhhj86hMiubah}(h]j6ah ](j!j!eh"]h$]h&]j!j!)j!huh1jg!hj86hMihj 6hhubj!)}(hhh]h)}(hReturn the hash bucketh]hReturn the hash bucket}(hj8hhhNhNubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMihj8hhubah}(h]h ]h"]h$]h&]uh1j!hj 6hhhj86hMiubeh}(h]h ](jUfunctioneh"]h$]h&]j!jUj!j,8j!j,8j!j!j!uh1jb!hhhj6hNhNubj!)}(hXF**Parameters** ``union futex_key *key`` Pointer to the futex key for which the hash is calculated ``struct futex_private_hash *fph`` Pointer to private hash if known ``struct futex_private_hash **fph_p`` Pointer to a private hash pointer; output for the private hash used when set. **Description** We hash on the keys returned from get_futex_key (see below) and return the corresponding hash bucket. If the FUTEX is PROCESS_PRIVATE then a per-process hash bucket (from the private hash) is returned if existing. Otherwise a hash bucket from the global hash is returned.h](h)}(h**Parameters**h]j)}(hj68h]h Parameters}(hj88hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj48ubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMmhj08ubj")}(hhh](j")}(hS``union futex_key *key`` Pointer to the futex key for which the hash is calculated h](j")}(h``union futex_key *key``h]jI)}(hjU8h]hunion futex_key *key}(hjW8hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjS8ubah}(h]h ]h"]h$]h&]uh1j"h\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMjhjO8ubj5")}(hhh]h)}(h9Pointer to the futex key for which the hash is calculatedh]h9Pointer to the futex key for which the hash is calculated}(hjn8hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjj8hMjhjk8ubah}(h]h ]h"]h$]h&]uh1j4"hjO8ubeh}(h]h ]h"]h$]h&]uh1j"hjj8hMjhjL8ubj")}(hD``struct futex_private_hash *fph`` Pointer to private hash if known h](j")}(h"``struct futex_private_hash *fph``h]jI)}(hj8h]hstruct futex_private_hash *fph}(hj8hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj8ubah}(h]h ]h"]h$]h&]uh1j"h\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMkhj8ubj5")}(hhh]h)}(h Pointer to private hash if knownh]h Pointer to private hash if known}(hj8hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj8hMkhj8ubah}(h]h ]h"]h$]h&]uh1j4"hj8ubeh}(h]h ]h"]h$]h&]uh1j"hj8hMkhjL8ubj")}(ht``struct futex_private_hash **fph_p`` Pointer to a private hash pointer; output for the private hash used when set. h](j")}(h%``struct futex_private_hash **fph_p``h]jI)}(hj8h]h!struct futex_private_hash **fph_p}(hj8hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj8ubah}(h]h ]h"]h$]h&]uh1j"h\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMmhj8ubj5")}(hhh]h)}(hMPointer to a private hash pointer; output for the private hash used when set.h]hMPointer to a private hash pointer; output for the private hash used when set.}(hj8hhhNhNubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMlhj8ubah}(h]h ]h"]h$]h&]uh1j4"hj8ubeh}(h]h ]h"]h$]h&]uh1j"hj8hMmhjL8ubeh}(h]h ]h"]h$]h&]uh1j"hj08ubh)}(h**Description**h]j)}(hj9h]h Description}(hj9hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj9ubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMohj08ubh)}(hXWe hash on the keys returned from get_futex_key (see below) and return the corresponding hash bucket. If the FUTEX is PROCESS_PRIVATE then a per-process hash bucket (from the private hash) is returned if existing. Otherwise a hash bucket from the global hash is returned.h]hXWe hash on the keys returned from get_futex_key (see below) and return the corresponding hash bucket. If the FUTEX is PROCESS_PRIVATE then a per-process hash bucket (from the private hash) is returned if existing. Otherwise a hash bucket from the global hash is returned.}(hj9hhhNhNubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMnhj08ubeh}(h]h ] kernelindentah"]h$]h&]uh1j!hj6hhhNhNubjR!)}(hhh]h}(h]h ]h"]h$]h&]entries](j^!futex_setup_timer (C function)c.futex_setup_timerhNtauh1jQ!hj6hhhNhNubjc!)}(hhh](jh!)}(htstruct hrtimer_sleeper * futex_setup_timer (ktime_t *time, struct hrtimer_sleeper *timeout, int flags, u64 range_ns)h]jn!)}(hrstruct hrtimer_sleeper *futex_setup_timer(ktime_t *time, struct hrtimer_sleeper *timeout, int flags, u64 range_ns)h](jI$)}(hjL$h]hstruct}(hjH9hhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hjD9hhh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMubj$)}(h h]h }(hjV9hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjD9hhhjU9hMubh)}(hhh]jz!)}(hhrtimer_sleeperh]hhrtimer_sleeper}(hjg9hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjd9ubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetji9modnameN classnameNj$j$)}j$]j$)}j$futex_setup_timersbc.futex_setup_timerasbuh1hhjD9hhhjU9hMubj$)}(h h]h }(hj9hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjD9hhhjU9hMubj$)}(hj$h]h*}(hj9hhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjD9hhhjU9hMubjt!)}(hfutex_setup_timerh]jz!)}(hj9h]hfutex_setup_timer}(hj9hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj9ubah}(h]h ](j!j!eh"]h$]h&]jjuh1js!hjD9hhhjU9hMubj=$)}(hI(ktime_t *time, struct hrtimer_sleeper *timeout, int flags, u64 range_ns)h](jC$)}(h ktime_t *timeh](h)}(hhh]jz!)}(hktime_th]hktime_t}(hj9hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj9ubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetj9modnameN classnameNj$j$)}j$]j9c.futex_setup_timerasbuh1hhj9ubj$)}(h h]h }(hj9hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj9ubj$)}(hj$h]h*}(hj9hhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj9ubjz!)}(htimeh]htime}(hj9hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj9ubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hj9ubjC$)}(hstruct hrtimer_sleeper *timeouth](jI$)}(hjL$h]hstruct}(hj:hhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hj:ubj$)}(h h]h }(hj$:hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj:ubh)}(hhh]jz!)}(hhrtimer_sleeperh]hhrtimer_sleeper}(hj5:hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj2:ubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetj7:modnameN classnameNj$j$)}j$]j9c.futex_setup_timerasbuh1hhj:ubj$)}(h h]h }(hjS:hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj:ubj$)}(hj$h]h*}(hja:hhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj:ubjz!)}(htimeouth]htimeout}(hjn:hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj:ubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hj9ubjC$)}(h int flagsh](j$)}(hinth]hint}(hj:hhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj:ubj$)}(h h]h }(hj:hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj:ubjz!)}(hflagsh]hflags}(hj:hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj:ubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hj9ubjC$)}(h u64 range_nsh](h)}(hhh]jz!)}(hu64h]hu64}(hj:hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj:ubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetj:modnameN classnameNj$j$)}j$]j9c.futex_setup_timerasbuh1hhj:ubj$)}(h h]h }(hj:hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj:ubjz!)}(hrange_nsh]hrange_ns}(hj:hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj:ubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hj9ubeh}(h]h ]h"]h$]h&]jjuh1j<$hjD9hhhjU9hMubeh}(h]h ]h"]h$]h&]jjj!uh1jm!j!j!hj@9hhhjU9hMubah}(h]j;9ah ](j!j!eh"]h$]h&]j!j!)j!huh1jg!hjU9hMhj=9hhubj!)}(hhh]h)}(hset up the sleeping hrtimer.h]hset up the sleeping hrtimer.}(hj;hhhNhNubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhj;hhubah}(h]h ]h"]h$]h&]uh1j!hj=9hhhjU9hMubeh}(h]h ](jUfunctioneh"]h$]h&]j!jUj!j-;j!j-;j!j!j!uh1jb!hhhj6hNhNubj!)}(hX/**Parameters** ``ktime_t *time`` ptr to the given timeout value ``struct hrtimer_sleeper *timeout`` the hrtimer_sleeper structure to be set up ``int flags`` futex flags ``u64 range_ns`` optional range in ns **Return** Initialized hrtimer_sleeper structure or NULL if no timeout value givenh](h)}(h**Parameters**h]j)}(hj7;h]h Parameters}(hj9;hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj5;ubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhj1;ubj")}(hhh](j")}(h1``ktime_t *time`` ptr to the given timeout value h](j")}(h``ktime_t *time``h]jI)}(hjV;h]h ktime_t *time}(hjX;hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjT;ubah}(h]h ]h"]h$]h&]uh1j"h\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhjP;ubj5")}(hhh]h)}(hptr to the given timeout valueh]hptr to the given timeout value}(hjo;hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjk;hMhjl;ubah}(h]h ]h"]h$]h&]uh1j4"hjP;ubeh}(h]h ]h"]h$]h&]uh1j"hjk;hMhjM;ubj")}(hO``struct hrtimer_sleeper *timeout`` the hrtimer_sleeper structure to be set up h](j")}(h#``struct hrtimer_sleeper *timeout``h]jI)}(hj;h]hstruct hrtimer_sleeper *timeout}(hj;hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj;ubah}(h]h ]h"]h$]h&]uh1j"h\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhj;ubj5")}(hhh]h)}(h*the hrtimer_sleeper structure to be set uph]h*the hrtimer_sleeper structure to be set up}(hj;hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj;hMhj;ubah}(h]h ]h"]h$]h&]uh1j4"hj;ubeh}(h]h ]h"]h$]h&]uh1j"hj;hMhjM;ubj")}(h``int flags`` futex flags h](j")}(h ``int flags``h]jI)}(hj;h]h int flags}(hj;hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj;ubah}(h]h ]h"]h$]h&]uh1j"h\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhj;ubj5")}(hhh]h)}(h futex flagsh]h futex flags}(hj;hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj;hMhj;ubah}(h]h ]h"]h$]h&]uh1j4"hj;ubeh}(h]h ]h"]h$]h&]uh1j"hj;hMhjM;ubj")}(h&``u64 range_ns`` optional range in ns h](j")}(h``u64 range_ns``h]jI)}(hj<h]h u64 range_ns}(hj<hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj;ubah}(h]h ]h"]h$]h&]uh1j"h\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhj;ubj5")}(hhh]h)}(hoptional range in nsh]hoptional range in ns}(hj<hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj<hMhj<ubah}(h]h ]h"]h$]h&]uh1j4"hj;ubeh}(h]h ]h"]h$]h&]uh1j"hj<hMhjM;ubeh}(h]h ]h"]h$]h&]uh1j"hj1;ubh)}(h **Return**h]j)}(hj<<h]hReturn}(hj><hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj:<ubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhj1;ubh)}(hGInitialized hrtimer_sleeper structure or NULL if no timeout value givenh]hGInitialized hrtimer_sleeper structure or NULL if no timeout value given}(hjR<hhhNhNubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhj1;ubeh}(h]h ] kernelindentah"]h$]h&]uh1j!hj6hhhNhNubjR!)}(hhh]h}(h]h ]h"]h$]h&]entries](j^!get_futex_key (C function)c.get_futex_keyhNtauh1jQ!hj6hhhNhNubjc!)}(hhh](jh!)}(heint get_futex_key (u32 __user *uaddr, unsigned int flags, union futex_key *key, enum futex_access rw)h]jn!)}(hdint get_futex_key(u32 __user *uaddr, unsigned int flags, union futex_key *key, enum futex_access rw)h](j$)}(hinth]hint}(hj<hhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj}<hhh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMubj$)}(h h]h }(hj<hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj}<hhhj<hMubjt!)}(h get_futex_keyh]jz!)}(h get_futex_keyh]h get_futex_key}(hj<hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj<ubah}(h]h ](j!j!eh"]h$]h&]jjuh1js!hj}<hhhj<hMubj=$)}(hS(u32 __user *uaddr, unsigned int flags, union futex_key *key, enum futex_access rw)h](jC$)}(hu32 __user *uaddrh](h)}(hhh]jz!)}(hu32h]hu32}(hj<hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj<ubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetj<modnameN classnameNj$j$)}j$]j$)}j$j<sbc.get_futex_keyasbuh1hhj<ubj$)}(h h]h }(hj<hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj<ubh__user}(hj<hhhNhNubj$)}(h h]h }(hj<hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj<ubj$)}(hj$h]h*}(hj=hhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj<ubjz!)}(huaddrh]huaddr}(hj=hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj<ubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hj<ubjC$)}(hunsigned int flagsh](j$)}(hunsignedh]hunsigned}(hj'=hhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj#=ubj$)}(h h]h }(hj5=hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj#=ubj$)}(hinth]hint}(hjC=hhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj#=ubj$)}(h h]h }(hjQ=hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj#=ubjz!)}(hflagsh]hflags}(hj_=hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj#=ubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hj<ubjC$)}(hunion futex_key *keyh](jI$)}(hj6h]hunion}(hjx=hhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hjt=ubj$)}(h h]h }(hj=hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjt=ubh)}(hhh]jz!)}(h futex_keyh]h futex_key}(hj=hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj=ubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetj=modnameN classnameNj$j$)}j$]j<c.get_futex_keyasbuh1hhjt=ubj$)}(h h]h }(hj=hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjt=ubj$)}(hj$h]h*}(hj=hhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjt=ubjz!)}(hkeyh]hkey}(hj=hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjt=ubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hj<ubjC$)}(henum futex_access rwh](jI$)}(henumh]henum}(hj=hhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hj=ubj$)}(h h]h }(hj=hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj=ubh)}(hhh]jz!)}(h futex_accessh]h futex_access}(hj>hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj>ubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetj >modnameN classnameNj$j$)}j$]j<c.get_futex_keyasbuh1hhj=ubj$)}(h h]h }(hj%>hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj=ubjz!)}(hrwh]hrw}(hj3>hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj=ubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hj<ubeh}(h]h ]h"]h$]h&]jjuh1j<$hj}<hhhj<hMubeh}(h]h ]h"]h$]h&]jjj!uh1jm!j!j!hjy<hhhj<hMubah}(h]jt<ah ](j!j!eh"]h$]h&]j!j!)j!huh1jg!hj<hMhjv<hhubj!)}(hhh]h)}(h-Get parameters which are the keys for a futexh]h-Get parameters which are the keys for a futex}(hj]>hhhNhNubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhjZ>hhubah}(h]h ]h"]h$]h&]uh1j!hjv<hhhj<hMubeh}(h]h ](jUfunctioneh"]h$]h&]j!jUj!ju>j!ju>j!j!j!uh1jb!hhhj6hNhNubj!)}(hX<**Parameters** ``u32 __user *uaddr`` virtual address of the futex ``unsigned int flags`` FLAGS_* ``union futex_key *key`` address where result is stored. ``enum futex_access rw`` mapping needs to be read/write (values: FUTEX_READ, FUTEX_WRITE) **Return** a negative error code or 0 **Description** The key words are stored in **key** on success. For shared mappings (when **fshared**), the key is: ( inode->i_sequence, page offset within mapping, offset_within_page ) [ also see get_inode_sequence_number() ] For private mappings (or when **!fshared**), the key is: ( current->mm, address, 0 ) This allows (cross process, where applicable) identification of the futex without keeping the page pinned for the duration of the FUTEX_WAIT. lock_page() might sleep, the caller should not hold a spinlock.h](h)}(h**Parameters**h]j)}(hj>h]h Parameters}(hj>hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj}>ubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhjy>ubj")}(hhh](j")}(h3``u32 __user *uaddr`` virtual address of the futex h](j")}(h``u32 __user *uaddr``h]jI)}(hj>h]hu32 __user *uaddr}(hj>hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj>ubah}(h]h ]h"]h$]h&]uh1j"h\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhj>ubj5")}(hhh]h)}(hvirtual address of the futexh]hvirtual address of the futex}(hj>hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj>hMhj>ubah}(h]h ]h"]h$]h&]uh1j4"hj>ubeh}(h]h ]h"]h$]h&]uh1j"hj>hMhj>ubj")}(h``unsigned int flags`` FLAGS_* h](j")}(h``unsigned int flags``h]jI)}(hj>h]hunsigned int flags}(hj>hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj>ubah}(h]h ]h"]h$]h&]uh1j"h\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhj>ubj5")}(hhh]h)}(hFLAGS_*h]hFLAGS_*}(hj>hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj>hMhj>ubah}(h]h ]h"]h$]h&]uh1j4"hj>ubeh}(h]h ]h"]h$]h&]uh1j"hj>hMhj>ubj")}(h9``union futex_key *key`` address where result is stored. h](j")}(h``union futex_key *key``h]jI)}(hj?h]hunion futex_key *key}(hj?hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj?ubah}(h]h ]h"]h$]h&]uh1j"h\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhj ?ubj5")}(hhh]h)}(haddress where result is stored.h]haddress where result is stored.}(hj)?hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj%?hMhj&?ubah}(h]h ]h"]h$]h&]uh1j4"hj ?ubeh}(h]h ]h"]h$]h&]uh1j"hj%?hMhj>ubj")}(hZ``enum futex_access rw`` mapping needs to be read/write (values: FUTEX_READ, FUTEX_WRITE) h](j")}(h``enum futex_access rw``h]jI)}(hjI?h]henum futex_access rw}(hjK?hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjG?ubah}(h]h ]h"]h$]h&]uh1j"h\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhjC?ubj5")}(hhh]h)}(h@mapping needs to be read/write (values: FUTEX_READ, FUTEX_WRITE)h]h@mapping needs to be read/write (values: FUTEX_READ, FUTEX_WRITE)}(hjb?hhhNhNubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhj_?ubah}(h]h ]h"]h$]h&]uh1j4"hjC?ubeh}(h]h ]h"]h$]h&]uh1j"hj^?hMhj>ubeh}(h]h ]h"]h$]h&]uh1j"hjy>ubh)}(h **Return**h]j)}(hj?h]hReturn}(hj?hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj?ubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhjy>ubh)}(ha negative error code or 0h]ha negative error code or 0}(hj?hhhNhNubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhjy>ubh)}(h**Description**h]j)}(hj?h]h Description}(hj?hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj?ubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhjy>ubh)}(h/The key words are stored in **key** on success.h](hThe key words are stored in }(hj?hhhNhNubj)}(h**key**h]hkey}(hj?hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj?ubh on success.}(hj?hhhNhNubeh}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhjy>ubh)}(h3For shared mappings (when **fshared**), the key is:h](hFor shared mappings (when }(hj?hhhNhNubj)}(h **fshared**h]hfshared}(hj?hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj?ubh), the key is:}(hj?hhhNhNubeh}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhjy>ubj!)}(hF( inode->i_sequence, page offset within mapping, offset_within_page ) h]h)}(hE( inode->i_sequence, page offset within mapping, offset_within_page )h]hE( inode->i_sequence, page offset within mapping, offset_within_page )}(hj@hhhNhNubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhj@ubah}(h]h ]h"]h$]h&]uh1j!hj@hMhjy>ubh)}(h([ also see get_inode_sequence_number() ]h]h([ also see get_inode_sequence_number() ]}(hj@hhhNhNubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhjy>ubh)}(h8For private mappings (or when **!fshared**), the key is:h](hFor private mappings (or when }(hj,@hhhNhNubj)}(h **!fshared**h]h!fshared}(hj4@hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj,@ubh), the key is:}(hj,@hhhNhNubeh}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhjy>ubj!)}(h( current->mm, address, 0 ) h]h)}(h( current->mm, address, 0 )h]h( current->mm, address, 0 )}(hjQ@hhhNhNubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhjM@ubah}(h]h ]h"]h$]h&]uh1j!hj_@hMhjy>ubh)}(hThis allows (cross process, where applicable) identification of the futex without keeping the page pinned for the duration of the FUTEX_WAIT.h]hThis allows (cross process, where applicable) identification of the futex without keeping the page pinned for the duration of the FUTEX_WAIT.}(hjf@hhhNhNubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhjy>ubh)}(h?lock_page() might sleep, the caller should not hold a spinlock.h]h?lock_page() might sleep, the caller should not hold a spinlock.}(hju@hhhNhNubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhjy>ubeh}(h]h ] kernelindentah"]h$]h&]uh1j!hj6hhhNhNubjR!)}(hhh]h}(h]h ]h"]h$]h&]entries](j^!$fault_in_user_writeable (C function)c.fault_in_user_writeablehNtauh1jQ!hj6hhhNhNubjc!)}(hhh](jh!)}(h/int fault_in_user_writeable (u32 __user *uaddr)h]jn!)}(h.int fault_in_user_writeable(u32 __user *uaddr)h](j$)}(hinth]hint}(hj@hhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj@hhh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMubj$)}(h h]h }(hj@hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj@hhhj@hMubjt!)}(hfault_in_user_writeableh]jz!)}(hfault_in_user_writeableh]hfault_in_user_writeable}(hj@hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj@ubah}(h]h ](j!j!eh"]h$]h&]jjuh1js!hj@hhhj@hMubj=$)}(h(u32 __user *uaddr)h]jC$)}(hu32 __user *uaddrh](h)}(hhh]jz!)}(hu32h]hu32}(hj@hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj@ubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetj@modnameN classnameNj$j$)}j$]j$)}j$j@sbc.fault_in_user_writeableasbuh1hhj@ubj$)}(h h]h }(hjAhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj@ubh__user}(hj@hhhNhNubj$)}(h h]h }(hjAhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj@ubj$)}(hj$h]h*}(hj$AhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj@ubjz!)}(huaddrh]huaddr}(hj1AhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj@ubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hj@ubah}(h]h ]h"]h$]h&]jjuh1j<$hj@hhhj@hMubeh}(h]h ]h"]h$]h&]jjj!uh1jm!j!j!hj@hhhj@hMubah}(h]j@ah ](j!j!eh"]h$]h&]j!j!)j!huh1jg!hj@hMhj@hhubj!)}(hhh]h)}(h*Fault in user address and verify RW accessh]h*Fault in user address and verify RW access}(hj[AhhhNhNubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhjXAhhubah}(h]h ]h"]h$]h&]uh1j!hj@hhhj@hMubeh}(h]h ](jUfunctioneh"]h$]h&]j!jUj!jsAj!jsAj!j!j!uh1jb!hhhj6hNhNubj!)}(hX**Parameters** ``u32 __user *uaddr`` pointer to faulting user space address **Description** Slow path to fixup the fault we just took in the atomic write access to **uaddr**. We have no generic implementation of a non-destructive write to the user address. We know that we faulted in the atomic pagefault disabled section so we can as well avoid the #PF overhead by calling get_user_pages() right away.h](h)}(h**Parameters**h]j)}(hj}Ah]h Parameters}(hjAhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj{Aubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhjwAubj")}(hhh]j")}(h=``u32 __user *uaddr`` pointer to faulting user space address h](j")}(h``u32 __user *uaddr``h]jI)}(hjAh]hu32 __user *uaddr}(hjAhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjAubah}(h]h ]h"]h$]h&]uh1j"h\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhjAubj5")}(hhh]h)}(h&pointer to faulting user space addressh]h&pointer to faulting user space address}(hjAhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjAhMhjAubah}(h]h ]h"]h$]h&]uh1j4"hjAubeh}(h]h ]h"]h$]h&]uh1j"hjAhMhjAubah}(h]h ]h"]h$]h&]uh1j"hjwAubh)}(h**Description**h]j)}(hjAh]h Description}(hjAhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjAubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhjwAubh)}(hRSlow path to fixup the fault we just took in the atomic write access to **uaddr**.h](hHSlow path to fixup the fault we just took in the atomic write access to }(hjAhhhNhNubj)}(h **uaddr**h]huaddr}(hjAhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjAubh.}(hjAhhhNhNubeh}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhjwAubh)}(hWe have no generic implementation of a non-destructive write to the user address. We know that we faulted in the atomic pagefault disabled section so we can as well avoid the #PF overhead by calling get_user_pages() right away.h]hWe have no generic implementation of a non-destructive write to the user address. We know that we faulted in the atomic pagefault disabled section so we can as well avoid the #PF overhead by calling get_user_pages() right away.}(hjBhhhNhNubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhjwAubeh}(h]h ] kernelindentah"]h$]h&]uh1j!hj6hhhNhNubjR!)}(hhh]h}(h]h ]h"]h$]h&]entries](j^!futex_top_waiter (C function)c.futex_top_waiterhNtauh1jQ!hj6hhhNhNubjc!)}(hhh](jh!)}(hVstruct futex_q * futex_top_waiter (struct futex_hash_bucket *hb, union futex_key *key)h]jn!)}(hTstruct futex_q *futex_top_waiter(struct futex_hash_bucket *hb, union futex_key *key)h](jI$)}(hjL$h]hstruct}(hj=BhhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hj9Bhhh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMubj$)}(h h]h }(hjKBhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj9BhhhjJBhMubh)}(hhh]jz!)}(hfutex_qh]hfutex_q}(hj\BhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjYBubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetj^BmodnameN classnameNj$j$)}j$]j$)}j$futex_top_waitersbc.futex_top_waiterasbuh1hhj9BhhhjJBhMubj$)}(h h]h }(hj}BhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj9BhhhjJBhMubj$)}(hj$h]h*}(hjBhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj9BhhhjJBhMubjt!)}(hfutex_top_waiterh]jz!)}(hjzBh]hfutex_top_waiter}(hjBhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjBubah}(h]h ](j!j!eh"]h$]h&]jjuh1js!hj9BhhhjJBhMubj=$)}(h4(struct futex_hash_bucket *hb, union futex_key *key)h](jC$)}(hstruct futex_hash_bucket *hbh](jI$)}(hjL$h]hstruct}(hjBhhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hjBubj$)}(h h]h }(hjBhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjBubh)}(hhh]jz!)}(hfutex_hash_bucketh]hfutex_hash_bucket}(hjBhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjBubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetjBmodnameN classnameNj$j$)}j$]jxBc.futex_top_waiterasbuh1hhjBubj$)}(h h]h }(hjBhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjBubj$)}(hj$h]h*}(hjChhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjBubjz!)}(hhbh]hhb}(hjChhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjBubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hjBubjC$)}(hunion futex_key *keyh](jI$)}(hj6h]hunion}(hj'ChhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hj#Cubj$)}(h h]h }(hj4ChhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj#Cubh)}(hhh]jz!)}(h futex_keyh]h futex_key}(hjEChhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjBCubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetjGCmodnameN classnameNj$j$)}j$]jxBc.futex_top_waiterasbuh1hhj#Cubj$)}(h h]h }(hjcChhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj#Cubj$)}(hj$h]h*}(hjqChhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj#Cubjz!)}(hkeyh]hkey}(hj~ChhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj#Cubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hjBubeh}(h]h ]h"]h$]h&]jjuh1j<$hj9BhhhjJBhMubeh}(h]h ]h"]h$]h&]jjj!uh1jm!j!j!hj5BhhhjJBhMubah}(h]j0Bah ](j!j!eh"]h$]h&]j!j!)j!huh1jg!hjJBhMhj2Bhhubj!)}(hhh]h)}(h-Return the highest priority waiter on a futexh]h-Return the highest priority waiter on a futex}(hjChhhNhNubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhjChhubah}(h]h ]h"]h$]h&]uh1j!hj2BhhhjJBhMubeh}(h]h ](jUfunctioneh"]h$]h&]j!jUj!jCj!jCj!j!j!uh1jb!hhhj6hNhNubj!)}(h**Parameters** ``struct futex_hash_bucket *hb`` the hash bucket the futex_q's reside in ``union futex_key *key`` the futex key (to distinguish it from other futex futex_q's) **Description** Must be called with the hb lock held.h](h)}(h**Parameters**h]j)}(hjCh]h Parameters}(hjChhhNhNubah}(h]h ]h"]h$]h&]uh1jhjCubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhjCubj")}(hhh](j")}(hI``struct futex_hash_bucket *hb`` the hash bucket the futex_q's reside in h](j")}(h ``struct futex_hash_bucket *hb``h]jI)}(hjCh]hstruct futex_hash_bucket *hb}(hjChhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjCubah}(h]h ]h"]h$]h&]uh1j"h\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhjCubj5")}(hhh]h)}(h'the hash bucket the futex_q's reside inh]h)the hash bucket the futex_q’s reside in}(hjDhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjChMhjCubah}(h]h ]h"]h$]h&]uh1j4"hjCubeh}(h]h ]h"]h$]h&]uh1j"hjChMhjCubj")}(hV``union futex_key *key`` the futex key (to distinguish it from other futex futex_q's) h](j")}(h``union futex_key *key``h]jI)}(hj"Dh]hunion futex_key *key}(hj$DhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj Dubah}(h]h ]h"]h$]h&]uh1j"h\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhjDubj5")}(hhh]h)}(hthe futex key (to distinguish it from other futex futex_q’s)}(hj;DhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj7DhMhj8Dubah}(h]h ]h"]h$]h&]uh1j4"hjDubeh}(h]h ]h"]h$]h&]uh1j"hj7DhMhjCubeh}(h]h ]h"]h$]h&]uh1j"hjCubh)}(h**Description**h]j)}(hj]Dh]h Description}(hj_DhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj[Dubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhjCubh)}(h%Must be called with the hb lock held.h]h%Must be called with the hb lock held.}(hjsDhhhNhNubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhjCubeh}(h]h ] kernelindentah"]h$]h&]uh1j!hj6hhhNhNubjR!)}(hhh]h}(h]h ]h"]h$]h&]entries](j^!#wait_for_owner_exiting (C function)c.wait_for_owner_exitinghNtauh1jQ!hj6hhhNhNubjc!)}(hhh](jh!)}(hBvoid wait_for_owner_exiting (int ret, struct task_struct *exiting)h]jn!)}(hAvoid wait_for_owner_exiting(int ret, struct task_struct *exiting)h](j$)}(hvoidh]hvoid}(hjDhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjDhhh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMubj$)}(h h]h }(hjDhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjDhhhjDhMubjt!)}(hwait_for_owner_exitingh]jz!)}(hwait_for_owner_exitingh]hwait_for_owner_exiting}(hjDhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjDubah}(h]h ](j!j!eh"]h$]h&]jjuh1js!hjDhhhjDhMubj=$)}(h&(int ret, struct task_struct *exiting)h](jC$)}(hint reth](j$)}(hinth]hint}(hjDhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjDubj$)}(h h]h }(hjDhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjDubjz!)}(hreth]hret}(hjDhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjDubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hjDubjC$)}(hstruct task_struct *exitingh](jI$)}(hjL$h]hstruct}(hjEhhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hjEubj$)}(h h]h }(hj!EhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjEubh)}(hhh]jz!)}(h task_structh]h task_struct}(hj2EhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj/Eubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetj4EmodnameN classnameNj$j$)}j$]j$)}j$jDsbc.wait_for_owner_exitingasbuh1hhjEubj$)}(h h]h }(hjREhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjEubj$)}(hj$h]h*}(hj`EhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjEubjz!)}(hexitingh]hexiting}(hjmEhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjEubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hjDubeh}(h]h ]h"]h$]h&]jjuh1j<$hjDhhhjDhMubeh}(h]h ]h"]h$]h&]jjj!uh1jm!j!j!hjDhhhjDhMubah}(h]jDah ](j!j!eh"]h$]h&]j!j!)j!huh1jg!hjDhMhjDhhubj!)}(hhh]h)}(h Block until the owner has exitedh]h Block until the owner has exited}(hjEhhhNhNubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhjEhhubah}(h]h ]h"]h$]h&]uh1j!hjDhhhjDhMubeh}(h]h ](jUfunctioneh"]h$]h&]j!jUj!jEj!jEj!j!j!uh1jb!hhhj6hNhNubj!)}(h**Parameters** ``int ret`` owner's current futex lock status ``struct task_struct *exiting`` Pointer to the exiting task **Description** Caller must hold a refcount on **exiting**.h](h)}(h**Parameters**h]j)}(hjEh]h Parameters}(hjEhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjEubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chM hjEubj")}(hhh](j")}(h.``int ret`` owner's current futex lock status h](j")}(h ``int ret``h]jI)}(hjEh]hint ret}(hjEhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjEubah}(h]h ]h"]h$]h&]uh1j"h\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chM hjEubj5")}(hhh]h)}(h!owner's current futex lock statush]h#owner’s current futex lock status}(hjEhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjEhM hjEubah}(h]h ]h"]h$]h&]uh1j4"hjEubeh}(h]h ]h"]h$]h&]uh1j"hjEhM hjEubj")}(h<``struct task_struct *exiting`` Pointer to the exiting task h](j")}(h``struct task_struct *exiting``h]jI)}(hjFh]hstruct task_struct *exiting}(hjFhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjFubah}(h]h ]h"]h$]h&]uh1j"h\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chM hj Fubj5")}(hhh]h)}(hPointer to the exiting taskh]hPointer to the exiting task}(hj*FhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj&FhM hj'Fubah}(h]h ]h"]h$]h&]uh1j4"hj Fubeh}(h]h ]h"]h$]h&]uh1j"hj&FhM hjEubeh}(h]h ]h"]h$]h&]uh1j"hjEubh)}(h**Description**h]j)}(hjLFh]h Description}(hjNFhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjJFubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chM hjEubh)}(h+Caller must hold a refcount on **exiting**.h](hCaller must hold a refcount on }(hjbFhhhNhNubj)}(h **exiting**h]hexiting}(hjjFhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjbFubh.}(hjbFhhhNhNubeh}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chM hjEubeh}(h]h ] kernelindentah"]h$]h&]uh1j!hj6hhhNhNubjR!)}(hhh]h}(h]h ]h"]h$]h&]entries](j^!__futex_unqueue (C function)c.__futex_unqueuehNtauh1jQ!hj6hhhNhNubjc!)}(hhh](jh!)}(h(void __futex_unqueue (struct futex_q *q)h]jn!)}(h'void __futex_unqueue(struct futex_q *q)h](j$)}(hvoidh]hvoid}(hjFhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjFhhh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chM'ubj$)}(h h]h }(hjFhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjFhhhjFhM'ubjt!)}(h__futex_unqueueh]jz!)}(h__futex_unqueueh]h__futex_unqueue}(hjFhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjFubah}(h]h ](j!j!eh"]h$]h&]jjuh1js!hjFhhhjFhM'ubj=$)}(h(struct futex_q *q)h]jC$)}(hstruct futex_q *qh](jI$)}(hjL$h]hstruct}(hjFhhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hjFubj$)}(h h]h }(hjFhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjFubh)}(hhh]jz!)}(hfutex_qh]hfutex_q}(hjFhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjFubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetjGmodnameN classnameNj$j$)}j$]j$)}j$jFsbc.__futex_unqueueasbuh1hhjFubj$)}(h h]h }(hjGhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjFubj$)}(hj$h]h*}(hj,GhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjFubjz!)}(hqh]hq}(hj9GhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjFubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hjFubah}(h]h ]h"]h$]h&]jjuh1j<$hjFhhhjFhM'ubeh}(h]h ]h"]h$]h&]jjj!uh1jm!j!j!hjFhhhjFhM'ubah}(h]jFah ](j!j!eh"]h$]h&]j!j!)j!huh1jg!hjFhM'hjFhhubj!)}(hhh]h)}(h-Remove the futex_q from its futex_hash_bucketh]h-Remove the futex_q from its futex_hash_bucket}(hjcGhhhNhNubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chM'hj`Ghhubah}(h]h ]h"]h$]h&]uh1j!hjFhhhjFhM'ubeh}(h]h ](jUfunctioneh"]h$]h&]j!jUj!j{Gj!j{Gj!j!j!uh1jb!hhhj6hNhNubj!)}(h**Parameters** ``struct futex_q *q`` The futex_q to unqueue **Description** The q->lock_ptr must not be NULL and must be held by the caller.h](h)}(h**Parameters**h]j)}(hjGh]h Parameters}(hjGhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjGubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chM+hjGubj")}(hhh]j")}(h-``struct futex_q *q`` The futex_q to unqueue h](j")}(h``struct futex_q *q``h]jI)}(hjGh]hstruct futex_q *q}(hjGhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjGubah}(h]h ]h"]h$]h&]uh1j"h\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chM(hjGubj5")}(hhh]h)}(hThe futex_q to unqueueh]hThe futex_q to unqueue}(hjGhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjGhM(hjGubah}(h]h ]h"]h$]h&]uh1j4"hjGubeh}(h]h ]h"]h$]h&]uh1j"hjGhM(hjGubah}(h]h ]h"]h$]h&]uh1j"hjGubh)}(h**Description**h]j)}(hjGh]h Description}(hjGhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjGubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chM*hjGubh)}(h@The q->lock_ptr must not be NULL and must be held by the caller.h]h@The q->lock_ptr must not be NULL and must be held by the caller.}(hjGhhhNhNubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chM)hjGubeh}(h]h ] kernelindentah"]h$]h&]uh1j!hj6hhhNhNubjR!)}(hhh]h}(h]h ]h"]h$]h&]entries](j^!futex_unqueue (C function)c.futex_unqueuehNtauh1jQ!hj6hhhNhNubjc!)}(hhh](jh!)}(h%int futex_unqueue (struct futex_q *q)h]jn!)}(h$int futex_unqueue(struct futex_q *q)h](j$)}(hinth]hint}(hj$HhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj Hhhh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMgubj$)}(h h]h }(hj3HhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj Hhhhj2HhMgubjt!)}(h futex_unqueueh]jz!)}(h futex_unqueueh]h futex_unqueue}(hjEHhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjAHubah}(h]h ](j!j!eh"]h$]h&]jjuh1js!hj Hhhhj2HhMgubj=$)}(h(struct futex_q *q)h]jC$)}(hstruct futex_q *qh](jI$)}(hjL$h]hstruct}(hjaHhhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hj]Hubj$)}(h h]h }(hjnHhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj]Hubh)}(hhh]jz!)}(hfutex_qh]hfutex_q}(hjHhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj|Hubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetjHmodnameN classnameNj$j$)}j$]j$)}j$jGHsbc.futex_unqueueasbuh1hhj]Hubj$)}(h h]h }(hjHhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj]Hubj$)}(hj$h]h*}(hjHhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj]Hubjz!)}(hj;Gh]hq}(hjHhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj]Hubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hjYHubah}(h]h ]h"]h$]h&]jjuh1j<$hj Hhhhj2HhMgubeh}(h]h ]h"]h$]h&]jjj!uh1jm!j!j!hjHhhhj2HhMgubah}(h]jHah ](j!j!eh"]h$]h&]j!j!)j!huh1jg!hj2HhMghjHhhubj!)}(hhh]h)}(h-Remove the futex_q from its futex_hash_bucketh]h-Remove the futex_q from its futex_hash_bucket}(hjHhhhNhNubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMghjHhhubah}(h]h ]h"]h$]h&]uh1j!hjHhhhj2HhMgubeh}(h]h ](jUfunctioneh"]h$]h&]j!jUj!jHj!jHj!j!j!uh1jb!hhhj6hNhNubj!)}(hXh**Parameters** ``struct futex_q *q`` The futex_q to unqueue **Description** The q->lock_ptr must not be held by the caller. A call to futex_unqueue() must be paired with exactly one earlier call to futex_queue(). **Return** - 1 - if the futex_q was still queued (and we removed unqueued it); - 0 - if the futex_q was already removed by the waking threadh](h)}(h**Parameters**h]j)}(hjIh]h Parameters}(hjIhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjIubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMkhjHubj")}(hhh]j")}(h-``struct futex_q *q`` The futex_q to unqueue h](j")}(h``struct futex_q *q``h]jI)}(hj$Ih]hstruct futex_q *q}(hj&IhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj"Iubah}(h]h ]h"]h$]h&]uh1j"h\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhhjIubj5")}(hhh]h)}(hThe futex_q to unqueueh]hThe futex_q to unqueue}(hj=IhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj9IhMhhj:Iubah}(h]h ]h"]h$]h&]uh1j4"hjIubeh}(h]h ]h"]h$]h&]uh1j"hj9IhMhhjIubah}(h]h ]h"]h$]h&]uh1j"hjHubh)}(h**Description**h]j)}(hj_Ih]h Description}(hjaIhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj]Iubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMjhjHubh)}(hThe q->lock_ptr must not be held by the caller. A call to futex_unqueue() must be paired with exactly one earlier call to futex_queue().h]hThe q->lock_ptr must not be held by the caller. A call to futex_unqueue() must be paired with exactly one earlier call to futex_queue().}(hjuIhhhNhNubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMihjHubh)}(h **Return**h]j)}(hjIh]hReturn}(hjIhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjIubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMlhjHubj )}(hhh](j )}(hA1 - if the futex_q was still queued (and we removed unqueued it);h]h)}(hjIh]hA1 - if the futex_q was still queued (and we removed unqueued it);}(hjIhhhNhNubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMmhjIubah}(h]h ]h"]h$]h&]uh1j hjIubj )}(h;0 - if the futex_q was already removed by the waking threadh]h)}(hjIh]h;0 - if the futex_q was already removed by the waking thread}(hjIhhhNhNubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMnhjIubah}(h]h ]h"]h$]h&]uh1j hjIubeh}(h]h ]h"]h$]h&]j5 j6 uh1j hjIhMmhjHubeh}(h]h ] kernelindentah"]h$]h&]uh1j!hj6hhhNhNubjR!)}(hhh]h}(h]h ]h"]h$]h&]entries](j^!!futex_exit_recursive (C function)c.futex_exit_recursivehNtauh1jQ!hj6hhhNhNubjc!)}(hhh](jh!)}(h3void futex_exit_recursive (struct task_struct *tsk)h]jn!)}(h2void futex_exit_recursive(struct task_struct *tsk)h](j$)}(hvoidh]hvoid}(hjIhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjIhhh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMubj$)}(h h]h }(hjJhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjIhhhjJhMubjt!)}(hfutex_exit_recursiveh]jz!)}(hfutex_exit_recursiveh]hfutex_exit_recursive}(hjJhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjJubah}(h]h ](j!j!eh"]h$]h&]jjuh1js!hjIhhhjJhMubj=$)}(h(struct task_struct *tsk)h]jC$)}(hstruct task_struct *tskh](jI$)}(hjL$h]hstruct}(hj2JhhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hj.Jubj$)}(h h]h }(hj?JhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj.Jubh)}(hhh]jz!)}(h task_structh]h task_struct}(hjPJhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjMJubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetjRJmodnameN classnameNj$j$)}j$]j$)}j$jJsbc.futex_exit_recursiveasbuh1hhj.Jubj$)}(h h]h }(hjpJhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj.Jubj$)}(hj$h]h*}(hj~JhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj.Jubjz!)}(htskh]htsk}(hjJhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj.Jubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hj*Jubah}(h]h ]h"]h$]h&]jjuh1j<$hjIhhhjJhMubeh}(h]h ]h"]h$]h&]jjj!uh1jm!j!j!hjIhhhjJhMubah}(h]jIah ](j!j!eh"]h$]h&]j!j!)j!huh1jg!hjJhMhjIhhubj!)}(hhh]h)}(h-Set the tasks futex state to FUTEX_STATE_DEADh]h-Set the tasks futex state to FUTEX_STATE_DEAD}(hjJhhhNhNubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhjJhhubah}(h]h ]h"]h$]h&]uh1j!hjIhhhjJhMubeh}(h]h ](jUfunctioneh"]h$]h&]j!jUj!jJj!jJj!j!j!uh1jb!hhhj6hNhNubj!)}(hX**Parameters** ``struct task_struct *tsk`` task to set the state on **Description** Set the futex exit state of the task lockless. The futex waiter code observes that state when a task is exiting and loops until the task has actually finished the futex cleanup. The worst case for this is that the waiter runs through the wait loop until the state becomes visible. This is called from the recursive fault handling path in make_task_dead(). This is best effort. Either the futex exit code has run already or not. If the OWNER_DIED bit has been set on the futex then the waiter can take it over. If not, the problem is pushed back to user space. If the futex exit code did not run yet, then an already queued waiter might block forever, but there is nothing which can be done about that.h](h)}(h**Parameters**h]j)}(hjJh]h Parameters}(hjJhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjJubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhjJubj")}(hhh]j")}(h5``struct task_struct *tsk`` task to set the state on h](j")}(h``struct task_struct *tsk``h]jI)}(hjJh]hstruct task_struct *tsk}(hjJhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjJubah}(h]h ]h"]h$]h&]uh1j"h\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhjJubj5")}(hhh]h)}(htask to set the state onh]htask to set the state on}(hjKhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj KhMhj Kubah}(h]h ]h"]h$]h&]uh1j4"hjJubeh}(h]h ]h"]h$]h&]uh1j"hj KhMhjJubah}(h]h ]h"]h$]h&]uh1j"hjJubh)}(h**Description**h]j)}(hj1Kh]h Description}(hj3KhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj/Kubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhjJubh)}(hXSet the futex exit state of the task lockless. The futex waiter code observes that state when a task is exiting and loops until the task has actually finished the futex cleanup. The worst case for this is that the waiter runs through the wait loop until the state becomes visible.h]hXSet the futex exit state of the task lockless. The futex waiter code observes that state when a task is exiting and loops until the task has actually finished the futex cleanup. The worst case for this is that the waiter runs through the wait loop until the state becomes visible.}(hjGKhhhNhNubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhjJubh)}(hJThis is called from the recursive fault handling path in make_task_dead().h]hJThis is called from the recursive fault handling path in make_task_dead().}(hjVKhhhNhNubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhjJubh)}(hXYThis is best effort. Either the futex exit code has run already or not. If the OWNER_DIED bit has been set on the futex then the waiter can take it over. If not, the problem is pushed back to user space. If the futex exit code did not run yet, then an already queued waiter might block forever, but there is nothing which can be done about that.h]hXYThis is best effort. Either the futex exit code has run already or not. If the OWNER_DIED bit has been set on the futex then the waiter can take it over. If not, the problem is pushed back to user space. If the futex exit code did not run yet, then an already queued waiter might block forever, but there is nothing which can be done about that.}(hjeKhhhNhNubah}(h]h ]h"]h$]h&]uh1hh\/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1355: ./kernel/futex/core.chMhjJubeh}(h]h ] kernelindentah"]h$]h&]uh1j!hj6hhhNhNubjR!)}(hhh]h}(h]h ]h"]h$]h&]entries](j^!futex_q (C struct) c.futex_qhNtauh1jQ!hj6hhh]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhNubjc!)}(hhh](jh!)}(hfutex_qh]jn!)}(hstruct futex_qh](jI$)}(hjL$h]hstruct}(hjKhhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hjKhhh]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhKubj$)}(h h]h }(hjKhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjKhhhjKhKubjt!)}(hfutex_qh]jz!)}(hjKh]hfutex_q}(hjKhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjKubah}(h]h ](j!j!eh"]h$]h&]jjuh1js!hjKhhhjKhKubeh}(h]h ]h"]h$]h&]jjj!uh1jm!j!j!hjKhhhjKhKubah}(h]jKah ](j!j!eh"]h$]h&]j!j!)j!huh1jg!hjKhKhjKhhubj!)}(hhh]h)}(h2The hashed futex queue entry, one per waiting taskh]h2The hashed futex queue entry, one per waiting task}(hjKhhhNhNubah}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhKhjKhhubah}(h]h ]h"]h$]h&]uh1j!hjKhhhjKhKubeh}(h]h ](jUstructeh"]h$]h&]j!jUj!jKj!jKj!j!j!uh1jb!hhhj6hjKhNubj!)}(hX**Definition**:: struct futex_q { struct plist_node list; struct task_struct *task; spinlock_t *lock_ptr; futex_wake_fn *wake; void *wake_data; union futex_key key; struct futex_pi_state *pi_state; struct rt_mutex_waiter *rt_waiter; union futex_key *requeue_pi_key; u32 bitset; atomic_t requeue_state; struct futex_private_hash *drop_fph; #ifdef CONFIG_PREEMPT_RT; struct rcuwait requeue_wait; #endif; }; **Members** ``list`` priority-sorted list of tasks waiting on this futex ``task`` the task waiting on the futex ``lock_ptr`` the hash bucket lock ``wake`` the wake handler for this queue ``wake_data`` data associated with the wake handler ``key`` the key the futex is hashed on ``pi_state`` optional priority inheritance state ``rt_waiter`` rt_waiter storage for use with requeue_pi ``requeue_pi_key`` the requeue_pi target futex key ``bitset`` bitset for the optional bitmasked wakeup ``requeue_state`` State field for futex_requeue_pi() ``drop_fph`` Waiter should drop the extra private hash reference when set ``requeue_wait`` RCU wait for futex_requeue_pi() (RT only)h](h)}(h**Definition**::h](j)}(h**Definition**h]h Definition}(hjKhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjKubh:}(hjKhhhNhNubeh}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhKhjKubj~)}(hXstruct futex_q { struct plist_node list; struct task_struct *task; spinlock_t *lock_ptr; futex_wake_fn *wake; void *wake_data; union futex_key key; struct futex_pi_state *pi_state; struct rt_mutex_waiter *rt_waiter; union futex_key *requeue_pi_key; u32 bitset; atomic_t requeue_state; struct futex_private_hash *drop_fph; #ifdef CONFIG_PREEMPT_RT; struct rcuwait requeue_wait; #endif; };h]hXstruct futex_q { struct plist_node list; struct task_struct *task; spinlock_t *lock_ptr; futex_wake_fn *wake; void *wake_data; union futex_key key; struct futex_pi_state *pi_state; struct rt_mutex_waiter *rt_waiter; union futex_key *requeue_pi_key; u32 bitset; atomic_t requeue_state; struct futex_private_hash *drop_fph; #ifdef CONFIG_PREEMPT_RT; struct rcuwait requeue_wait; #endif; };}hjLsbah}(h]h ]h"]h$]h&]jjuh1j}h]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhKhjKubh)}(h **Members**h]j)}(hj%Lh]hMembers}(hj'LhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj#Lubah}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhKhjKubj")}(hhh](j")}(h=``list`` priority-sorted list of tasks waiting on this futex h](j")}(h``list``h]jI)}(hjDLh]hlist}(hjFLhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjBLubah}(h]h ]h"]h$]h&]uh1j"h]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhKhj>Lubj5")}(hhh]h)}(h3priority-sorted list of tasks waiting on this futexh]h3priority-sorted list of tasks waiting on this futex}(hj]LhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjYLhKhjZLubah}(h]h ]h"]h$]h&]uh1j4"hj>Lubeh}(h]h ]h"]h$]h&]uh1j"hjYLhKhj;Lubj")}(h'``task`` the task waiting on the futex h](j")}(h``task``h]jI)}(hj}Lh]htask}(hjLhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj{Lubah}(h]h ]h"]h$]h&]uh1j"h]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhKhjwLubj5")}(hhh]h)}(hthe task waiting on the futexh]hthe task waiting on the futex}(hjLhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjLhKhjLubah}(h]h ]h"]h$]h&]uh1j4"hjwLubeh}(h]h ]h"]h$]h&]uh1j"hjLhKhj;Lubj")}(h"``lock_ptr`` the hash bucket lock h](j")}(h ``lock_ptr``h]jI)}(hjLh]hlock_ptr}(hjLhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjLubah}(h]h ]h"]h$]h&]uh1j"h]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhKhjLubj5")}(hhh]h)}(hthe hash bucket lockh]hthe hash bucket lock}(hjLhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjLhKhjLubah}(h]h ]h"]h$]h&]uh1j4"hjLubeh}(h]h ]h"]h$]h&]uh1j"hjLhKhj;Lubj")}(h)``wake`` the wake handler for this queue h](j")}(h``wake``h]jI)}(hjLh]hwake}(hjLhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjLubah}(h]h ]h"]h$]h&]uh1j"h]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhKhjLubj5")}(hhh]h)}(hthe wake handler for this queueh]hthe wake handler for this queue}(hjMhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjMhKhjMubah}(h]h ]h"]h$]h&]uh1j4"hjLubeh}(h]h ]h"]h$]h&]uh1j"hjMhKhj;Lubj")}(h4``wake_data`` data associated with the wake handler h](j")}(h ``wake_data``h]jI)}(hj(Mh]h wake_data}(hj*MhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj&Mubah}(h]h ]h"]h$]h&]uh1j"h]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhKhj"Mubj5")}(hhh]h)}(h%data associated with the wake handlerh]h%data associated with the wake handler}(hjAMhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj=MhKhj>Mubah}(h]h ]h"]h$]h&]uh1j4"hj"Mubeh}(h]h ]h"]h$]h&]uh1j"hj=MhKhj;Lubj")}(h'``key`` the key the futex is hashed on h](j")}(h``key``h]jI)}(hjaMh]hkey}(hjcMhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj_Mubah}(h]h ]h"]h$]h&]uh1j"h]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhKhj[Mubj5")}(hhh]h)}(hthe key the futex is hashed onh]hthe key the futex is hashed on}(hjzMhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjvMhKhjwMubah}(h]h ]h"]h$]h&]uh1j4"hj[Mubeh}(h]h ]h"]h$]h&]uh1j"hjvMhKhj;Lubj")}(h1``pi_state`` optional priority inheritance state h](j")}(h ``pi_state``h]jI)}(hjMh]hpi_state}(hjMhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjMubah}(h]h ]h"]h$]h&]uh1j"h]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhKhjMubj5")}(hhh]h)}(h#optional priority inheritance stateh]h#optional priority inheritance state}(hjMhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjMhKhjMubah}(h]h ]h"]h$]h&]uh1j4"hjMubeh}(h]h ]h"]h$]h&]uh1j"hjMhKhj;Lubj")}(h8``rt_waiter`` rt_waiter storage for use with requeue_pi h](j")}(h ``rt_waiter``h]jI)}(hjMh]h rt_waiter}(hjMhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjMubah}(h]h ]h"]h$]h&]uh1j"h]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhKhjMubj5")}(hhh]h)}(h)rt_waiter storage for use with requeue_pih]h)rt_waiter storage for use with requeue_pi}(hjMhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjMhKhjMubah}(h]h ]h"]h$]h&]uh1j4"hjMubeh}(h]h ]h"]h$]h&]uh1j"hjMhKhj;Lubj")}(h3``requeue_pi_key`` the requeue_pi target futex key h](j")}(h``requeue_pi_key``h]jI)}(hj Nh]hrequeue_pi_key}(hjNhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj Nubah}(h]h ]h"]h$]h&]uh1j"h]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhKhjNubj5")}(hhh]h)}(hthe requeue_pi target futex keyh]hthe requeue_pi target futex key}(hj%NhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj!NhKhj"Nubah}(h]h ]h"]h$]h&]uh1j4"hjNubeh}(h]h ]h"]h$]h&]uh1j"hj!NhKhj;Lubj")}(h4``bitset`` bitset for the optional bitmasked wakeup h](j")}(h ``bitset``h]jI)}(hjENh]hbitset}(hjGNhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjCNubah}(h]h ]h"]h$]h&]uh1j"h]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhKhj?Nubj5")}(hhh]h)}(h(bitset for the optional bitmasked wakeuph]h(bitset for the optional bitmasked wakeup}(hj^NhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjZNhKhj[Nubah}(h]h ]h"]h$]h&]uh1j4"hj?Nubeh}(h]h ]h"]h$]h&]uh1j"hjZNhKhj;Lubj")}(h5``requeue_state`` State field for futex_requeue_pi() h](j")}(h``requeue_state``h]jI)}(hj~Nh]h requeue_state}(hjNhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj|Nubah}(h]h ]h"]h$]h&]uh1j"h]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhKhjxNubj5")}(hhh]h)}(h"State field for futex_requeue_pi()h]h"State field for futex_requeue_pi()}(hjNhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjNhKhjNubah}(h]h ]h"]h$]h&]uh1j4"hjxNubeh}(h]h ]h"]h$]h&]uh1j"hjNhKhj;Lubj")}(hJ``drop_fph`` Waiter should drop the extra private hash reference when set h](j")}(h ``drop_fph``h]jI)}(hjNh]hdrop_fph}(hjNhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjNubah}(h]h ]h"]h$]h&]uh1j"h]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhKhjNubj5")}(hhh]h)}(hlist `) || q->lock_ptr == 0. The order of wakeup is always to make the first condition true, then the second.h](hmA futex_q has a woken state, just like tasks have TASK_RUNNING. It is considered woken when plist_node_empty(}(hjXOhhhNhNubh)}(h:c:type:`q->list `h]jI)}(hjbOh]hq->list}(hjdOhhhNhNubah}(h]h ](jTjUc-typeeh"]h$]h&]uh1jHhj`Oubah}(h]h ]h"]h$]h&]refdocja refdomainjUreftypetype refexplicitrefwarnj$j$)}j$]sbjgj;Guh1hh]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhKhjXOubhg) || q->lock_ptr == 0. The order of wakeup is always to make the first condition true, then the second.}(hjXOhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhjOhKhj6hhubh)}(hxPI futexes are typically woken before they are removed from the hash list via the rt_mutex code. See futex_unqueue_pi().h]hxPI futexes are typically woken before they are removed from the hash list via the rt_mutex code. See futex_unqueue_pi().}(hjOhhhNhNubah}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhKhj6hhubjR!)}(hhh]h}(h]h ]h"]h$]h&]entries](j^!futex_match (C function) c.futex_matchhNtauh1jQ!hj6hhhjKhNubjc!)}(hhh](jh!)}(h>int futex_match (union futex_key *key1, union futex_key *key2)h]jn!)}(h=int futex_match(union futex_key *key1, union futex_key *key2)h](j$)}(hinth]hint}(hjOhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjOhhh]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhM ubj$)}(h h]h }(hjOhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjOhhhjOhM ubjt!)}(h futex_matchh]jz!)}(h futex_matchh]h futex_match}(hjOhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjOubah}(h]h ](j!j!eh"]h$]h&]jjuh1js!hjOhhhjOhM ubj=$)}(h.(union futex_key *key1, union futex_key *key2)h](jC$)}(hunion futex_key *key1h](jI$)}(hj6h]hunion}(hjOhhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hjOubj$)}(h h]h }(hjOhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjOubh)}(hhh]jz!)}(h futex_keyh]h futex_key}(hjPhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj Pubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetjPmodnameN classnameNj$j$)}j$]j$)}j$jOsb c.futex_matchasbuh1hhjOubj$)}(h h]h }(hj/PhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjOubj$)}(hj$h]h*}(hj=PhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjOubjz!)}(hkey1h]hkey1}(hjJPhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjOubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hjOubjC$)}(hunion futex_key *key2h](jI$)}(hj6h]hunion}(hjcPhhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hj_Pubj$)}(h h]h }(hjpPhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj_Pubh)}(hhh]jz!)}(h futex_keyh]h futex_key}(hjPhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj~Pubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetjPmodnameN classnameNj$j$)}j$]j+P c.futex_matchasbuh1hhj_Pubj$)}(h h]h }(hjPhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj_Pubj$)}(hj$h]h*}(hjPhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj_Pubjz!)}(hkey2h]hkey2}(hjPhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj_Pubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hjOubeh}(h]h ]h"]h$]h&]jjuh1j<$hjOhhhjOhM ubeh}(h]h ]h"]h$]h&]jjj!uh1jm!j!j!hjOhhhjOhM ubah}(h]jOah ](j!j!eh"]h$]h&]j!j!)j!huh1jg!hjOhM hjOhhubj!)}(hhh]h)}(h&Check whether two futex keys are equalh]h&Check whether two futex keys are equal}(hjPhhhNhNubah}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhM hjPhhubah}(h]h ]h"]h$]h&]uh1j!hjOhhhjOhM ubeh}(h]h ](jUfunctioneh"]h$]h&]j!jUj!jPj!jPj!j!j!uh1jb!hhhj6hjKhNubj!)}(h**Parameters** ``union futex_key *key1`` Pointer to key1 ``union futex_key *key2`` Pointer to key2 **Description** Return 1 if two futex_keys are equal, 0 otherwise.h](h)}(h**Parameters**h]j)}(hjQh]h Parameters}(hjQhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjQubah}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhMhjQubj")}(hhh](j")}(h*``union futex_key *key1`` Pointer to key1 h](j")}(h``union futex_key *key1``h]jI)}(hj%Qh]hunion futex_key *key1}(hj'QhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj#Qubah}(h]h ]h"]h$]h&]uh1j"h]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhM hjQubj5")}(hhh]h)}(hPointer to key1h]hPointer to key1}(hj>QhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj:QhM hj;Qubah}(h]h ]h"]h$]h&]uh1j4"hjQubeh}(h]h ]h"]h$]h&]uh1j"hj:QhM hjQubj")}(h*``union futex_key *key2`` Pointer to key2 h](j")}(h``union futex_key *key2``h]jI)}(hj^Qh]hunion futex_key *key2}(hj`QhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj\Qubah}(h]h ]h"]h$]h&]uh1j"h]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhM hjXQubj5")}(hhh]h)}(hPointer to key2h]hPointer to key2}(hjwQhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjsQhM hjtQubah}(h]h ]h"]h$]h&]uh1j4"hjXQubeh}(h]h ]h"]h$]h&]uh1j"hjsQhM hjQubeh}(h]h ]h"]h$]h&]uh1j"hjQubh)}(h**Description**h]j)}(hjQh]h Description}(hjQhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjQubah}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhMhjQubh)}(h2Return 1 if two futex_keys are equal, 0 otherwise.h]h2Return 1 if two futex_keys are equal, 0 otherwise.}(hjQhhhNhNubah}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhM hjQubeh}(h]h ] kernelindentah"]h$]h&]uh1j!hj6hhhjKhNubjR!)}(hhh]h}(h]h ]h"]h$]h&]entries](j^!futex_queue (C function) c.futex_queuehNtauh1jQ!hj6hhhjKhNubjc!)}(hhh](jh!)}(h\void futex_queue (struct futex_q *q, struct futex_hash_bucket *hb, struct task_struct *task)h]jn!)}(h[void futex_queue(struct futex_q *q, struct futex_hash_bucket *hb, struct task_struct *task)h](j$)}(hvoidh]hvoid}(hjQhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjQhhh]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhM:ubj$)}(h h]h }(hjQhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjQhhhjQhM:ubjt!)}(h futex_queueh]jz!)}(h futex_queueh]h futex_queue}(hjQhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjQubah}(h]h ](j!j!eh"]h$]h&]jjuh1js!hjQhhhjQhM:ubj=$)}(hK(struct futex_q *q, struct futex_hash_bucket *hb, struct task_struct *task)h](jC$)}(hstruct futex_q *qh](jI$)}(hjL$h]hstruct}(hjRhhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hjRubj$)}(h h]h }(hj(RhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjRubh)}(hhh]jz!)}(hfutex_qh]hfutex_q}(hj9RhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj6Rubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetj;RmodnameN classnameNj$j$)}j$]j$)}j$jRsb c.futex_queueasbuh1hhjRubj$)}(h h]h }(hjYRhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjRubj$)}(hj$h]h*}(hjgRhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjRubjz!)}(hj;Gh]hq}(hjtRhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjRubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hjRubjC$)}(hstruct futex_hash_bucket *hbh](jI$)}(hjL$h]hstruct}(hjRhhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hjRubj$)}(h h]h }(hjRhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjRubh)}(hhh]jz!)}(hfutex_hash_bucketh]hfutex_hash_bucket}(hjRhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjRubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetjRmodnameN classnameNj$j$)}j$]jUR c.futex_queueasbuh1hhjRubj$)}(h h]h }(hjRhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjRubj$)}(hj$h]h*}(hjRhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjRubjz!)}(hhbh]hhb}(hjRhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjRubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hjRubjC$)}(hstruct task_struct *taskh](jI$)}(hjL$h]hstruct}(hjRhhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hjRubj$)}(h h]h }(hj ShhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjRubh)}(hhh]jz!)}(h task_structh]h task_struct}(hjShhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjSubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetjSmodnameN classnameNj$j$)}j$]jUR c.futex_queueasbuh1hhjRubj$)}(h h]h }(hj8ShhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjRubj$)}(hj$h]h*}(hjFShhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjRubjz!)}(htaskh]htask}(hjSShhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjRubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hjRubeh}(h]h ]h"]h$]h&]jjuh1j<$hjQhhhjQhM:ubeh}(h]h ]h"]h$]h&]jjj!uh1jm!j!j!hjQhhhjQhM:ubah}(h]jQah ](j!j!eh"]h$]h&]j!j!)j!huh1jg!hjQhM:hjQhhubj!)}(hhh]h)}(h,Enqueue the futex_q on the futex_hash_bucketh]h,Enqueue the futex_q on the futex_hash_bucket}(hj}ShhhNhNubah}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhM:hjzShhubah}(h]h ]h"]h$]h&]uh1j!hjQhhhjQhM:ubeh}(h]h ](jUfunctioneh"]h$]h&]j!jUj!jSj!jSj!j!j!uh1jb!hhhj6hjKhNubj!)}(hX**Parameters** ``struct futex_q *q`` The futex_q to enqueue ``struct futex_hash_bucket *hb`` The destination hash bucket ``struct task_struct *task`` Task queueing this futex **Description** The hb->lock must be held by the caller, and is released here. A call to futex_queue() is typically paired with exactly one call to futex_unqueue(). The exceptions involve the PI related operations, which may use futex_unqueue_pi() or nothing if the unqueue is done as part of the wake process and the unqueue state is implicit in the state of woken task (see futex_wait_requeue_pi() for an example). Note that **task** may be NULL, for async usage of futexes.h](h)}(h**Parameters**h]j)}(hjSh]h Parameters}(hjShhhNhNubah}(h]h ]h"]h$]h&]uh1jhjSubah}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhM>hjSubj")}(hhh](j")}(h-``struct futex_q *q`` The futex_q to enqueue h](j")}(h``struct futex_q *q``h]jI)}(hjSh]hstruct futex_q *q}(hjShhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjSubah}(h]h ]h"]h$]h&]uh1j"h]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhM;hjSubj5")}(hhh]h)}(hThe futex_q to enqueueh]hThe futex_q to enqueue}(hjShhhNhNubah}(h]h ]h"]h$]h&]uh1hhjShM;hjSubah}(h]h ]h"]h$]h&]uh1j4"hjSubeh}(h]h ]h"]h$]h&]uh1j"hjShM;hjSubj")}(h=``struct futex_hash_bucket *hb`` The destination hash bucket h](j")}(h ``struct futex_hash_bucket *hb``h]jI)}(hjSh]hstruct futex_hash_bucket *hb}(hjShhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjSubah}(h]h ]h"]h$]h&]uh1j"h]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhM<hjSubj5")}(hhh]h)}(hThe destination hash bucketh]hThe destination hash bucket}(hjThhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ThM<hj Tubah}(h]h ]h"]h$]h&]uh1j4"hjSubeh}(h]h ]h"]h$]h&]uh1j"hj ThM<hjSubj")}(h6``struct task_struct *task`` Task queueing this futex h](j")}(h``struct task_struct *task``h]jI)}(hj0Th]hstruct task_struct *task}(hj2ThhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj.Tubah}(h]h ]h"]h$]h&]uh1j"h]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhM=hj*Tubj5")}(hhh]h)}(hTask queueing this futexh]hTask queueing this futex}(hjIThhhNhNubah}(h]h ]h"]h$]h&]uh1hhjEThM=hjFTubah}(h]h ]h"]h$]h&]uh1j4"hj*Tubeh}(h]h ]h"]h$]h&]uh1j"hjEThM=hjSubeh}(h]h ]h"]h$]h&]uh1j"hjSubh)}(h**Description**h]j)}(hjkTh]h Description}(hjmThhhNhNubah}(h]h ]h"]h$]h&]uh1jhjiTubah}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhM?hjSubh)}(hXThe hb->lock must be held by the caller, and is released here. A call to futex_queue() is typically paired with exactly one call to futex_unqueue(). The exceptions involve the PI related operations, which may use futex_unqueue_pi() or nothing if the unqueue is done as part of the wake process and the unqueue state is implicit in the state of woken task (see futex_wait_requeue_pi() for an example).h]hXThe hb->lock must be held by the caller, and is released here. A call to futex_queue() is typically paired with exactly one call to futex_unqueue(). The exceptions involve the PI related operations, which may use futex_unqueue_pi() or nothing if the unqueue is done as part of the wake process and the unqueue state is implicit in the state of woken task (see futex_wait_requeue_pi() for an example).}(hjThhhNhNubah}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhM>hjSubh)}(h;Note that **task** may be NULL, for async usage of futexes.h](h Note that }(hjThhhNhNubj)}(h**task**h]htask}(hjThhhNhNubah}(h]h ]h"]h$]h&]uh1jhjTubh) may be NULL, for async usage of futexes.}(hjThhhNhNubeh}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhMEhjSubeh}(h]h ] kernelindentah"]h$]h&]uh1j!hj6hhhjKhNubjR!)}(hhh]h}(h]h ]h"]h$]h&]entries](j^!futex_vector (C struct)c.futex_vectorhNtauh1jQ!hj6hhhjKhNubjc!)}(hhh](jh!)}(h futex_vectorh]jn!)}(hstruct futex_vectorh](jI$)}(hjL$h]hstruct}(hjThhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hjThhh]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhMJubj$)}(h h]h }(hjThhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjThhhjThMJubjt!)}(h futex_vectorh]jz!)}(hjTh]h futex_vector}(hjThhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjTubah}(h]h ](j!j!eh"]h$]h&]jjuh1js!hjThhhjThMJubeh}(h]h ]h"]h$]h&]jjj!uh1jm!j!j!hjThhhjThMJubah}(h]jTah ](j!j!eh"]h$]h&]j!j!)j!huh1jg!hjThMJhjThhubj!)}(hhh]h)}(h"Auxiliary struct for futex_waitv()h]h"Auxiliary struct for futex_waitv()}(hjUhhhNhNubah}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhMhjUhhubah}(h]h ]h"]h$]h&]uh1j!hjThhhjThMJubeh}(h]h ](jUstructeh"]h$]h&]j!jUj!j+Uj!j+Uj!j!j!uh1jb!hhhj6hjKhNubj!)}(h**Definition**:: struct futex_vector { struct futex_waitv w; struct futex_q q; }; **Members** ``w`` Userspace provided data ``q`` Kernel side datah](h)}(h**Definition**::h](j)}(h**Definition**h]h Definition}(hj7UhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj3Uubh:}(hj3UhhhNhNubeh}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhMhj/Uubj~)}(hHstruct futex_vector { struct futex_waitv w; struct futex_q q; };h]hHstruct futex_vector { struct futex_waitv w; struct futex_q q; };}hjPUsbah}(h]h ]h"]h$]h&]jjuh1j}h]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhMhj/Uubh)}(h **Members**h]j)}(hjaUh]hMembers}(hjcUhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj_Uubah}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhMhj/Uubj")}(hhh](j")}(h``w`` Userspace provided data h](j")}(h``w``h]jI)}(hjUh]hw}(hjUhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj~Uubah}(h]h ]h"]h$]h&]uh1j"h]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhMhjzUubj5")}(hhh]h)}(hUserspace provided datah]hUserspace provided data}(hjUhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjUhMhjUubah}(h]h ]h"]h$]h&]uh1j4"hjzUubeh}(h]h ]h"]h$]h&]uh1j"hjUhMhjwUubj")}(h``q`` Kernel side datah](j")}(h``q``h]jI)}(hjUh]hq}(hjUhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjUubah}(h]h ]h"]h$]h&]uh1j"h]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhMhjUubj5")}(hhh]h)}(hKernel side datah]hKernel side data}(hjUhhhNhNubah}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhMhjUubah}(h]h ]h"]h$]h&]uh1j4"hjUubeh}(h]h ]h"]h$]h&]uh1j"hjUhMhjwUubeh}(h]h ]h"]h$]h&]uh1j"hj/Uubeh}(h]h ] kernelindentah"]h$]h&]uh1j!hj6hhhjKhNubh)}(h**Description**h]j)}(hjUh]h Description}(hjUhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjUubah}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhMhj6hhubh)}(hBStruct used to build an array with all data need for futex_waitv()h]hBStruct used to build an array with all data need for futex_waitv()}(hjVhhhNhNubah}(h]h ]h"]h$]h&]uh1hh]/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1358: ./kernel/futex/futex.hhMhj6hhubjR!)}(hhh]h}(h]h ]h"]h$]h&]entries](j^!!futex_lock_pi_atomic (C function)c.futex_lock_pi_atomichNtauh1jQ!hj6hhhNhNubjc!)}(hhh](jh!)}(hint futex_lock_pi_atomic (u32 __user *uaddr, struct futex_hash_bucket *hb, union futex_key *key, struct futex_pi_state **ps, struct task_struct *task, struct task_struct **exiting, int set_waiters)h]jn!)}(hint futex_lock_pi_atomic(u32 __user *uaddr, struct futex_hash_bucket *hb, union futex_key *key, struct futex_pi_state **ps, struct task_struct *task, struct task_struct **exiting, int set_waiters)h](j$)}(hinth]hint}(hj:VhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj6VhhhZ/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1361: ./kernel/futex/pi.chM.ubj$)}(h h]h }(hjIVhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj6VhhhjHVhM.ubjt!)}(hfutex_lock_pi_atomich]jz!)}(hfutex_lock_pi_atomich]hfutex_lock_pi_atomic}(hj[VhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjWVubah}(h]h ](j!j!eh"]h$]h&]jjuh1js!hj6VhhhjHVhM.ubj=$)}(h(u32 __user *uaddr, struct futex_hash_bucket *hb, union futex_key *key, struct futex_pi_state **ps, struct task_struct *task, struct task_struct **exiting, int set_waiters)h](jC$)}(hu32 __user *uaddrh](h)}(hhh]jz!)}(hu32h]hu32}(hjzVhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjwVubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetj|VmodnameN classnameNj$j$)}j$]j$)}j$j]Vsbc.futex_lock_pi_atomicasbuh1hhjsVubj$)}(h h]h }(hjVhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjsVubh__user}(hjsVhhhNhNubj$)}(h h]h }(hjVhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjsVubj$)}(hj$h]h*}(hjVhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjsVubjz!)}(huaddrh]huaddr}(hjVhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjsVubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hjoVubjC$)}(hstruct futex_hash_bucket *hbh](jI$)}(hjL$h]hstruct}(hjVhhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hjVubj$)}(h h]h }(hjVhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjVubh)}(hhh]jz!)}(hfutex_hash_bucketh]hfutex_hash_bucket}(hjVhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjVubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetjWmodnameN classnameNj$j$)}j$]jVc.futex_lock_pi_atomicasbuh1hhjVubj$)}(h h]h }(hjWhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjVubj$)}(hj$h]h*}(hj*WhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjVubjz!)}(hhbh]hhb}(hj7WhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjVubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hjoVubjC$)}(hunion futex_key *keyh](jI$)}(hj6h]hunion}(hjPWhhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hjLWubj$)}(h h]h }(hj]WhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjLWubh)}(hhh]jz!)}(h futex_keyh]h futex_key}(hjnWhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjkWubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetjpWmodnameN classnameNj$j$)}j$]jVc.futex_lock_pi_atomicasbuh1hhjLWubj$)}(h h]h }(hjWhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjLWubj$)}(hj$h]h*}(hjWhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjLWubjz!)}(hkeyh]hkey}(hjWhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjLWubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hjoVubjC$)}(hstruct futex_pi_state **psh](jI$)}(hjL$h]hstruct}(hjWhhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hjWubj$)}(h h]h }(hjWhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjWubh)}(hhh]jz!)}(hfutex_pi_stateh]hfutex_pi_state}(hjWhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjWubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetjWmodnameN classnameNj$j$)}j$]jVc.futex_lock_pi_atomicasbuh1hhjWubj$)}(h h]h }(hjWhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjWubj$)}(hj$h]h*}(hj XhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjWubj$)}(hj$h]h*}(hjXhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjWubjz!)}(hpsh]hps}(hj$XhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjWubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hjoVubjC$)}(hstruct task_struct *taskh](jI$)}(hjL$h]hstruct}(hj=XhhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hj9Xubj$)}(h h]h }(hjJXhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj9Xubh)}(hhh]jz!)}(h task_structh]h task_struct}(hj[XhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjXXubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetj]XmodnameN classnameNj$j$)}j$]jVc.futex_lock_pi_atomicasbuh1hhj9Xubj$)}(h h]h }(hjyXhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj9Xubj$)}(hj$h]h*}(hjXhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj9Xubjz!)}(htaskh]htask}(hjXhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj9Xubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hjoVubjC$)}(hstruct task_struct **exitingh](jI$)}(hjL$h]hstruct}(hjXhhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hjXubj$)}(h h]h }(hjXhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjXubh)}(hhh]jz!)}(h task_structh]h task_struct}(hjXhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjXubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetjXmodnameN classnameNj$j$)}j$]jVc.futex_lock_pi_atomicasbuh1hhjXubj$)}(h h]h }(hjXhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjXubj$)}(hj$h]h*}(hjXhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjXubj$)}(hj$h]h*}(hjYhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjXubjz!)}(hexitingh]hexiting}(hjYhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjXubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hjoVubjC$)}(hint set_waitersh](j$)}(hinth]hint}(hj*YhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj&Yubj$)}(h h]h }(hj8YhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj&Yubjz!)}(h set_waitersh]h set_waiters}(hjFYhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj&Yubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hjoVubeh}(h]h ]h"]h$]h&]jjuh1j<$hj6VhhhjHVhM.ubeh}(h]h ]h"]h$]h&]jjj!uh1jm!j!j!hj2VhhhjHVhM.ubah}(h]j-Vah ](j!j!eh"]h$]h&]j!j!)j!huh1jg!hjHVhM.hj/Vhhubj!)}(hhh]h)}(h0Atomic work required to acquire a pi aware futexh]h0Atomic work required to acquire a pi aware futex}(hjpYhhhNhNubah}(h]h ]h"]h$]h&]uh1hhZ/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1361: ./kernel/futex/pi.chM.hjmYhhubah}(h]h ]h"]h$]h&]uh1j!hj/VhhhjHVhM.ubeh}(h]h ](jUfunctioneh"]h$]h&]j!jUj!jYj!jYj!j!j!uh1jb!hhhj6hNhNubj!)}(hX**Parameters** ``u32 __user *uaddr`` the pi futex user address ``struct futex_hash_bucket *hb`` the pi futex hash bucket ``union futex_key *key`` the futex key associated with uaddr and hb ``struct futex_pi_state **ps`` the pi_state pointer where we store the result of the lookup ``struct task_struct *task`` the task to perform the atomic lock work for. This will be "current" except in the case of requeue pi. ``struct task_struct **exiting`` Pointer to store the task pointer of the owner task which is in the middle of exiting ``int set_waiters`` force setting the FUTEX_WAITERS bit (1) or not (0) **Return** - 0 - ready to wait; - 1 - acquired the lock; - <0 - error **Description** The hb->lock must be held by the caller. **exiting** is only set when the return value is -EBUSY. If so, this holds a refcount on the exiting task on return and the caller needs to drop it after waiting for the exit to complete.h](h)}(h**Parameters**h]j)}(hjYh]h Parameters}(hjYhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjYubah}(h]h ]h"]h$]h&]uh1hhZ/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1361: ./kernel/futex/pi.c'hM2hjYubj")}(hhh](j")}(h0``u32 __user *uaddr`` the pi futex user address h](j")}(h``u32 __user *uaddr``h]jI)}(hjYh]hu32 __user *uaddr}(hjYhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjYubah}(h]h ]h"]h$]h&]uh1j"hZ/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1361: ./kernel/futex/pi.chM/hjYubj5")}(hhh]h)}(hthe pi futex user addressh]hthe pi futex user address}(hjYhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjYhM/hjYubah}(h]h ]h"]h$]h&]uh1j4"hjYubeh}(h]h ]h"]h$]h&]uh1j"hjYhM/hjYubj")}(h:``struct futex_hash_bucket *hb`` the pi futex hash bucket h](j")}(h ``struct futex_hash_bucket *hb``h]jI)}(hjYh]hstruct futex_hash_bucket *hb}(hjYhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjYubah}(h]h ]h"]h$]h&]uh1j"hZ/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1361: ./kernel/futex/pi.chM0hjYubj5")}(hhh]h)}(hthe pi futex hash bucketh]hthe pi futex hash bucket}(hjZhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjYhM0hjZubah}(h]h ]h"]h$]h&]uh1j4"hjYubeh}(h]h ]h"]h$]h&]uh1j"hjYhM0hjYubj")}(hD``union futex_key *key`` the futex key associated with uaddr and hb h](j")}(h``union futex_key *key``h]jI)}(hj#Zh]hunion futex_key *key}(hj%ZhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj!Zubah}(h]h ]h"]h$]h&]uh1j"hZ/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1361: ./kernel/futex/pi.chM1hjZubj5")}(hhh]h)}(h*the futex key associated with uaddr and hbh]h*the futex key associated with uaddr and hb}(hjhjYubh)}(h(The hb->lock must be held by the caller.h]h(The hb->lock must be held by the caller.}(hj[hhhNhNubah}(h]h ]h"]h$]h&]uh1hhZ/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1361: ./kernel/futex/pi.chM>hjYubh)}(h**exiting** is only set when the return value is -EBUSY. If so, this holds a refcount on the exiting task on return and the caller needs to drop it after waiting for the exit to complete.h](j)}(h **exiting**h]hexiting}(hj[hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj[ubh is only set when the return value is -EBUSY. If so, this holds a refcount on the exiting task on return and the caller needs to drop it after waiting for the exit to complete.}(hj[hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhZ/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1361: ./kernel/futex/pi.chM@hjYubeh}(h]h ] kernelindentah"]h$]h&]uh1j!hj6hhhNhNubjR!)}(hhh]h}(h]h ]h"]h$]h&]entries](j^!fixup_pi_owner (C function)c.fixup_pi_ownerhNtauh1jQ!hj6hhhNhNubjc!)}(hhh](jh!)}(hEint fixup_pi_owner (u32 __user *uaddr, struct futex_q *q, int locked)h]jn!)}(hDint fixup_pi_owner(u32 __user *uaddr, struct futex_q *q, int locked)h](j$)}(hinth]hint}(hj\hhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj \hhhZ/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1361: ./kernel/futex/pi.chMubj$)}(h h]h }(hj \hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj \hhhj\hMubjt!)}(hfixup_pi_ownerh]jz!)}(hfixup_pi_ownerh]hfixup_pi_owner}(hj2\hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj.\ubah}(h]h ](j!j!eh"]h$]h&]jjuh1js!hj \hhhj\hMubj=$)}(h2(u32 __user *uaddr, struct futex_q *q, int locked)h](jC$)}(hu32 __user *uaddrh](h)}(hhh]jz!)}(hu32h]hu32}(hjQ\hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjN\ubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetjS\modnameN classnameNj$j$)}j$]j$)}j$j4\sbc.fixup_pi_ownerasbuh1hhjJ\ubj$)}(h h]h }(hjq\hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjJ\ubh__user}(hjJ\hhhNhNubj$)}(h h]h }(hj\hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjJ\ubj$)}(hj$h]h*}(hj\hhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjJ\ubjz!)}(huaddrh]huaddr}(hj\hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjJ\ubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hjF\ubjC$)}(hstruct futex_q *qh](jI$)}(hjL$h]hstruct}(hj\hhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hj\ubj$)}(h h]h }(hj\hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj\ubh)}(hhh]jz!)}(hfutex_qh]hfutex_q}(hj\hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj\ubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetj\modnameN classnameNj$j$)}j$]jm\c.fixup_pi_ownerasbuh1hhj\ubj$)}(h h]h }(hj\hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj\ubj$)}(hj$h]h*}(hj]hhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj\ubjz!)}(hj;Gh]hq}(hj]hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj\ubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hjF\ubjC$)}(h int lockedh](j$)}(hinth]hint}(hj&]hhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj"]ubj$)}(h h]h }(hj4]hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj"]ubjz!)}(hlockedh]hlocked}(hjB]hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj"]ubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hjF\ubeh}(h]h ]h"]h$]h&]jjuh1j<$hj \hhhj\hMubeh}(h]h ]h"]h$]h&]jjj!uh1jm!j!j!hj \hhhj\hMubah}(h]j\ah ](j!j!eh"]h$]h&]j!j!)j!huh1jg!hj\hMhj\hhubj!)}(hhh]h)}(h-Post lock pi_state and corner case managementh]h-Post lock pi_state and corner case management}(hjl]hhhNhNubah}(h]h ]h"]h$]h&]uh1hhZ/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1361: ./kernel/futex/pi.chMhji]hhubah}(h]h ]h"]h$]h&]uh1j!hj\hhhj\hMubeh}(h]h ](jUfunctioneh"]h$]h&]j!jUj!j]j!j]j!j!j!uh1jb!hhhj6hNhNubj!)}(hX **Parameters** ``u32 __user *uaddr`` user address of the futex ``struct futex_q *q`` futex_q (contains pi_state and access to the rt_mutex) ``int locked`` if the attempt to take the rt_mutex succeeded (1) or not (0) **Description** After attempting to lock an rt_mutex, this function is called to cleanup the pi_state owner as well as handle race conditions that may allow us to acquire the lock. Must be called with the hb lock held. **Return** - 1 - success, lock taken; - 0 - success, lock not taken; - <0 - on error (-EFAULT)h](h)}(h**Parameters**h]j)}(hj]h]h Parameters}(hj]hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj]ubah}(h]h ]h"]h$]h&]uh1hhZ/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1361: ./kernel/futex/pi.chMhj]ubj")}(hhh](j")}(h0``u32 __user *uaddr`` user address of the futex h](j")}(h``u32 __user *uaddr``h]jI)}(hj]h]hu32 __user *uaddr}(hj]hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj]ubah}(h]h ]h"]h$]h&]uh1j"hZ/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1361: ./kernel/futex/pi.chMhj]ubj5")}(hhh]h)}(huser address of the futexh]huser address of the futex}(hj]hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj]hMhj]ubah}(h]h ]h"]h$]h&]uh1j4"hj]ubeh}(h]h ]h"]h$]h&]uh1j"hj]hMhj]ubj")}(hM``struct futex_q *q`` futex_q (contains pi_state and access to the rt_mutex) h](j")}(h``struct futex_q *q``h]jI)}(hj]h]hstruct futex_q *q}(hj]hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj]ubah}(h]h ]h"]h$]h&]uh1j"hZ/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1361: ./kernel/futex/pi.chMhj]ubj5")}(hhh]h)}(h6futex_q (contains pi_state and access to the rt_mutex)h]h6futex_q (contains pi_state and access to the rt_mutex)}(hj]hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj]hMhj]ubah}(h]h ]h"]h$]h&]uh1j4"hj]ubeh}(h]h ]h"]h$]h&]uh1j"hj]hMhj]ubj")}(hL``int locked`` if the attempt to take the rt_mutex succeeded (1) or not (0) h](j")}(h``int locked``h]jI)}(hj^h]h int locked}(hj!^hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj^ubah}(h]h ]h"]h$]h&]uh1j"hZ/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1361: ./kernel/futex/pi.chMhj^ubj5")}(hhh]h)}(h``union futex_key *key2`` the new key for the requeued futex_qh](j")}(h``union futex_key *key2``h]jI)}(hjbh]hunion futex_key *key2}(hjbhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjbubah}(h]h ]h"]h$]h&]uh1j"h_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chKJhjaubj5")}(hhh]h)}(h$the new key for the requeued futex_qh]h$the new key for the requeued futex_q}(hjbhhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chKIhjbubah}(h]h ]h"]h$]h&]uh1j4"hjaubeh}(h]h ]h"]h$]h&]uh1j"hjbhKJhjOaubeh}(h]h ]h"]h$]h&]uh1j"hj3aubeh}(h]h ] kernelindentah"]h$]h&]uh1j!hj6hhhNhNubjR!)}(hhh]h}(h]h ]h"]h$]h&]entries](j^!"requeue_pi_wake_futex (C function)c.requeue_pi_wake_futexhNtauh1jQ!hj6hhhNhNubjc!)}(hhh](jh!)}(hbvoid requeue_pi_wake_futex (struct futex_q *q, union futex_key *key, struct futex_hash_bucket *hb)h]jn!)}(havoid requeue_pi_wake_futex(struct futex_q *q, union futex_key *key, struct futex_hash_bucket *hb)h](j$)}(hvoidh]hvoid}(hj]bhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjYbhhh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chKubj$)}(h h]h }(hjlbhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjYbhhhjkbhKubjt!)}(hrequeue_pi_wake_futexh]jz!)}(hrequeue_pi_wake_futexh]hrequeue_pi_wake_futex}(hj~bhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjzbubah}(h]h ](j!j!eh"]h$]h&]jjuh1js!hjYbhhhjkbhKubj=$)}(hG(struct futex_q *q, union futex_key *key, struct futex_hash_bucket *hb)h](jC$)}(hstruct futex_q *qh](jI$)}(hjL$h]hstruct}(hjbhhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hjbubj$)}(h h]h }(hjbhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjbubh)}(hhh]jz!)}(hfutex_qh]hfutex_q}(hjbhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjbubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetjbmodnameN classnameNj$j$)}j$]j$)}j$jbsbc.requeue_pi_wake_futexasbuh1hhjbubj$)}(h h]h }(hjbhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjbubj$)}(hj$h]h*}(hjbhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjbubjz!)}(hj;Gh]hq}(hjbhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjbubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hjbubjC$)}(hunion futex_key *keyh](jI$)}(hj6h]hunion}(hj chhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hjcubj$)}(h h]h }(hjchhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjcubh)}(hhh]jz!)}(h futex_keyh]h futex_key}(hj)chhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj&cubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetj+cmodnameN classnameNj$j$)}j$]jbc.requeue_pi_wake_futexasbuh1hhjcubj$)}(h h]h }(hjGchhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjcubj$)}(hj$h]h*}(hjUchhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjcubjz!)}(hkeyh]hkey}(hjbchhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjcubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hjbubjC$)}(hstruct futex_hash_bucket *hbh](jI$)}(hjL$h]hstruct}(hj{chhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hjwcubj$)}(h h]h }(hjchhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjwcubh)}(hhh]jz!)}(hfutex_hash_bucketh]hfutex_hash_bucket}(hjchhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjcubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetjcmodnameN classnameNj$j$)}j$]jbc.requeue_pi_wake_futexasbuh1hhjwcubj$)}(h h]h }(hjchhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjwcubj$)}(hj$h]h*}(hjchhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjwcubjz!)}(hhbh]hhb}(hjchhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjwcubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hjbubeh}(h]h ]h"]h$]h&]jjuh1j<$hjYbhhhjkbhKubeh}(h]h ]h"]h$]h&]jjj!uh1jm!j!j!hjUbhhhjkbhKubah}(h]jPbah ](j!j!eh"]h$]h&]j!j!)j!huh1jg!hjkbhKhjRbhhubj!)}(hhh]h)}(h1Wake a task that acquired the lock during requeueh]h1Wake a task that acquired the lock during requeue}(hjchhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chKhjchhubah}(h]h ]h"]h$]h&]uh1j!hjRbhhhjkbhKubeh}(h]h ](jUfunctioneh"]h$]h&]j!jUj!jdj!jdj!j!j!uh1jb!hhhj6hNhNubj!)}(hX**Parameters** ``struct futex_q *q`` the futex_q ``union futex_key *key`` the key of the requeue target futex ``struct futex_hash_bucket *hb`` the hash_bucket of the requeue target futex **Description** During futex_requeue, with requeue_pi=1, it is possible to acquire the target futex if it is uncontended or via a lock steal. 1) Set **q**::key to the requeue target futex key so the waiter can detect the wakeup on the right futex. 2) Dequeue **q** from the hash bucket. 3) Set **q**::rt_waiter to NULL so the woken up task can detect atomic lock acquisition. 4) Set the q->lock_ptr to the requeue target hb->lock for the case that the waiter has to fixup the pi state. 5) Complete the requeue state so the waiter can make progress. After this point the waiter task can return from the syscall immediately in case that the pi state does not have to be fixed up. 6) Wake the waiter task. Must be called with both q->lock_ptr and hb->lock held.h](h)}(h**Parameters**h]j)}(hjdh]h Parameters}(hj dhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjdubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chKhjdubj")}(hhh](j")}(h"``struct futex_q *q`` the futex_q h](j")}(h``struct futex_q *q``h]jI)}(hj=dh]hstruct futex_q *q}(hj?dhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj;dubah}(h]h ]h"]h$]h&]uh1j"h_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chKhj7dubj5")}(hhh]h)}(h the futex_qh]h the futex_q}(hjVdhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjRdhKhjSdubah}(h]h ]h"]h$]h&]uh1j4"hj7dubeh}(h]h ]h"]h$]h&]uh1j"hjRdhKhj4dubj")}(h=``union futex_key *key`` the key of the requeue target futex h](j")}(h``union futex_key *key``h]jI)}(hjvdh]hunion futex_key *key}(hjxdhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjtdubah}(h]h ]h"]h$]h&]uh1j"h_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chKhjpdubj5")}(hhh]h)}(h#the key of the requeue target futexh]h#the key of the requeue target futex}(hjdhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjdhKhjdubah}(h]h ]h"]h$]h&]uh1j4"hjpdubeh}(h]h ]h"]h$]h&]uh1j"hjdhKhj4dubj")}(hM``struct futex_hash_bucket *hb`` the hash_bucket of the requeue target futex h](j")}(h ``struct futex_hash_bucket *hb``h]jI)}(hjdh]hstruct futex_hash_bucket *hb}(hjdhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjdubah}(h]h ]h"]h$]h&]uh1j"h_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chKhjdubj5")}(hhh]h)}(h+the hash_bucket of the requeue target futexh]h+the hash_bucket of the requeue target futex}(hjdhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjdhKhjdubah}(h]h ]h"]h$]h&]uh1j4"hjdubeh}(h]h ]h"]h$]h&]uh1j"hjdhKhj4dubeh}(h]h ]h"]h$]h&]uh1j"hjdubh)}(h**Description**h]j)}(hjdh]h Description}(hjdhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjdubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chKhjdubh)}(h}During futex_requeue, with requeue_pi=1, it is possible to acquire the target futex if it is uncontended or via a lock steal.h]h}During futex_requeue, with requeue_pi=1, it is possible to acquire the target futex if it is uncontended or via a lock steal.}(hjehhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chKhjdubhenumerated_list)}(hhh](j )}(hgSet **q**::key to the requeue target futex key so the waiter can detect the wakeup on the right futex. h]h)}(hfSet **q**::key to the requeue target futex key so the waiter can detect the wakeup on the right futex.h](hSet }(hjehhhNhNubj)}(h**q**h]hq}(hj ehhhNhNubah}(h]h ]h"]h$]h&]uh1jhjeubh]::key to the requeue target futex key so the waiter can detect the wakeup on the right futex.}(hjehhhNhNubeh}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chKhjeubah}(h]h ]h"]h$]h&]uh1j hjeubj )}(h$Dequeue **q** from the hash bucket. h]h)}(h#Dequeue **q** from the hash bucket.h](hDequeue }(hjCehhhNhNubj)}(h**q**h]hq}(hjKehhhNhNubah}(h]h ]h"]h$]h&]uh1jhjCeubh from the hash bucket.}(hjCehhhNhNubeh}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chKhj?eubah}(h]h ]h"]h$]h&]uh1j hjeubj )}(hVSet **q**::rt_waiter to NULL so the woken up task can detect atomic lock acquisition. h]h)}(hUSet **q**::rt_waiter to NULL so the woken up task can detect atomic lock acquisition.h](hSet }(hjnehhhNhNubj)}(h**q**h]hq}(hjvehhhNhNubah}(h]h ]h"]h$]h&]uh1jhjneubhL::rt_waiter to NULL so the woken up task can detect atomic lock acquisition.}(hjnehhhNhNubeh}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chKhjjeubah}(h]h ]h"]h$]h&]uh1j hjeubj )}(hkSet the q->lock_ptr to the requeue target hb->lock for the case that the waiter has to fixup the pi state. h]h)}(hjSet the q->lock_ptr to the requeue target hb->lock for the case that the waiter has to fixup the pi state.h]hjSet the q->lock_ptr to the requeue target hb->lock for the case that the waiter has to fixup the pi state.}(hjehhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chKhjeubah}(h]h ]h"]h$]h&]uh1j hjeubj )}(hComplete the requeue state so the waiter can make progress. After this point the waiter task can return from the syscall immediately in case that the pi state does not have to be fixed up. h]h)}(hComplete the requeue state so the waiter can make progress. After this point the waiter task can return from the syscall immediately in case that the pi state does not have to be fixed up.h]hComplete the requeue state so the waiter can make progress. After this point the waiter task can return from the syscall immediately in case that the pi state does not have to be fixed up.}(hjehhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chKhjeubah}(h]h ]h"]h$]h&]uh1j hjeubj )}(hWake the waiter task. h]h)}(hWake the waiter task.h]hWake the waiter task.}(hjehhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chKhjeubah}(h]h ]h"]h$]h&]uh1j hjeubeh}(h]h ]h"]h$]h&]enumtypearabicprefixhsuffix)uh1jehjdubh)}(h7Must be called with both q->lock_ptr and hb->lock held.h]h7Must be called with both q->lock_ptr and hb->lock held.}(hjehhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chKhjdubeh}(h]h ] kernelindentah"]h$]h&]uh1j!hj6hhhNhNubjR!)}(hhh]h}(h]h ]h"]h$]h&]entries](j^!'futex_proxy_trylock_atomic (C function)c.futex_proxy_trylock_atomichNtauh1jQ!hj6hhhNhNubjc!)}(hhh](jh!)}(hint futex_proxy_trylock_atomic (u32 __user *pifutex, struct futex_hash_bucket *hb1, struct futex_hash_bucket *hb2, union futex_key *key1, union futex_key *key2, struct futex_pi_state **ps, struct task_struct **exiting, int set_waiters)h]jn!)}(hint futex_proxy_trylock_atomic(u32 __user *pifutex, struct futex_hash_bucket *hb1, struct futex_hash_bucket *hb2, union futex_key *key1, union futex_key *key2, struct futex_pi_state **ps, struct task_struct **exiting, int set_waiters)h](j$)}(hinth]hint}(hjfhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjfhhh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chMubj$)}(h h]h }(hj)fhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjfhhhj(fhMubjt!)}(hfutex_proxy_trylock_atomich]jz!)}(hfutex_proxy_trylock_atomich]hfutex_proxy_trylock_atomic}(hj;fhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj7fubah}(h]h ](j!j!eh"]h$]h&]jjuh1js!hjfhhhj(fhMubj=$)}(h(u32 __user *pifutex, struct futex_hash_bucket *hb1, struct futex_hash_bucket *hb2, union futex_key *key1, union futex_key *key2, struct futex_pi_state **ps, struct task_struct **exiting, int set_waiters)h](jC$)}(hu32 __user *pifutexh](h)}(hhh]jz!)}(hu32h]hu32}(hjZfhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjWfubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetj\fmodnameN classnameNj$j$)}j$]j$)}j$j=fsbc.futex_proxy_trylock_atomicasbuh1hhjSfubj$)}(h h]h }(hjzfhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjSfubh__user}(hjSfhhhNhNubj$)}(h h]h }(hjfhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjSfubj$)}(hj$h]h*}(hjfhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjSfubjz!)}(hpifutexh]hpifutex}(hjfhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjSfubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hjOfubjC$)}(hstruct futex_hash_bucket *hb1h](jI$)}(hjL$h]hstruct}(hjfhhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hjfubj$)}(h h]h }(hjfhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjfubh)}(hhh]jz!)}(hfutex_hash_bucketh]hfutex_hash_bucket}(hjfhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjfubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetjfmodnameN classnameNj$j$)}j$]jvfc.futex_proxy_trylock_atomicasbuh1hhjfubj$)}(h h]h }(hjfhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjfubj$)}(hj$h]h*}(hj ghhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjfubjz!)}(hhb1h]hhb1}(hjghhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjfubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hjOfubjC$)}(hstruct futex_hash_bucket *hb2h](jI$)}(hjL$h]hstruct}(hj0ghhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hj,gubj$)}(h h]h }(hj=ghhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj,gubh)}(hhh]jz!)}(hfutex_hash_bucketh]hfutex_hash_bucket}(hjNghhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjKgubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetjPgmodnameN classnameNj$j$)}j$]jvfc.futex_proxy_trylock_atomicasbuh1hhj,gubj$)}(h h]h }(hjlghhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj,gubj$)}(hj$h]h*}(hjzghhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj,gubjz!)}(hhb2h]hhb2}(hjghhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj,gubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hjOfubjC$)}(hunion futex_key *key1h](jI$)}(hj6h]hunion}(hjghhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hjgubj$)}(h h]h }(hjghhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjgubh)}(hhh]jz!)}(h futex_keyh]h futex_key}(hjghhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjgubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetjgmodnameN classnameNj$j$)}j$]jvfc.futex_proxy_trylock_atomicasbuh1hhjgubj$)}(h h]h }(hjghhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjgubj$)}(hj$h]h*}(hjghhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjgubjz!)}(hkey1h]hkey1}(hjghhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjgubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hjOfubjC$)}(hunion futex_key *key2h](jI$)}(hj6h]hunion}(hjhhhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hj hubj$)}(h h]h }(hjhhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj hubh)}(hhh]jz!)}(h futex_keyh]h futex_key}(hj.hhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj+hubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetj0hmodnameN classnameNj$j$)}j$]jvfc.futex_proxy_trylock_atomicasbuh1hhj hubj$)}(h h]h }(hjLhhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj hubj$)}(hj$h]h*}(hjZhhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj hubjz!)}(hkey2h]hkey2}(hjghhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj hubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hjOfubjC$)}(hstruct futex_pi_state **psh](jI$)}(hjL$h]hstruct}(hjhhhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hj|hubj$)}(h h]h }(hjhhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj|hubh)}(hhh]jz!)}(hfutex_pi_stateh]hfutex_pi_state}(hjhhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjhubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetjhmodnameN classnameNj$j$)}j$]jvfc.futex_proxy_trylock_atomicasbuh1hhj|hubj$)}(h h]h }(hjhhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj|hubj$)}(hj$h]h*}(hjhhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj|hubj$)}(hj$h]h*}(hjhhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj|hubjz!)}(hpsh]hps}(hjhhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj|hubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hjOfubjC$)}(hstruct task_struct **exitingh](jI$)}(hjL$h]hstruct}(hjhhhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hjhubj$)}(h h]h }(hj ihhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjhubh)}(hhh]jz!)}(h task_structh]h task_struct}(hjihhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjiubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetjimodnameN classnameNj$j$)}j$]jvfc.futex_proxy_trylock_atomicasbuh1hhjhubj$)}(h h]h }(hj9ihhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjhubj$)}(hj$h]h*}(hjGihhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjhubj$)}(hj$h]h*}(hjTihhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjhubjz!)}(hexitingh]hexiting}(hjaihhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjhubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hjOfubjC$)}(hint set_waitersh](j$)}(hinth]hint}(hjzihhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjviubj$)}(h h]h }(hjihhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjviubjz!)}(h set_waitersh]h set_waiters}(hjihhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjviubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hjOfubeh}(h]h ]h"]h$]h&]jjuh1j<$hjfhhhj(fhMubeh}(h]h ]h"]h$]h&]jjj!uh1jm!j!j!hjfhhhj(fhMubah}(h]j fah ](j!j!eh"]h$]h&]j!j!)j!huh1jg!hj(fhMhjfhhubj!)}(hhh]h)}(h)Attempt an atomic lock for the top waiterh]h)Attempt an atomic lock for the top waiter}(hjihhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chMhjihhubah}(h]h ]h"]h$]h&]uh1j!hjfhhhj(fhMubeh}(h]h ](jUfunctioneh"]h$]h&]j!jUj!jij!jij!j!j!uh1jb!hhhj6hNhNubj!)}(hX**Parameters** ``u32 __user *pifutex`` the user address of the to futex ``struct futex_hash_bucket *hb1`` the from futex hash bucket, must be locked by the caller ``struct futex_hash_bucket *hb2`` the to futex hash bucket, must be locked by the caller ``union futex_key *key1`` the from futex key ``union futex_key *key2`` the to futex key ``struct futex_pi_state **ps`` address to store the pi_state pointer ``struct task_struct **exiting`` Pointer to store the task pointer of the owner task which is in the middle of exiting ``int set_waiters`` force setting the FUTEX_WAITERS bit (1) or not (0) **Description** Try and get the lock on behalf of the top waiter if we can do it atomically. Wake the top waiter if we succeed. If the caller specified set_waiters, then direct futex_lock_pi_atomic() to force setting the FUTEX_WAITERS bit. hb1 and hb2 must be held by the caller. **exiting** is only set when the return value is -EBUSY. If so, this holds a refcount on the exiting task on return and the caller needs to drop it after waiting for the exit to complete. **Return** - 0 - failed to acquire the lock atomically; - >0 - acquired the lock, return value is vpid of the top_waiter - <0 - errorh](h)}(h**Parameters**h]j)}(hjih]h Parameters}(hjihhhNhNubah}(h]h ]h"]h$]h&]uh1jhjiubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chM hjiubj")}(hhh](j")}(h9``u32 __user *pifutex`` the user address of the to futex h](j")}(h``u32 __user *pifutex``h]jI)}(hjjh]hu32 __user *pifutex}(hjjhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjiubah}(h]h ]h"]h$]h&]uh1j"h_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chMhjiubj5")}(hhh]h)}(h the user address of the to futexh]h the user address of the to futex}(hjjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjjhMhjjubah}(h]h ]h"]h$]h&]uh1j4"hjiubeh}(h]h ]h"]h$]h&]uh1j"hjjhMhjiubj")}(h[``struct futex_hash_bucket *hb1`` the from futex hash bucket, must be locked by the caller h](j")}(h!``struct futex_hash_bucket *hb1``h]jI)}(hj:jh]hstruct futex_hash_bucket *hb1}(hj>0 - acquired the lock, return value is vpid of the top_waiterh]h)}(hjClh]h>>0 - acquired the lock, return value is vpid of the top_waiter}(hjElhhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chMhjAlubah}(h]h ]h"]h$]h&]uh1j hj&lubj )}(h <0 - errorh]h)}(hj[lh]h <0 - error}(hj]lhhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chMhjYlubah}(h]h ]h"]h$]h&]uh1j hj&lubeh}(h]h ]h"]h$]h&]j5 j6 uh1j hj:lhMhjiubeh}(h]h ] kernelindentah"]h$]h&]uh1j!hj6hhhNhNubjR!)}(hhh]h}(h]h ]h"]h$]h&]entries](j^!futex_requeue (C function)c.futex_requeuehNtauh1jQ!hj6hhhNhNubjc!)}(hhh](jh!)}(hint futex_requeue (u32 __user *uaddr1, unsigned int flags1, u32 __user *uaddr2, unsigned int flags2, int nr_wake, int nr_requeue, u32 *cmpval, int requeue_pi)h]jn!)}(hint futex_requeue(u32 __user *uaddr1, unsigned int flags1, u32 __user *uaddr2, unsigned int flags2, int nr_wake, int nr_requeue, u32 *cmpval, int requeue_pi)h](j$)}(hinth]hint}(hjlhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjlhhh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chMtubj$)}(h h]h }(hjlhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjlhhhjlhMtubjt!)}(h futex_requeueh]jz!)}(h futex_requeueh]h futex_requeue}(hjlhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjlubah}(h]h ](j!j!eh"]h$]h&]jjuh1js!hjlhhhjlhMtubj=$)}(h(u32 __user *uaddr1, unsigned int flags1, u32 __user *uaddr2, unsigned int flags2, int nr_wake, int nr_requeue, u32 *cmpval, int requeue_pi)h](jC$)}(hu32 __user *uaddr1h](h)}(hhh]jz!)}(hu32h]hu32}(hjlhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjlubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetjlmodnameN classnameNj$j$)}j$]j$)}j$jlsbc.futex_requeueasbuh1hhjlubj$)}(h h]h }(hjlhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjlubh__user}(hjlhhhNhNubj$)}(h h]h }(hj mhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjlubj$)}(hj$h]h*}(hjmhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjlubjz!)}(huaddr1h]huaddr1}(hj$mhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjlubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hjlubjC$)}(hunsigned int flags1h](j$)}(hunsignedh]hunsigned}(hj=mhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj9mubj$)}(h h]h }(hjKmhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj9mubj$)}(hinth]hint}(hjYmhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj9mubj$)}(h h]h }(hjgmhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj9mubjz!)}(hflags1h]hflags1}(hjumhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj9mubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hjlubjC$)}(hu32 __user *uaddr2h](h)}(hhh]jz!)}(hu32h]hu32}(hjmhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjmubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetjmmodnameN classnameNj$j$)}j$]jlc.futex_requeueasbuh1hhjmubj$)}(h h]h }(hjmhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjmubh__user}(hjmhhhNhNubj$)}(h h]h }(hjmhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjmubj$)}(hj$h]h*}(hjmhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjmubjz!)}(huaddr2h]huaddr2}(hjmhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjmubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hjlubjC$)}(hunsigned int flags2h](j$)}(hunsignedh]hunsigned}(hjmhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjmubj$)}(h h]h }(hjnhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjmubj$)}(hinth]hint}(hjnhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjmubj$)}(h h]h }(hjnhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjmubjz!)}(hflags2h]hflags2}(hj-nhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjmubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hjlubjC$)}(h int nr_wakeh](j$)}(hinth]hint}(hjFnhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjBnubj$)}(h h]h }(hjTnhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjBnubjz!)}(hnr_wakeh]hnr_wake}(hjbnhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjBnubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hjlubjC$)}(hint nr_requeueh](j$)}(hinth]hint}(hj{nhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjwnubj$)}(h h]h }(hjnhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjwnubjz!)}(h nr_requeueh]h nr_requeue}(hjnhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjwnubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hjlubjC$)}(h u32 *cmpvalh](h)}(hhh]jz!)}(hu32h]hu32}(hjnhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjnubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetjnmodnameN classnameNj$j$)}j$]jlc.futex_requeueasbuh1hhjnubj$)}(h h]h }(hjnhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjnubj$)}(hj$h]h*}(hjnhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjnubjz!)}(hcmpvalh]hcmpval}(hjnhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjnubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hjlubjC$)}(hint requeue_pih](j$)}(hinth]hint}(hjohhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjoubj$)}(h h]h }(hjohhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjoubjz!)}(h requeue_pih]h requeue_pi}(hj!ohhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjoubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hjlubeh}(h]h ]h"]h$]h&]jjuh1j<$hjlhhhjlhMtubeh}(h]h ]h"]h$]h&]jjj!uh1jm!j!j!hjlhhhjlhMtubah}(h]jlah ](j!j!eh"]h$]h&]j!j!)j!huh1jg!hjlhMthjlhhubj!)}(hhh]h)}(h%Requeue waiters from uaddr1 to uaddr2h]h%Requeue waiters from uaddr1 to uaddr2}(hjKohhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chMthjHohhubah}(h]h ]h"]h$]h&]uh1j!hjlhhhjlhMtubeh}(h]h ](jUfunctioneh"]h$]h&]j!jUj!jcoj!jcoj!j!j!uh1jb!hhhj6hNhNubj!)}(hX**Parameters** ``u32 __user *uaddr1`` source futex user address ``unsigned int flags1`` futex flags (FLAGS_SHARED, etc.) ``u32 __user *uaddr2`` target futex user address ``unsigned int flags2`` futex flags (FLAGS_SHARED, etc.) ``int nr_wake`` number of waiters to wake (must be 1 for requeue_pi) ``int nr_requeue`` number of waiters to requeue (0-INT_MAX) ``u32 *cmpval`` **uaddr1** expected value (or ``NULL``) ``int requeue_pi`` if we are attempting to requeue from a non-pi futex to a pi futex (pi to pi requeue is not supported) **Description** Requeue waiters on uaddr1 to uaddr2. In the requeue_pi case, try to acquire uaddr2 atomically on behalf of the top waiter. **Return** - >=0 - on success, the number of tasks requeued or woken; - <0 - on errorh](h)}(h**Parameters**h]j)}(hjmoh]h Parameters}(hjoohhhNhNubah}(h]h ]h"]h$]h&]uh1jhjkoubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chMxhjgoubj")}(hhh](j")}(h1``u32 __user *uaddr1`` source futex user address h](j")}(h``u32 __user *uaddr1``h]jI)}(hjoh]hu32 __user *uaddr1}(hjohhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjoubah}(h]h ]h"]h$]h&]uh1j"h_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chMuhjoubj5")}(hhh]h)}(hsource futex user addressh]hsource futex user address}(hjohhhNhNubah}(h]h ]h"]h$]h&]uh1hhjohMuhjoubah}(h]h ]h"]h$]h&]uh1j4"hjoubeh}(h]h ]h"]h$]h&]uh1j"hjohMuhjoubj")}(h9``unsigned int flags1`` futex flags (FLAGS_SHARED, etc.) h](j")}(h``unsigned int flags1``h]jI)}(hjoh]hunsigned int flags1}(hjohhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjoubah}(h]h ]h"]h$]h&]uh1j"h_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chMvhjoubj5")}(hhh]h)}(h futex flags (FLAGS_SHARED, etc.)h]h futex flags (FLAGS_SHARED, etc.)}(hjohhhNhNubah}(h]h ]h"]h$]h&]uh1hhjohMvhjoubah}(h]h ]h"]h$]h&]uh1j4"hjoubeh}(h]h ]h"]h$]h&]uh1j"hjohMvhjoubj")}(h1``u32 __user *uaddr2`` target futex user address h](j")}(h``u32 __user *uaddr2``h]jI)}(hjoh]hu32 __user *uaddr2}(hjphhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjoubah}(h]h ]h"]h$]h&]uh1j"h_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chMwhjoubj5")}(hhh]h)}(htarget futex user addressh]htarget futex user address}(hjphhhNhNubah}(h]h ]h"]h$]h&]uh1hhjphMwhjpubah}(h]h ]h"]h$]h&]uh1j4"hjoubeh}(h]h ]h"]h$]h&]uh1j"hjphMwhjoubj")}(h9``unsigned int flags2`` futex flags (FLAGS_SHARED, etc.) h](j")}(h``unsigned int flags2``h]jI)}(hj7ph]hunsigned int flags2}(hj9phhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj5pubah}(h]h ]h"]h$]h&]uh1j"h_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chMxhj1pubj5")}(hhh]h)}(h futex flags (FLAGS_SHARED, etc.)h]h futex flags (FLAGS_SHARED, etc.)}(hjPphhhNhNubah}(h]h ]h"]h$]h&]uh1hhjLphMxhjMpubah}(h]h ]h"]h$]h&]uh1j4"hj1pubeh}(h]h ]h"]h$]h&]uh1j"hjLphMxhjoubj")}(hE``int nr_wake`` number of waiters to wake (must be 1 for requeue_pi) h](j")}(h``int nr_wake``h]jI)}(hjpph]h int nr_wake}(hjrphhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjnpubah}(h]h ]h"]h$]h&]uh1j"h_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chMyhjjpubj5")}(hhh]h)}(h4number of waiters to wake (must be 1 for requeue_pi)h]h4number of waiters to wake (must be 1 for requeue_pi)}(hjphhhNhNubah}(h]h ]h"]h$]h&]uh1hhjphMyhjpubah}(h]h ]h"]h$]h&]uh1j4"hjjpubeh}(h]h ]h"]h$]h&]uh1j"hjphMyhjoubj")}(h<``int nr_requeue`` number of waiters to requeue (0-INT_MAX) h](j")}(h``int nr_requeue``h]jI)}(hjph]hint nr_requeue}(hjphhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjpubah}(h]h ]h"]h$]h&]uh1j"h_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chMzhjpubj5")}(hhh]h)}(h(number of waiters to requeue (0-INT_MAX)h]h(number of waiters to requeue (0-INT_MAX)}(hjphhhNhNubah}(h]h ]h"]h$]h&]uh1hhjphMzhjpubah}(h]h ]h"]h$]h&]uh1j4"hjpubeh}(h]h ]h"]h$]h&]uh1j"hjphMzhjoubj")}(h8``u32 *cmpval`` **uaddr1** expected value (or ``NULL``) h](j")}(h``u32 *cmpval``h]jI)}(hjph]h u32 *cmpval}(hjphhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjpubah}(h]h ]h"]h$]h&]uh1j"h_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chM{hjpubj5")}(hhh]h)}(h'**uaddr1** expected value (or ``NULL``)h](j)}(h **uaddr1**h]huaddr1}(hjphhhNhNubah}(h]h ]h"]h$]h&]uh1jhjpubh expected value (or }(hjphhhNhNubjI)}(h``NULL``h]hNULL}(hjqhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjpubh)}(hjphhhNhNubeh}(h]h ]h"]h$]h&]uh1hhjphM{hjpubah}(h]h ]h"]h$]h&]uh1j4"hjpubeh}(h]h ]h"]h$]h&]uh1j"hjphM{hjoubj")}(hy``int requeue_pi`` if we are attempting to requeue from a non-pi futex to a pi futex (pi to pi requeue is not supported) h](j")}(h``int requeue_pi``h]jI)}(hj;qh]hint requeue_pi}(hj=qhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj9qubah}(h]h ]h"]h$]h&]uh1j"h_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chM}hj5qubj5")}(hhh]h)}(heif we are attempting to requeue from a non-pi futex to a pi futex (pi to pi requeue is not supported)h]heif we are attempting to requeue from a non-pi futex to a pi futex (pi to pi requeue is not supported)}(hjTqhhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chM|hjQqubah}(h]h ]h"]h$]h&]uh1j4"hj5qubeh}(h]h ]h"]h$]h&]uh1j"hjPqhM}hjoubeh}(h]h ]h"]h$]h&]uh1j"hjgoubh)}(h**Description**h]j)}(hjwqh]h Description}(hjyqhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjuqubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chMhjgoubh)}(hzRequeue waiters on uaddr1 to uaddr2. In the requeue_pi case, try to acquire uaddr2 atomically on behalf of the top waiter.h]hzRequeue waiters on uaddr1 to uaddr2. In the requeue_pi case, try to acquire uaddr2 atomically on behalf of the top waiter.}(hjqhhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chM~hjgoubh)}(h **Return**h]j)}(hjqh]hReturn}(hjqhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjqubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chMhjgoubj )}(hhh](j )}(h8>=0 - on success, the number of tasks requeued or woken;h]h)}(hjqh]h8>=0 - on success, the number of tasks requeued or woken;}(hjqhhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chMhjqubah}(h]h ]h"]h$]h&]uh1j hjqubj )}(h <0 - on errorh]h)}(hjqh]h <0 - on error}(hjqhhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chMhjqubah}(h]h ]h"]h$]h&]uh1j hjqubeh}(h]h ]h"]h$]h&]j5 j6 uh1j hjqhMhjgoubeh}(h]h ] kernelindentah"]h$]h&]uh1j!hj6hhhNhNubjR!)}(hhh]h}(h]h ]h"]h$]h&]entries](j^!+handle_early_requeue_pi_wakeup (C function) c.handle_early_requeue_pi_wakeuphNtauh1jQ!hj6hhhNhNubjc!)}(hhh](jh!)}(huint handle_early_requeue_pi_wakeup (struct futex_hash_bucket *hb, struct futex_q *q, struct hrtimer_sleeper *timeout)h]jn!)}(htint handle_early_requeue_pi_wakeup(struct futex_hash_bucket *hb, struct futex_q *q, struct hrtimer_sleeper *timeout)h](j$)}(hinth]hint}(hj rhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj rhhh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chMubj$)}(h h]h }(hjrhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj rhhhjrhMubjt!)}(hhandle_early_requeue_pi_wakeuph]jz!)}(hhandle_early_requeue_pi_wakeuph]hhandle_early_requeue_pi_wakeup}(hj.rhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj*rubah}(h]h ](j!j!eh"]h$]h&]jjuh1js!hj rhhhjrhMubj=$)}(hR(struct futex_hash_bucket *hb, struct futex_q *q, struct hrtimer_sleeper *timeout)h](jC$)}(hstruct futex_hash_bucket *hbh](jI$)}(hjL$h]hstruct}(hjJrhhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hjFrubj$)}(h h]h }(hjWrhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjFrubh)}(hhh]jz!)}(hfutex_hash_bucketh]hfutex_hash_bucket}(hjhrhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjerubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetjjrmodnameN classnameNj$j$)}j$]j$)}j$j0rsb c.handle_early_requeue_pi_wakeupasbuh1hhjFrubj$)}(h h]h }(hjrhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjFrubj$)}(hj$h]h*}(hjrhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjFrubjz!)}(hhbh]hhb}(hjrhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjFrubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hjBrubjC$)}(hstruct futex_q *qh](jI$)}(hjL$h]hstruct}(hjrhhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hjrubj$)}(h h]h }(hjrhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjrubh)}(hhh]jz!)}(hfutex_qh]hfutex_q}(hjrhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjrubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetjrmodnameN classnameNj$j$)}j$]jr c.handle_early_requeue_pi_wakeupasbuh1hhjrubj$)}(h h]h }(hjrhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjrubj$)}(hj$h]h*}(hjshhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjrubjz!)}(hj;Gh]hq}(hjshhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjrubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hjBrubjC$)}(hstruct hrtimer_sleeper *timeouth](jI$)}(hjL$h]hstruct}(hj+shhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hj'subj$)}(h h]h }(hj8shhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj'subh)}(hhh]jz!)}(hhrtimer_sleeperh]hhrtimer_sleeper}(hjIshhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjFsubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetjKsmodnameN classnameNj$j$)}j$]jr c.handle_early_requeue_pi_wakeupasbuh1hhj'subj$)}(h h]h }(hjgshhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj'subj$)}(hj$h]h*}(hjushhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj'subjz!)}(htimeouth]htimeout}(hjshhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj'subeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hjBrubeh}(h]h ]h"]h$]h&]jjuh1j<$hj rhhhjrhMubeh}(h]h ]h"]h$]h&]jjj!uh1jm!j!j!hjrhhhjrhMubah}(h]jrah ](j!j!eh"]h$]h&]j!j!)j!huh1jg!hjrhMhjrhhubj!)}(hhh]h)}(h(Handle early wakeup on the initial futexh]h(Handle early wakeup on the initial futex}(hjshhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chMhjshhubah}(h]h ]h"]h$]h&]uh1j!hjrhhhjrhMubeh}(h]h ](jUfunctioneh"]h$]h&]j!jUj!jsj!jsj!j!j!uh1jb!hhhj6hNhNubj!)}(hX}**Parameters** ``struct futex_hash_bucket *hb`` the hash_bucket futex_q was original enqueued on ``struct futex_q *q`` the futex_q woken while waiting to be requeued ``struct hrtimer_sleeper *timeout`` the timeout associated with the wait (NULL if none) **Description** Determine the cause for the early wakeup. **Return** -EWOULDBLOCK or -ETIMEDOUT or -ERESTARTNOINTRh](h)}(h**Parameters**h]j)}(hjsh]h Parameters}(hjshhhNhNubah}(h]h ]h"]h$]h&]uh1jhjsubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chMhjsubj")}(hhh](j")}(hR``struct futex_hash_bucket *hb`` the hash_bucket futex_q was original enqueued on h](j")}(h ``struct futex_hash_bucket *hb``h]jI)}(hjsh]hstruct futex_hash_bucket *hb}(hjshhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjsubah}(h]h ]h"]h$]h&]uh1j"h_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chMhjsubj5")}(hhh]h)}(h0the hash_bucket futex_q was original enqueued onh]h0the hash_bucket futex_q was original enqueued on}(hjthhhNhNubah}(h]h ]h"]h$]h&]uh1hhjthMhjtubah}(h]h ]h"]h$]h&]uh1j4"hjsubeh}(h]h ]h"]h$]h&]uh1j"hjthMhjsubj")}(hE``struct futex_q *q`` the futex_q woken while waiting to be requeued h](j")}(h``struct futex_q *q``h]jI)}(hj&th]hstruct futex_q *q}(hj(thhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj$tubah}(h]h ]h"]h$]h&]uh1j"h_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chMhj tubj5")}(hhh]h)}(h.the futex_q woken while waiting to be requeuedh]h.the futex_q woken while waiting to be requeued}(hj?thhhNhNubah}(h]h ]h"]h$]h&]uh1hhj;thMhj``u32 __user *uaddr`` the futex we initially wait on (non-pi) h](j")}(h``u32 __user *uaddr``h]jI)}(hjwh]hu32 __user *uaddr}(hjwhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjwubah}(h]h ]h"]h$]h&]uh1j"h_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chMhjwubj5")}(hhh]h)}(h'the futex we initially wait on (non-pi)h]h'the futex we initially wait on (non-pi)}(hjwhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjwhMhjwubah}(h]h ]h"]h$]h&]uh1j4"hjwubeh}(h]h ]h"]h$]h&]uh1j"hjwhMhjwubj")}(h``unsigned int flags`` futex flags (FLAGS_SHARED, FLAGS_CLOCKRT, etc.), they must be the same type, no requeueing from private to shared, etc. h](j")}(h``unsigned int flags``h]jI)}(hjwh]hunsigned int flags}(hjwhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjwubah}(h]h ]h"]h$]h&]uh1j"h_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chMhjwubj5")}(hhh]h)}(hwfutex flags (FLAGS_SHARED, FLAGS_CLOCKRT, etc.), they must be the same type, no requeueing from private to shared, etc.h]hwfutex flags (FLAGS_SHARED, FLAGS_CLOCKRT, etc.), they must be the same type, no requeueing from private to shared, etc.}(hjwhhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chMhjwubah}(h]h ]h"]h$]h&]uh1j4"hjwubeh}(h]h ]h"]h$]h&]uh1j"hjwhMhjwubj")}(h(``u32 val`` the expected value of uaddr h](j")}(h ``u32 val``h]jI)}(hjxh]hu32 val}(hjxhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj xubah}(h]h ]h"]h$]h&]uh1j"h_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chMhjxubj5")}(hhh]h)}(hthe expected value of uaddrh]hthe expected value of uaddr}(hj'xhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj#xhMhj$xubah}(h]h ]h"]h$]h&]uh1j4"hjxubeh}(h]h ]h"]h$]h&]uh1j"hj#xhMhjwubj")}(h'``ktime_t *abs_time`` absolute timeout h](j")}(h``ktime_t *abs_time``h]jI)}(hjGxh]hktime_t *abs_time}(hjIxhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjExubah}(h]h ]h"]h$]h&]uh1j"h_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chMhjAxubj5")}(hhh]h)}(habsolute timeouth]habsolute timeout}(hj`xhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj\xhMhj]xubah}(h]h ]h"]h$]h&]uh1j4"hjAxubeh}(h]h ]h"]h$]h&]uh1j"hj\xhMhjwubj")}(hF``u32 bitset`` 32 bit wakeup bitset set by userspace, defaults to all h](j")}(h``u32 bitset``h]jI)}(hjxh]h u32 bitset}(hjxhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj~xubah}(h]h ]h"]h$]h&]uh1j"h_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chMhjzxubj5")}(hhh]h)}(h632 bit wakeup bitset set by userspace, defaults to allh]h632 bit wakeup bitset set by userspace, defaults to all}(hjxhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjxhMhjxubah}(h]h ]h"]h$]h&]uh1j4"hjzxubeh}(h]h ]h"]h$]h&]uh1j"hjxhMhjwubj")}(hR``u32 __user *uaddr2`` the pi futex we will take prior to returning to user-space h](j")}(h``u32 __user *uaddr2``h]jI)}(hjxh]hu32 __user *uaddr2}(hjxhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjxubah}(h]h ]h"]h$]h&]uh1j"h_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chMhjxubj5")}(hhh]h)}(h:the pi futex we will take prior to returning to user-spaceh]h:the pi futex we will take prior to returning to user-space}(hjxhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjxhMhjxubah}(h]h ]h"]h$]h&]uh1j4"hjxubeh}(h]h ]h"]h$]h&]uh1j"hjxhMhjwubeh}(h]h ]h"]h$]h&]uh1j"hjvwubh)}(h**Description**h]j)}(hjxh]h Description}(hjxhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjxubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chMhjvwubh)}(hXThe caller will wait on uaddr and will be requeued by futex_requeue() to uaddr2 which must be PI aware and unique from uaddr. Normal wakeup will wake on uaddr2 and complete the acquisition of the rt_mutex prior to returning to userspace. This ensures the rt_mutex maintains an owner when it has waiters; without one, the pi logic would not know which task to boost/deboost, if there was a need to.h]hXThe caller will wait on uaddr and will be requeued by futex_requeue() to uaddr2 which must be PI aware and unique from uaddr. Normal wakeup will wake on uaddr2 and complete the acquisition of the rt_mutex prior to returning to userspace. This ensures the rt_mutex maintains an owner when it has waiters; without one, the pi logic would not know which task to boost/deboost, if there was a need to.}(hj yhhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chMhjvwubh)}(hWe call schedule in futex_wait_queue() when we enqueue and return there via the following-- 1) wakeup on uaddr2 after an atomic lock acquisition by futex_requeue() 2) wakeup on uaddr2 after a requeue 3) signal 4) timeouth]hWe call schedule in futex_wait_queue() when we enqueue and return there via the following-- 1) wakeup on uaddr2 after an atomic lock acquisition by futex_requeue() 2) wakeup on uaddr2 after a requeue 3) signal 4) timeout}(hjyhhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chMhjvwubh)}(h)If 3, cleanup and return -ERESTARTNOINTR.h]h)If 3, cleanup and return -ERESTARTNOINTR.}(hj(yhhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chM hjvwubh)}(hIf 2, we may then block on trying to take the rt_mutex and return via: 5) successful lock 6) signal 7) timeout 8) other lock acquisition failureh]hIf 2, we may then block on trying to take the rt_mutex and return via: 5) successful lock 6) signal 7) timeout 8) other lock acquisition failure}(hj7yhhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chM hjvwubh)}(hEIf 6, return -EWOULDBLOCK (restarting the syscall would do the same).h]hEIf 6, return -EWOULDBLOCK (restarting the syscall would do the same).}(hjFyhhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chMhjvwubh)}(h1If 4 or 7, we cleanup and return with -ETIMEDOUT.h]h1If 4 or 7, we cleanup and return with -ETIMEDOUT.}(hjUyhhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chMhjvwubh)}(h **Return**h]j)}(hjfyh]hReturn}(hjhyhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjdyubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chMhjvwubj )}(hhh](j )}(h0 - On success;h]h)}(hjyh]h0 - On success;}(hjyhhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chMhjyubah}(h]h ]h"]h$]h&]uh1j hj|yubj )}(h <0 - On errorh]h)}(hjyh]h <0 - On error}(hjyhhhNhNubah}(h]h ]h"]h$]h&]uh1hh_/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1364: ./kernel/futex/requeue.chMhjyubah}(h]h ]h"]h$]h&]uh1j hj|yubeh}(h]h ]h"]h$]h&]j5 j6 uh1j hjyhMhjvwubeh}(h]h ] kernelindentah"]h$]h&]uh1j!hj6hhhNhNubjR!)}(hhh]h}(h]h ]h"]h$]h&]entries](j^!futex_do_wait (C function)c.futex_do_waithNtauh1jQ!hj6hhhNhNubjc!)}(hhh](jh!)}(hGvoid futex_do_wait (struct futex_q *q, struct hrtimer_sleeper *timeout)h]jn!)}(hFvoid futex_do_wait(struct futex_q *q, struct hrtimer_sleeper *timeout)h](j$)}(hvoidh]hvoid}(hjyhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjyhhh`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMnubj$)}(h h]h }(hjyhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjyhhhjyhMnubjt!)}(h futex_do_waith]jz!)}(h futex_do_waith]h futex_do_wait}(hjyhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjyubah}(h]h ](j!j!eh"]h$]h&]jjuh1js!hjyhhhjyhMnubj=$)}(h4(struct futex_q *q, struct hrtimer_sleeper *timeout)h](jC$)}(hstruct futex_q *qh](jI$)}(hjL$h]hstruct}(hjzhhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hjzubj$)}(h h]h }(hjzhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjzubh)}(hhh]jz!)}(hfutex_qh]hfutex_q}(hj0zhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj-zubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetj2zmodnameN classnameNj$j$)}j$]j$)}j$jysbc.futex_do_waitasbuh1hhjzubj$)}(h h]h }(hjPzhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjzubj$)}(hj$h]h*}(hj^zhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjzubjz!)}(hj;Gh]hq}(hjkzhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjzubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hj zubjC$)}(hstruct hrtimer_sleeper *timeouth](jI$)}(hjL$h]hstruct}(hjzhhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hjzubj$)}(h h]h }(hjzhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjzubh)}(hhh]jz!)}(hhrtimer_sleeperh]hhrtimer_sleeper}(hjzhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjzubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetjzmodnameN classnameNj$j$)}j$]jLzc.futex_do_waitasbuh1hhjzubj$)}(h h]h }(hjzhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjzubj$)}(hj$h]h*}(hjzhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjzubjz!)}(htimeouth]htimeout}(hjzhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjzubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hj zubeh}(h]h ]h"]h$]h&]jjuh1j<$hjyhhhjyhMnubeh}(h]h ]h"]h$]h&]jjj!uh1jm!j!j!hjyhhhjyhMnubah}(h]jyah ](j!j!eh"]h$]h&]j!j!)j!huh1jg!hjyhMnhjyhhubj!)}(hhh]h)}(h#wait for wakeup, timeout, or signalh]h#wait for wakeup, timeout, or signal}(hj{hhhNhNubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMnhj{hhubah}(h]h ]h"]h$]h&]uh1j!hjyhhhjyhMnubeh}(h]h ](jUfunctioneh"]h$]h&]j!jUj!j{j!j{j!j!j!uh1jb!hhhj6hNhNubj!)}(h**Parameters** ``struct futex_q *q`` the futex_q to queue up on ``struct hrtimer_sleeper *timeout`` the prepared hrtimer_sleeper, or null for no timeouth](h)}(h**Parameters**h]j)}(hj&{h]h Parameters}(hj({hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj${ubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMrhj {ubj")}(hhh](j")}(h1``struct futex_q *q`` the futex_q to queue up on h](j")}(h``struct futex_q *q``h]jI)}(hjE{h]hstruct futex_q *q}(hjG{hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjC{ubah}(h]h ]h"]h$]h&]uh1j"h`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMohj?{ubj5")}(hhh]h)}(hthe futex_q to queue up onh]hthe futex_q to queue up on}(hj^{hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjZ{hMohj[{ubah}(h]h ]h"]h$]h&]uh1j4"hj?{ubeh}(h]h ]h"]h$]h&]uh1j"hjZ{hMohj<{ubj")}(hX``struct hrtimer_sleeper *timeout`` the prepared hrtimer_sleeper, or null for no timeouth](j")}(h#``struct hrtimer_sleeper *timeout``h]jI)}(hj~{h]hstruct hrtimer_sleeper *timeout}(hj{hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj|{ubah}(h]h ]h"]h$]h&]uh1j"h`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMqhjx{ubj5")}(hhh]h)}(h4the prepared hrtimer_sleeper, or null for no timeouth]h4the prepared hrtimer_sleeper, or null for no timeout}(hj{hhhNhNubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMphj{ubah}(h]h ]h"]h$]h&]uh1j4"hjx{ubeh}(h]h ]h"]h$]h&]uh1j"hj{hMqhj<{ubeh}(h]h ]h"]h$]h&]uh1j"hj {ubeh}(h]h ] kernelindentah"]h$]h&]uh1j!hj6hhhNhNubjR!)}(hhh]h}(h]h ]h"]h$]h&]entries](j^!#futex_unqueue_multiple (C function)c.futex_unqueue_multiplehNtauh1jQ!hj6hhhNhNubjc!)}(hhh](jh!)}(h>int futex_unqueue_multiple (struct futex_vector *v, int count)h]jn!)}(h=int futex_unqueue_multiple(struct futex_vector *v, int count)h](j$)}(hinth]hint}(hj{hhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj{hhh`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMubj$)}(h h]h }(hj{hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj{hhhj{hMubjt!)}(hfutex_unqueue_multipleh]jz!)}(hfutex_unqueue_multipleh]hfutex_unqueue_multiple}(hj{hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj{ubah}(h]h ](j!j!eh"]h$]h&]jjuh1js!hj{hhhj{hMubj=$)}(h#(struct futex_vector *v, int count)h](jC$)}(hstruct futex_vector *vh](jI$)}(hjL$h]hstruct}(hj|hhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hj|ubj$)}(h h]h }(hj"|hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj|ubh)}(hhh]jz!)}(h futex_vectorh]h futex_vector}(hj3|hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj0|ubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetj5|modnameN classnameNj$j$)}j$]j$)}j$j{sbc.futex_unqueue_multipleasbuh1hhj|ubj$)}(h h]h }(hjS|hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj|ubj$)}(hj$h]h*}(hja|hhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj|ubjz!)}(hvh]hv}(hjn|hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj|ubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hj |ubjC$)}(h int counth](j$)}(hinth]hint}(hj|hhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj|ubj$)}(h h]h }(hj|hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj|ubjz!)}(hcounth]hcount}(hj|hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj|ubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hj |ubeh}(h]h ]h"]h$]h&]jjuh1j<$hj{hhhj{hMubeh}(h]h ]h"]h$]h&]jjj!uh1jm!j!j!hj{hhhj{hMubah}(h]j{ah ](j!j!eh"]h$]h&]j!j!)j!huh1jg!hj{hMhj{hhubj!)}(hhh]h)}(h-Remove various futexes from their hash bucketh]h-Remove various futexes from their hash bucket}(hj|hhhNhNubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMhj|hhubah}(h]h ]h"]h$]h&]uh1j!hj{hhhj{hMubeh}(h]h ](jUfunctioneh"]h$]h&]j!jUj!j|j!j|j!j!j!uh1jb!hhhj6hNhNubj!)}(hX**Parameters** ``struct futex_vector *v`` The list of futexes to unqueue ``int count`` Number of futexes in the list **Description** Helper to unqueue a list of futexes. This can't fail. **Return** - >=0 - Index of the last futex that was awoken; - -1 - No futex was awokenh](h)}(h**Parameters**h]j)}(hj|h]h Parameters}(hj|hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj|ubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMhj|ubj")}(hhh](j")}(h:``struct futex_vector *v`` The list of futexes to unqueue h](j")}(h``struct futex_vector *v``h]jI)}(hj}h]hstruct futex_vector *v}(hj}hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj }ubah}(h]h ]h"]h$]h&]uh1j"h`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMhj}ubj5")}(hhh]h)}(hThe list of futexes to unqueueh]hThe list of futexes to unqueue}(hj'}hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj#}hMhj$}ubah}(h]h ]h"]h$]h&]uh1j4"hj}ubeh}(h]h ]h"]h$]h&]uh1j"hj#}hMhj}ubj")}(h,``int count`` Number of futexes in the list h](j")}(h ``int count``h]jI)}(hjG}h]h int count}(hjI}hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjE}ubah}(h]h ]h"]h$]h&]uh1j"h`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMhjA}ubj5")}(hhh]h)}(hNumber of futexes in the listh]hNumber of futexes in the list}(hj`}hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj\}hMhj]}ubah}(h]h ]h"]h$]h&]uh1j4"hjA}ubeh}(h]h ]h"]h$]h&]uh1j"hj\}hMhj}ubeh}(h]h ]h"]h$]h&]uh1j"hj|ubh)}(h**Description**h]j)}(hj}h]h Description}(hj}hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj}ubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMhj|ubh)}(h5Helper to unqueue a list of futexes. This can't fail.h]h7Helper to unqueue a list of futexes. This can’t fail.}(hj}hhhNhNubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMhj|ubh)}(h **Return**h]j)}(hj}h]hReturn}(hj}hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj}ubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMhj|ubj )}(hhh](j )}(h.>=0 - Index of the last futex that was awoken;h]h)}(hj}h]h.>=0 - Index of the last futex that was awoken;}(hj}hhhNhNubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMhj}ubah}(h]h ]h"]h$]h&]uh1j hj}ubj )}(h-1 - No futex was awokenh]h option_list)}(hhh]hoption_list_item)}(hhh](h option_group)}(hhh]hoption)}(h-1h]h option_string)}(hj}h]h-1}hj}sbah}(h]h ]h"]h$]h&]uh1j}hj}ubah}(h]h ]h"]h$]h&]uh1j}hj}ubah}(h]h ]h"]h$]h&]uh1j}hj}ubh description)}(h- No futex was awokenh]j )}(hhh]j )}(hNo futex was awokenh]h)}(hj~h]hNo futex was awoken}(hj~hhhNhNubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMhj~ubah}(h]h ]h"]h$]h&]uh1j hj~ubah}(h]h ]h"]h$]h&]j5 j6 uh1j hj(~hMhj~ubah}(h]h ]h"]h$]h&]uh1j~hj}ubeh}(h]h ]h"]h$]h&]uh1j}hj}ubah}(h]h ]h"]h$]h&]uh1j}hj(~hMhj}ubah}(h]h ]h"]h$]h&]uh1j hj}ubeh}(h]h ]h"]h$]h&]j5 j6 uh1j hj}hMhj|ubeh}(h]h ] kernelindentah"]h$]h&]uh1j!hj6hhhNhNubjR!)}(hhh]h}(h]h ]h"]h$]h&]entries](j^!&futex_wait_multiple_setup (C function)c.futex_wait_multiple_setuphNtauh1jQ!hj6hhhNhNubjc!)}(hhh](jh!)}(hNint futex_wait_multiple_setup (struct futex_vector *vs, int count, int *woken)h]jn!)}(hMint futex_wait_multiple_setup(struct futex_vector *vs, int count, int *woken)h](j$)}(hinth]hint}(hjs~hhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjo~hhh`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMubj$)}(h h]h }(hj~hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjo~hhhj~hMubjt!)}(hfutex_wait_multiple_setuph]jz!)}(hfutex_wait_multiple_setuph]hfutex_wait_multiple_setup}(hj~hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj~ubah}(h]h ](j!j!eh"]h$]h&]jjuh1js!hjo~hhhj~hMubj=$)}(h0(struct futex_vector *vs, int count, int *woken)h](jC$)}(hstruct futex_vector *vsh](jI$)}(hjL$h]hstruct}(hj~hhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hj~ubj$)}(h h]h }(hj~hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj~ubh)}(hhh]jz!)}(h futex_vectorh]h futex_vector}(hj~hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj~ubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetj~modnameN classnameNj$j$)}j$]j$)}j$j~sbc.futex_wait_multiple_setupasbuh1hhj~ubj$)}(h h]h }(hj~hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj~ubj$)}(hj$h]h*}(hj~hhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj~ubjz!)}(hvsh]hvs}(hj hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj~ubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hj~ubjC$)}(h int counth](j$)}(hinth]hint}(hj"hhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjubj$)}(h h]h }(hj0hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjubjz!)}(hcounth]hcount}(hj>hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hj~ubjC$)}(h int *wokenh](j$)}(hinth]hint}(hjWhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjSubj$)}(h h]h }(hjehhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjSubj$)}(hj$h]h*}(hjshhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjSubjz!)}(hwokenh]hwoken}(hjhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjSubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hj~ubeh}(h]h ]h"]h$]h&]jjuh1j<$hjo~hhhj~hMubeh}(h]h ]h"]h$]h&]jjj!uh1jm!j!j!hjk~hhhj~hMubah}(h]jf~ah ](j!j!eh"]h$]h&]j!j!)j!huh1jg!hj~hMhjh~hhubj!)}(hhh]h)}(h,Prepare to wait and enqueue multiple futexesh]h,Prepare to wait and enqueue multiple futexes}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMhjhhubah}(h]h ]h"]h$]h&]uh1j!hjh~hhhj~hMubeh}(h]h ](jUfunctioneh"]h$]h&]j!jUj!jj!jj!j!j!uh1jb!hhhj6hNhNubj!)}(hXL**Parameters** ``struct futex_vector *vs`` The futex list to wait on ``int count`` The size of the list ``int *woken`` Index of the last woken futex, if any. Used to notify the caller that it can return this index to userspace (return parameter) **Description** Prepare multiple futexes in a single step and enqueue them. This may fail if the futex list is invalid or if any futex was already awoken. On success the task is ready to interruptible sleep. **Return** - 1 - One of the futexes was woken by another thread - 0 - Success - <0 - -EFAULT, -EWOULDBLOCK or -EINVALh](h)}(h**Parameters**h]j)}(hjh]h Parameters}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMhjubj")}(hhh](j")}(h6``struct futex_vector *vs`` The futex list to wait on h](j")}(h``struct futex_vector *vs``h]jI)}(hjh]hstruct futex_vector *vs}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjubah}(h]h ]h"]h$]h&]uh1j"h`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMhjubj5")}(hhh]h)}(hThe futex list to wait onh]hThe futex list to wait on}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhMhjubah}(h]h ]h"]h$]h&]uh1j4"hjubeh}(h]h ]h"]h$]h&]uh1j"hjhMhjubj")}(h#``int count`` The size of the list h](j")}(h ``int count``h]jI)}(hj$h]h int count}(hj&hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj"ubah}(h]h ]h"]h$]h&]uh1j"h`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMhjubj5")}(hhh]h)}(hThe size of the listh]hThe size of the list}(hj=hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj9hMhj:ubah}(h]h ]h"]h$]h&]uh1j4"hjubeh}(h]h ]h"]h$]h&]uh1j"hj9hMhjubj")}(h``int *woken`` Index of the last woken futex, if any. Used to notify the caller that it can return this index to userspace (return parameter) h](j")}(h``int *woken``h]jI)}(hj]h]h int *woken}(hj_hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj[ubah}(h]h ]h"]h$]h&]uh1j"h`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMhjWubj5")}(hhh]h)}(h~Index of the last woken futex, if any. Used to notify the caller that it can return this index to userspace (return parameter)h]h~Index of the last woken futex, if any. Used to notify the caller that it can return this index to userspace (return parameter)}(hjvhhhNhNubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMhjsubah}(h]h ]h"]h$]h&]uh1j4"hjWubeh}(h]h ]h"]h$]h&]uh1j"hjrhMhjubeh}(h]h ]h"]h$]h&]uh1j"hjubh)}(h**Description**h]j)}(hjh]h Description}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMhjubh)}(hPrepare multiple futexes in a single step and enqueue them. This may fail if the futex list is invalid or if any futex was already awoken. On success the task is ready to interruptible sleep.h]hPrepare multiple futexes in a single step and enqueue them. This may fail if the futex list is invalid or if any futex was already awoken. On success the task is ready to interruptible sleep.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMhjubh)}(h **Return**h]j)}(hjh]hReturn}(hj€hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMhjubj )}(hhh](j )}(h21 - One of the futexes was woken by another threadh]h)}(hjۀh]h21 - One of the futexes was woken by another thread}(hj݀hhhNhNubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMhjـubah}(h]h ]h"]h$]h&]uh1j hjրubj )}(h 0 - Successh]h)}(hjh]h 0 - Success}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMhjubah}(h]h ]h"]h$]h&]uh1j hjրubj )}(h%<0 - -EFAULT, -EWOULDBLOCK or -EINVALh]h)}(hj h]h%<0 - -EFAULT, -EWOULDBLOCK or -EINVAL}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMhj ubah}(h]h ]h"]h$]h&]uh1j hjրubeh}(h]h ]h"]h$]h&]j5 j6 uh1j hjhMhjubeh}(h]h ] kernelindentah"]h$]h&]uh1j!hj6hhhNhNubjR!)}(hhh]h}(h]h ]h"]h$]h&]entries](j^!!futex_sleep_multiple (C function)c.futex_sleep_multiplehNtauh1jQ!hj6hhhNhNubjc!)}(hhh](jh!)}(hcvoid futex_sleep_multiple (struct futex_vector *vs, unsigned int count, struct hrtimer_sleeper *to)h]jn!)}(hbvoid futex_sleep_multiple(struct futex_vector *vs, unsigned int count, struct hrtimer_sleeper *to)h](j$)}(hvoidh]hvoid}(hjGhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjChhh`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMubj$)}(h h]h }(hjVhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjChhhjUhMubjt!)}(hfutex_sleep_multipleh]jz!)}(hfutex_sleep_multipleh]hfutex_sleep_multiple}(hjhhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjdubah}(h]h ](j!j!eh"]h$]h&]jjuh1js!hjChhhjUhMubj=$)}(hI(struct futex_vector *vs, unsigned int count, struct hrtimer_sleeper *to)h](jC$)}(hstruct futex_vector *vsh](jI$)}(hjL$h]hstruct}(hjhhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hjubj$)}(h h]h }(hjhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjubh)}(hhh]jz!)}(h futex_vectorh]h futex_vector}(hjhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetjmodnameN classnameNj$j$)}j$]j$)}j$jjsbc.futex_sleep_multipleasbuh1hhjubj$)}(h h]h }(hjhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjubj$)}(hj$h]h*}(hjЁhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjubjz!)}(hvsh]hvs}(hj݁hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hj|ubjC$)}(hunsigned int counth](j$)}(hunsignedh]hunsigned}(hjhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjubj$)}(h h]h }(hjhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjubj$)}(hinth]hint}(hjhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjubj$)}(h h]h }(hj hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjubjz!)}(hcounth]hcount}(hj.hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hj|ubjC$)}(hstruct hrtimer_sleeper *toh](jI$)}(hjL$h]hstruct}(hjGhhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hjCubj$)}(h h]h }(hjThhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjCubh)}(hhh]jz!)}(hhrtimer_sleeperh]hhrtimer_sleeper}(hjehhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjbubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetjgmodnameN classnameNj$j$)}j$]jc.futex_sleep_multipleasbuh1hhjCubj$)}(h h]h }(hjhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjCubj$)}(hj$h]h*}(hjhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjCubjz!)}(htoh]hto}(hjhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjCubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hj|ubeh}(h]h ]h"]h$]h&]jjuh1j<$hjChhhjUhMubeh}(h]h ]h"]h$]h&]jjj!uh1jm!j!j!hj?hhhjUhMubah}(h]j:ah ](j!j!eh"]h$]h&]j!j!)j!huh1jg!hjUhMhj<hhubj!)}(hhh]h)}(h#Check sleeping conditions and sleeph]h#Check sleeping conditions and sleep}(hjȂhhhNhNubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMhjłhhubah}(h]h ]h"]h$]h&]uh1j!hj<hhhjUhMubeh}(h]h ](jUfunctioneh"]h$]h&]j!jUj!jj!jj!j!j!uh1jb!hhhj6hNhNubj!)}(hX**Parameters** ``struct futex_vector *vs`` List of futexes to wait for ``unsigned int count`` Length of vs ``struct hrtimer_sleeper *to`` Timeout **Description** Sleep if and only if the timeout hasn't expired and no futex on the list has been woken up.h](h)}(h**Parameters**h]j)}(hjh]h Parameters}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMhjubj")}(hhh](j")}(h8``struct futex_vector *vs`` List of futexes to wait for h](j")}(h``struct futex_vector *vs``h]jI)}(hj h]hstruct futex_vector *vs}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjubah}(h]h ]h"]h$]h&]uh1j"h`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMhjubj5")}(hhh]h)}(hList of futexes to wait forh]hList of futexes to wait for}(hj"hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhMhjubah}(h]h ]h"]h$]h&]uh1j4"hjubeh}(h]h ]h"]h$]h&]uh1j"hjhMhjubj")}(h$``unsigned int count`` Length of vs h](j")}(h``unsigned int count``h]jI)}(hjBh]hunsigned int count}(hjDhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj@ubah}(h]h ]h"]h$]h&]uh1j"h`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMhj<ubj5")}(hhh]h)}(h Length of vsh]h Length of vs}(hj[hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjWhMhjXubah}(h]h ]h"]h$]h&]uh1j4"hj<ubeh}(h]h ]h"]h$]h&]uh1j"hjWhMhjubj")}(h'``struct hrtimer_sleeper *to`` Timeout h](j")}(h``struct hrtimer_sleeper *to``h]jI)}(hj{h]hstruct hrtimer_sleeper *to}(hj}hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjyubah}(h]h ]h"]h$]h&]uh1j"h`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMhjuubj5")}(hhh]h)}(hTimeouth]hTimeout}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhMhjubah}(h]h ]h"]h$]h&]uh1j4"hjuubeh}(h]h ]h"]h$]h&]uh1j"hjhMhjubeh}(h]h ]h"]h$]h&]uh1j"hjubh)}(h**Description**h]j)}(hjh]h Description}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMhjubh)}(h[Sleep if and only if the timeout hasn't expired and no futex on the list has been woken up.h]h]Sleep if and only if the timeout hasn’t expired and no futex on the list has been woken up.}(hj̃hhhNhNubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMhjubeh}(h]h ] kernelindentah"]h$]h&]uh1j!hj6hhhNhNubjR!)}(hhh]h}(h]h ]h"]h$]h&]entries](j^! futex_wait_multiple (C function)c.futex_wait_multiplehNtauh1jQ!hj6hhhNhNubjc!)}(hhh](jh!)}(haint futex_wait_multiple (struct futex_vector *vs, unsigned int count, struct hrtimer_sleeper *to)h]jn!)}(h`int futex_wait_multiple(struct futex_vector *vs, unsigned int count, struct hrtimer_sleeper *to)h](j$)}(hinth]hint}(hjhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjhhh`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chM*ubj$)}(h h]h }(hj hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjhhhj hM*ubjt!)}(hfutex_wait_multipleh]jz!)}(hfutex_wait_multipleh]hfutex_wait_multiple}(hjhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjubah}(h]h ](j!j!eh"]h$]h&]jjuh1js!hjhhhj hM*ubj=$)}(hI(struct futex_vector *vs, unsigned int count, struct hrtimer_sleeper *to)h](jC$)}(hstruct futex_vector *vs.h](jI$)}(hjL$h]hstruct}(hj8hhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hj4ubj$)}(h h]h }(hjEhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj4ubh)}(hhh]jz!)}(h futex_vectorh]h futex_vector}(hjVhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjSubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetjXmodnameN classnameNj$j$)}j$]j$)}j$jsbc.futex_wait_multipleasbuh1hhj4ubj$)}(h h]h }(hjvhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj4ubj$)}(hj$h]h*}(hjhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj4ubjz!)}(hvsh]hvs}(hjhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj4ubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hj0ubjC$)}(hunsigned int counth](j$)}(hunsignedh]hunsigned}(hjhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjubj$)}(h h]h }(hjhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjubj$)}(hinth]hint}(hjƄhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjubj$)}(h h]h }(hjԄhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjubjz!)}(hcounth]hcount}(hjhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hj0ubjC$)}(hstruct hrtimer_sleeper *toh](jI$)}(hjL$h]hstruct}(hjhhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hjubj$)}(h h]h }(hjhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjubh)}(hhh]jz!)}(hhrtimer_sleeperh]hhrtimer_sleeper}(hjhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetjmodnameN classnameNj$j$)}j$]jrc.futex_wait_multipleasbuh1hhjubj$)}(h h]h }(hj7hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjubj$)}(hj$h]h*}(hjEhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjubjz!)}(htoh]hto}(hjRhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hj0ubeh}(h]h ]h"]h$]h&]jjuh1j<$hjhhhj hM*ubeh}(h]h ]h"]h$]h&]jjj!uh1jm!j!j!hjhhhj hM*ubah}(h]jah ](j!j!eh"]h$]h&]j!j!)j!huh1jg!hj hM*hjhhubj!)}(hhh]h)}(h.Prepare to wait on and enqueue several futexesh]h.Prepare to wait on and enqueue several futexes}(hj|hhhNhNubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chM*hjyhhubah}(h]h ]h"]h$]h&]uh1j!hjhhhj hM*ubeh}(h]h ](jUfunctioneh"]h$]h&]j!jUj!jj!jj!j!j!uh1jb!hhhj6hNhNubj!)}(hX**Parameters** ``struct futex_vector *vs`` The list of futexes to wait on ``unsigned int count`` The number of objects ``struct hrtimer_sleeper *to`` Timeout before giving up and returning to userspace **Description** Entry point for the FUTEX_WAIT_MULTIPLE futex operation, this function sleeps on a group of futexes and returns on the first futex that is wake, or after the timeout has elapsed. **Return** - >=0 - Hint to the futex that was awoken - <0 - On errorh](h)}(h**Parameters**h]j)}(hjh]h Parameters}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chM.hjubj")}(hhh](j")}(h;``struct futex_vector *vs`` The list of futexes to wait on h](j")}(h``struct futex_vector *vs``h]jI)}(hjh]hstruct futex_vector *vs}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjubah}(h]h ]h"]h$]h&]uh1j"h`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chM+hjubj5")}(hhh]h)}(hThe list of futexes to wait onh]hThe list of futexes to wait on}(hjօhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj҅hM+hjӅubah}(h]h ]h"]h$]h&]uh1j4"hjubeh}(h]h ]h"]h$]h&]uh1j"hj҅hM+hjubj")}(h-``unsigned int count`` The number of objects h](j")}(h``unsigned int count``h]jI)}(hjh]hunsigned int count}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjubah}(h]h ]h"]h$]h&]uh1j"h`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chM,hjubj5")}(hhh]h)}(hThe number of objectsh]hThe number of objects}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hM,hj ubah}(h]h ]h"]h$]h&]uh1j4"hjubeh}(h]h ]h"]h$]h&]uh1j"hj hM,hjubj")}(hS``struct hrtimer_sleeper *to`` Timeout before giving up and returning to userspace h](j")}(h``struct hrtimer_sleeper *to``h]jI)}(hj/h]hstruct hrtimer_sleeper *to}(hj1hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhj-ubah}(h]h ]h"]h$]h&]uh1j"h`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chM-hj)ubj5")}(hhh]h)}(h3Timeout before giving up and returning to userspaceh]h3Timeout before giving up and returning to userspace}(hjHhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjDhM-hjEubah}(h]h ]h"]h$]h&]uh1j4"hj)ubeh}(h]h ]h"]h$]h&]uh1j"hjDhM-hjubeh}(h]h ]h"]h$]h&]uh1j"hjubh)}(h**Description**h]j)}(hjjh]h Description}(hjlhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjhubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chM/hjubh)}(hEntry point for the FUTEX_WAIT_MULTIPLE futex operation, this function sleeps on a group of futexes and returns on the first futex that is wake, or after the timeout has elapsed.h]hEntry point for the FUTEX_WAIT_MULTIPLE futex operation, this function sleeps on a group of futexes and returns on the first futex that is wake, or after the timeout has elapsed.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chM.hjubh)}(h **Return**h]j)}(hjh]hReturn}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chM2hjubj )}(hhh](j )}(h'>=0 - Hint to the futex that was awokenh]h)}(hjh]h'>=0 - Hint to the futex that was awoken}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chM3hjubah}(h]h ]h"]h$]h&]uh1j hjubj )}(h<0 - On errorh]h)}(hjĆh]h<0 - On error}(hjƆhhhNhNubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chM4hj†ubah}(h]h ]h"]h$]h&]uh1j hjubeh}(h]h ]h"]h$]h&]j5 j6 uh1j hjhM3hjubeh}(h]h ] kernelindentah"]h$]h&]uh1j!hj6hhhNhNubjR!)}(hhh]h}(h]h ]h"]h$]h&]entries](j^!futex_wait_setup (C function)c.futex_wait_setuphNtauh1jQ!hj6hhhNhNubjc!)}(hhh](jh!)}(hint futex_wait_setup (u32 __user *uaddr, u32 val, unsigned int flags, struct futex_q *q, union futex_key *key2, struct task_struct *task)h]jn!)}(hint futex_wait_setup(u32 __user *uaddr, u32 val, unsigned int flags, struct futex_q *q, union futex_key *key2, struct task_struct *task)h](j$)}(hinth]hint}(hjhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjhhh`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chM]ubj$)}(h h]h }(hjhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjhhhjhM]ubjt!)}(hfutex_wait_setuph]jz!)}(hfutex_wait_setuph]hfutex_wait_setup}(hj!hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjubah}(h]h ](j!j!eh"]h$]h&]jjuh1js!hjhhhjhM]ubj=$)}(ht(u32 __user *uaddr, u32 val, unsigned int flags, struct futex_q *q, union futex_key *key2, struct task_struct *task)h](jC$)}(hu32 __user *uaddrh](h)}(hhh]jz!)}(hu32h]hu32}(hj@hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj=ubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetjBmodnameN classnameNj$j$)}j$]j$)}j$j#sbc.futex_wait_setupasbuh1hhj9ubj$)}(h h]h }(hj`hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj9ubh__user}(hj9hhhNhNubj$)}(h h]h }(hjrhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj9ubj$)}(hj$h]h*}(hjhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj9ubjz!)}(huaddrh]huaddr}(hjhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj9ubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hj5ubjC$)}(hu32 valh](h)}(hhh]jz!)}(hu32h]hu32}(hjhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetjmodnameN classnameNj$j$)}j$]j\c.futex_wait_setupasbuh1hhjubj$)}(h h]h }(hjLJhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjubjz!)}(hvalh]hval}(hjՇhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hj5ubjC$)}(hunsigned int flagsh](j$)}(hunsignedh]hunsigned}(hjhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjubj$)}(h h]h }(hjhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjubj$)}(hinth]hint}(hj hhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjubj$)}(h h]h }(hjhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjubjz!)}(hflagsh]hflags}(hj&hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hj5ubjC$)}(hstruct futex_q *qh](jI$)}(hjL$h]hstruct}(hj?hhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hj;ubj$)}(h h]h }(hjLhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj;ubh)}(hhh]jz!)}(hfutex_qh]hfutex_q}(hj]hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjZubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetj_modnameN classnameNj$j$)}j$]j\c.futex_wait_setupasbuh1hhj;ubj$)}(h h]h }(hj{hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hj;ubj$)}(hj$h]h*}(hjhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hj;ubjz!)}(hj;Gh]hq}(hjhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj;ubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hj5ubjC$)}(hunion futex_key *key2h](jI$)}(hj6h]hunion}(hjhhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hjubj$)}(h h]h }(hjhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjubh)}(hhh]jz!)}(h futex_keyh]h futex_key}(hj̈hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjɈubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetjΈmodnameN classnameNj$j$)}j$]j\c.futex_wait_setupasbuh1hhjubj$)}(h h]h }(hjhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjubj$)}(hj$h]h*}(hjhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjubjz!)}(hkey2h]hkey2}(hjhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hj5ubjC$)}(hstruct task_struct *taskh](jI$)}(hjL$h]hstruct}(hjhhhNhNubah}(h]h ]jU$ah"]h$]h&]uh1jH$hjubj$)}(h h]h }(hj+hhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjubh)}(hhh]jz!)}(h task_structh]h task_struct}(hj<hhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hj9ubah}(h]h ]h"]h$]h&] refdomainjUreftypej$ reftargetj>modnameN classnameNj$j$)}j$]j\c.futex_wait_setupasbuh1hhjubj$)}(h h]h }(hjZhhhNhNubah}(h]h ]j $ah"]h$]h&]uh1j$hjubj$)}(hj$h]h*}(hjhhhhNhNubah}(h]h ]j$ah"]h$]h&]uh1j$hjubjz!)}(htaskh]htask}(hjuhhhNhNubah}(h]h ]j!ah"]h$]h&]uh1jy!hjubeh}(h]h ]h"]h$]h&]noemphjjuh1jB$hj5ubeh}(h]h ]h"]h$]h&]jjuh1j<$hjhhhjhM]ubeh}(h]h ]h"]h$]h&]jjj!uh1jm!j!j!hjhhhjhM]ubah}(h]jah ](j!j!eh"]h$]h&]j!j!)j!huh1jg!hjhM]hjhhubj!)}(hhh]h)}(hPrepare to wait on a futexh]hPrepare to wait on a futex}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chM]hjhhubah}(h]h ]h"]h$]h&]uh1j!hjhhhjhM]ubeh}(h]h ](jUfunctioneh"]h$]h&]j!jUj!jj!jj!j!j!uh1jb!hhhj6hNhNubj!)}(hX**Parameters** ``u32 __user *uaddr`` the futex userspace address ``u32 val`` the expected value ``unsigned int flags`` futex flags (FLAGS_SHARED, etc.) ``struct futex_q *q`` the associated futex_q ``union futex_key *key2`` the second futex_key if used for requeue PI ``struct task_struct *task`` Task queueing this futex **Description** Setup the futex_q and locate the hash_bucket. Get the futex value and compare it with the expected value. Handle atomic faults internally. Return with the hb lock held on success, and unlocked on failure. **Return** - 0 - uaddr contains val and hb has been locked; - <0 - On error and the hb is unlocked. A possible reason: the uaddr can not be read, does not contain the expected value or is not properly aligned.h](h)}(h**Parameters**h]j)}(hjh]h Parameters}(hjÉhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMahjubj")}(hhh](j")}(h2``u32 __user *uaddr`` the futex userspace address h](j")}(h``u32 __user *uaddr``h]jI)}(hjh]hu32 __user *uaddr}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjމubah}(h]h ]h"]h$]h&]uh1j"h`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chM^hjډubj5")}(hhh]h)}(hthe futex userspace addressh]hthe futex userspace address}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhM^hjubah}(h]h ]h"]h$]h&]uh1j4"hjډubeh}(h]h ]h"]h$]h&]uh1j"hjhM^hj׉ubj")}(h``u32 val`` the expected value h](j")}(h ``u32 val``h]jI)}(hjh]hu32 val}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjubah}(h]h ]h"]h$]h&]uh1j"h`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chM_hjubj5")}(hhh]h)}(hthe expected valueh]hthe expected value}(hj2hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj.hM_hj/ubah}(h]h ]h"]h$]h&]uh1j4"hjubeh}(h]h ]h"]h$]h&]uh1j"hj.hM_hj׉ubj")}(h8``unsigned int flags`` futex flags (FLAGS_SHARED, etc.) h](j")}(h``unsigned int flags``h]jI)}(hjRh]hunsigned int flags}(hjThhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjPubah}(h]h ]h"]h$]h&]uh1j"h`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chM`hjLubj5")}(hhh]h)}(h futex flags (FLAGS_SHARED, etc.)h]h futex flags (FLAGS_SHARED, etc.)}(hjkhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjghM`hjhubah}(h]h ]h"]h$]h&]uh1j4"hjLubeh}(h]h ]h"]h$]h&]uh1j"hjghM`hj׉ubj")}(h-``struct futex_q *q`` the associated futex_q h](j")}(h``struct futex_q *q``h]jI)}(hjh]hstruct futex_q *q}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjubah}(h]h ]h"]h$]h&]uh1j"h`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMahjubj5")}(hhh]h)}(hthe associated futex_qh]hthe associated futex_q}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhMahjubah}(h]h ]h"]h$]h&]uh1j4"hjubeh}(h]h ]h"]h$]h&]uh1j"hjhMahj׉ubj")}(hF``union futex_key *key2`` the second futex_key if used for requeue PI h](j")}(h``union futex_key *key2``h]jI)}(hjĊh]hunion futex_key *key2}(hjƊhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjŠubah}(h]h ]h"]h$]h&]uh1j"h`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMbhjubj5")}(hhh]h)}(h+the second futex_key if used for requeue PIh]h+the second futex_key if used for requeue PI}(hj݊hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjيhMbhjڊubah}(h]h ]h"]h$]h&]uh1j4"hjubeh}(h]h ]h"]h$]h&]uh1j"hjيhMbhj׉ubj")}(h6``struct task_struct *task`` Task queueing this futex h](j")}(h``struct task_struct *task``h]jI)}(hjh]hstruct task_struct *task}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjubah}(h]h ]h"]h$]h&]uh1j"h`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMchjubj5")}(hhh]h)}(hTask queueing this futexh]hTask queueing this futex}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhMchjubah}(h]h ]h"]h$]h&]uh1j4"hjubeh}(h]h ]h"]h$]h&]uh1j"hjhMchj׉ubeh}(h]h ]h"]h$]h&]uh1j"hjubh)}(h**Description**h]j)}(hj8h]h Description}(hj:hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj6ubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMehjubh)}(hSetup the futex_q and locate the hash_bucket. Get the futex value and compare it with the expected value. Handle atomic faults internally. Return with the hb lock held on success, and unlocked on failure.h]hSetup the futex_q and locate the hash_bucket. Get the futex value and compare it with the expected value. Handle atomic faults internally. Return with the hb lock held on success, and unlocked on failure.}(hjNhhhNhNubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMdhjubh)}(h **Return**h]j)}(hj_h]hReturn}(hjahhhNhNubah}(h]h ]h"]h$]h&]uh1jhj]ubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMhhjubj )}(hhh](j )}(h.0 - uaddr contains val and hb has been locked;h]h)}(hjzh]h.0 - uaddr contains val and hb has been locked;}(hj|hhhNhNubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMihjxubah}(h]h ]h"]h$]h&]uh1j hjuubj )}(h<0 - On error and the hb is unlocked. A possible reason: the uaddr can not be read, does not contain the expected value or is not properly aligned.h]j")}(hhh]j")}(h<0 - On error and the hb is unlocked. A possible reason: the uaddr can not be read, does not contain the expected value or is not properly aligned.h](j")}(hJ<0 - On error and the hb is unlocked. A possible reason: the uaddr can noth]hJ<0 - On error and the hb is unlocked. A possible reason: the uaddr can not}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j"h`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMjhjubj5")}(hhh]h)}(hHbe read, does not contain the expected value or is not properly aligned.h]hHbe read, does not contain the expected value or is not properly aligned.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hh`/var/lib/git/docbuild/linux/Documentation/kernel-hacking/locking:1367: ./kernel/futex/waitwake.chMkhjubah}(h]h ]h"]h$]h&]uh1j4"hjubeh}(h]h ]h"]h$]h&]uh1j"hjhMjhjubah}(h]h ]h"]h$]h&]uh1j"hjubah}(h]h ]h"]h$]h&]uh1j hjuubeh}(h]h ]h"]h$]h&]j5 j6 uh1j hjhMihjubeh}(h]h ] kernelindentah"]h$]h&]uh1j!hj6hhhNhNubeh}(h]futex-api-referenceah ]h"]futex api referenceah$]h&]uh1hhhhhhhhMIubh)}(hhh](h)}(hFurther readingh]hFurther reading}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhM[ubj )}(hhh](j )}(he``Documentation/locking/spinlocks.rst``: Linus Torvalds' spinlocking tutorial in the kernel sources. h]h)}(hd``Documentation/locking/spinlocks.rst``: Linus Torvalds' spinlocking tutorial in the kernel sources.h](jI)}(h'``Documentation/locking/spinlocks.rst``h]h#Documentation/locking/spinlocks.rst}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjubh?: Linus Torvalds’ spinlocking tutorial in the kernel sources.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM]hjubah}(h]h ]h"]h$]h&]uh1j hjhhhhhNubj )}(hX?Unix Systems for Modern Architectures: Symmetric Multiprocessing and Caching for Kernel Programmers: Curt Schimmel's very good introduction to kernel level locking (not written for Linux, but nearly everything applies). The book is expensive, but really worth every penny to understand SMP locking. [ISBN: 0201633388] h](h)}(hdUnix Systems for Modern Architectures: Symmetric Multiprocessing and Caching for Kernel Programmers:h]hdUnix Systems for Modern Architectures: Symmetric Multiprocessing and Caching for Kernel Programmers:}(hj'hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM`hj#ubh)}(hCurt Schimmel's very good introduction to kernel level locking (not written for Linux, but nearly everything applies). The book is expensive, but really worth every penny to understand SMP locking. [ISBN: 0201633388]h]hCurt Schimmel’s very good introduction to kernel level locking (not written for Linux, but nearly everything applies). The book is expensive, but really worth every penny to understand SMP locking. [ISBN: 0201633388]}(hj5hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMchj#ubeh}(h]h ]h"]h$]h&]uh1j hjhhhhhNubeh}(h]h ]h"]h$]h&]j5 j6 uh1j hhhM]hjhhubeh}(h]further-readingah ]h"]further readingah$]h&]uh1hhhhhhhhM[ubh)}(hhh](h)}(hThanksh]hThanks}(hjZhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjWhhhhhMiubh)}(hBThanks to Telsa Gwynne for DocBooking, neatening and adding style.h]hBThanks to Telsa Gwynne for DocBooking, neatening and adding style.}(hjhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMkhjWhhubh)}(hThanks to Martin Pool, Philipp Rumpf, Stephen Rothwell, Paul Mackerras, Ruedi Aschwanden, Alan Cox, Manfred Spraul, Tim Waugh, Pete Zaitcev, James Morris, Robert Love, Paul McKenney, John Ashby for proofreading, correcting, flaming, commenting.h]hThanks to Martin Pool, Philipp Rumpf, Stephen Rothwell, Paul Mackerras, Ruedi Aschwanden, Alan Cox, Manfred Spraul, Tim Waugh, Pete Zaitcev, James Morris, Robert Love, Paul McKenney, John Ashby for proofreading, correcting, flaming, commenting.}(hjvhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMmhjWhhubh)}(h=Thanks to the cabal for having no influence on this document.h]h=Thanks to the cabal for having no influence on this document.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMrhjWhhubeh}(h]thanksah ]h"]thanksah$]h&]uh1hhhhhhhhMiubh)}(hhh](h)}(hGlossaryh]hGlossary}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMuubj")}(hhh](j")}(hXpreemption Prior to 2.5, or when ``CONFIG_PREEMPT`` is unset, processes in user context inside the kernel would not preempt each other (ie. you had that CPU until you gave it up, except for interrupts). With the addition of ``CONFIG_PREEMPT`` in 2.5.4, this changed: when in user context, higher priority tasks can "cut in": spinlocks were changed to disable preemption, even on UP. h](j")}(h preemptionh]h preemption}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j"hhhM}hjubj5")}(hhh]h)}(hXsPrior to 2.5, or when ``CONFIG_PREEMPT`` is unset, processes in user context inside the kernel would not preempt each other (ie. you had that CPU until you gave it up, except for interrupts). With the addition of ``CONFIG_PREEMPT`` in 2.5.4, this changed: when in user context, higher priority tasks can "cut in": spinlocks were changed to disable preemption, even on UP.h](hPrior to 2.5, or when }(hjÌhhhNhNubjI)}(h``CONFIG_PREEMPT``h]hCONFIG_PREEMPT}(hjˌhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjÌubh is unset, processes in user context inside the kernel would not preempt each other (ie. you had that CPU until you gave it up, except for interrupts). With the addition of }(hjÌhhhNhNubjI)}(h``CONFIG_PREEMPT``h]hCONFIG_PREEMPT}(hj݌hhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjÌubh in 2.5.4, this changed: when in user context, higher priority tasks can “cut in”: spinlocks were changed to disable preemption, even on UP.}(hjÌhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMxhjubah}(h]h ]h"]h$]h&]uh1j4"hjubeh}(h]h ]h"]h$]h&]uh1j"hhhM}hjubj")}(hX3bh Bottom Half: for historical reasons, functions with '_bh' in them often now refer to any software interrupt, e.g. spin_lock_bh() blocks any software interrupt on the current CPU. Bottom halves are deprecated, and will eventually be replaced by tasklets. Only one bottom half will be running at any time. h](j")}(hbhh]hbh}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j"hhhMhjubj5")}(hhh]h)}(hX/Bottom Half: for historical reasons, functions with '_bh' in them often now refer to any software interrupt, e.g. spin_lock_bh() blocks any software interrupt on the current CPU. Bottom halves are deprecated, and will eventually be replaced by tasklets. Only one bottom half will be running at any time.h]hX3Bottom Half: for historical reasons, functions with ‘_bh’ in them often now refer to any software interrupt, e.g. spin_lock_bh() blocks any software interrupt on the current CPU. Bottom halves are deprecated, and will eventually be replaced by tasklets. Only one bottom half will be running at any time.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1j4"hjubeh}(h]h ]h"]h$]h&]uh1j"hhhMhjhhubj")}(hyHardware Interrupt / Hardware IRQ Hardware interrupt request. in_hardirq() returns true in a hardware interrupt handler. h](j")}(h!Hardware Interrupt / Hardware IRQh]h!Hardware Interrupt / Hardware IRQ}(hj4hhhNhNubah}(h]h ]h"]h$]h&]uh1j"hhhMhj0ubj5")}(hhh]h)}(hVHardware interrupt request. in_hardirq() returns true in a hardware interrupt handler.h]hVHardware interrupt request. in_hardirq() returns true in a hardware interrupt handler.}(hjEhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjBubah}(h]h ]h"]h$]h&]uh1j4"hj0ubeh}(h]h ]h"]h$]h&]uh1j"hhhMhjhhubj")}(hInterrupt Context Not user context: processing a hardware irq or software irq. Indicated by the in_interrupt() macro returning true. h](j")}(hInterrupt Contexth]hInterrupt Context}(hjchhhNhNubah}(h]h ]h"]h$]h&]uh1j"hhhMhj_ubj5")}(hhh]h)}(hrNot user context: processing a hardware irq or software irq. Indicated by the in_interrupt() macro returning true.h]hrNot user context: processing a hardware irq or software irq. Indicated by the in_interrupt() macro returning true.}(hjthhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjqubah}(h]h ]h"]h$]h&]uh1j4"hj_ubeh}(h]h ]h"]h$]h&]uh1j"hhhMhjhhubj")}(h_SMP Symmetric Multi-Processor: kernels compiled for multiple-CPU machines. (``CONFIG_SMP=y``). h](j")}(hSMPh]hSMP}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j"hhhMhjubj5")}(hhh]h)}(hZSymmetric Multi-Processor: kernels compiled for multiple-CPU machines. (``CONFIG_SMP=y``).h](hHSymmetric Multi-Processor: kernels compiled for multiple-CPU machines. (}(hjhhhNhNubjI)}(h``CONFIG_SMP=y``h]h CONFIG_SMP=y}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjubh).}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1j4"hjubeh}(h]h ]h"]h$]h&]uh1j"hhhMhjhhubj")}(hX~Software Interrupt / softirq Software interrupt handler. in_hardirq() returns false; in_softirq() returns true. Tasklets and softirqs both fall into the category of 'software interrupts'. Strictly speaking a softirq is one of up to 32 enumerated software interrupts which can run on multiple CPUs at once. Sometimes used to refer to tasklets as well (ie. all software interrupts). h](j")}(hSoftware Interrupt / softirqh]hSoftware Interrupt / softirq}(hjӍhhhNhNubah}(h]h ]h"]h$]h&]uh1j"hhhMhjύubj5")}(hhh](h)}(hSoftware interrupt handler. in_hardirq() returns false; in_softirq() returns true. Tasklets and softirqs both fall into the category of 'software interrupts'.h]hSoftware interrupt handler. in_hardirq() returns false; in_softirq() returns true. Tasklets and softirqs both fall into the category of ‘software interrupts’.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubh)}(hStrictly speaking a softirq is one of up to 32 enumerated software interrupts which can run on multiple CPUs at once. Sometimes used to refer to tasklets as well (ie. all software interrupts).h]hStrictly speaking a softirq is one of up to 32 enumerated software interrupts which can run on multiple CPUs at once. Sometimes used to refer to tasklets as well (ie. all software interrupts).}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubeh}(h]h ]h"]h$]h&]uh1j4"hjύubeh}(h]h ]h"]h$]h&]uh1j"hhhMhjhhubj")}(hltasklet A dynamically-registrable software interrupt, which is guaranteed to only run on one CPU at a time. h](j")}(htaskleth]htasklet}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j"hhhMhj ubj5")}(hhh]h)}(hcA dynamically-registrable software interrupt, which is guaranteed to only run on one CPU at a time.h]hcA dynamically-registrable software interrupt, which is guaranteed to only run on one CPU at a time.}(hj!hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1j4"hj ubeh}(h]h ]h"]h$]h&]uh1j"hhhMhjhhubj")}(htimer A dynamically-registrable software interrupt, which is run at (or close to) a given time. When running, it is just like a tasklet (in fact, they are called from the ``TIMER_SOFTIRQ``). h](j")}(htimerh]htimer}(hj?hhhNhNubah}(h]h ]h"]h$]h&]uh1j"hhhMhj;ubj5")}(hhh]h)}(hA dynamically-registrable software interrupt, which is run at (or close to) a given time. When running, it is just like a tasklet (in fact, they are called from the ``TIMER_SOFTIRQ``).h](hA dynamically-registrable software interrupt, which is run at (or close to) a given time. When running, it is just like a tasklet (in fact, they are called from the }(hjPhhhNhNubjI)}(h``TIMER_SOFTIRQ``h]h TIMER_SOFTIRQ}(hjXhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjPubh).}(hjPhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjMubah}(h]h ]h"]h$]h&]uh1j4"hj;ubeh}(h]h ]h"]h$]h&]uh1j"hhhMhjhhubj")}(h/UP Uni-Processor: Non-SMP. (``CONFIG_SMP=n``). h](j")}(hUPh]hUP}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j"hhhMhj|ubj5")}(hhh]h)}(h+Uni-Processor: Non-SMP. (``CONFIG_SMP=n``).h](hUni-Processor: Non-SMP. (}(hjhhhNhNubjI)}(h``CONFIG_SMP=n``h]h CONFIG_SMP=n}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjubh).}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1j4"hj|ubeh}(h]h ]h"]h$]h&]uh1j"hhhMhjhhubj")}(hXUser Context The kernel executing on behalf of a particular process (ie. a system call or trap) or kernel thread. You can tell which process with the ``current`` macro.) Not to be confused with userspace. Can be interrupted by software or hardware interrupts. h](j")}(h User Contexth]h User Context}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j"hhhMhjubj5")}(hhh]h)}(hThe kernel executing on behalf of a particular process (ie. a system call or trap) or kernel thread. You can tell which process with the ``current`` macro.) Not to be confused with userspace. Can be interrupted by software or hardware interrupts.h](hThe kernel executing on behalf of a particular process (ie. a system call or trap) or kernel thread. You can tell which process with the }(hjҎhhhNhNubjI)}(h ``current``h]hcurrent}(hjڎhhhNhNubah}(h]h ]h"]h$]h&]uh1jHhjҎubhb macro.) Not to be confused with userspace. Can be interrupted by software or hardware interrupts.}(hjҎhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjώubah}(h]h ]h"]h$]h&]uh1j4"hjubeh}(h]h ]h"]h$]h&]uh1j"hhhMhjhhubj")}(h>Userspace A process executing its own code outside the kernel.h](j")}(h Userspaceh]h Userspace}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j"hhhMhjubj5")}(hhh]h)}(h4A process executing its own code outside the kernel.h]h4A process executing its own code outside the kernel.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1j4"hjubeh}(h]h ]h"]h$]h&]uh1j"hhhMhjhhubeh}(h]h ]h"]h$]h&]uh1j"hjhhhhhNubeh}(h]glossaryah ]h"]glossaryah$]h&]uh1hhhhhhhhMuubeh}(h](unreliable-guide-to-lockingheh ]h"](unreliable guide to lockingkernel_hacking_lockeh$]h&]uh1hhhhhhhhKexpect_referenced_by_name}jAhsexpect_referenced_by_id}hhsubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksjfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerjjerror_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourcehÌ _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}(0what functions are safe to call from interrupts?]j~adeadlock: simple and advanced]jahard irq context]j&a per-cpu data]jdaurefids}h]hasnameids}(jAhj@j=jMjJjjjjjjjjjj|jjjfjcjjjjj)j&jjj!jjjjjjjj j6jk jh j j jAj>j9j6jjj0j-jjjjjjjjj(j%jjjjjGjDj?j<jjjjjjjjjWjtjjj=!jj j j6!j3!j5j5jjjTjQjjj8j5u nametypes}(jAj@jMjjjjjjjfjjj)jj!jjjj jk j jAj9jj0jjjjj(jjjGj?jjjjjWjj=!j j6!j5jjTjj8uh}(hhj=hjJjjjPjjjjjj/j|jjjjcjjjijjj&jjjjjjj,jjKjjj6jjh jj jn j>j j6j7 jjDj-jjjjjjjjj-j%jjj3jjDjDjj<jjjJjjjjZjjjtjjjZjjj jj3!j j5j@!j`!ji!j"j"j#j#j%j%j='jB'j(j(j{*j*j,j,j.j.j0j0j?2jD2j3j3jj6j6j#6j;9j@9jt<jy<j@j@j0Bj5BjDjDjFjFjHjHjIjIjKjKjOjOjQjQjTjTj-Vj2Vj\j \j^j_jPbjUbj fjfjljljrjrjtjtjyjyj{j{jf~jk~j:j?jjjjjQjjjWj5jjjjj.u footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}jxKsRparse_messages]hsystem_message)}(hhh]h)}(heUnexpected possible title overline or transition. Treating it as ordinary text because it's so short.h]hgUnexpected possible title overline or transition. Treating it as ordinary text because it’s so short.}(hjڏhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj׏ubah}(h]h ]h"]h$]h&]levelKtypeINFOlineMBsourcehuh1jՏhj ubatransform_messages]j֏)}(hhh]h)}(hhh]h9Hyperlink target "kernel-hacking-lock" is not referenced.}hjsbah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]levelKtypejsourcehÌlineKuh1jՏuba transformerN include_log] decorationNhhub.