Streamlining

Author: madeline-underwood

content/learning-paths/cross-platform/simd-loops/1-about.md

@@ -8,35 +8,17 @@ layout: learningpathall
 
 Writing high-performance software on Arm often means using single-instruction, multiple-data (SIMD) technologies. Many developers start with NEON, a familiar fixed-width vector extension. As Arm architectures evolve, so do the SIMD capabilities available to you.
 
-This Learning Path uses the **Scalable Vector Extension (SVE)** and the **Scalable Matrix Extension (SME)** to teach modern SIMD patterns. They are two powerful, scalable vector extensions designed for modern workloads. Unlike NEON, these architecture extensions are not just wider; they are fundamentally different. They introduce predication, vector-length-agnostic (VLA) programming, gather/scatter, streaming modes, and tile-based compute with ZA state. The result is more power and flexibility, with a learning curve to match.
+This Learning Path uses the **Scalable Vector Extension (SVE)** and the **Scalable Matrix Extension (SME)** to demonstrate modern SIMD patterns. They are two powerful, scalable vector extensions designed for modern workloads. Unlike NEON, these architecture extensions are not just wider; they are fundamentally different. They introduce predication, vector-length-agnostic (VLA) programming, gather/scatter, streaming modes, and tile-based compute with ZA state. The result is more power and flexibility, but there can be a learning curve to match.
 
