Merge pull request #2110 from madeline-underwood/SME_Jul

SME2_JA to review

Author: jasonrandrews

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

@@ -1,33 +1,33 @@
 ---
-title: Set up your Environment
+title: Set up your SME2 development environment
 weight: 3
 
 ### FIXED, DO NOT MODIFY
 layout: learningpathall
 ---
 
-To follow this Learning Path, you will need to set up an environment to develop
-with SME2 and download the code examples. This learning path assumes two
-different ways of working, and you will need to select the one appropriate for
-your machine:
-- Case #1: Your machine has native SME2 support --- check the [list of devices
-  with SME2 support](#devices-with-sme2-support).
-- Case #2: Your machine does not have native SME2 support. This learning path
-  supports this use case by enabling you to run code with SME2 instructions in
-  an emulator in bare metal mode, i.e., the emulator runs the SME2 code
-  *without* an operating system.
+## Choose your SME2 setup: native or emulated
 
-## Code examples
+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:
 
-[Download the code examples](https://gitlab.arm.com/learning-code-examples/code-examples/-/archive/main/code-examples-main.tar.gz?path=learning-paths/cross-platform/multiplying-matrices-with-sme2) for this learning path, expand the archive, and change your current directory to:
-``code-examples/learning-paths/cross-platform/multiplying-matrices-with-sme2`` :
+* [**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-docker) - use a container to emulate SME2 in bare metal mode (without an OS).
+
+## Download and explore the code examples
+
+To get started, begin by [downloading the code examples](https://gitlab.arm.com/learning-cde-examples/code-examples/-/archive/main/code-examples-main.tar.gz?path=learning-paths/cross-platform/multiplying-matrices-with-sme2).
+
+Now extract the archive, and change directory to:
+``code-examples/learning-paths/cross-platform/multiplying-matrices-with-sme2.``
 
 ```BASH
 tar xfz code-examples-main-learning-paths-cross-platform-multiplying-matrices-with-sme2.tar.gz -s /code-examples-main-learning-paths-cross-platform-multiplying-matrices-with-sme2/code-examples/
 cd code-examples/learning-paths/cross-platform/multiplying-matrices-with-sme2
 ```
 
-The listing of the content of this directory should look like this:
+The directory structure should look like this:
 
 ```TXT
 code-examples/learning-paths/cross-platform/multiplying-matrices-with-sme2/
@@ -58,48 +58,36 @@ code-examples/learning-paths/cross-platform/multiplying-matrices-with-sme2/
 └── sme2_check.c
 ```
 
-It contains:
-- The code examples that will be used throughout this learning path.
-- A ``Makefile`` that builds the code examples.
-- A shell script called ``run-fvp.sh`` that runs the FVP (used in the emulated
-  SME2 case).
-- A directory called ``docker`` that contains materials related to Docker, which
-  are:
-  - A script called ``assets.source_me`` that provides the FVP and compiler
-    toolchain references.
-  - A Docker recipe called ``sme2-environment.docker`` to build the container
-    that you will use.
-  - A shell script called ``build-my-container.sh`` that you can use if you want
-    to build the Docker container. This is not essential; ready-made images are
-    available for you.
-  - A script called ``build-all-containers.sh`` that was used to create the
-    image for you to download to provide multi-architecture support for both
-    x86_64 and AArch64.
-- A configuration script for VS Code to be able to use the container from the
-  IDE called ``.devcontainer/devcontainer.json``.
+Amongst other files, it includes:
+- Code examples.
+- A `Makefile` to build the code.
+- `run-fvp.sh` to run the FVP model.
+- 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 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.
 
 {{% notice Note %}}
-From this point in the Learning Path, all instructions assume that your current
-directory is
-``code-examples/learning-paths/cross-platform/multiplying-matrices-with-sme2``.
+From this point, all instructions assume that your current directory is
+``code-examples/learning-paths/cross-platform/multiplying-matrices-with-sme2``, so ensure that you are in the correct directory before proceeding.
 {{% /notice %}}
 
-## Platforms with native SME2 support
+## Set up a system with native SME2 support
+
+To run SME2 code natively, ensure your system includes SME2 hardware and uses a compiler version that supports SME2.
+
+For the compiler, you can use [Clang](https://www.llvm.org/) version 18 or later, or [GCC](https://gcc.gnu.org/) version 14 or later. This Learning Path uses ``clang``.
+
+{{% notice Note %}}
+At the time of writing, macOS ships with `clang` version 17.0.0, which doesn't support SME2. Use a newer version, such as 20.1.7, available through Homebrew.{{% /notice%}}
 
-If your machine has native support for SME2, then you only need to ensure that
-you have a compiler with support for SME2 instructions.
+You can check your compiler version using the command:``clang --version``
 
-A recent enough version of the compiler is required because SME2 is a recent
-addition to the Arm instruction set. Compiler versions that are too old will
-have incomplete or no SME2 support, leading to compilation errors or
-non-functional code. You can use [Clang](https://www.llvm.org/) version 18 or
-later, or [GCC](https://gcc.gnu.org/) version 14 or later. This Learning Path
-uses ``clang``.
+### Install Clang
 
-At the time of writing, the ``clang`` version shipped with macOS is ``17.0.0``,
-which forces us to use the version from ``homebrew`` (which has version
-``20.1.7``). Ensure the ``clang`` compiler you are using is recent enough with
-``clang --version``:
+Install Clang using the instructions below, selecting either macOS or Linux/Ubuntu, depending on your setup:
 
 {{< tabpane code=true >}}
 
@@ -113,52 +101,40 @@ which forces us to use the version from ``homebrew`` (which has version
 
 {{< /tabpane >}}
 
-You are now all set to start hacking with SME2!
+You are now all set to start hacking with SME2.
 
-## Platforms with emulated SME2 support
+## Set up a system using SME2 emulation with Docker
 
-If your machine does not have SME2 support or if you want to run SME2 with an
-emulator, you will need to install Docker. Docker containers provide
-functionality to execute commands in an isolated environment, where you have all
-the necessary tools you require without cluttering your machine. The containers
-run independently, meaning they do not interfere with other containers on the
-same machine or server.
+If your machine doesn't support SME2, or you want to emulate it, you can use the Docker-based environment that this Learning Path models.
 
-This learning path provides a Docker image that has a compiler and [Arm's Fixed
-Virtual Platform (FVP)
+The Docker container includes both a compiler and [Arm's Fixed Virtual Platform (FVP)
 model](https://developer.arm.com/Tools%20and%20Software/Fixed%20Virtual%20Platforms)
-for emulating code with SME2 instructions. The Docker image recipe is provided
-(with the code examples) so you can study it and build it yourself. You could
-also decide not to use the Docker image and follow the
-``sme2-environment.docker`` Docker file instructions to install the tools on
-your machine.
+for emulating code that uses SME2 instructions. You can either run the prebuilt container image provided in this Learning Path or build it yourself using the Docker file that is included. 
 
-### Docker
+If building manually, follow the instructions in the ``sme2-environment.docker`` file to install the required tools on your machine.
+
+### Install and verify Docker
 
 {{% notice Note %}}
-This Learning Path works without ``docker``, but the compiler and the FVP must
-be available in your search path.
+Docker is optional, but if you don’t use it, you must manually install the compiler and FVP, and ensure they’re in your `PATH`.
 {{% /notice %}}
 
-Start by checking that ``docker`` is installed on your machine by typing the
-following command line in a terminal:
+To begin, start by checking that Docker is installed on your machine:
 
 ```BASH { output_lines="2" }
 docker --version
 Docker version 27.3.1, build ce12230
 ```
 
-If the above command fails with a message similar to "``docker: command not
-found``" then follow the steps from the [Docker Install
-Guide](https://learn.arm.com/install-guides/docker/).
+If the above command fails with an error message similar to "``docker: command not found``", then follow the steps from the [Docker Install Guide](https://learn.arm.com/install-guides/docker/) to install Docker.
 
 {{% notice Note %}}
-You might need to log in again or restart your machine for the changes to take
+You might need to log out and back in again or restart your machine for the changes to take
 effect.
 {{% /notice %}}
 
 Once you have confirmed that Docker is installed on your machine, you can check
-that it is operating normally with the following:
+that it is working with the following:
 
 ```BASH { output_lines="2-27" }
 docker run hello-world
@@ -201,13 +177,12 @@ https://docs.docker.com/get-started/
 ```
 
 You can use Docker in the following ways:
-- Directly from the command line. For example, when you are working from a
-  terminal on your local machine.
-- Within a containerized environment. Configure VS Code to execute all the
-  commands inside a Docker container, allowing you to work seamlessly within the
-  Docker environment.
+- [Directly from the command line](#run-commands-from-a-terminal-using-docker) - for example, when you are working from a terminal on your local machine.
+
+- [Within a containerized environment](#use-an-interactive-docker-shell) - by configuring VS Code to execute all the commands inside a Docker container, allowing you to work seamlessly within the
+Docker environment.
 
-### Working with Docker from a terminal
+### Run commands from a terminal using Docker
 
 When a command is executed in the Docker container environment, you must prepend
 it with instructions on the command line so that your shell executes it within
@@ -233,64 +208,88 @@ For example, to run ``make``, you need to enter:
 docker run --rm -v "$PWD:/work" -w /work armswdev/sme2-learning-path:sme2-environment-v2 make
 ```
 
-### Working within the Docker container from the terminal
+### Use an interactive Docker shell
 
-The above commands are long and error-prone, so you can instead choose to work
-interactively within the terminal, which would save you from prepending the
-``docker run ...`` magic before each command you want to execute. To work in
-this mode, run Docker without any command (note the ``-it`` command line
-argument to the Docker invocation):
+The standard `docker run` commands can be long and repetitive. To streamline your workflow, you can start an interactive Docker session that allows you to run commands directly - without having to prepend docker run each time.
+
+To launch an interactive shell inside the container, use the `-it` flag:
 
 ```BASH
 docker run --rm -it -v "$PWD:/work" -w /work armswdev/sme2-learning-path:sme2-environment-v2
 ```
 
-You are now in the Docker container; you can execute all commands directly. For
+You are now in the Docker container, and you can execute all commands directly. For
 example, the ``make`` command can now be simply invoked with:
 
 ```BASH
 make
 ```
 
-To exit the container, simply hit CTRL+D. Note that the container is not
-persistent (it was invoked with ``--rm``), so each invocation will use a
-container freshly built from the image. All the files reside outside the
-container, so changes you make to them will be persistent.
+To exit the container, simply hit CTRL+D. Note that the container is not persistent (it was invoked with ``--rm``), so each invocation will use a container freshly built from the image. All the files reside outside the container, so changes you make to them will be persistent.
 
-### Working within the Docker container with VSCode
+###  Develop with Docker in Visual Studio Code
 
-If you are using Visual Studio Code as your IDE, it can use the container as is.
+If you are using Visual Studio Code as your IDE, the container setup is already configured with `devcontainer/devcontainer.json`.
 
 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``:
 
-![example image alt-text#center](VSCode.png "Figure 1: Setting up the Docker Container.")
+![VSCode Docker alt-text#center](VSCode.png "Figure 1: Setting up the Docker container.")
 
 All your commands now run within the container, so there is no need to prepend
 them with a Docker invocation, as VS Code handles all this seamlessly for you.
 
 {{% notice Note %}}
 For the rest of this Learning Path, shell commands include the full Docker
-invocation so that users not using VS Code can copy the complete command line.
+invocation so that if you are not using VS Code you can copy the complete command line.
 However, if you are using VS Code, you only need to use the `COMMAND ARGUMENTS`
 part.
 {{% /notice %}}
 
-### Devices with SME2 support
+### Devices with native SME2 support
+
+These Apple devices support SME2 natively.
+
+- iPad
+
+  - iPad Pro 11"
+
+  - iPad Pro 13"
+
+- iPhone
+
+  - iPhone 16
+
+  - iPhone 16 Plus
+
+  - iPhone 16e
+
+  - iPhone 16 Pro
+
+  - iPhone 16 Pro Max
+
+- iMac
+
+- MacBook Air
+
+  - MacBook Air 13"
+
+  - MacBook Air 15"
+
+- Mac mini
+
+
+
+- MacBook Pro
+
+  - MacBook Pro 14"
+
+  - MacBook Pro 16"
 
-By chip:
+- Mac Studio
 
-| Manufacturer | Chip   | Devices |
-|--------------|--------|---------|
-| Apple        | M4     | iPad Pro 11" & 13", iMac, Mac mini, MacBook Air 13" & 15"|
-| Apple        | M4 Pro | Mac mini, MacBook Pro 14" & 16" |
-| Apple        | M4 Max | MacBook Pro 14" & 16", Mac Studio |
 
-By product:
 
-| Manufacturer | Product family | Models |
-|--------------|----------------|--------|
-| Apple        | iPhone 16      | iPhone 16, iPhone 16 Plus, iPhone 16e, iPhone 16 Pro, iPhone 16 Pro Max |