Refactor SIMD on Rust learning path content for clarity and consistency

Author: madeline-underwood

content/learning-paths/cross-platform/simd-on-rust/_index.md

@@ -1,17 +1,20 @@
 ---
-title: Learn how to write SIMD code on Arm using Rust
+title: Write SIMD code on Arm using Rust
 
 minutes_to_complete: 30
 
 description: Learn how to write SIMD code in Rust on Arm platforms using Neon intrinsics, portable SIMD abstractions, and optimize performance with architecture-specific instructions.
 
-who_is_this_for: This is an advanced topic for software developers who want take advantage of SIMD code on Arm systems using Rust.
+who_is_this_for: This is an advanced topic for software developers who want to take advantage of SIMD code on Arm systems using Rust.
 
 learning_objectives: 
-    - Learn how to write SIMD code with Rust on Arm.
+    - Write SIMD code with Rust using std::arch and Neon intrinsics on Arm
+    - Use portable SIMD abstractions with std::simd for cross-platform code
+    - Apply feature detection and target attributes for architecture-specific optimizations
+    - Compare C and Rust SIMD implementations and disassembly output
 
 prerequisites:
-    - An Arm-based computer with recent versions of a C compiler (Clang or GCC) and a Rust compiler installed.
+    - An Arm-based computer with recent versions of a C compiler (Clang or GCC) and a Rust compiler installed
 
 author: Konstantinos Margaritis
 

content/learning-paths/cross-platform/simd-on-rust/conclusion.md

@@ -8,5 +8,5 @@ layout: learningpathall
 
 You have now seen a few examples of writing SIMD code on Arm with Rust. 
 