-**SIMD Loops** offer a hands-on way to climb the learning curve. It is a public codebase of self-contained, real loop kernels written in C, Arm C Language Extensions (ACLE) intrinsics, and selected inline assembly. Kernels span tasks such as matrix multiply, sorting, and string processing. You can build them, run them, step through them, and adapt them for your own SIMD workloads.
+The **SIMD Loops** project offers a hands-on way to climb the learning curve. It is a public codebase of self-contained, real loop kernels written in C, Arm C Language Extensions (ACLE) intrinsics, and selected inline assembly. Kernels span tasks such as matrix multiply, sorting, and string processing. You can build them, run them, step through them, and adapt them for your own SIMD workloads.
 
 > Repo: [SIMD Loops](https://gitlab.arm.com/architecture/simd-loops)
 
-## What is SIMD Loops?
-
-SIMD Loops is an open-source
-project, licensed under BSD 3-Clause, built to help you learn how to write SIMD code for modern Arm
-architectures, specifically using SVE and SME.
-It is designed for programmers who already know
-their way around NEON intrinsics but are now facing the more powerful and
-complex world of SVE and SME.
-
-The goal of SIMD Loops is to provide working, readable examples that demonstrate
-how to use the full range of features available in SVE, SVE2, and SME2. Each
-example is a self-contained loop kernel, a small piece of code that performs
-a specific task like matrix multiplication, vector reduction, histogram, or
-memory copy. These examples show how that task can be implemented across different
-vector instruction sets.
-
-Unlike a cookbook that tries to provide a recipe for every problem, SIMD Loops
-takes the opposite approach. It aims to showcase the architecture rather than
-the problem. The loop kernels are chosen to be realistic and meaningful, but the
-main goal is to demonstrate how specific features and instructions work in
-practice. If you are trying to understand scalability, predication,
-gather/scatter, streaming mode, ZA storage, compact instructions, or the
-mechanics of matrix tiles, this is where you will see them in action.
+SIMD Loops is an open-source project, licensed under BSD 3-Clause, built to help you learn how to write SIMD code for modern Arm architectures, specifically using SVE and SME. It is designed for programmers who already know their way around NEON intrinsics but are now facing the more powerful and complex world of SVE and SME.
+
+The goal of SIMD Loops is to provide working, readable examples that demonstrate how to use the full range of features available in SVE, SVE2, and SME2. Each example is a self-contained loop kernel, a small piece of code that performs a specific task like matrix multiplication, vector reduction, histogram, or memory copy. These examples show how that task can be implemented across different vector instruction sets.
+
+Unlike a cookbook that attempts to provide a recipe for every problem, SIMD Loops takes the opposite approach. It aims to showcase the architecture rather than the problem itself. The loop kernels are chosen to be realistic and meaningful, but the main goal is to demonstrate how specific features and instructions work in practice. If you are trying to understand scalability, predication, gather/scatter, streaming mode, ZA storage, compact instructions, or the mechanics of matrix tiles, this is where you can see them in action.
 
 The project includes:
 - Many numbered loop kernels, each focused on a specific feature or pattern

content/learning-paths/cross-platform/simd-loops/2-using.md

@@ -13,7 +13,7 @@ git clone https://gitlab.arm.com/architecture/simd-loops simd-loops.git
 cd simd-loops.git
 ```
 
-Confirm you are using an Arm machine:
+Confirm that you are using an Arm machine:
 
 ```bash
 uname -m
@@ -33,11 +33,7 @@ arm64
 
 ## SIMD Loops structure
 
-In the SIMD Loops project, the source code for the loops is organized under the `loops` directory. The complete
-list of loops is documented in the `loops.inc` file, which includes a brief
-description and the purpose of each loop. Every loop is associated with a
-uniquely named source file following the pattern `loop_<NNN>.c`, where
-`<NNN>` represents the loop number.
+In the SIMD Loops project, the source code for the loops is organized under the `loops` directory. The complete list of loops is documented in the `loops.inc` file, which includes a brief description and the purpose of each loop. Every loop is associated with a uniquely named source file following the pattern `loop_<NNN>.c`, where `<NNN>` represents the loop number.
 
 A subset of the `loops.inc` file is below:
 
@@ -84,27 +80,15 @@ void inner_loop_<NNN>(struct loop_<NNN>_data *data) { ... }
 // Main of loop: buffer allocation, loop function call, result checking
 ```
 
-Each loop is implemented in several SIMD extension variants. Conditional
-compilation selects one of the implementations for the
-`inner_loop_<NNN>` function.
+Each loop is implemented in several SIMD extension variants. Conditional compilation selects one of the implementations for the `inner_loop_<NNN>` function.
 
-The native C implementation is written first, and
-it can be generated either when building natively with `-DHAVE_NATIVE` or through
-compiler auto-vectorization with `-DHAVE_AUTOVEC`.
+The native C implementation is written first, and it can be generated either when building natively with `-DHAVE_NATIVE` or through compiler auto-vectorization with `-DHAVE_AUTOVEC`.
 
-When SIMD ACLE is supported (SME, SVE, or NEON),
-the code is compiled using high-level intrinsics. If ACLE
-support is not available, the build process falls back to handwritten inline
-assembly targeting one of the available SIMD extensions, such as SME2.1, SME2,
-SVE2.1, SVE2, and others.
+When SIMD ACLE is supported (SME, SVE, or NEON), the code is compiled using high-level intrinsics. If ACLE support is not available, the build process falls back to handwritten inline assembly targeting one of the available SIMD extensions, such as SME2.1, SME2, SVE2.1, SVE2, and others.
 
-The overall code structure also includes setup and
-cleanup code in the main function, where memory buffers are allocated, the
-selected loop kernel is executed, and results are verified for correctness.
+The overall code structure also includes setup and cleanup code in the main function, where memory buffers are allocated, the selected loop kernel is executed, and results are verified for correctness.
 
-At compile time, you can select which loop optimization to compile, whether it
-is based on SME or SVE intrinsics, or one of the available inline assembly
-variants.
+At compile time, you can select which loop optimization to compile, whether it is based on SME or SVE intrinsics, or one of the available inline assembly variants.
 
 ```console
 make

content/learning-paths/cross-platform/simd-loops/3-example.md

@@ -6,13 +6,13 @@ weight: 4
 layout: learningpathall
 ---
 
-To illustrate the structure and design principles of SIMD Loops, consider loop 202 as an example
+To illustrate the structure and design principles of SIMD Loops, consider loop 202 as an example.
 
-Use a text editor to open `loops/loop_202.c`
+Use a text editor to open `loops/loop_202.c`.
 
 The function `inner_loop_202()` is defined around lines 60–70 in `loops/loop_202.c` and calls the `matmul_fp32` routine defined in `loops/matmul_fp32.c`
 
-Open `loops/matmul_fp32.c` in your editor
+Open `loops/matmul_fp32.c` in your editor.
 
 This loop implements single-precision floating-point matrix multiplication of the form:
 
@@ -24,8 +24,7 @@ You can view matrix multiplication in two equivalent ways:
 
 ## Data structure
 
-The loop begins by defining a data structure that captures the matrix
-dimensions (`M`, `K`, `N`) along with input and output buffers:
+The loop begins by defining a data structure that captures the matrix dimensions (`M`, `K`, `N`) along with input and output buffers:
 
 ```C
 struct loop_202_data {
@@ -43,19 +42,19 @@ For this loop:
 - Matrix `b` is stored in row-major order
 - The memory regions referenced by `a`, `b`, and `c` do not alias, as indicated by the `restrict` keyword
 
-This layout helps optimize memory access patterns across the targeted SIMD architectures
+This layout helps optimize memory access patterns across the targeted SIMD architectures.
 
 ## Loop attributes
 
 Loop attributes are specified per target architecture:
 - **SME targets** — `inner_loop_202` is invoked with the `__arm_streaming` attribute and uses a shared `ZA` register context (`__arm_inout("za")`). These attributes are wrapped in the `LOOP_ATTR` macro
 - **SVE or NEON targets** — no additional attributes are required
 
-This design enables portability across SIMD extensions
+This design enables portability across SIMD extensions.
 
 ## Function implementation
 
-`loops/matmul_fp32.c` provides several optimizations of matrix multiplication, including ACLE intrinsics and hand-optimized assembly
+`loops/matmul_fp32.c` provides several optimizations of matrix multiplication, including ACLE intrinsics and hand-optimized assembly.
 
 ### Scalar code
 
@@ -79,7 +78,7 @@ A scalar C implementation appears around lines 40–52. It follows the dot-produ
 
 ### SVE-optimized code
 
-The SVE version uses indexed floating-point multiply–accumulate (`fmla`) to optimize the matrix multiplication operation. The outer product is decomposed into indexed multiply steps, and results accumulate directly in `Z` registers
+The SVE version uses indexed floating-point multiply–accumulate (`fmla`) to optimize the matrix multiplication operation. The outer product is decomposed into indexed multiply steps, and results accumulate directly in `Z` registers.
 
 In the intrinsics version (lines 167–210), the innermost loop is structured as follows:
 
@@ -130,23 +129,23 @@ In the intrinsics version (lines 167–210), the innermost loop is structured as
   }
 ```
 
-At the beginning of the loop, the accumulators (`Z` registers) are zeroed using `svdup` (or `dup` in assembly), encapsulated in the `ZERO_PAIR` macro
+At the beginning of the loop, the accumulators (`Z` registers) are zeroed using `svdup` (or `dup` in assembly), encapsulated in the `ZERO_PAIR` macro.
 
 Within each iteration over the `K` dimension:
-- 128 bits (four consecutive floating-point values) are loaded from `A` using replicate loads `svld1rq` (or `ld1rqw`), via `LOADA_PAIR`
+- 128 bits (four consecutive floating-point values) are loaded from `A` using replicate loads `svld1rq` (or `ld1rqw`), through `LOADA_PAIR`
 - Two vectors are loaded from `B` using SVE vector loads, using `LOADB_PAIR`
 - Indexed `fmla` operations compute element–vector products and accumulate into 16 `Z` register accumulators
 - Partial sums build up the output tile
 
-After all `K` iterations, results in the `Z` registers are stored to `C` using the `STORE_PAIR` macro
+After all `K` iterations, results in the `Z` registers are stored to `C` using the `STORE_PAIR` macro.
 
-The equivalent SVE hand-optimized assembly appears around lines 478–598
+The equivalent SVE hand-optimized assembly appears around lines 478–598.
 
-This loop shows how SVE registers and indexed `fmla` enable efficient decomposition of the outer-product formulation into parallel, vectorized accumulation
+This loop shows how SVE registers and indexed `fmla` enable efficient decomposition of the outer-product formulation into parallel, vectorized accumulation.
 
-For SVE/SVE2 semantics and optimization guidance, see the [Scalable Vector Extensions resources](https://developer.arm.com/Architectures/Scalable%20Vector%20Extensions)
+For SVE/SVE2 semantics and optimization guidance, see the [Scalable Vector Extensions resources](https://developer.arm.com/Architectures/Scalable%20Vector%20Extensions).
 
-### SME2-optimized code
+## SME2-optimized code
 
 The SME2 implementation leverages the outer-product formulation of the matrix
 multiplication function, utilizing the `fmopa` SME instruction to perform the
@@ -226,17 +225,16 @@ For instruction semantics and SME/SME2 optimization guidance, see the [SME Progr
 
 ## Other optimizations
 
-Beyond the SME2 and SVE implementations, this loop also includes additional
-optimized versions that leverage architecture-specific features
+Beyond the SME2 and SVE implementations, this loop also includes additional optimized versions that leverage architecture-specific features.
 
 ### NEON
 
-The NEON version (lines 612–710) uses structure load/store combined with indexed `fmla` to vectorize the computation
+The NEON version (lines 612–710) uses structure load/store combined with indexed `fmla` to vectorize the computation.
 
 ### SVE2.1
 
-The SVE2.1 version (lines 355–462) extends the base SVE approach using multi-vector loads and stores
+The SVE2.1 version (lines 355–462) extends the base SVE approach using multi-vector loads and stores.
 
 ### SME2.1
 
-The SME2.1 version uses `movaz` / `svreadz_hor_za8_u8_vg4` to reinitialize `ZA` tile accumulators while moving data out to registers
+The SME2.1 version uses `movaz`/`svreadz_hor_za8_u8_vg4` to reinitialize `ZA` tile accumulators while moving data out to registers.

content/learning-paths/cross-platform/simd-loops/4-conclusion.md

@@ -15,5 +15,4 @@ Whether you are moving from NEON or starting directly with SVE and SME, the proj
 
 Use the repository to explore, modify, and benchmark kernels so you can understand tradeoffs and apply the patterns to your own workloads.
 
-For more information and to get started, visit the GitLab project and see the [README.md](https://gitlab.arm.com/architecture/simd-loops/-/blob/main/README.md)
-for the latest instructions on building and running the code. 
+For more information and to get started, visit the GitLab project and see the [README.md](https://gitlab.arm.com/architecture/simd-loops/-/blob/main/README.md) for the latest instructions on building and running the code.