Merge pull request #1759 from madeline-underwood/Thread_Sync

Thread sync_JA to review

Author: jasonrandrews

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

@@ -1,19 +1,21 @@
 ---
-title: Explore The Arm Memory Model & Thread Synchronization
+title: Explore Thread Synchronization in the Arm Memory Model
 
 minutes_to_complete: 150
 
-who_is_this_for: This is an advanced topic for engineers looking for a practical way to test different thread synchronization approaches within the context of the Arm memory model.
+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 snippets of thread synchronization assembly against the formal definition of the Arm Memory Model
-    - Test snippets of thread synchronization assembly on Arm hardware to compare against the formal 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 different memory consistency models like Sequential Consistency, Weak Ordering, Relaxed Consistency, Processor Consistency, etc.
+    - An understanding of memory consistency models (such as Sequential Consistency, Weak Ordering, Relaxed Consistency, and Processor Consistency).
     - An understanding of thread synchronization.
-    - An understanding of Arm assembly, general-purpose registers, and how to find information on Arm assembly instructions.
-    - An understanding of memory barriers including acquire-release semantics.
+    - 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.
 
 author: Julio Suarez
 
@@ -35,7 +37,7 @@ further_reading:
         link: https://developer.arm.com/documentation/ddi0487/la
         type: documentation
     - resource:
-        title: Armv8 Barriers
+        title: "Barriers, Learn the Architecture: Armv8-A Memory Systems."
         link: https://developer.arm.com/documentation/100941/0101/Barriers
         type: documentation
     - resource:

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

@@ -4,62 +4,65 @@ weight: 2
 layout: "learningpathall"
 ---
 
-## CPU Memory Model vs Language/Runtime Memory Models
+## The Memory Consistency Model
 
-Majority of developers will not need to be deeply familiar with the memory consistency model of the CPU their code will execute on. This is because programming languages and runtime engines abstract away the CPUs memory model by presenting the programmer with a language/runtime memory model. This abstraction is achieved by providing developers with a set of language/runtime specific memory ordering rules, synchronization constructs, and supporting libraries. As long as the developer uses these correctly, language compilers and runtime engines will make sure the code executes correctly on any CPU regardless of how strong or weakly ordered it is.
+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 may want to dig deeper into this topic for various reasons including:
+That said, developers might want to dig deeper into this topic for various reasons including:
 
-- Extract more performance from weakly ordered CPUs (like Arm CPUs).
-  - Compilers and runtimes will do a good job of maximizing performance. Only in well understood niche cases will there be a potential for performance gain by going beyond what the compiler/runtime would do to higher level code. For most cases, all it takes to get more performance is to use the latest compilers, compiler switches, and runtimes.
-- Develop confidence in the correctness of synchronization constructs.
-- Develop an understanding of how compilers and runtimes select different machine instructions while still honoring the memory ordering rules of the language/runtime and CPU.
+- 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.
+- Gaining confidence in the correctness of synchronization constructs.
+- Understanding how compilers and runtimes select machine instructions while still honoring the memory ordering rules.
 
-In this Learning Path, you will use publicly available tools to explore thread synchronization on Arm CPUs. You will gain enough working knowledge of the tools to be able to explore thread synchronization concepts. At the end of this Learning Path, you will be able access more information to get a deeper understanding of this subject.
+In this Learning Path, you will use publicly available tools to explore thread synchronization on Arm CPUs. You will gain enough working knowledge of these tools to explore thread synchronization concepts. 
+
+{{% notice Learning Tip%}}
+At the end of this Learning Path, you can find details of further resources that you can consult to gain a deeper understanding of this subject.{{% /notice %}}
 
 ##  The Formal Definition of the Arm Memory Model
 
