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/RCU/rcubarriermodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget"/translations/zh_TW/RCU/rcubarriermodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget"/translations/it_IT/RCU/rcubarriermodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget"/translations/ja_JP/RCU/rcubarriermodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget"/translations/ko_KR/RCU/rcubarriermodnameN classnameN refexplicituh1hhh ubh)}(hhh]hPortuguese (Brazilian)}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget"/translations/pt_BR/RCU/rcubarriermodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget"/translations/sp_SP/RCU/rcubarriermodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhtarget)}(h.. _rcu_barrier:h]h}(h]h ]h"]h$]h&]refid rcu-barrieruh1hhKhhhhhrcu, p_callback);h]h/list_del_rcu(p); call_rcu(&p->rcu, p_callback);}hjsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1j hhhKhhhhubh)}(hSince call_rcu() never blocks, this code can safely be used from within IRQ context. The function p_callback() might be defined as follows::h]hSince call_rcu() never blocks, this code can safely be used from within IRQ context. The function p_callback() might be defined as follows:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubj )}(hstatic void p_callback(struct rcu_head *rp) { struct pstruct *p = container_of(rp, struct pstruct, rcu); kfree(p); }h]hstatic void p_callback(struct rcu_head *rp) { struct pstruct *p = container_of(rp, struct pstruct, rcu); kfree(p); }}hj,sbah}(h]h ]h"]h$]h&]jjuh1j hhhKhhhhubh)}(hhh](h)}(h%Unloading Modules That Use call_rcu()h]h%Unloading Modules That Use call_rcu()}(hj=hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj:hhhhhKubh)}(hIBut what if the p_callback() function is defined in an unloadable module?h]hIBut what if the p_callback() function is defined in an unloadable module?}(hjKhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hj:hhubh)}(hIf we unload the module while some RCU callbacks are pending, the CPUs executing these callbacks are going to be severely disappointed when they are later invoked, as fancifully depicted at http://lwn.net/images/ns/kernel/rcu-drop.jpg.h](hIf we unload the module while some RCU callbacks are pending, the CPUs executing these callbacks are going to be severely disappointed when they are later invoked, as fancifully depicted at }(hjYhhhNhNubh)}(h,http://lwn.net/images/ns/kernel/rcu-drop.jpgh]h,http://lwn.net/images/ns/kernel/rcu-drop.jpg}(hjahhhNhNubah}(h]h ]h"]h$]h&]refurijcuh1hhjYubh.}(hjYhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK"hj:hhubh)}(hWe could try placing a synchronize_rcu() in the module-exit code path, but this is not sufficient. Although synchronize_rcu() does wait for a grace period to elapse, it does not wait for the callbacks to complete.h]hWe could try placing a synchronize_rcu() in the module-exit code path, but this is not sufficient. Although synchronize_rcu() does wait for a grace period to elapse, it does not wait for the callbacks to complete.}(hjzhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK'hj:hhubh)}(hXpOne might be tempted to try several back-to-back synchronize_rcu() calls, but this is still not guaranteed to work. If there is a very heavy RCU-callback load, then some of the callbacks might be deferred in order to allow other processing to proceed. For but one example, such deferral is required in realtime kernels in order to avoid excessive scheduling latencies.h]hXpOne might be tempted to try several back-to-back synchronize_rcu() calls, but this is still not guaranteed to work. If there is a very heavy RCU-callback load, then some of the callbacks might be deferred in order to allow other processing to proceed. For but one example, such deferral is required in realtime kernels in order to avoid excessive scheduling latencies.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK+hj:hhubeh}(h]#unloading-modules-that-use-call-rcuah ]h"]%unloading modules that use call_rcu()ah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h rcu_barrier()h]h rcu_barrier()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhK4ubh)}(hXThis situation can be handled by the rcu_barrier() primitive. Rather than waiting for a grace period to elapse, rcu_barrier() waits for all outstanding RCU callbacks to complete. Please note that rcu_barrier() does **not** imply synchronize_rcu(), in particular, if there are no RCU callbacks queued anywhere, rcu_barrier() is within its rights to return immediately, without waiting for anything, let alone a grace period.h](hThis situation can be handled by the rcu_barrier() primitive. Rather than waiting for a grace period to elapse, rcu_barrier() waits for all outstanding RCU callbacks to complete. Please note that rcu_barrier() does }(hjhhhNhNubhstrong)}(h**not**h]hnot}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh imply synchronize_rcu(), in particular, if there are no RCU callbacks queued anywhere, rcu_barrier() is within its rights to return immediately, without waiting for anything, let alone a grace period.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK6hjhhubh)}(h.Pseudo-code using rcu_barrier() is as follows:h]h.Pseudo-code using rcu_barrier() is as follows:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK=hjhhubh block_quote)}(hr1. Prevent any new RCU callbacks from being posted. 2. Execute rcu_barrier(). 3. Allow the module to be unloaded. h]henumerated_list)}(hhh](h list_item)}(h0Prevent any new RCU callbacks from being posted.h]h)}(hjh]h0Prevent any new RCU callbacks from being posted.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK?hjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hExecute rcu_barrier().h]h)}(hjh]hExecute rcu_barrier().}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK@hjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(h!Allow the module to be unloaded. h]h)}(h Allow the module to be unloaded.h]h Allow the module to be unloaded.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKAhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]enumtypearabicprefixhsuffix.uh1jhjubah}(h]h ]h"]h$]h&]uh1jhhhK?hjhhubh)}(hXThere is also an srcu_barrier() function for SRCU, and you of course must match the flavor of srcu_barrier() with that of call_srcu(). If your module uses multiple srcu_struct structures, then it must also use multiple invocations of srcu_barrier() when unloading that module. For example, if it uses call_rcu(), call_srcu() on srcu_struct_1, and call_srcu() on srcu_struct_2, then the following three lines of code will be required when unloading::h]hXThere is also an srcu_barrier() function for SRCU, and you of course must match the flavor of srcu_barrier() with that of call_srcu(). If your module uses multiple srcu_struct structures, then it must also use multiple invocations of srcu_barrier() when unloading that module. For example, if it uses call_rcu(), call_srcu() on srcu_struct_1, and call_srcu() on srcu_struct_2, then the following three lines of code will be required when unloading:}(hjChhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKChjhhubj )}(hS1 rcu_barrier(); 2 srcu_barrier(&srcu_struct_1); 3 srcu_barrier(&srcu_struct_2);h]hS1 rcu_barrier(); 2 srcu_barrier(&srcu_struct_1); 3 srcu_barrier(&srcu_struct_2);}hjQsbah}(h]h ]h"]h$]h&]jjuh1j hhhKKhjhhubh)}(haIf latency is of the essence, workqueues could be used to run these three functions concurrently.h]haIf latency is of the essence, workqueues could be used to run these three functions concurrently.}(hj_hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKOhjhhubh)}(hhAn ancient version of the rcutorture module makes use of rcu_barrier() in its exit function as follows::h]hgAn ancient version of the rcutorture module makes use of rcu_barrier() in its exit function as follows:}(hjmhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKRhjhhubj )}(hX 1 static void 2 rcu_torture_cleanup(void) 3 { 4 int i; 5 6 fullstop = 1; 7 if (shuffler_task != NULL) { 8 VERBOSE_PRINTK_STRING("Stopping rcu_torture_shuffle task"); 9 kthread_stop(shuffler_task); 10 } 11 shuffler_task = NULL; 12 13 if (writer_task != NULL) { 14 VERBOSE_PRINTK_STRING("Stopping rcu_torture_writer task"); 15 kthread_stop(writer_task); 16 } 17 writer_task = NULL; 18 19 if (reader_tasks != NULL) { 20 for (i = 0; i < nrealreaders; i++) { 21 if (reader_tasks[i] != NULL) { 22 VERBOSE_PRINTK_STRING( 23 "Stopping rcu_torture_reader task"); 24 kthread_stop(reader_tasks[i]); 25 } 26 reader_tasks[i] = NULL; 27 } 28 kfree(reader_tasks); 29 reader_tasks = NULL; 30 } 31 rcu_torture_current = NULL; 32 33 if (fakewriter_tasks != NULL) { 34 for (i = 0; i < nfakewriters; i++) { 35 if (fakewriter_tasks[i] != NULL) { 36 VERBOSE_PRINTK_STRING( 37 "Stopping rcu_torture_fakewriter task"); 38 kthread_stop(fakewriter_tasks[i]); 39 } 40 fakewriter_tasks[i] = NULL; 41 } 42 kfree(fakewriter_tasks); 43 fakewriter_tasks = NULL; 44 } 45 46 if (stats_task != NULL) { 47 VERBOSE_PRINTK_STRING("Stopping rcu_torture_stats task"); 48 kthread_stop(stats_task); 49 } 50 stats_task = NULL; 51 52 /* Wait for all RCU callbacks to fire. */ 53 rcu_barrier(); 54 55 rcu_torture_stats_print(); /* -After- the stats thread is stopped! */ 56 57 if (cur_ops->cleanup != NULL) 58 cur_ops->cleanup(); 59 if (atomic_read(&n_rcu_torture_error)) 60 rcu_torture_print_module_parms("End of test: FAILURE"); 61 else 62 rcu_torture_print_module_parms("End of test: SUCCESS"); 63 }h]hX 1 static void 2 rcu_torture_cleanup(void) 3 { 4 int i; 5 6 fullstop = 1; 7 if (shuffler_task != NULL) { 8 VERBOSE_PRINTK_STRING("Stopping rcu_torture_shuffle task"); 9 kthread_stop(shuffler_task); 10 } 11 shuffler_task = NULL; 12 13 if (writer_task != NULL) { 14 VERBOSE_PRINTK_STRING("Stopping rcu_torture_writer task"); 15 kthread_stop(writer_task); 16 } 17 writer_task = NULL; 18 19 if (reader_tasks != NULL) { 20 for (i = 0; i < nrealreaders; i++) { 21 if (reader_tasks[i] != NULL) { 22 VERBOSE_PRINTK_STRING( 23 "Stopping rcu_torture_reader task"); 24 kthread_stop(reader_tasks[i]); 25 } 26 reader_tasks[i] = NULL; 27 } 28 kfree(reader_tasks); 29 reader_tasks = NULL; 30 } 31 rcu_torture_current = NULL; 32 33 if (fakewriter_tasks != NULL) { 34 for (i = 0; i < nfakewriters; i++) { 35 if (fakewriter_tasks[i] != NULL) { 36 VERBOSE_PRINTK_STRING( 37 "Stopping rcu_torture_fakewriter task"); 38 kthread_stop(fakewriter_tasks[i]); 39 } 40 fakewriter_tasks[i] = NULL; 41 } 42 kfree(fakewriter_tasks); 43 fakewriter_tasks = NULL; 44 } 45 46 if (stats_task != NULL) { 47 VERBOSE_PRINTK_STRING("Stopping rcu_torture_stats task"); 48 kthread_stop(stats_task); 49 } 50 stats_task = NULL; 51 52 /* Wait for all RCU callbacks to fire. */ 53 rcu_barrier(); 54 55 rcu_torture_stats_print(); /* -After- the stats thread is stopped! */ 56 57 if (cur_ops->cleanup != NULL) 58 cur_ops->cleanup(); 59 if (atomic_read(&n_rcu_torture_error)) 60 rcu_torture_print_module_parms("End of test: FAILURE"); 61 else 62 rcu_torture_print_module_parms("End of test: SUCCESS"); 63 }}hj{sbah}(h]h ]h"]h$]h&]jjuh1j hhhKUhjhhubh)}(hX)Line 6 sets a global variable that prevents any RCU callbacks from re-posting themselves. This will not be necessary in most cases, since RCU callbacks rarely include calls to call_rcu(). However, the rcutorture module is an exception to this rule, and therefore needs to set this global variable.h]hX)Line 6 sets a global variable that prevents any RCU callbacks from re-posting themselves. This will not be necessary in most cases, since RCU callbacks rarely include calls to call_rcu(). However, the rcutorture module is an exception to this rule, and therefore needs to set this global variable.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hLines 7-50 stop all the kernel tasks associated with the rcutorture module. Therefore, once execution reaches line 53, no more rcutorture RCU callbacks will be posted. The rcu_barrier() call on line 53 waits for any pre-existing callbacks to complete.h]hLines 7-50 stop all the kernel tasks associated with the rcutorture module. Therefore, once execution reaches line 53, no more rcutorture RCU callbacks will be posted. The rcu_barrier() call on line 53 waits for any pre-existing callbacks to complete.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hThen lines 55-62 print status and do operation-specific cleanup, and then return, permitting the module-unload operation to be completed.h]hThen lines 55-62 print status and do operation-specific cleanup, and then return, permitting the module-unload operation to be completed.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(h.. _rcubarrier_quiz_1:h]h}(h]h ]h"]h$]h&]hrcubarrier-quiz-1uh1hhKhjhhhhubhdefinition_list)}(hhh]hdefinition_list_item)}(hSQuick Quiz #1: Is there any other situation where rcu_barrier() might be required? h](hterm)}(hQuick Quiz #1:h]hQuick Quiz #1:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjubh definition)}(hhh]h)}(hCIs there any other situation where rcu_barrier() might be required?h]hCIs there any other situation where rcu_barrier() might be required?}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhKhjubah}(h]jah ]h"]rcubarrier_quiz_1ah$]h&]uh1jhjhhhhhNexpect_referenced_by_name}jjsexpect_referenced_by_id}jjsubh)}(h9:ref:`Answer to Quick Quiz #1 `h]h)}(hjh]hinline)}(hjh]hAnswer to Quick Quiz #1}(hj hhhNhNubah}(h]h ](xrefstdstd-refeh"]h$]h&]uh1j hjubah}(h]h ]h"]h$]h&]refdocRCU/rcubarrier refdomainjreftyperef refexplicitrefwarn reftargetanswer_rcubarrier_quiz_1uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hX0Your module might have additional complications. For example, if your module invokes call_rcu() from timers, you will need to first refrain from posting new timers, cancel (or wait for) all the already-posted timers, and only then invoke rcu_barrier() to wait for any remaining RCU callbacks to complete.h]hX0Your module might have additional complications. For example, if your module invokes call_rcu() from timers, you will need to first refrain from posting new timers, cancel (or wait for) all the already-posted timers, and only then invoke rcu_barrier() to wait for any remaining RCU callbacks to complete.}(hj1hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXxOf course, if your module uses call_rcu(), you will need to invoke rcu_barrier() before unloading. Similarly, if your module uses call_srcu(), you will need to invoke srcu_barrier() before unloading, and on the same srcu_struct structure. If your module uses call_rcu() **and** call_srcu(), then (as noted above) you will need to invoke rcu_barrier() **and** srcu_barrier().h](hXOf course, if your module uses call_rcu(), you will need to invoke rcu_barrier() before unloading. Similarly, if your module uses call_srcu(), you will need to invoke srcu_barrier() before unloading, and on the same srcu_struct structure. If your module uses call_rcu() }(hj?hhhNhNubj)}(h**and**h]hand}(hjGhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj?ubhJ call_srcu(), then (as noted above) you will need to invoke rcu_barrier() }(hj?hhhNhNubj)}(h**and**h]hand}(hjYhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj?ubh srcu_barrier().}(hj?hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]id1ah ]h"] rcu_barrier()ah$]h&]uh1hhhhhhhhK4ubh)}(hhh](h)}(hImplementing rcu_barrier()h]hImplementing rcu_barrier()}(hj|hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjyhhhhhKubh)}(hXkDipankar Sarma's implementation of rcu_barrier() makes use of the fact that RCU callbacks are never reordered once queued on one of the per-CPU queues. His implementation queues an RCU callback on each of the per-CPU callback queues, and then waits until they have all started executing, at which point, all earlier RCU callbacks are guaranteed to have completed.h]hXmDipankar Sarma’s implementation of rcu_barrier() makes use of the fact that RCU callbacks are never reordered once queued on one of the per-CPU queues. His implementation queues an RCU callback on each of the per-CPU callback queues, and then waits until they have all started executing, at which point, all earlier RCU callbacks are guaranteed to have completed.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjyhhubh)}(h`h]h)}(hj h]j )}(hj h]hAnswer to Quick Quiz #2}(hjhhhNhNubah}(h]h ](jstdstd-refeh"]h$]h&]uh1j hj ubah}(h]h ]h"]h$]h&]refdocj# refdomainjreftyperef refexplicitrefwarnj)answer_rcubarrier_quiz_2uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1hhhhKhjyhhubh)}(hdThis code was rewritten in 2008 and several times thereafter, but this still gives the general idea.h]hdThis code was rewritten in 2008 and several times thereafter, but this still gives the general idea.}(hj1hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjyhhubh)}(hjThe rcu_barrier_func() runs on each CPU, where it invokes call_rcu() to post an RCU callback, as follows::h]hiThe rcu_barrier_func() runs on each CPU, where it invokes call_rcu() to post an RCU callback, as follows:}(hj?hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjyhhubj )}(hX' 1 static void rcu_barrier_func(void *notused) 2 { 3 int cpu = smp_processor_id(); 4 struct rcu_data *rdp = &per_cpu(rcu_data, cpu); 5 struct rcu_head *head; 6 7 head = &rdp->barrier; 8 atomic_inc(&rcu_barrier_cpu_count); 9 call_rcu(head, rcu_barrier_callback); 10 }h]hX' 1 static void rcu_barrier_func(void *notused) 2 { 3 int cpu = smp_processor_id(); 4 struct rcu_data *rdp = &per_cpu(rcu_data, cpu); 5 struct rcu_head *head; 6 7 head = &rdp->barrier; 8 atomic_inc(&rcu_barrier_cpu_count); 9 call_rcu(head, rcu_barrier_callback); 10 }}hjMsbah}(h]h ]h"]h$]h&]jjuh1j hhhKhjyhhubh)}(hXrLines 3 and 4 locate RCU's internal per-CPU rcu_data structure, which contains the struct rcu_head that needed for the later call to call_rcu(). Line 7 picks up a pointer to this struct rcu_head, and line 8 increments the global counter. This counter will later be decremented by the callback. Line 9 then registers the rcu_barrier_callback() on the current CPU's queue.h]hXvLines 3 and 4 locate RCU’s internal per-CPU rcu_data structure, which contains the struct rcu_head that needed for the later call to call_rcu(). Line 7 picks up a pointer to this struct rcu_head, and line 8 increments the global counter. This counter will later be decremented by the callback. Line 9 then registers the rcu_barrier_callback() on the current CPU’s queue.}(hj[hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjyhhubh)}(hThe rcu_barrier_callback() function simply atomically decrements the rcu_barrier_cpu_count variable and finalizes the completion when it reaches zero, as follows::h]hThe rcu_barrier_callback() function simply atomically decrements the rcu_barrier_cpu_count variable and finalizes the completion when it reaches zero, as follows:}(hjihhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjyhhubj )}(h1 static void rcu_barrier_callback(struct rcu_head *notused) 2 { 3 if (atomic_dec_and_test(&rcu_barrier_cpu_count)) 4 complete(&rcu_barrier_completion); 5 }h]h1 static void rcu_barrier_callback(struct rcu_head *notused) 2 { 3 if (atomic_dec_and_test(&rcu_barrier_cpu_count)) 4 complete(&rcu_barrier_completion); 5 }}hjwsbah}(h]h ]h"]h$]h&]jjuh1j hhhMhjyhhubh)}(h.. _rcubarrier_quiz_3:h]h}(h]h ]h"]h$]h&]hrcubarrier-quiz-3uh1hhMhjyhhhhubj)}(hhh]j)}(hX Quick Quiz #3: What happens if CPU 0's rcu_barrier_func() executes immediately (thus incrementing rcu_barrier_cpu_count to the value one), but the other CPU's rcu_barrier_func() invocations are delayed for a full grace period? Couldn't this result in rcu_barrier() returning prematurely? h](j)}(hQuick Quiz #3:h]hQuick Quiz #3:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMhjubj)}(hhh]h)}(hXWhat happens if CPU 0's rcu_barrier_func() executes immediately (thus incrementing rcu_barrier_cpu_count to the value one), but the other CPU's rcu_barrier_func() invocations are delayed for a full grace period? Couldn't this result in rcu_barrier() returning prematurely?h]hXWhat happens if CPU 0’s rcu_barrier_func() executes immediately (thus incrementing rcu_barrier_cpu_count to the value one), but the other CPU’s rcu_barrier_func() invocations are delayed for a full grace period? Couldn’t this result in rcu_barrier() returning prematurely?}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhMhjubah}(h]jah ]h"]rcubarrier_quiz_3ah$]h&]uh1jhjyhhhhhNj}jjsj}jjsubh)}(h9:ref:`Answer to Quick Quiz #3 `h]h)}(hjh]j )}(hjh]hAnswer to Quick Quiz #3}(hjhhhNhNubah}(h]h ](jstdstd-refeh"]h$]h&]uh1j hjubah}(h]h ]h"]h$]h&]refdocj# refdomainjreftyperef refexplicitrefwarnj)answer_rcubarrier_quiz_3uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1hhhhMhjyhhubh)}(hXCThe current rcu_barrier() implementation is more complex, due to the need to avoid disturbing idle CPUs (especially on battery-powered systems) and the need to minimally disturb non-idle CPUs in real-time systems. In addition, a great many optimizations have been applied. However, the code above illustrates the concepts.h]hXCThe current rcu_barrier() implementation is more complex, due to the need to avoid disturbing idle CPUs (especially on battery-powered systems) and the need to minimally disturb non-idle CPUs in real-time systems. In addition, a great many optimizations have been applied. However, the code above illustrates the concepts.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjyhhubeh}(h]implementing-rcu-barrierah ]h"]implementing rcu_barrier()ah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hrcu_barrier() Summaryh]hrcu_barrier() Summary}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhMubh)}(hXThe rcu_barrier() primitive is used relatively infrequently, since most code using RCU is in the core kernel rather than in modules. However, if you are using RCU from an unloadable module, you need to use rcu_barrier() so that your module may be safely unloaded.h]hXThe rcu_barrier() primitive is used relatively infrequently, since most code using RCU is in the core kernel rather than in modules. However, if you are using RCU from an unloadable module, you need to use rcu_barrier() so that your module may be safely unloaded.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubeh}(h]rcu-barrier-summaryah ]h"]rcu_barrier() summaryah$]h&]uh1hhhhhhhhMubh)}(hhh](h)}(hAnswers to Quick Quizzesh]hAnswers to Quick Quizzes}(hj4hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj1hhhhhM#ubh)}(h.. _answer_rcubarrier_quiz_1:h]h}(h]h ]h"]h$]h&]hanswer-rcubarrier-quiz-1uh1hhM%hj1hhhhubj)}(hhh](j)}(hSQuick Quiz #1: Is there any other situation where rcu_barrier() might be required? h](j)}(hQuick Quiz #1:h]hQuick Quiz #1:}(hjThhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhM)hjPubj)}(hhh]h)}(hCIs there any other situation where rcu_barrier() might be required?h]hCIs there any other situation where rcu_barrier() might be required?}(hjehhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM(hjbubah}(h]h ]h"]h$]h&]uh1jhjPubeh}(h]h ]h"]h$]h&]uh1jhhhM)hjMubj)}(hXAnswer: Interestingly enough, rcu_barrier() was not originally implemented for module unloading. Nikita Danilov was using RCU in a filesystem, which resulted in a similar situation at filesystem-unmount time. Dipankar Sarma coded up rcu_barrier() in response, so that Nikita could invoke it during the filesystem-unmount process. Much later, yours truly hit the RCU module-unload problem when implementing rcutorture, and found that rcu_barrier() solves this problem as well. h](j)}(hAnswer:h]hAnswer:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhM5hjubj)}(hhh](h)}(hXAInterestingly enough, rcu_barrier() was not originally implemented for module unloading. Nikita Danilov was using RCU in a filesystem, which resulted in a similar situation at filesystem-unmount time. Dipankar Sarma coded up rcu_barrier() in response, so that Nikita could invoke it during the filesystem-unmount process.h]hXAInterestingly enough, rcu_barrier() was not originally implemented for module unloading. Nikita Danilov was using RCU in a filesystem, which resulted in a similar situation at filesystem-unmount time. Dipankar Sarma coded up rcu_barrier() in response, so that Nikita could invoke it during the filesystem-unmount process.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM,hjubh)}(hMuch later, yours truly hit the RCU module-unload problem when implementing rcutorture, and found that rcu_barrier() solves this problem as well.h]hMuch later, yours truly hit the RCU module-unload problem when implementing rcutorture, and found that rcu_barrier() solves this problem as well.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM3hjubeh}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhM5hjMhhubeh}(h]jLah ]h"]answer_rcubarrier_quiz_1ah$]h&]uh1jhj1hhhhhNj}jjBsj}jLjBsubh)}(h0:ref:`Back to Quick Quiz #1 `h]h)}(hjh]j )}(hjh]hBack to Quick Quiz #1}(hjhhhNhNubah}(h]h ](jstdstd-refeh"]h$]h&]uh1j hjubah}(h]h ]h"]h$]h&]refdocj# refdomainjreftyperef refexplicitrefwarnj)rcubarrier_quiz_1uh1hhhhM7hjubah}(h]h ]h"]h$]h&]uh1hhhhM7hj1hhubh)}(h.. _answer_rcubarrier_quiz_2:h]h}(h]h ]h"]h$]h&]hanswer-rcubarrier-quiz-2uh1hhM9hj1hhhhubj)}(hhh](j)}(hzQuick Quiz #2: Why doesn't line 8 initialize rcu_barrier_cpu_count to zero, thereby avoiding the need for lines 9 and 10? h](j)}(hQuick Quiz #2:h]hQuick Quiz #2:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhM=hjubj)}(hhh]h)}(hjWhy doesn't line 8 initialize rcu_barrier_cpu_count to zero, thereby avoiding the need for lines 9 and 10?h]hlWhy doesn’t line 8 initialize rcu_barrier_cpu_count to zero, thereby avoiding the need for lines 9 and 10?}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM<hjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhM=hjubj)}(hX1Answer: Suppose that the on_each_cpu() function shown on line 8 was delayed, so that CPU 0's rcu_barrier_func() executed and the corresponding grace period elapsed, all before CPU 1's rcu_barrier_func() started executing. This would result in rcu_barrier_cpu_count being decremented to zero, so that line 11's wait_for_completion() would return immediately, failing to wait for CPU 1's callbacks to be invoked. Note that this was not a problem when the rcu_barrier() code was first added back in 2005. This is because on_each_cpu() disables preemption, which acted as an RCU read-side critical section, thus preventing CPU 0's grace period from completing until on_each_cpu() had dealt with all of the CPUs. However, with the RCU flavor consolidation around v4.20, this possibility was once again ruled out, because the consolidated RCU once again waits on nonpreemptible regions of code. Nevertheless, that extra count might still be a good idea. Relying on these sort of accidents of implementation can result in later surprise bugs when the implementation changes. h](j)}(hAnswer:h]hAnswer:}(hj/hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMThj+ubj)}(hhh](h)}(hXSuppose that the on_each_cpu() function shown on line 8 was delayed, so that CPU 0's rcu_barrier_func() executed and the corresponding grace period elapsed, all before CPU 1's rcu_barrier_func() started executing. This would result in rcu_barrier_cpu_count being decremented to zero, so that line 11's wait_for_completion() would return immediately, failing to wait for CPU 1's callbacks to be invoked.h]hXSuppose that the on_each_cpu() function shown on line 8 was delayed, so that CPU 0’s rcu_barrier_func() executed and the corresponding grace period elapsed, all before CPU 1’s rcu_barrier_func() started executing. This would result in rcu_barrier_cpu_count being decremented to zero, so that line 11’s wait_for_completion() would return immediately, failing to wait for CPU 1’s callbacks to be invoked.}(hj@hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM@hj=ubh)}(hX)Note that this was not a problem when the rcu_barrier() code was first added back in 2005. This is because on_each_cpu() disables preemption, which acted as an RCU read-side critical section, thus preventing CPU 0's grace period from completing until on_each_cpu() had dealt with all of the CPUs.h]hX+Note that this was not a problem when the rcu_barrier() code was first added back in 2005. This is because on_each_cpu() disables preemption, which acted as an RCU read-side critical section, thus preventing CPU 0’s grace period from completing until on_each_cpu() had dealt with all of the CPUs.}(hjNhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMHhj=ubh)}(hHowever, with the RCU flavor consolidation around v4.20, this possibility was once again ruled out, because the consolidated RCU once again waits on nonpreemptible regions of code.h]hHowever, with the RCU flavor consolidation around v4.20, this possibility was once again ruled out, because the consolidated RCU once again waits on nonpreemptible regions of code.}(hj\hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMNhj=ubh)}(hNevertheless, that extra count might still be a good idea. Relying on these sort of accidents of implementation can result in later surprise bugs when the implementation changes.h]hNevertheless, that extra count might still be a good idea. Relying on these sort of accidents of implementation can result in later surprise bugs when the implementation changes.}(hjjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMRhj=ubeh}(h]h ]h"]h$]h&]uh1jhj+ubeh}(h]h ]h"]h$]h&]uh1jhhhMThjhhubeh}(h]jah ]h"]answer_rcubarrier_quiz_2ah$]h&]uh1jhj1hhhhhNj}jjsj}jjsubh)}(h0:ref:`Back to Quick Quiz #2 `h]h)}(hjh]j )}(hjh]hBack to Quick Quiz #2}(hjhhhNhNubah}(h]h ](jstdstd-refeh"]h$]h&]uh1j hjubah}(h]h ]h"]h$]h&]refdocj# refdomainjreftyperef refexplicitrefwarnj)rcubarrier_quiz_2uh1hhhhMVhjubah}(h]h ]h"]h$]h&]uh1hhhhMVhj1hhubh)}(h.. _answer_rcubarrier_quiz_3:h]h}(h]h ]h"]h$]h&]hanswer-rcubarrier-quiz-3uh1hhMXhj1hhhhubj)}(hhh](j)}(hX Quick Quiz #3: What happens if CPU 0's rcu_barrier_func() executes immediately (thus incrementing rcu_barrier_cpu_count to the value one), but the other CPU's rcu_barrier_func() invocations are delayed for a full grace period? Couldn't this result in rcu_barrier() returning prematurely? h](j)}(hQuick Quiz #3:h]hQuick Quiz #3:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhM_hjubj)}(hhh]h)}(hXWhat happens if CPU 0's rcu_barrier_func() executes immediately (thus incrementing rcu_barrier_cpu_count to the value one), but the other CPU's rcu_barrier_func() invocations are delayed for a full grace period? Couldn't this result in rcu_barrier() returning prematurely?h]hXWhat happens if CPU 0’s rcu_barrier_func() executes immediately (thus incrementing rcu_barrier_cpu_count to the value one), but the other CPU’s rcu_barrier_func() invocations are delayed for a full grace period? Couldn’t this result in rcu_barrier() returning prematurely?}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM[hjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhM_hjubj)}(hXAnswer: This cannot happen. The reason is that on_each_cpu() has its last argument, the wait flag, set to "1". This flag is passed through to smp_call_function() and further to smp_call_function_on_cpu(), causing this latter to spin until the cross-CPU invocation of rcu_barrier_func() has completed. This by itself would prevent a grace period from completing on non-CONFIG_PREEMPTION kernels, since each CPU must undergo a context switch (or other quiescent state) before the grace period can complete. However, this is of no use in CONFIG_PREEMPTION kernels. Therefore, on_each_cpu() disables preemption across its call to smp_call_function() and also across the local call to rcu_barrier_func(). Because recent RCU implementations treat preemption-disabled regions of code as RCU read-side critical sections, this prevents grace periods from completing. This means that all CPUs have executed rcu_barrier_func() before the first rcu_barrier_callback() can possibly execute, in turn preventing rcu_barrier_cpu_count from prematurely reaching zero. But if on_each_cpu() ever decides to forgo disabling preemption, as might well happen due to real-time latency considerations, initializing rcu_barrier_cpu_count to one will save the day. h](j)}(hAnswer:h]hAnswer:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMwhjubj)}(hhh](h)}(hX)This cannot happen. The reason is that on_each_cpu() has its last argument, the wait flag, set to "1". This flag is passed through to smp_call_function() and further to smp_call_function_on_cpu(), causing this latter to spin until the cross-CPU invocation of rcu_barrier_func() has completed. This by itself would prevent a grace period from completing on non-CONFIG_PREEMPTION kernels, since each CPU must undergo a context switch (or other quiescent state) before the grace period can complete. However, this is of no use in CONFIG_PREEMPTION kernels.h]hX-This cannot happen. The reason is that on_each_cpu() has its last argument, the wait flag, set to “1”. This flag is passed through to smp_call_function() and further to smp_call_function_on_cpu(), causing this latter to spin until the cross-CPU invocation of rcu_barrier_func() has completed. This by itself would prevent a grace period from completing on non-CONFIG_PREEMPTION kernels, since each CPU must undergo a context switch (or other quiescent state) before the grace period can complete. However, this is of no use in CONFIG_PREEMPTION kernels.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMbhjubh)}(hXTherefore, on_each_cpu() disables preemption across its call to smp_call_function() and also across the local call to rcu_barrier_func(). Because recent RCU implementations treat preemption-disabled regions of code as RCU read-side critical sections, this prevents grace periods from completing. This means that all CPUs have executed rcu_barrier_func() before the first rcu_barrier_callback() can possibly execute, in turn preventing rcu_barrier_cpu_count from prematurely reaching zero.h]hXTherefore, on_each_cpu() disables preemption across its call to smp_call_function() and also across the local call to rcu_barrier_func(). Because recent RCU implementations treat preemption-disabled regions of code as RCU read-side critical sections, this prevents grace periods from completing. This means that all CPUs have executed rcu_barrier_func() before the first rcu_barrier_callback() can possibly execute, in turn preventing rcu_barrier_cpu_count from prematurely reaching zero.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMlhjubh)}(hBut if on_each_cpu() ever decides to forgo disabling preemption, as might well happen due to real-time latency considerations, initializing rcu_barrier_cpu_count to one will save the day.h]hBut if on_each_cpu() ever decides to forgo disabling preemption, as might well happen due to real-time latency considerations, initializing rcu_barrier_cpu_count to one will save the day.}(hj$hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMuhjubeh}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhMwhjhhubeh}(h]jah ]h"]answer_rcubarrier_quiz_3ah$]h&]uh1jhj1hhhhhNj}jBjsj}jjsubh)}(h0:ref:`Back to Quick Quiz #3 `h]h)}(hjIh]j )}(hjIh]hBack to Quick Quiz #3}(hjNhhhNhNubah}(h]h ](jstdstd-refeh"]h$]h&]uh1j hjKubah}(h]h ]h"]h$]h&]refdocj# refdomainjXreftyperef refexplicitrefwarnj)rcubarrier_quiz_3uh1hhhhMyhjGubah}(h]h ]h"]h$]h&]uh1hhhhMyhj1hhubeh}(h]answers-to-quick-quizzesah ]h"]answers to quick quizzesah$]h&]uh1hhhhhhhhM#ubeh}(h](rcu-and-unloadable-modulesheh ]h"](rcu and unloadable modules rcu_barriereh$]h&]uh1hhhhhhhhKj}j~hsj}hhsubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_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_handlerjerror_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}refids}(h]haj]jaj]jaj]jajL]jBaj]jaj]jaunameids}(j~hj}jzjjjvjsjjjjjjjjj.j+jujrjjLjjjBju nametypes}(j~j}jjvjjjjj.jujjjBuh}(hhjzhjj:jsjjjjjyjjjjj+j jrj1jLjMjjjju footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}jKsRparse_messages]transform_messages](hsystem_message)}(hhh]h)}(hhh]h1Hyperlink target "rcu-barrier" is not referenced.}hjsbah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]levelKtypeINFOsourcehÌlineKuh1jubj)}(hhh]h)}(hhh]h7Hyperlink target "rcubarrier-quiz-1" is not referenced.}hj1sbah}(h]h ]h"]h$]h&]uh1hhj.ubah}(h]h ]h"]h$]h&]levelKtypej+sourcehÌlineKuh1jubj)}(hhh]h)}(hhh]h7Hyperlink target "rcubarrier-quiz-2" is not referenced.}hjKsbah}(h]h ]h"]h$]h&]uh1hhjHubah}(h]h ]h"]h$]h&]levelKtypej+sourcehÌlineKuh1jubj)}(hhh]h)}(hhh]h7Hyperlink target "rcubarrier-quiz-3" is not referenced.}hjesbah}(h]h ]h"]h$]h&]uh1hhjbubah}(h]h ]h"]h$]h&]levelKtypej+sourcehÌlineMuh1jubj)}(hhh]h)}(hhh]h>Hyperlink target "answer-rcubarrier-quiz-1" is not referenced.}hjsbah}(h]h ]h"]h$]h&]uh1hhj|ubah}(h]h ]h"]h$]h&]levelKtypej+sourcehÌlineM%uh1jubj)}(hhh]h)}(hhh]h>Hyperlink target "answer-rcubarrier-quiz-2" is not referenced.}hjsbah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]levelKtypej+sourcehÌlineM9uh1jubj)}(hhh]h)}(hhh]h>Hyperlink target "answer-rcubarrier-quiz-3" is not referenced.}hjsbah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]levelKtypej+sourcehÌlineMXuh1jube transformerN include_log] decorationNhhub.