LCOV - code coverage report
Current view: top level - include/linux - rcupdate.h (source / functions) Hit Total Coverage
Test: coverage.info Lines: 2 2 100.0 %
Date: 2017-01-25 Functions: 1 1 100.0 %

          Line data    Source code
       1             : /*
       2             :  * Read-Copy Update mechanism for mutual exclusion
       3             :  *
       4             :  * This program is free software; you can redistribute it and/or modify
       5             :  * it under the terms of the GNU General Public License as published by
       6             :  * the Free Software Foundation; either version 2 of the License, or
       7             :  * (at your option) any later version.
       8             :  *
       9             :  * This program is distributed in the hope that it will be useful,
      10             :  * but WITHOUT ANY WARRANTY; without even the implied warranty of
      11             :  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
      12             :  * GNU General Public License for more details.
      13             :  *
      14             :  * You should have received a copy of the GNU General Public License
      15             :  * along with this program; if not, write to the Free Software
      16             :  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
      17             :  *
      18             :  * Copyright IBM Corporation, 2001
      19             :  *
      20             :  * Author: Dipankar Sarma <dipankar@in.ibm.com>
      21             :  *
      22             :  * Based on the original work by Paul McKenney <paulmck@us.ibm.com>
      23             :  * and inputs from Rusty Russell, Andrea Arcangeli and Andi Kleen.
      24             :  * Papers:
      25             :  * http://www.rdrop.com/users/paulmck/paper/rclockpdcsproof.pdf
      26             :  * http://lse.sourceforge.net/locking/rclock_OLS.2001.05.01c.sc.pdf (OLS2001)
      27             :  *
      28             :  * For detailed explanation of Read-Copy Update mechanism see -
      29             :  *              http://lse.sourceforge.net/locking/rcupdate.html
      30             :  *
      31             :  */
      32             : 
      33             : #ifndef __LINUX_RCUPDATE_H
      34             : #define __LINUX_RCUPDATE_H
      35             : 
      36             : #include <linux/cache.h>
      37             : #include <linux/spinlock.h>
      38             : #include <linux/threads.h>
      39             : #include <linux/cpumask.h>
      40             : #include <linux/seqlock.h>
      41             : #include <linux/lockdep.h>
      42             : #include <linux/completion.h>
      43             : 
      44             : /**
      45             :  * struct rcu_head - callback structure for use with RCU
      46             :  * @next: next update requests in a list
      47             :  * @func: actual update function to call after the grace period.
      48             :  */
      49             : struct rcu_head {
      50             :         struct rcu_head *next;
      51             :         void (*func)(struct rcu_head *head);
      52             : };
      53             : 
      54             : /* Exported common interfaces */
      55             : extern void synchronize_rcu_bh(void);
      56             : extern void synchronize_sched(void);
      57             : extern void rcu_barrier(void);
      58             : extern void rcu_barrier_bh(void);
      59             : extern void rcu_barrier_sched(void);
      60             : extern void synchronize_sched_expedited(void);
      61             : extern int sched_expedited_torture_stats(char *page);
      62             : 
      63             : /* Internal to kernel */
      64             : extern void rcu_init(void);
      65             : 
      66             : #if defined(CONFIG_TREE_RCU) || defined(CONFIG_TREE_PREEMPT_RCU)
      67             : #include <linux/rcutree.h>
      68             : #elif defined(CONFIG_TINY_RCU)
      69             : #include <linux/rcutiny.h>
      70             : #else
      71             : #error "Unknown RCU implementation specified to kernel configuration"
      72             : #endif
      73             : 
      74             : #define RCU_HEAD_INIT   { .next = NULL, .func = NULL }
      75             : #define RCU_HEAD(head) struct rcu_head head = RCU_HEAD_INIT
      76             : #define INIT_RCU_HEAD(ptr) do { \
      77             :        (ptr)->next = NULL; (ptr)->func = NULL; \
      78             : } while (0)
      79             : 
      80             : #ifdef CONFIG_DEBUG_LOCK_ALLOC
      81             : extern struct lockdep_map rcu_lock_map;
      82             : # define rcu_read_acquire()     \
      83             :                         lock_acquire(&rcu_lock_map, 0, 0, 2, 1, NULL, _THIS_IP_)
      84             : # define rcu_read_release()     lock_release(&rcu_lock_map, 1, _THIS_IP_)
      85             : #else
      86             : # define rcu_read_acquire()     do { } while (0)
      87             : # define rcu_read_release()     do { } while (0)
      88             : #endif
      89             : 
      90             : /**
      91             :  * rcu_read_lock - mark the beginning of an RCU read-side critical section.
      92             :  *
      93             :  * When synchronize_rcu() is invoked on one CPU while other CPUs
      94             :  * are within RCU read-side critical sections, then the
      95             :  * synchronize_rcu() is guaranteed to block until after all the other
      96             :  * CPUs exit their critical sections.  Similarly, if call_rcu() is invoked
      97             :  * on one CPU while other CPUs are within RCU read-side critical
      98             :  * sections, invocation of the corresponding RCU callback is deferred
      99             :  * until after the all the other CPUs exit their critical sections.
     100             :  *
     101             :  * Note, however, that RCU callbacks are permitted to run concurrently
     102             :  * with RCU read-side critical sections.  One way that this can happen
     103             :  * is via the following sequence of events: (1) CPU 0 enters an RCU
     104             :  * read-side critical section, (2) CPU 1 invokes call_rcu() to register
     105             :  * an RCU callback, (3) CPU 0 exits the RCU read-side critical section,
     106             :  * (4) CPU 2 enters a RCU read-side critical section, (5) the RCU
     107             :  * callback is invoked.  This is legal, because the RCU read-side critical
     108             :  * section that was running concurrently with the call_rcu() (and which
     109             :  * therefore might be referencing something that the corresponding RCU
     110             :  * callback would free up) has completed before the corresponding
     111             :  * RCU callback is invoked.
     112             :  *
     113             :  * RCU read-side critical sections may be nested.  Any deferred actions
     114             :  * will be deferred until the outermost RCU read-side critical section
     115             :  * completes.
     116             :  *
     117             :  * It is illegal to block while in an RCU read-side critical section.
     118             :  */
     119             : static inline void rcu_read_lock(void)
     120             : {
     121         254 :         __rcu_read_lock();
     122             :         __acquire(RCU);
     123         127 :         rcu_read_acquire();
     124             : }
     125             : 
     126             : /*
     127             :  * So where is rcu_write_lock()?  It does not exist, as there is no
     128             :  * way for writers to lock out RCU readers.  This is a feature, not
     129             :  * a bug -- this property is what provides RCU's performance benefits.
     130             :  * Of course, writers must coordinate with each other.  The normal
     131             :  * spinlock primitives work well for this, but any other technique may be
     132             :  * used as well.  RCU does not care how the writers keep out of each
     133             :  * others' way, as long as they do so.
     134             :  */
     135             : 
     136             : /**
     137             :  * rcu_read_unlock - marks the end of an RCU read-side critical section.
     138             :  *
     139             :  * See rcu_read_lock() for more information.
     140             :  */
     141             : static inline void rcu_read_unlock(void)
     142             : {
     143             :         rcu_read_release();
     144             :         __release(RCU);
     145             :         __rcu_read_unlock();
     146             : }
     147             : 
     148             : /**
     149             :  * rcu_read_lock_bh - mark the beginning of a softirq-only RCU critical section
     150             :  *
     151             :  * This is equivalent of rcu_read_lock(), but to be used when updates
     152             :  * are being done using call_rcu_bh(). Since call_rcu_bh() callbacks
     153             :  * consider completion of a softirq handler to be a quiescent state,
     154             :  * a process in RCU read-side critical section must be protected by
     155             :  * disabling softirqs. Read-side critical sections in interrupt context
     156             :  * can use just rcu_read_lock().
     157             :  *
     158             :  */
     159             : static inline void rcu_read_lock_bh(void)
     160             : {
     161             :         __rcu_read_lock_bh();
     162             :         __acquire(RCU_BH);
     163             :         rcu_read_acquire();
     164             : }
     165             : 
     166             : /*
     167             :  * rcu_read_unlock_bh - marks the end of a softirq-only RCU critical section
     168             :  *
     169             :  * See rcu_read_lock_bh() for more information.
     170             :  */
     171             : static inline void rcu_read_unlock_bh(void)
     172             : {
     173             :         rcu_read_release();
     174             :         __release(RCU_BH);
     175             :         __rcu_read_unlock_bh();
     176             : }
     177             : 
     178             : /**
     179             :  * rcu_read_lock_sched - mark the beginning of a RCU-classic critical section
     180             :  *
     181             :  * Should be used with either
     182             :  * - synchronize_sched()
     183             :  * or
     184             :  * - call_rcu_sched() and rcu_barrier_sched()
     185             :  * on the write-side to insure proper synchronization.
     186             :  */
     187             : static inline void rcu_read_lock_sched(void)
     188             : {
     189             :         preempt_disable();
     190             :         __acquire(RCU_SCHED);
     191             :         rcu_read_acquire();
     192             : }
     193             : 
     194             : /* Used by lockdep and tracing: cannot be traced, cannot call lockdep. */
     195             : static inline notrace void rcu_read_lock_sched_notrace(void)
     196             : {
     197             :         preempt_disable_notrace();
     198             :         __acquire(RCU_SCHED);
     199             : }
     200             : 
     201             : /*
     202             :  * rcu_read_unlock_sched - marks the end of a RCU-classic critical section
     203             :  *
     204             :  * See rcu_read_lock_sched for more information.
     205             :  */
     206             : static inline void rcu_read_unlock_sched(void)
     207             : {
     208             :         rcu_read_release();
     209             :         __release(RCU_SCHED);
     210             :         preempt_enable();
     211             : }
     212             : 
     213             : /* Used by lockdep and tracing: cannot be traced, cannot call lockdep. */
     214             : static inline notrace void rcu_read_unlock_sched_notrace(void)
     215             : {
     216             :         __release(RCU_SCHED);
     217             :         preempt_enable_notrace();
     218             : }
     219             : 
     220             : 
     221             : /**
     222             :  * rcu_dereference - fetch an RCU-protected pointer in an
     223             :  * RCU read-side critical section.  This pointer may later
     224             :  * be safely dereferenced.
     225             :  *
     226             :  * Inserts memory barriers on architectures that require them
     227             :  * (currently only the Alpha), and, more importantly, documents
     228             :  * exactly which pointers are protected by RCU.
     229             :  */
     230             : 
     231             : #define rcu_dereference(p)     ({ \
     232             :                                 typeof(p) _________p1 = ACCESS_ONCE(p); \
     233             :                                 smp_read_barrier_depends(); \
     234             :                                 (_________p1); \
     235             :                                 })
     236             : 
     237             : /**
     238             :  * rcu_assign_pointer - assign (publicize) a pointer to a newly
     239             :  * initialized structure that will be dereferenced by RCU read-side
     240             :  * critical sections.  Returns the value assigned.
     241             :  *
     242             :  * Inserts memory barriers on architectures that require them
     243             :  * (pretty much all of them other than x86), and also prevents
     244             :  * the compiler from reordering the code that initializes the
     245             :  * structure after the pointer assignment.  More importantly, this
     246             :  * call documents which pointers will be dereferenced by RCU read-side
     247             :  * code.
     248             :  */
     249             : 
     250             : #define rcu_assign_pointer(p, v) \
     251             :         ({ \
     252             :                 if (!__builtin_constant_p(v) || \
     253             :                     ((v) != NULL)) \
     254             :                         smp_wmb(); \
     255             :                 (p) = (v); \
     256             :         })
     257             : 
     258             : /* Infrastructure to implement the synchronize_() primitives. */
     259             : 
     260             : struct rcu_synchronize {
     261             :         struct rcu_head head;
     262             :         struct completion completion;
     263             : };
     264             : 
     265             : extern void wakeme_after_rcu(struct rcu_head  *head);
     266             : 
     267             : /**
     268             :  * call_rcu - Queue an RCU callback for invocation after a grace period.
     269             :  * @head: structure to be used for queueing the RCU updates.
     270             :  * @func: actual update function to be invoked after the grace period
     271             :  *
     272             :  * The update function will be invoked some time after a full grace
     273             :  * period elapses, in other words after all currently executing RCU
     274             :  * read-side critical sections have completed.  RCU read-side critical
     275             :  * sections are delimited by rcu_read_lock() and rcu_read_unlock(),
     276             :  * and may be nested.
     277             :  */
     278             : extern void call_rcu(struct rcu_head *head,
     279             :                               void (*func)(struct rcu_head *head));
     280             : 
     281             : /**
     282             :  * call_rcu_bh - Queue an RCU for invocation after a quicker grace period.
     283             :  * @head: structure to be used for queueing the RCU updates.
     284             :  * @func: actual update function to be invoked after the grace period
     285             :  *
     286             :  * The update function will be invoked some time after a full grace
     287             :  * period elapses, in other words after all currently executing RCU
     288             :  * read-side critical sections have completed. call_rcu_bh() assumes
     289             :  * that the read-side critical sections end on completion of a softirq
     290             :  * handler. This means that read-side critical sections in process
     291             :  * context must not be interrupted by softirqs. This interface is to be
     292             :  * used when most of the read-side critical sections are in softirq context.
     293             :  * RCU read-side critical sections are delimited by :
     294             :  *  - rcu_read_lock() and  rcu_read_unlock(), if in interrupt context.
     295             :  *  OR
     296             :  *  - rcu_read_lock_bh() and rcu_read_unlock_bh(), if in process context.
     297             :  *  These may be nested.
     298             :  */
     299             : extern void call_rcu_bh(struct rcu_head *head,
     300             :                         void (*func)(struct rcu_head *head));
     301             : 
     302             : #endif /* __LINUX_RCUPDATE_H */

Generated by: LCOV version 1.10