-The formal definition of the Arm memory model is in the [Arm Architecture Reference Manual for A-profile architecture](https://developer.arm.com/documentation/ddi0487/la) (Arm ARM) under the section called `The AArch64 Application Level Memory Model`. The ordering requirements defined in the Arm ARM is a transliteration of the `aarch64.cat` file hosted on the Arm [herd7 simulator tool](https://developer.arm.com/herd7). In fact, this `aarch64.cat` file is the authoritative definition of the Arm memory model. As it is a formal definition, it is complex.
+The formal definition of the Arm memory model is described in the [Arm Architecture Reference Manual for A-profile architecture](https://developer.arm.com/documentation/ddi0487/la) (often referred to as "the Arm ARM") under the section called `The AArch64 Application Level Memory Model`. The ordering requirements defined in the Arm ARM is a transliteration of the `aarch64.cat` file hosted on the Arm [herd7 simulator tool](https://developer.arm.com/herd7). In fact, the `aarch64.cat` file is the authoritative definition of the Arm memory model. As a formal definition, it is inherently complex.
 
-##  Herd7 Simulator & Litmus7 Tool
+##  Herd7 Simulator and Litmus7 Tool
 
-The herd7 simulator provides a way to test snippets of Arm assembly against the formal definition of the Arm memory model (the `aarch64.cat` file mentioned above). The litmus7 tool can take the same snippets of assembly that run on herd7 and run them on actual Arm hardware. This allows for comparing the formal memory model to the memory model of an actual Arm CPU. These snippets of assembly are called litmus tests.
+The herd7 simulator tests snippets of Arm assembly against the formal definition of the Arm memory model (the `aarch64.cat` file mentioned above). The litmus7 tool runs the same snippets of assembly on actual Arm hardware, enabling a direct comparison between the formal model and the real-world behavior of an actual Arm CPU. These snippets of assembly are called litmus tests.
 
-It's important to understand that it is possible for an implementation of an Arm CPU to be more strongly ordered than the formally defined Arm memory model. This case is not a violation of the memory model because it will still execute code in a way that is compliant with the memory ordering rules.
+It's important to note that an Arm CPU implementation might exhibit stronger ordering than the formal memory model. This is not a violation; the CPU still executes code in a way that is compliant with the memory ordering rules.
 
 ## Install the Tools
 
-Herd7 and Litmus7 are part of the [diy7](http://diy.inria.fr/) tool suite. The diy7 tool suite can be installed by following the [installation instructions](http://diy.inria.fr/sources/index.html). You will install the tools on an Arm Linux system so that both herd7 and litmus7 can be compared side by side on the same system.
+Herd7 and Litmus7 are part of the [diy7](http://diy.inria.fr/) tool suite. You can install the diy7 tool suite by following the [installation instructions](http://diy.inria.fr/sources/index.html). Install the tools on an Arm Linux system so that both herd7 and litmus7 can be compared side by side.
 
 Start an Arm-based cloud instance. This example uses a `t4g.xlarge` AWS instance running Ubuntu 22.04 LTS, but other instances types are possible. 
 
 If you are new to cloud-based virtual machines, refer to [Get started with Servers and Cloud Computing](/learning-paths/servers-and-cloud-computing/intro/). 
 
-First confirm you are using a Arm-based instance with the following command.
+First confirm you are using a Arm-based instance:
 
 ```bash
 uname -m
 ```
-You should see the following output.
+You should see the following output:
 
 ```output
 aarch64
 ```
 
-Next, install OCaml Package Manager (opam). You will need `opam` to install the `herdtools7` tool suite:
+Install OCaml Package Manager (opam). You need `opam` to install the `herdtools7` tool suite:
 ```bash
 sudo apt update
 sudo apt install opam -y
 ```
 
-Setup `opam` to install the tools:
+Set up `opam` to install the tools:
 ```bash
 opam init
 opam update
 eval $(opam env)
 ```
 
-Now install the `herdtool7` tool suite which include both `litmus7` and `herd7`:
+Now install the `herdtool7` tool suite (which includes both `litmus7` and `herd7`):
 
 ```bash
 opam install herdtools7
@@ -68,7 +71,7 @@ opam install herdtools7
 
 ## Herd7 and Litmus7 Example Commands
 
-You can run `--help` on both the tools to review all the options available.
+You can run `--help` on both tools to review all available options:
 ```
 herd7 --help
 ```
@@ -80,27 +83,27 @@ The input to both `herd7` and `litmus7` tools are snippets of assembly code, cal
 
 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.
 
-Example of running herd7.
+Run herd7 with a litmus test:
 ```
 herd7 ./test.litmus
 ```
 
-Example of running litmus7.
+Run litmus7 with a litmus test:
 ```
 litmus7 ./test.litmus
 ```
 
-Example of running litmus7 with 5,000,000 test iterations (default is 1,000,000).
+Run litmus7 with 5,000,000 test iterations (default is 1,000,000):
 ```
 litmus7 ./test.litmus -s 5000000
 ```
 
-Example of running a litmus7 tests in parallel on 8 CPUs.
+Run a litmus7 test in parallel on 8 CPUs:
 ```
 litmus7 ./test.litmus -a 8
 ```
 
-Example of running litmus7 and asking GCC to emit atomic instructions as required by the litmus test (the possible need for this is explained later).
+Run litmus7 with GCC emitting atomic instructions as required by the litmus test (explained later):
 ```
 litmus7 ./test.litmus -ccopts="-mcpu=native"
 ```