Commit 869cc745 authored by Paul E. McKenney's avatar Paul E. McKenney
Browse files

doc: Update memory-ordering documentation for ->gp-seq 



Signed-off-by: default avatarPaul E. McKenney <paulmck@linux.vnet.ibm.com>
parent b1e1f21f

Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.html

+10 −12
Original line number Diff line number Diff line
@@ -357,7 +357,7 @@ parts, starting in this section with the various phases of 
grace-period initialization.



<p>The first ordering-related grace-period initialization action is to

increment the <tt>rcu_state</tt> structure's <tt>-&gt;gpnum</tt>

advance the <tt>rcu_state</tt> structure's <tt>-&gt;gp_seq</tt>

grace-period-number counter, as shown below:



</p><p><img src="TreeRCU-gp-init-1.svg" alt="TreeRCU-gp-init-1.svg" width="75%">
@@ -388,7 +388,7 @@ its last CPU and if the next <tt>rcu_node</tt> structure has no online CPUs). 


<p>The final <tt>rcu_gp_init()</tt> pass through the <tt>rcu_node</tt>

tree traverses breadth-first, setting each <tt>rcu_node</tt> structure's

<tt>-&gt;gpnum</tt> field to the newly incremented value from the

<tt>-&gt;gp_seq</tt> field to the newly advanced value from the

<tt>rcu_state</tt> structure, as shown in the following diagram.



</p><p><img src="TreeRCU-gp-init-3.svg" alt="TreeRCU-gp-init-1.svg" width="75%">
@@ -398,9 +398,9 @@ tree traverses breadth-first, setting each <tt>rcu_node</tt> structure's 
to notice that a new grace period has started, as described in the next

section.

But because the grace-period kthread started the grace period at the

root (with the increment of the <tt>rcu_state</tt> structure's

<tt>-&gt;gpnum</tt> field) before setting each leaf <tt>rcu_node</tt>

structure's <tt>-&gt;gpnum</tt> field, each CPU's observation of

root (with the advancing of the <tt>rcu_state</tt> structure's

<tt>-&gt;gp_seq</tt> field) before setting each leaf <tt>rcu_node</tt>

structure's <tt>-&gt;gp_seq</tt> field, each CPU's observation of

the start of the grace period will happen after the actual start

of the grace period.
@@ -466,7 +466,7 @@ section that the grace period must wait on. 
<tr><td>

	But a RCU read-side critical section might have started

	after the beginning of the grace period

	(the <tt>-&gt;gpnum++</tt> from earlier), so why should

	(the advancing of <tt>-&gt;gp_seq</tt> from earlier), so why should

	the grace period wait on such a critical section?

</td></tr>

<tr><th align="left">Answer:</th></tr>
@@ -609,10 +609,8 @@ states outstanding from other CPUs. 
<h4><a name="Grace-Period Cleanup">Grace-Period Cleanup</a></h4>



<p>Grace-period cleanup first scans the <tt>rcu_node</tt> tree

breadth-first setting all the <tt>-&gt;completed</tt> fields equal

to the number of the newly completed grace period, then it sets

the <tt>rcu_state</tt> structure's <tt>-&gt;completed</tt> field,

again to the number of the newly completed grace period.

breadth-first advancing all the <tt>-&gt;gp_seq</tt> fields, then it

advances the <tt>rcu_state</tt> structure's <tt>-&gt;gp_seq</tt> field.

The ordering effects are shown below:



</p><p><img src="TreeRCU-gp-cleanup.svg" alt="TreeRCU-gp-cleanup.svg" width="75%">
@@ -634,7 +632,7 @@ grace-period cleanup is complete, the next grace period can begin. 
	CPU has reported its quiescent state, but it may be some

	milliseconds before RCU becomes aware of this.

	The latest reasonable candidate is once the <tt>rcu_state</tt>

	structure's <tt>-&gt;completed</tt> field has been updated,

	structure's <tt>-&gt;gp_seq</tt> field has been updated,

	but it is quite possible that some CPUs have already completed

	phase two of their updates by that time.

	In short, if you are going to work with RCU, you need to
@@ -647,7 +645,7 @@ grace-period cleanup is complete, the next grace period can begin. 
<h4><a name="Callback Invocation">Callback Invocation</a></h4>



<p>Once a given CPU's leaf <tt>rcu_node</tt> structure's

<tt>-&gt;completed</tt> field has been updated, that CPU can begin

<tt>-&gt;gp_seq</tt> field has been updated, that CPU can begin

invoking its RCU callbacks that were waiting for this grace period

to end.

These callbacks are identified by <tt>rcu_advance_cbs()</tt>,

Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp-cleanup.svg