-Performance-wise, there is little difference between C and Rust as Rust is perfectly capable of generating the same assembly code as C in most cases. That said, if you want to program optimal SIMD code using the Arm ASIMD/Neon intrinsics, `std::arch` is the most obvious choice. If, however, your approach needs to be as portable as possible and you don't want to spend time providing multiple implementations for each architecture then `std::simd` is a very viable alternative (even though it's not part of the stable compiler yet).
+Performance-wise, there's little difference between C and Rust as Rust is perfectly capable of generating the same assembly code as C in most cases. That said, if you want to program optimal SIMD code using the Arm ASIMD/Neon intrinsics, `std::arch` is the most obvious choice. If, however, your approach needs to be as portable as possible and you don't want to spend time providing multiple implementations for each architecture then `std::simd` is a very viable alternative (even though it's not part of the stable compiler yet).
 

content/learning-paths/cross-platform/simd-on-rust/intro-to-rust.md

@@ -12,10 +12,10 @@ In this Learning Path, you will learn the basics of how to program SIMD code on
 
 Rust is a safe programming language with some key advantages:
 
-* It is a modern, strong-typed language.
-* Rust is memory safe by design: it is very difficult to introduce a bug like buffer overflow with Rust.
-* Strict language: the Rust compiler is very strict and does not let you make easy mistakes as you might with C.
-* The usage and support for Rust is expanding to many architectures and operating systems.
+* It's a modern, strong-typed language
+* Rust is memory safe by design: it's very difficult to introduce a bug like buffer overflow with Rust
+* Strict language: the Rust compiler is very strict and doesn't let you make easy mistakes as you might with C
+* The usage and support for Rust is expanding to many architectures and operating systems
 
 ## SIMD with Rust
 
@@ -24,19 +24,19 @@ Support for intrinsics in languages such as C and C++ is generally added by the
 Rust is a little different in that regard. While vendors are still very involved in providing the support for SIMD intrinsics in the compiler, there are other alternatives and approaches used to provide SIMD abstraction.
 
 Currently there are 2 SIMD programming interfaces in Rust:
-* One under `std::arch` which follows the C intrinsics as much as possible.
-* Another, `std::simd`, which provides a portable abstraction to SIMD programming so that code can just be recompiled across different architectures with more or less the same results. While there are similar libraries for C and C++, this is different in that the intent is for it to be merged as an official extension to the Rust standard library under `std::simd`.
+* One under `std::arch` which follows the C intrinsics as much as possible
+* Another, `std::simd`, which provides a portable abstraction to SIMD programming so that code can be recompiled across different architectures with more or less the same results. While there are similar libraries for C and C++, this is different in that the intent is for it to be merged as an official extension to the Rust standard library under `std::simd`
 
 You will learn how to use both of these interfaces to write code that uses Advanced SIMD/Neon instructions on an Arm CPU.
 
 Before you start, make sure you have the [Rust compiler installed](/install-guides/rust). 
 
-You can check if you have a working `rustc` compiler installed by running the following command:
+To check if you have a working `rustc` compiler installed, run the following command:
 
 ```bash
 rustc --version
 ```
-Your output should look similar to the following:
+The output should look similar to:
 
 ```bash
 rustc 1.79.0 (129f3b996 2024-06-10)
@@ -50,15 +50,15 @@ Switch to the `nightly` version to `rustc` by running the following:
 rustup default nightly
 ```
 
-Now run the version command again to check if you have the right version:
+To check the version again, run:
 
 ```bash
 rustc --version
 ```
-Your output should now look similar to the following:
+The output should now look similar to:
 
 ```bash
 rustc 1.82.0-nightly (92c6c0380 2024-07-21)
 ```
 
-Now that you have a working Rust compiler with the features supported in the nightly version, you can continue with building and running the examples included in this learning path. Please note that the code examples in this learning path are not optimally written for Rust (to do that you would have to use `cargo`, find the proper `crates` to do specific tasks, for example for 2D arrays, which would increase the complexity of this learning path significantly).
+Now that you have a working Rust compiler with the features supported in the nightly version, you can continue with building and running the examples included in this Learning Path. The code examples in this Learning Path aren't optimally written for Rust (to do that you would have to use `cargo`, find the proper `crates` to do specific tasks, for example for 2D arrays, which would increase the complexity of this Learning Path significantly).

content/learning-paths/cross-platform/simd-on-rust/simd-on-rust-part1.md

@@ -8,9 +8,9 @@ layout: learningpathall
 
 ## Differences with programming with intrinsics in C and Rust
 
-As per the Arm Community blog post about [Neon Intrinsics in Rust](https://community.arm.com/arm-community-blogs/b/architectures-and-processors-blog/posts/rust-neon-intrinsics), there are some differences between C and Rust when programming with intrinsics which are listed in the blog and which will be expanded on in this Learning Path with code examples.
+As per the Arm Community blog post about [Neon Intrinsics in Rust](https://community.arm.com/arm-community-blogs/b/architectures-and-processors-blog/posts/rust-neon-intrinsics), there are some differences between C and Rust when programming with intrinsics which are listed in the blog and which you'll expand on in this Learning Path with code examples.
 
-We start with an example that uses Arm Advanced SIMD (Neon) intrinsics in C. Create a file named `average_neon.c` with the contents shown below. This program computes the average value of every pair of elements in 2 arrays:
+You'll start with an example that uses Arm Advanced SIMD (Neon) intrinsics in C. Create a file named `average_neon.c` with the contents shown below. This program computes the average value of every pair of elements in 2 arrays:
 
 ```C
 #include <stdio.h>
@@ -58,12 +58,12 @@ Compile the code as follows:
 ```bash
 gcc -O3 -fno-inline average_neon.c -o average_neon
 ```
-Now run the program as follows:
+Run the program:
 
 ```bash
 ./average_neon
 ```
-The output should look like the following:
+The output should look similar to:
 
 ```output
 A[0] = 2.00, B[0] = -9.00 -> C[0] = -3.50
@@ -77,7 +77,7 @@ A[7] = 16.00, B[7] = -30.00 -> C[7] = -7.00
 ...
 ```
 
-Note that the `-fno-inline` option was passed to the compiler. Use this option to prevent the C compiler from inlining the `average_vec` function. This is needed to compare the disassembly output of the `average_vec` function from the C version against the disassembly output from the Rust version. 
+Note that the `-fno-inline` option was passed to the compiler. Use this option to prevent the C compiler from inlining the `average_vec` function. You'll need this to compare the disassembly output of the `average_vec` function from the C version against the disassembly output from the Rust version. 
 
 Generate the disassembly output from the C version as shown below:
 
@@ -153,8 +153,7 @@ Run the program as follows:
 ```bash
 ./average1
 ```
-
-The output should look like the following:
+The output should look similar to:
 
 ```output
 A[0] = 2, B[0] = -9 -> C[0] = -3.5
@@ -170,15 +169,15 @@ A[7] = 16, B[7] = -30 -> C[7] = -7
 
 The outputs shown from these 2 versions are the same apart from the formatting.
 
-This particular example is not very complicated but you will notice some key differences between C and Rust already:
+This particular example isn't very complicated but you'll notice some key differences between C and Rust already:
 
-* Uninitialized variables - mutable/immutable arguments passed to the functions are not a concern for a C developer creating a proof of concept program. This is not the case with Rust programming, which forces the developer to think about these things right from the start. This usually means that it takes longer to write a simple program in Rust but you can be certain that this program will not suffer from trivial bugs such as buffer overflows, out of bounds, illegal conversions etc.
-* Conversions/Castings need to be explicit, e.g., `2.0_f32 * ((i+1) as f32)`.
-* There is no need to pass size as a parameter as Rust includes size information in its arrays.
+* Uninitialized variables - mutable/immutable arguments passed to the functions aren't a concern for a C developer creating a proof of concept program. This isn't the case with Rust programming, which forces the developer to think about these things right from the start. This usually means that it takes longer to write a program in Rust but you can be certain that this program won't suffer from trivial bugs such as buffer overflows, out of bounds, illegal conversions etc.
+* Conversions/Castings need to be explicit, for example `2.0_f32 * ((i+1) as f32)`
+* There's no need to pass size as a parameter as Rust includes size information in its arrays
 
-Note that this program is not written in the most optimal way for Rust. It is just a 'port' of the C program into Rust with the minimal changes needed to compile and run.
+Note that this program isn't written in the most optimal way for Rust. It's a 'port' of the C program into Rust with the minimal changes needed to compile and run.
 
-The next step is to use SIMD intrinsics in your Rust program for the averaging loop. Replace the previous `average_vec` function with the function shown below and save the updated contents in a file named `average2.rs` as shown below:
+The next step is to use SIMD intrinsics in your Rust program for the averaging loop. Replace the previous `average_vec` function with the function shown below and save the updated contents in a file named `average2.rs`:
 
 ```Rust
 #[inline(never)]
@@ -234,12 +233,11 @@ A[6] = 14, B[6] = -27 -> C[6] = -6.5
 A[7] = 16, B[7] = -30 -> C[7] = -7
 ...
 ```
-
 The results are the same but let's look at some of the differences:
 
-* You need to use `target_arch` and `target_feature` to use specific hardware extensions. This is Rust's feature detection which is explained in more detail in the next section.
-* All definitions and functions need to be enabled with `use`, either selectively, for example `use std::arch::aarch64::float32x4_t` or with a wildcard `use std::arch::aarch64::*`. If in doubt, use the latter.
-* You will notice `#[inline(never)]` in the definition of `average_vec`. This is to let the compiler know that it should not inline this function because you will compare the disassembly against the C version.
+* You need to use `target_arch` and `target_feature` to use specific hardware extensions. This is Rust's feature detection which is explained in more detail in the next section
+* All definitions and functions need to be enabled with `use`, either selectively, for example `use std::arch::aarch64::float32x4_t` or with a wildcard `use std::arch::aarch64::*`. If in doubt, use the latter
+* You'll notice `#[inline(never)]` in the definition of `average_vec`. This is to let the compiler know that it shouldn't inline this function because you'll compare the disassembly against the C version
 
 Now generate the disassembly output for `average2`as follows:
 

content/learning-paths/cross-platform/simd-on-rust/simd-on-rust-part2.md

@@ -8,7 +8,7 @@ layout: learningpathall
 
 ## An example with dot product instructions
 
-You can now continue with an example around `dotprod` intrinsics. Shown below is a program that calculates the sum of absolute differences (SAD) of a 32x32 array of 8-bit unsigned integers (`uint8_t`) using the `vdotq_u32` intrinsic. Save the contents in a file named `dotprod1.c` as shown below:
+You can now continue with an example around `dotprod` intrinsics. Shown below is a program that calculates the sum of absolute differences (SAD) of a 32x32 array of 8-bit unsigned integers (`uint8_t`) using the `vdotq_u32` intrinsic. Save the contents in a file named `dotprod1.c`:
 
 ```C
 #include <stdio.h>
@@ -59,17 +59,17 @@ int main() {
 }
 ```
 
-Now compile the program as follows:
+Compile the program as follows:
 
 ```bash 
 gcc -O3 -march=armv8.2-a+dotprod dotprod1.c -o dotprod1
 ```
 
-And run the program as per below:
+Run the program:
 ```bash
 ./dotprod1
 ```
-The output should look like the following:
+The output should look similar to:
 ```output
 A[0] = [ 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f ]
 B[0] = [ 00 00 00 00 04 04 04 04 00 00 00 00 04 04 04 04 00 00 00 00 04 04 04 04 00 00 00 00 04 04 04 04 ]
@@ -198,12 +198,12 @@ Compile the program as follows:
 rustc -O dotprod2.rs
 ```
 
-Run the program as per below:
+Run the program:
 ```bash
 ./dotprod2
 ```
 
-The output should look like the following:
+The output should look similar to:
 
 ```output
 A[0] = [ 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f ]
@@ -220,11 +220,11 @@ sad = 7400
 
 As you can see both executables produce the same output.
 
-Now generate the disassembly output as shown below:
+Generate the disassembly output:
 ```bash
 objdump -S dotprod2
 ```
-The output should look like the following:
+The output should look similar to:
 ```asm
 0000000000006394 <_ZN4core9core_arch10arm_shared4neon9generated9vdotq_u3217h5c7bc8d63e4a993fE>:
     6394:       3dc00000        ldr     q0, [x0]
@@ -275,11 +275,11 @@ The output should look like the following:
     6724:       d65f03c0        ret
 ```
 
-Note that where you might expect to see a `udot` instruction, there is a `bl` instruction which indicates a branch. The `udot` instruction is instead called in another function, which carries out the loads again.
+Note that where you might expect to see a `udot` instruction, there's a `bl` instruction which indicates a branch. The `udot` instruction is instead called in another function, which carries out the loads again.
 
 This seems counter-intuitive but the reason is that, unlike C, Rust treats the intrinsics like normal functions.
 
-Like functions, inlining them is not always guaranteed. If it is possible to inline the intrinsic, code generation and performance would be almost as that with C. If it is not possible, you might find that the same code in Rust performs worse than in C.
+Like functions, inlining them isn't always guaranteed. If it's possible to inline the intrinsic, code generation and performance would be almost as that with C. If it's not possible, you might find that the same code in Rust performs worse than in C.
 
 Because of this, you have to look carefully at the disassembly generated from your SIMD Rust code. So, how can you fix this behavior and get the expected generated code?
 
@@ -337,5 +337,5 @@ Now look at the changed disassembly output as follows:
     66bc:       d65f03c0        ret
 ```
 
-This disassembly output is now as you would expect it to be as well as being better performant. You will see that the compiler automatically unrolled the loop twice because it was able to figure out that the number of iterations was small. Increasing the iterations will probably disable aggressive unrolling but it will at least inline the intrinsics properly.
+This disassembly output is now as you would expect it to be as well as being better performant. You'll see that the compiler automatically unrolled the loop twice because it was able to figure out that the number of iterations was small. Increasing the iterations will probably disable aggressive unrolling but it will at least inline the intrinsics properly.