Merge pull request #1590 from madeline-underwood/sme_maddy_review

SME2_Andy to check

Author: pareenaverma

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

@@ -0,0 +1,212 @@
+---
+title: Set up your Environment
+weight: 3
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## Installing software for this Learning Path
+
+To follow this Learning Path, you will need to set up an environment to develop with SME2.
+
+You will require:
+
+ - A compiler with support for SME2 instructions. 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``.
+
+ - An emulator to execute code with the SME2 instructions. This Learning
+   Path uses [Arm's Fixed Virtual Platform (FVP) model](https://developer.arm.com/Tools%20and%20Software/Fixed%20Virtual%20Platforms).
+
+You will also require Git and Docker installed on your machine.
+
+### Set up Git
+
+To check if Git is already installed on your machine, use the following command line in a terminal:
+
+```BASH { output_lines=2 }
+git --version
+git version 2.47.1
+```
+
+If the above command line fails with a message similar to "``git: command not found``", then install Git following the steps for your machine's OS.
+
+{{< tabpane code=true >}}
+  {{< tab header="Linux/Ubuntu" language="bash">}}
+sudo apt install git
+  {{< /tab >}}
+  {{< tab header="macOS" language="bash">}}
+brew install git
+  {{< /tab >}}
+{{< /tabpane >}}
+
+### Docker
+
+To enable you to get started easily and with the tools that you need, you can fetch a Docker container with the required compiler and FVP. Alternatively, if you do wish to build the container yourself, the ``Dockerfile`` is also available.
+
+
+{{% notice Note %}}
+This Learning Path works without ``docker``, but the compiler and the FVP must be available in your search path.
+{{% /notice %}}
+
+Start by checking that ``docker`` is installed on your machine by typing the following
+command line in a terminal:
+
+```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/).
+
+{{% notice Note %}}
+You might need to login 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:
+
+```BASH { output_lines="2-27" }
+docker run hello-world
+Unable to find image 'hello-world:latest' locally
+latest: Pulling from library/hello-world
+478afc919002: Pull complete
+Digest: sha256:305243c734571da2d100c8c8b3c3167a098cab6049c9a5b066b6021a60fcb966
+Status: Downloaded newer image for hello-world:latest
+
+Hello from Docker!
+This message shows that your installation appears to be working correctly.
+
+To generate this message, Docker followed these steps:
+ 
+ 1. The Docker client contacted the Docker daemon.
+ 
+ 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
+    (arm64v8)
+ 
+ 3. The Docker daemon created a new container from that image which runs the
+    executable that produces the output you are currently reading.
+ 
+ 4. The Docker daemon streamed that output to the Docker client, which sent it
+    to your terminal.
+
+To try something more ambitious, you can run an Ubuntu container with:
+ $ docker run -it ubuntu bash
+
+Share images, automate workflows, and more with a free Docker ID:
+ https://hub.docker.com/
+
+For more examples and ideas, visit:
+ https://docs.docker.com/get-started/
+```
+
+## Environment
+
+Now, using Git, clone the environment for experimenting with SME2 to a directory
+named ``SME2.git``:
+
+```BASH
+git clone  https://gitlab.arm.com/learning-code-examples/TODO_SOME_PATH SME2-learning-path.git
+```
+
+This list of content in the repository should look like this :
+
+```TXT
+SME2-learning-path.git/
+├── .clang-format
+├── .devcontainer/
+│   └── devcontainer.json
+├── .git/
+├── .gitignore
+├── Makefile
+├── README.rst
+├── docker/
+│   ├── assets.source_me
+│   ├── build-all-containers.sh
+│   ├── build-my-container.sh
+│   └── sme2-environment.docker
+├── hello.c
+├── main.c
+├── matmul.h
+├── matmul_asm.c
+├── matmul_asm_impl.S
+├── matmul_intr.c
+├── matmul_vanilla.c
+├── misc.c
+├── misc.h
+├── preprocess_l_asm.S
+├── preprocess_vanilla.c
+├── run-fvp.sh
+└── sme2_check.c
+```
+
+It contains:
+- Code examples.
+- A ``Makefile`` that builds the code examples.
+- A shell script called ``run-fvp.sh`` that runs the FVP.
+- 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 however, as ready-made images are made 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``.
+
+The next step is to change directory to your checkout:
+
+```BASH
+cd SME2-learning-path.git
+```
+{{% notice Note %}}
+From this point in the Learning Path, all instructions assume that your current
+directory is ``SME2-learning-path.git``.{{% /notice %}}
+
+
+## Using the environment
+
+Docker containers provide you with the functionality to execute commands in an isolated environment, where you have all the necessary tools that you require without having to clutter your machine. The containers runs independently, which means that they do not interfere with other containers on the same machine or server.  
+
+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 run all the commands inside a Docker container, allowing you to work seamlessly within the Docker environment.
+
+### Working from a terminal
+
+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 the container. 
+
+For example, to execute ``COMMAND ARGUMENTS`` in the SME2 Docker container, the command line looks like this:
+
+```SH
+docker run --rm -v "$PWD:/work" -w /work armswdev/sme2-learning-path:sme2-environment-v1 COMMAND ARGUMENTS
+```
+
+This invokes Docker, using the
+``armswdev/sme2-learning-path:sme2-environment-v1``container
+image, and mounts the current working directory (the ``SME2-learning-path.git``)
+inside the container to ``/work``, then sets ``/work`` as the
+working directory and runs ``COMMAND ARGUMENTS`` in this environment.
+
+For example, to run ``make``, you need to enter:
+
+```SH
+docker run --rm -v "$PWD:/work" -w /work armswdev/sme2-learning-path:sme2-environment-v1 make
+```
+
+### Working from within the Docker container
+
+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. 
+
+It automatically finds and uses ``.devcontainer/devcontainer.json``:
+
+![example image 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. However, if you are using VS Code, you only need to use the `COMMAND ARGUMENTS` part. 
+{{% /notice %}}

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

@@ -0,0 +1,173 @@
+---
+title: Test your environment
+weight: 4
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+In this section, you will check that your environment is all set up and ready to develop with SME2. This will be your first hands-on experience with the environment.
+
+## Compile the examples
+
+First, compile the example code with Clang:
+
+```BASH { output_lines="2-19" }
+docker run --rm -v "$PWD:/work" -w /work armswdev/sme2-learning-path:sme2-environment-v1 make
+clang --target=aarch64-none-elf -march=armv9.4-a+sme2 -fno-exceptions -fno-rtti -mno-unaligned-access -O2 -Wall -std=c99 -nostartfiles -lcrt0-semihost -lsemihost -Wl,--defsym=__boot_flash=0x80000000 -Wl,--defsym=__flash=0x80001000 -Wl,--defsym=__ram=0x81000000 -T picolibc.ld -o hello hello.c
+clang --target=aarch64-none-elf -march=armv9.4-a+sme2 -fno-exceptions -fno-rtti -mno-unaligned-access -O2 -Wall -std=c99 -c -o sme2_check.o sme2_check.c
+clang --target=aarch64-none-elf -march=armv9.4-a+sme2 -fno-exceptions -fno-rtti -mno-unaligned-access -O2 -Wall -std=c99 -c -o misc.o misc.c
+clang --target=aarch64-none-elf -march=armv9.4-a+sme2 -fno-exceptions -fno-rtti -mno-unaligned-access -O2 -Wall -std=c99 -nostartfiles -lcrt0-semihost -lsemihost -Wl,--defsym=__boot_flash=0x80000000 -Wl,--defsym=__flash=0x80001000 -Wl,--defsym=__ram=0x81000000 -T picolibc.ld -o sme2_check sme2_check.o misc.o
+clang --target=aarch64-none-elf -march=armv9.4-a+sme2 -fno-exceptions -fno-rtti -mno-unaligned-access -O2 -Wall -std=c99 -DIMPL=asm -c -o main_asm.o main.c
+clang --target=aarch64-none-elf -march=armv9.4-a+sme2 -fno-exceptions -fno-rtti -mno-unaligned-access -O2 -Wall -std=c99 -c -o matmul_asm.o matmul_asm.c
+clang --target=aarch64-none-elf -march=armv9.4-a+sme2 -fno-exceptions -fno-rtti -mno-unaligned-access -O2 -Wall -std=c99 -c -o matmul_asm_impl.o matmul_asm_impl.S
+clang --target=aarch64-none-elf -march=armv9.4-a+sme2 -fno-exceptions -fno-rtti -mno-unaligned-access -O2 -Wall -std=c99 -c -o preprocess_l_asm.o preprocess_l_asm.S
+clang --target=aarch64-none-elf  -fno-exceptions -fno-rtti -mno-unaligned-access -O2 -Wall -std=c99 -c -o matmul_vanilla.o matmul_vanilla.c
+clang --target=aarch64-none-elf  -fno-exceptions -fno-rtti -mno-unaligned-access -O2 -Wall -std=c99 -c -o preprocess_vanilla.o preprocess_vanilla.c
+clang --target=aarch64-none-elf -march=armv9.4-a+sme2 -fno-exceptions -fno-rtti -mno-unaligned-access -O2 -Wall -std=c99 -nostartfiles -lcrt0-semihost -lsemihost -Wl,--defsym=__boot_flash=0x80000000 -Wl,--defsym=__flash=0x80001000 -Wl,--defsym=__ram=0x81000000 -T picolibc.ld -o sme2_matmul_asm main_asm.o matmul_asm.o matmul_asm_impl.o preprocess_l_asm.o matmul_vanilla.o preprocess_vanilla.o misc.o
+clang --target=aarch64-none-elf -march=armv9.4-a+sme2 -fno-exceptions -fno-rtti -mno-unaligned-access -O2 -Wall -std=c99 -DIMPL=intr -c -o main_intr.o main.c
+clang --target=aarch64-none-elf -march=armv9.4-a+sme2 -fno-exceptions -fno-rtti -mno-unaligned-access -O2 -Wall -std=c99 -c -o matmul_intr.o matmul_intr.c
+clang --target=aarch64-none-elf -march=armv9.4-a+sme2 -fno-exceptions -fno-rtti -mno-unaligned-access -O2 -Wall -std=c99 -nostartfiles -lcrt0-semihost -lsemihost -Wl,--defsym=__boot_flash=0x80000000 -Wl,--defsym=__flash=0x80001000 -Wl,--defsym=__ram=0x81000000 -T picolibc.ld -o sme2_matmul_intr main_intr.o matmul_intr.o matmul_vanilla.o preprocess_vanilla.o misc.o
+llvm-objdump --demangle -d hello > hello.lst
+llvm-objdump --demangle -d sme2_check > sme2_check.lst
+llvm-objdump --demangle -d sme2_matmul_asm > sme2_matmul_asm.lst
+llvm-objdump --demangle -d sme2_matmul_intr > sme2_matmul_intr.lst
+```
+
+ Executed within the docker ``armswdev/sme2-learning-path:sme2-environment-v1`` environment, the ``make`` command performs the following tasks:
+
+- It builds four executables: ``hello``, ``sme2_check``, ``sme2_matmul_asm``, and ``sme2_matmul_intr``.
+- It creates the assembly listings for the four executables: ``hello.lst``, ``sme2_check.lst``, ``sme2_matmul_asm.lst``, and ``sme2_matmul_intr.lst``.
+
+{{% notice Note %}}
+At any point, you can clean the directory of all the files that have been built by invoking the ``make clean`` target:
+
+```BASH
+$ docker run --rm -v "$PWD:/work" -w /work armswdev/sme2-learning-path:sme2-environment-v1 make clean
+```
+{{% /notice %}}
+
+## Basic checks
+
+The very first program that you should run is the famous "Hello, world !" example that
+will tell you if your environment is set up correctly. 
+
+The source code is contained in ``hello.c`` and looks like this:
+
+```C
+#include <stdio.h>
+#include <stdlib.h>
+
+int main(int argc, char *argv[]) {
+    printf("Hello, world !\n");
+    return EXIT_SUCCESS;
+}
+```
+
+Run the FVP simulation of the ``hello`` program with:
+
+```BASH { output_lines="2-4" }
+docker run --rm -v "$PWD:/work" -w /work armswdev/sme2-learning-path:sme2-environment-v1 ./run-fvp.sh hello
+Hello, world !
+
+Info: /OSCI/SystemC: Simulation stopped by user.
+```
+
+The important line here is "``Hello, world !``" as it demonstrates that the generic code
+can be compiled and run on the FVP.
+
+## SME2 checks
+
+You will now run the ``sme2_check`` program, which checks that SME2 works as
+expected, in both the compiler and in the FVP. 
+
+The source code is found in
+``sme2_check.c``:
+
+```C
+#include <stdio.h>
+#include <stdlib.h>
+
+#include "misc.h"
+
+#ifdef __ARM_FEATURE_SME2
+#include <arm_sme.h>
+#else
+#error __ARM_FEATURE_SME2 is not defined
+#endif
+
+#define get_cpu_ftr(regId, feat, msb, lsb)                                     \
+    ({                                                                         \
+        unsigned long __val;                                                   \
+        __asm__("mrs %0, " #regId : "=r"(__val));                              \
+        printf("%-20s: 0x%016lx\n", #regId, __val);                            \
+        printf("  - %-10s: 0x%08lx\n", #feat,                                  \
+               (__val >> lsb) & ((1 << (msb - lsb)) - 1));                     \
+    })
+
+int main(int argc, char *argv[]) {
+    get_cpu_ftr(ID_AA64PFR0_EL1, SVE, 35, 32);
+    get_cpu_ftr(ID_AA64PFR1_EL1, SME, 27, 24);
+
+    int n = 0;
+#ifdef __ARM_FEATURE_SME2
+    setup_sme();
+    n = svcntb() * 8;
+#endif
+    if (n) {
+        printf("SVE is available with length %d\n", n);
+    } else {
+        printf("SVE is unavailable.\n");
+        exit(EXIT_FAILURE);
+    }
+
+    printf("Checking has_sme: %d\n", __arm_has_sme());
+    printf("Checking in_streaming_mode: %d\n", __arm_in_streaming_mode());
+
+    printf("Starting streaming mode...\n");
+    __asm__("smstart");
+
+    printf("Checking in_streaming_mode: %d\n", __arm_in_streaming_mode());
+
+    printf("Stopping streaming mode...\n");
+    __asm__("smstop");
+
+    printf("Checking in_streaming_mode: %d\n", __arm_in_streaming_mode());
+
+    return EXIT_SUCCESS;
+}
+```
+
+The ``sme2_check`` program displays the SVE field of the ``ID_AA64PFR0_EL1`` system register and the SME field of the ``ID_AA64PFR1_EL1`` system register. It will then check if SVE and SME are available, then finally will switch into streaming mode and back from streaming mode.  
+
+The ``__ARM_FEATURE_SME2`` macro is provided by the compiler when it targets an SME-capable target, which is specified with the ``-march=armv9.4-a+sme2`` command line option to ``clang`` in
+file ``Makefile``. 
+
+The ``arm_sme.h`` include file is part of the Arm C Library
+Extension ([ACLE](https://arm-software.github.io/acle/main/)). 
+
+The ACLE provides types and function declarations to enable C/C++ programmers to make the best possible use of the Arm architecture. You can use the SME-related part of the library, but it does also provide support for Neon or other Arm architectural extensions.
+
+```BASH
+docker run --rm -v "$PWD:/work" -w /work armswdev/sme2-learning-path:sme2-environment-v1 ./run-fvp.sh sme2_check
+```
+
+The output should be similar to:
+
+```TXT
+ID_AA64PFR0_EL1     : 0x1101101131111112
+  - SVE       : 0x00000001
+ID_AA64PFR1_EL1     : 0x0000101002000001
+  - SME       : 0x00000002
+SVE is available with length 512
+Checking has_sme: 1
+Checking in_streaming_mode: 0
+Starting streaming mode...
+Checking in_streaming_mode: 1
+Stopping streaming mode...
+Checking in_streaming_mode: 0
+
+Info: /OSCI/SystemC: Simulation stopped by user.
+```
+
+You have now checked that the code can be compiled and run with full SME2 support, and are all set to move to the next section.