+65 −58
Original line number Diff line number Diff line
@@ -384,11 +384,11 @@ 
     inkscape:window-height="1144"

     id="namedview208"

     showgrid="true"

     inkscape:zoom="0.70710678"

     inkscape:cx="617.89017"

     inkscape:cy="542.52419"

     inkscape:window-x="86"

     inkscape:window-y="28"

     inkscape:zoom="0.78716603"

     inkscape:cx="513.06403"

     inkscape:cy="623.1214"

     inkscape:window-x="102"

     inkscape:window-y="38"

     inkscape:window-maximized="0"

     inkscape:current-layer="g3188-3"

     fit-margin-top="5"
@@ -417,13 +417,15 @@ 
     id="g3188">

    <text

       xml:space="preserve"

       x="3199.1516"

       x="3145.9592"

       y="13255.592"

       font-style="normal"

       font-weight="bold"

       font-size="192"

       id="text202"

       style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;font-family:Courier">-&gt;completed = -&gt;gpnum</text>

       style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;font-family:Courier"><tspan

         style="font-size:172.87567139px"

         id="tspan3143">rcu_seq_end(&amp;rnp-&gt;gp_seq)</tspan></text>

    <g

       id="g3107"

       transform="translate(947.90548,11584.029)">
@@ -502,13 +504,15 @@ 
    </g>

    <text

       xml:space="preserve"

       x="5324.5371"

       y="15414.598"

       x="5264.4731"

       y="15428.84"

       font-style="normal"

       font-weight="bold"

       font-size="192"

       id="text202-753"

       style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;completed = -&gt;gpnum</text>

       id="text202-36-7"

       style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"><tspan

         style="font-size:172.87567139px"

         id="tspan3166-5">rcu_seq_end(&amp;rnp-&gt;gp_seq)</tspan></text>

  </g>

  <g

     style="fill:none;stroke-width:0.025in"
@@ -547,15 +551,6 @@ 
       sodipodi:linespacing="125%"><tspan

         style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"

         id="tspan3104-6-5-6-0">Leaf</tspan></text>

    <text

       xml:space="preserve"

       x="7479.5796"

       y="17699.943"

       font-style="normal"

       font-weight="bold"

       font-size="192"

       id="text202-9"

       style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;completed = -&gt;gpnum</text>

    <path

       sodipodi:nodetypes="cc"

       inkscape:connector-curvature="0"
@@ -566,15 +561,6 @@ 
       style="fill:none;stroke-width:0.025in"

       transform="translate(-737.93887,7732.6672)"

       id="g3188-3">

      <text

         xml:space="preserve"

         x="3225.7478"

         y="13175.802"

         font-style="normal"

         font-weight="bold"

         font-size="192"

         id="text202-60"

         style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;font-family:Courier">rsp-&gt;completed =</text>

      <g

         id="g3107-62"

         transform="translate(947.90548,11584.029)">
@@ -607,15 +593,6 @@ 
         sodipodi:linespacing="125%"><tspan

           style="font-size:159.57754517px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;writing-mode:lr-tb;text-anchor:start;font-family:Liberation Sans;-inkscape-font-specification:Liberation Sans"

           id="tspan3104-6-5-7">Root</tspan></text>

      <text

         xml:space="preserve"

         x="3225.7478"

         y="13390.038"

         font-style="normal"

         font-weight="bold"

         font-size="192"

         id="text202-60-3"

         style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">       rnp-&gt;completed</text>

      <flowRoot

         xml:space="preserve"

         id="flowRoot3356"
@@ -627,7 +604,18 @@ 
             height="63.63961"

             x="332.34018"

             y="681.87292" /></flowRegion><flowPara

           id="flowPara3362" /></flowRoot>    </g>

           id="flowPara3362" /></flowRoot>      <text

         xml:space="preserve"

         x="3156.6121"

         y="13317.754"

         font-style="normal"

         font-weight="bold"

         font-size="192"

         id="text202-36-6"

         style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"><tspan

           style="font-size:172.87567139px"

           id="tspan3166-0">rcu_seq_end(&amp;rsp-&gt;gp_seq)</tspan></text>

    </g>

    <g

       style="fill:none;stroke-width:0.025in"

       transform="translate(-858.40227,7769.0342)"
@@ -859,6 +847,17 @@ 
       id="path3414-8-3-6-6"

       inkscape:connector-curvature="0"

       sodipodi:nodetypes="cc" />

    <text

       xml:space="preserve"

       x="7418.769"

       y="17646.104"

       font-style="normal"

       font-weight="bold"

       font-size="192"

       id="text202-36-70"

       style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"><tspan

         style="font-size:172.87567139px"

         id="tspan3166-93">rcu_seq_end(&amp;rnp-&gt;gp_seq)</tspan></text>

  </g>

  <g

     transform="translate(-1642.5377,-11611.245)"
