Review thread synch and the Arm memory model Learning Path

Author: jasonrandrews

content/learning-paths/servers-and-cloud-computing/memory_consistency/_index.md

@@ -1,19 +1,19 @@
 ---
-title: Explore Thread Synchronization in the Arm Memory Model
+title: Explore Thread Synchronization in the Arm memory model
 
 minutes_to_complete: 150
 
 who_is_this_for: This is an advanced topic for developers seeking practical ways to test thread synchronization approaches in the Arm memory model.
 
 learning_objectives:
-    - Test thread synchronization assembly snippets against the formal definition of the Arm Memory Model.
+    - Test thread synchronization assembly snippets against the formal definition of the Arm memory model.
     - Test thread synchronization assembly snippets on Arm hardware.
     - Compare the results of different thread synchronization approaches. 
 
 prerequisites:
     - An understanding of memory consistency models (such as Sequential Consistency, Weak Ordering, Relaxed Consistency, and Processor Consistency).
     - An understanding of thread synchronization.
-    - Familiarity with Arm Assembly Language, and the ability to find relevant information on Arm assembly instructions.
+    - Familiarity with Arm assembly language, and the ability to find relevant information on Arm assembly instructions.
     - Familiarity with general-purpose registers.
     - Familiarity with memory barriers, including Acquire-Release Semantics.
 
@@ -27,6 +27,7 @@ armips:
 operatingsystems:
     - Linux
 tools_software_languages:
+    - Runbook
     - Herd7
     - Litmus7
     - Arm ISA

content/learning-paths/servers-and-cloud-computing/memory_consistency/arm_mem_model.md

@@ -8,7 +8,7 @@ layout: "learningpathall"
 
 Most developers don't need deep knowledge of a CPU's memory consistency model. Programming languages and runtimes abstract the CPU’s model by providing their own memory ordering rules, synchronization constructs, and libraries. As long as the developer uses these correctly, compilers and runtime engines ensure that the code executes correctly on any CPU - whether its memory ordering is strong or weak.
 
-That said, developers might want to dig deeper into this topic for various reasons including:
+Developers might want to dig deeper into this topic for various reasons including:
 
 - Extracting additional performance from weakly-ordered CPUs, such as Arm CPUs:
   - Although compilers and runtimes typically do a good job of maximizing performance, manual tuning in well understood niche cases might provide further improvements. In most cases, all it takes to improve performance is using latest compilers, compiler switches, and runtimes.
@@ -81,7 +81,7 @@ litmus7 --help
 
 The input to both `herd7` and `litmus7` tools are snippets of assembly code, called litmus tests.
 
-Shown below are some example of running the tools with a litmus test. In the next section, you will go through an actual litmus test example.
+Shown below are some example of running the tools with a litmus test. 
 
 Run herd7 with a litmus test:
 ```
@@ -107,3 +107,5 @@ Run litmus7 with GCC emitting atomic instructions as required by the litmus test
 ```
 litmus7 ./test.litmus -ccopts="-mcpu=native"
 ```
+
+Continue to the next section to learn about a litmus test example. 

content/learning-paths/servers-and-cloud-computing/memory_consistency/examples.md

@@ -302,7 +302,7 @@ Histogram (1 states)
 
 Both `herd7` and `litmus7` show the expected result. It might be worth increasing the number of iterations on `litmus7` to build more confidence in the result.
 
-Now lets remove the load-acquire in `P1` and use a dependency as a barrier. Create a new litmus file `test6.litmus` with the contents shown below:
+Now remove the load-acquire in `P1` and use a dependency as a barrier. Create a new litmus file `test6.litmus` with the contents shown below:
 
 ```
 AArch64 MP+Loop+Dep

content/learning-paths/servers-and-cloud-computing/memory_consistency/explore_deeper.md

@@ -25,7 +25,7 @@ The [diy7 documentation](https://diy.inria.fr/doc/index.html) also provides link
 
 - [Barriers on Armv8](https://developer.arm.com/documentation/100941/0101/Barriers).
 - [Load-Acquire and Store-Release on Armv8](https://developer.arm.com/documentation/102336/0100/Load-Acquire-and-Store-Release-instructions).
-- [Barrier Litmus Tests and Cookbook](https://developer.arm.com/documentation/genc007826/latest). This was written during the Armv7 days, but it still has relevance.
+- [Barrier Litmus Tests and Cookbook](https://developer.arm.com/documentation/genc007826/latest). This was written in 2009, but is still relevant.
 
 ## More Tests to Explore
 

content/learning-paths/servers-and-cloud-computing/memory_consistency/litmus_syntax.md

@@ -138,7 +138,7 @@ Positive: 1 Negative: 3
 ```
 Outcome `(1,0)` is observed when testing against the Arm memory model, as indicated by the positive witness on the test condition. This result demonstrates that the Arm memory model violates Sequential Consistency. 
 
-The Arm memory model tends to be considered a Relaxed Consistency model, which means that it is possible for an Arm CPU in the real world to use ordering rules that are stronger than Relaxed Consistency. Going stronger on the memory model will not violate the Arm ordering rules. A stronger memory model means that there might be less opportunity for hardware-based optimizations, it will not affect the correctness of code execution - assuming there are no bugs in the code. That said, you can think of all Arm Neoverse CPUs as following a Relaxed Consistency model, which means that acquire-release ordering is supported.
+The Arm memory model tends to be considered a Relaxed Consistency model, which means that it is possible for an Arm CPU in the real world to use ordering rules that are stronger than Relaxed Consistency. Going stronger on the memory model will not violate the Arm ordering rules. A stronger memory model means that there might be less opportunity for hardware-based optimizations, it will not affect the correctness of code execution - assuming there are no bugs in the code. You can think of all Arm Neoverse CPUs as following a Relaxed Consistency model, which means that acquire-release ordering is supported.
 
 In a Release Consistency model, ordinary memory accesses like `STR` and `LDR` do not need to follow program order. This relaxation in the ordering rules expands the list of instruction permutations in the litmus test above. It is these additional instruction permutations allowed by the Relaxed Consistency model that yield at least one permutation that results in `(1,0)`. Below is one such example of a permutation. For this permutation, the `LDR` instructions in `P1` are reordered.