Further improvements

Author: madeline-underwood

content/learning-paths/cross-platform/multiplying-matrices-with-sme2/1-get-started.md

@@ -8,13 +8,12 @@ layout: learningpathall
 
 ## Choose your SME2 setup: native or emulated
 
-Before you can build or run any SME2-accelerated code, you need to set up your development environment. 
-
-This section walks you through the required tools and the two supported execution options, which are: 
+To build or run SME2-accelerated code, first set up your development environment.
+This section walks you through the required tools and two supported setup options:
 
 * [**Native SME2 hardware**](#set-up-a-system-with-native-SME2-support) - build and run directly on a system with SME2 support. For supported devices, see [Devices with SME2 support](#devices-with-sme2-support). 
 
-* [**Docker-based emulation**](#set-up-a-system-using-sme2-emulation-with-dockerset-up-a-system-using-SME2-emulation-with-Docker) - use a container to emulate SME2 in bare metal mode (without an OS).
+* [**Docker-based emulation**](#set-up-a-system-using-sme2-emulation-with-docker) - use a container to emulate SME2 in bare metal mode (without an OS).
 
 ## Download and explore the code examples
 
@@ -66,7 +65,7 @@ Amongst other files, it includes:
 - A `docker` directory containing:
   - `assets.source_me` to provide toolchain paths.
   - `build-my-container.sh`, a script that automates building the Docker image from the `sme2-environment.docker` file. It runs the Docker build command with the correct arguments so you don’t have to remember them. 
-  - `sme2-environment.docker`, a Docker file that defines the steps to build the SME2 container image. It installs all the necessary dependencies, including the SME2-compatible compiler and Arm FVP emulator.
+  - `sme2-environment.docker`, a custom Docker file that defines the steps to build the SME2 container image. It installs all the necessary dependencies, including the SME2-compatible compiler and Arm FVP emulator.
   - `build-all-containers.sh`, a script to build multi-architecture images.
 - `.devcontainer/devcontainer.json` for VS Code container support.
 
@@ -234,7 +233,7 @@ If you are using Visual Studio Code as your IDE, the container setup is already
 
 Make sure you have the [Microsoft Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension installed.
 
-Then select the **Reopen in Container** menu entry as Figure 1 shows.
+Then select the **Reopen in Container** menu entry as shown below.
 
 It automatically finds and uses ``.devcontainer/devcontainer.json``:
 
@@ -252,7 +251,7 @@ part.
 
 ### Devices with native SME2 support
 
-#### Apple devices (by product type)
+These Apple devices support SME2 natively.
 
 - iPad
 

content/learning-paths/cross-platform/multiplying-matrices-with-sme2/2-check-your-environment.md

@@ -6,13 +6,11 @@ weight: 4
 layout: learningpathall
 ---
 
-In this section, you will verify that your environment is set up and ready to
-develop with SME2. This will be your first hands-on experience with the
-environment.
+In this section, you'll verify that your environment is ready for SME2 development. This is your first hands-on task and confirms that the toolchain, hardware (or emulator), and compiler are set up correctly.
 
-## Compile the examples
+## Build the code examples
 
-First, build the code examples by running `make`:
+Use the `make` command to compile all examples and generate assembly listings:
 
 {{< tabpane code=true >}}
   {{< tab header="Native SME2 support" language="bash" output_lines="2-19">}}
@@ -66,6 +64,8 @@ The `make` command performs the following tasks:
 - It creates the assembly listings for the four executables: `hello.lst`,
   `sme2_check.lst`, `sme2_matmul_asm.lst`, and `sme2_matmul_intr.lst`.
 
+  These targets compile and link all example programs and generate disassembly listings for inspection.
+
 At any point, you can clean the directory of all the files that have been built
 by invoking `make clean`:
 
@@ -114,12 +114,20 @@ Run the `hello` program with:
   {{< /tab >}}
 {{< /tabpane >}}
 
-In the emulated case, you may see that the FVP prints out extra lines. The key confirmation is the presence of "Hello, world!" in the output. it demonstrates that the generic code can be compiled and executed.
+In the emulated case, you may see that the FVP prints out extra lines. The key confirmation is the presence of "Hello, world!" in the output. It demonstrates that the generic code can be compiled and executed.
 
 ## Check SME2 availability
 
 You will now run the `sme2_check` program, which verifies that SME2 works as expected. This checks both the compiler and the CPU (or the emulated CPU) are properly supporting SME2.
 
+The `sme2_check` program verifies that SME2 is available and working. It confirms:
+
+* The compiler supports SME2 (via __ARM_FEATURE_SME2)
+
+* The system or emulator reports SME2 capability
+
+* Streaming mode works as expected
+
 The source code is found in `sme2_check.c`:
 
 ```C { line_numbers="true" }
@@ -191,10 +199,7 @@ The ``sme2_check`` program then displays whether SVE, SME and SME2 are supported
 at line 24. The checking of SVE, SME and SME2 is done differently depending on
 ``BAREMETAL``. This platform specific behaviour is abstracted by the
 ``display_cpu_features()``:
-- In baremetal mode, our program has access to system registers and can thus do
-  some low level peek at what the silicon actually supports. The program will
-  print the SVE field of the ``ID_AA64PFR0_EL1`` system register and the SME
-  field of the ``ID_AA64PFR1_EL1`` system register.
+- In baremetal mode, our program has access to system registers and can inspect system registers for SME2 support. The program will print the SVE field of the ``ID_AA64PFR0_EL1`` system register and the SME field of the ``ID_AA64PFR1_EL1`` system register.
 - In non baremetal mode, on an Apple platform the program needs to use a higher
   level API call.
 
@@ -213,6 +218,8 @@ annotated with the ``__arm_locally_streaming`` attribute, which instructs the
 compiler to automatically switch to streaming mode when invoking this function.
 Streaming mode will be discussed in more depth in the next section.
 
+Look for the following confirmation messages in the output:
+
 {{< tabpane code=true >}}
   {{< tab header="Native SME2 support" language="bash" output_lines="2-9">}}
   ./sme2_check
@@ -243,5 +250,4 @@ Streaming mode will be discussed in more depth in the next section.
   {{< /tab >}}
 {{< /tabpane >}}
 
-You have now checked that the code can be compiled and run with full SME2
-support. You are all set to move to the next section.
+You've now confirmed that your environment can compile and run SME2 code, and that SME2 features like streaming mode are working correctly. You're ready to continue to the next section and start working with SME2 in practice.

content/learning-paths/cross-platform/multiplying-matrices-with-sme2/3-streaming-mode.md

@@ -1,5 +1,5 @@
 ---
-title: Streaming mode and ZA State in SME
+title: Streaming mode and ZA state in SME
 weight: 5
 
 ### FIXED, DO NOT MODIFY
@@ -8,7 +8,7 @@ layout: learningpathall
 
 ## Understanding streaming mode
 
-In large-scale software, programs often switch between streaming and non-streaming mode. Some streaming-mode functions may call others, requiring portions of processor state, such as the ZA storage, to be saved and restored. This behavior is defined in the Arm C Language Extensions (ACLE) and is supported by the compiler.
+Programs can switch between streaming and non-streaming mode during execution. When one streaming-mode function calls another, parts of the processor state - such as ZA storage - might need to be saved and restored. This behavior is governed by the Arm C Language Extensions (ACLE) and is managed by the compiler.
 
 To use streaming mode, you simply annotate the relevant functions with the appropriate keywords. The compiler handles the low-level mechanics of streaming mode management, removing the need for error-prone, manual work.
 
@@ -18,29 +18,28 @@ For more information, see the [Introduction to streaming and non-streaming mode]
 
 ## Streaming mode behavior and compiler handling
 
+Streaming mode changes how the processor and compiler manage execution context. Here's how it works:
+
 * The AArch64 architecture defines a concept called *streaming mode*, controlled
 by a processor state bit `PSTATE.SM`. 
 
-* At any given point in time, the processor is either in streaming mode (`PSTATE.SM==1`) or in non-streaming mode (`PSTATE.SM==0`). 
+* At any given point in time, the processor is either in streaming mode (`PSTATE.SM == 1`) or in non-streaming mode (`PSTATE.SM == 0`). 
 
 * To enter streaming mode, there is the instruction `SMSTART`, and to return to non-streaming mode, the instruction is `SMSTOP`.
 
 * Streaming mode affects C and C++ code in the following ways:
 
   - It can change the length of SVE vectors and predicates. The length of an SVE vector in streaming mode is called the *Streaming Vector Length* (SVL), which might differ from the non-streaming vector length. See [Effect of streaming mode on VL](https://arm-software.github.io/acle/main/acle.html#effect-of-streaming-mode-on-vl) for further information.
-  - Some instructions, and their associated ACLE intrinsics, can only be executed in streaming mode.These intrinsics are called *streaming intrinsics*.
-  - Other instructions are restricted to non-streaming mode, and their instrinsics are called *non-streaming intrinsics*.
+  - Some instructions, and their associated ACLE intrinsics, can only be executed in streaming mode.These are called *streaming intrinsics*.
+  - Other instructions are restricted to non-streaming mode. These are called *non-streaming intrinsics*.
 
 The ACLE specification extends the C and C++ abstract machine model to include streaming mode. At any given time, the abstract machine is either in streaming or non-streaming mode.
 
 This distinction between abstract machine mode and processor mode is mostly a specification detail. At runtime, the processor’s mode may differ from the abstract machine’s mode - as long as the observable program behavior remains consistent (as per the "as-if" rule).
 
-One
-practical consequence of this is that C and C++ code does not specify the exact
-placement of `SMSTART` and `SMSTOP` instructions; the source code simply places
-limits on where such instructions go. For example, when stepping through a
-program in a debugger, the processor mode might sometimes be different from the
-one implied by the source code.
+{{% notice Note %}}
+One practical consequence of this is that C and C++ code does not specify the exact placement of `SMSTART` and `SMSTOP` instructions; the source code simply places limits on where such instructions go. For example, when stepping through a program in a debugger, the processor mode might sometimes be different from the one implied by the source code.
+{{% /notice %}}
 
 ACLE provides attributes that specify whether the abstract machine executes statements:
 
@@ -56,10 +55,11 @@ is enabled.
 
 In C and C++, ZA usage is specified at the function level: a function either uses ZA or it doesn't. That is, a function either has ZA state or it does not.
 
-If a function does have ZA state, the function can either share that ZA state
-with the function's caller or create new ZA state. In the latter
-case, it is the compiler's responsibility to free up ZA so that the function can
-use it - see the description of the lazy saving scheme in
-[AAPCS64](https://arm-software.github.io/acle/main/acle.html#AAPCS64) for details
-about how the compiler does this.
+Functions that use ZA can either:
+
+- Share the caller’s ZA state
+- Allocate a new ZA state for themselves
+
+When new state is needed, the compiler is responsible for preserving the caller’s state using a *lazy saving* scheme. For more information, see the [AAPCS64 section of the ACLE spec](https://arm-software.github.io/acle/main/acle.html#AAPCS64).
+
 

content/learning-paths/cross-platform/multiplying-matrices-with-sme2/4-vanilla-matmul.md

@@ -8,7 +8,7 @@ layout: learningpathall
 
 ## Overview
 
-In this section, you'll implement a basic matrix multiplication algorithm in C, using a row-major memory layout. This version serves as a reference implementation for validating optimized versions later in the Learning Path.
+In this section, you'll implement a basic matrix multiplication algorithm in C using row-major memory layout. This version acts as a reference implementation that you'll use to validate the correctness of optimized versions later in the Learning Path.
 
 ## Vanilla matrix multiplication algorithm
 
@@ -21,6 +21,8 @@ It produces an output matrix C [`Cr` rows x `Cc` columns].
 
 The algorithm works by iterating over each row of A and each column of B. It multiplies the corresponding elements and sums the products to generate each element of matrix C, as shown in the figure below.
 
+The diagram below shows how matrix C is computed by iterating over rows of A and columns of B:
+
 ![Standard Matrix Multiplication alt-text#center](matmul.png "Figure 2: Standard matrix multiplication.")
 
 This implies that the A, B, and C matrices have some constraints on their
@@ -34,16 +36,14 @@ properties and use, see this [Wikipedia article on Matrix Multiplication](https:
 
 ## Variable mappings in this Learning Path
 
-In this Learning Path, you'll use the following variable names:
+The following variable names are used throughout the Learning Path to represent matrix dimensions and operands:
 
-- `matLeft` corresponds to the left-hand side argument of the matrix
-  multiplication.
+- `matLeft` corresponds to the left-hand side argument of the matrix multiplication.
 - `matRight`corresponds to the right-hand side of the matrix multiplication.
 - `M` is `matLeft` number of rows.
 - `K` is `matLeft` number of columns (and `matRight` number of rows).
 - `N` is `matRight` number of columns.
-- `matResult`corresponds to the result of the matrix multiplication, with
-  `M` rows and `N` columns.
+- `matResult`corresponds to the result of the matrix multiplication, with `M` rows and `N` columns.
 
 ## C implementation