@@ -887,13 +886,15 @@ 
    </g>

    <text

       xml:space="preserve"

       x="5327.3057"

       x="5274.1133"

       y="15428.84"

       font-style="normal"

       font-weight="bold"

       font-size="192"

       id="text202-36"

       style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;completed = -&gt;gpnum</text>

       style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"><tspan

         style="font-size:172.87567139px"

         id="tspan3166">rcu_seq_end(&amp;rnp-&gt;gp_seq)</tspan></text>

  </g>

  <g

     transform="translate(-151.71746,-11647.612)"
@@ -972,13 +973,15 @@ 
         id="tspan3104-6-5-6-0-92">Leaf</tspan></text>

    <text

       xml:space="preserve"

       x="7486.4907"

       y="17670.119"

       x="7408.5918"

       y="17619.504"

       font-style="normal"

       font-weight="bold"

       font-size="192"

       id="text202-6"

       style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;completed = -&gt;gpnum</text>

       id="text202-36-2"

       style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"><tspan

         style="font-size:172.87567139px"

         id="tspan3166-9">rcu_seq_end(&amp;rnp-&gt;gp_seq)</tspan></text>

  </g>

  <g

     transform="translate(-6817.1997,-11647.612)"
@@ -1019,13 +1022,15 @@ 
         id="tspan3104-6-5-6-0-1">Leaf</tspan></text>

    <text

       xml:space="preserve"

       x="7474.1382"

       y="17688.926"

       x="7416.8003"

       y="17619.504"

       font-style="normal"

       font-weight="bold"

       font-size="192"

       id="text202-5"

       style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;completed = -&gt;gpnum</text>

       id="text202-36-3"

       style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"><tspan

         style="font-size:172.87567139px"

         id="tspan3166-56">rcu_seq_end(&amp;rnp-&gt;gp_seq)</tspan></text>

  </g>

  <path

     style="fill:none;stroke:#000000;stroke-width:13.29812908px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
@@ -1059,15 +1064,6 @@ 
     id="path3414-8-3-6"

     inkscape:connector-curvature="0"

     sodipodi:nodetypes="cc" />

  <text

     xml:space="preserve"

     x="7318.9653"

     y="6031.6353"

     font-style="normal"

     font-weight="bold"

     font-size="192"

     id="text202-2"

     style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;completed = -&gt;gpnum</text>

  <g

     style="fill:none;stroke-width:0.025in"

     id="g4504-3-9"
@@ -1123,4 +1119,15 @@ 
     id="path3134-9-0-3-5"

     d="m 6875.6003,15833.906 1595.7755,0"

     style="fill:none;stroke:#969696;stroke-width:53.19251633;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Send-36)" />

  <text

     xml:space="preserve"

     x="7275.2612"

     y="5971.8916"

     font-style="normal"

     font-weight="bold"

     font-size="192"

     id="text202-36-1"

     style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier"><tspan

       style="font-size:172.87567139px"

       id="tspan3166-2">rcu_seq_end(&amp;rnp-&gt;gp_seq)</tspan></text>

</svg>

Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp-init-1.svg

+9 −7
Original line number Diff line number Diff line
@@ -272,13 +272,13 @@ 
     inkscape:window-height="1144"

     id="namedview208"

     showgrid="true"

     inkscape:zoom="0.70710678"

     inkscape:cx="617.89019"

     inkscape:cy="636.57143"

     inkscape:window-x="697"

     inkscape:zoom="2.6330492"

     inkscape:cx="524.82797"

     inkscape:cy="519.31194"

     inkscape:window-x="79"

     inkscape:window-y="28"

     inkscape:window-maximized="0"

     inkscape:current-layer="svg2"

     inkscape:current-layer="g3188"

     fit-margin-top="5"

     fit-margin-right="5"

     fit-margin-left="5"
@@ -305,13 +305,15 @@ 
     id="g3188">

    <text

       xml:space="preserve"

       x="3305.5364"

       x="3119.363"

       y="13255.592"

       font-style="normal"

       font-weight="bold"

       font-size="192"

       id="text202"

       style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;font-family:Courier">rsp-&gt;gpnum++</text>

       style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;font-family:Courier"><tspan

         style="font-size:172.87567139px"

         id="tspan3071">rcu_seq_start(rsp-&gt;gp_seq)</tspan></text>

    <g

       id="g3107"

       transform="translate(947.90548,11584.029)">

Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp-init-3.svg

+30 −26
Original line number Diff line number Diff line
@@ -19,7 +19,7 @@ 
   id="svg2"

   version="1.1"

   inkscape:version="0.48.4 r9939"

   sodipodi:docname="TreeRCU-gp-init-2.svg">

   sodipodi:docname="TreeRCU-gp-init-3.svg">

  <metadata

     id="metadata212">

    <rdf:RDF>
@@ -257,18 +257,22 @@ 
     inkscape:window-width="1087"

     inkscape:window-height="1144"

     id="namedview208"

     showgrid="false"

     inkscape:zoom="0.70710678"

     showgrid="true"

     inkscape:zoom="0.68224756"

     inkscape:cx="617.89019"

     inkscape:cy="625.84293"

     inkscape:window-x="697"

     inkscape:window-x="54"

     inkscape:window-y="28"

     inkscape:window-maximized="0"

     inkscape:current-layer="svg2"

     inkscape:current-layer="g3153"

     fit-margin-top="5"

     fit-margin-right="5"

     fit-margin-left="5"

     fit-margin-bottom="5" />

     fit-margin-bottom="5">

    <inkscape:grid

       type="xygrid"

       id="grid3090" />

  </sodipodi:namedview>

  <path

     sodipodi:nodetypes="cccccccccccccccccccccccc"

     inkscape:connector-curvature="0"
@@ -281,13 +285,13 @@ 
     id="g3188">

    <text

       xml:space="preserve"

       x="3305.5364"

       x="3145.9592"

       y="13255.592"

       font-style="normal"

       font-weight="bold"

       font-size="192"

       id="text202"

       style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;font-family:Courier">-&gt;gpnum = rsp-&gt;gpnum</text>

       style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;font-family:Courier">-&gt;gp_seq = rsp-&gt;gp_seq</text>

    <g

       id="g3107"

       transform="translate(947.90548,11584.029)">
@@ -366,13 +370,13 @@ 
    </g>

    <text

       xml:space="preserve"

       x="5392.3345"

       y="15407.104"

       x="5253.6904"

       y="15407.032"

       font-style="normal"

       font-weight="bold"

       font-size="192"

       id="text202-6"

       style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;gpnum = rsp-&gt;gpnum</text>

       style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;gp_seq = rsp-&gt;gp_seq</text>

  </g>

  <g

     style="fill:none;stroke-width:0.025in"
@@ -413,13 +417,13 @@ 
         id="tspan3104-6-5-6-0">Leaf</tspan></text>

    <text

       xml:space="preserve"

       x="7536.4883"

       y="17640.934"

       x="7415.4365"

       y="17670.572"

       font-style="normal"

       font-weight="bold"

       font-size="192"

       id="text202-9"

       style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;gpnum = rsp-&gt;gpnum</text>

       style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;gp_seq = rsp-&gt;gp_seq</text>

  </g>

  <g

     transform="translate(-1642.5375,-11610.962)"
@@ -448,13 +452,13 @@ 
    </g>

    <text

       xml:space="preserve"

       x="5378.4146"

       y="15436.927"

       x="5258.0688"

       y="15412.313"

       font-style="normal"

       font-weight="bold"

       font-size="192"

       id="text202-3"

       style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;gpnum = rsp-&gt;gpnum</text>

       style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;gp_seq = rsp-&gt;gp_seq</text>

  </g>

  <g

     transform="translate(-151.71726,-11647.329)"
@@ -533,13 +537,13 @@ 
         id="tspan3104-6-5-6-0-92">Leaf</tspan></text>

    <text

       xml:space="preserve"

       x="7520.1294"

       y="17673.639"

       x="7405.2607"

       y="17670.572"

       font-style="normal"

       font-weight="bold"

       font-size="192"

       id="text202-35"

       style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;gpnum = rsp-&gt;gpnum</text>

       style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;gp_seq = rsp-&gt;gp_seq</text>

  </g>

  <g

     transform="translate(-6817.1998,-11647.329)"
@@ -580,13 +584,13 @@ 
         id="tspan3104-6-5-6-0-1">Leaf</tspan></text>

    <text

       xml:space="preserve"

       x="7521.4663"

       y="17666.062"

       x="7413.4688"

       y="17670.566"

       font-style="normal"

       font-weight="bold"

       font-size="192"

       id="text202-75"

       style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;gpnum = rsp-&gt;gpnum</text>

       style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;gp_seq = rsp-&gt;gp_seq</text>

  </g>

  <path

     style="fill:none;stroke:#000000;stroke-width:13.29812908px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Lend)"
@@ -622,11 +626,11 @@ 
     sodipodi:nodetypes="cc" />

  <text

     xml:space="preserve"

     x="7370.856"

     y="5997.5972"

     x="7271.9297"

     y="6023.2412"

     font-style="normal"

     font-weight="bold"

     font-size="192"

     id="text202-62"

     style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;gpnum = rsp-&gt;gpnum</text>

     style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">-&gt;gp_seq = rsp-&gt;gp_seq</text>

</svg>

Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp.svg

+123 −114

File changed.

Preview size limit exceeded, changes collapsed.