You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This Learning Path demonstrates how to use SME2 on macOS on a device with an M4 chip. It does not provide instructions for using SME2 on iPhone or iPad, even though they have SME2 support.
12
+
This Learning Path demonstrates how to use SME2 on macOS on a device with an M4 chip, or on some Android phones that have SME2 support. It does not provide instructions for using SME2 on iPhone or iPad, even though they have SME2 support.
13
13
{{< /notice >}}
14
14
15
15
To build or run SME2-accelerated code, first set up your development environment.
16
16
This section walks you through the required tools and two supported setup options:
17
17
18
18
*[**Native SME2 hardware**](#native-sme2) - build and run directly on a system with SME2 support, see [Devices with native SME2 support](#devices)
19
19
20
+
*[**Android with SME2 hardware**](#android-sme2) - cross build and run on Android phones with SME2 support, see [Devices with native SME2 support](#devices)
21
+
20
22
*[**Docker-based emulation**](#docker-sme2) - use a container to emulate SME2 in bare metal mode (without an OS)
21
23
22
24
## Download and explore the code examples
23
25
24
-
To get started, begin by [downloading the code examples](https://gitlab.arm.com/learning-code-examples/code-examples/-/archive/d41190c0cf962f778ae71b94adf5330033019aed/code-examples-d41190c0cf962f778ae71b94adf5330033019aed.tar.gz?path=learning-paths/cross-platform/multiplying-matrices-with-sme2).
26
+
To get started, begin by [downloading the code examples](https://gitlab.arm.com/learning-code-examples/code-examples/-/archive/2632d7cae67fc1ce6b43438a38e00b9edb78f5d9/code-examples-2632d7cae67fc1ce6b43438a38e00b9edb78f5d9.tar.gz?path=learning-paths/cross-platform/multiplying-matrices-with-sme2).
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/
- A `CMakeLists.txt` to build the code together with a `cmake/` subdirectory that contains the toolchain file needed for baremetal builds as well as some function to hide some cmake details from the top-level `CMakeLists.txt`.
68
73
-`run-fvp.sh` to run the FVP model.
69
74
- A `docker` directory containing:
70
-
-`assets.source_me` to provide toolchain paths.
75
+
-`assets.source_me` to provide tools information like versions and paths.
71
76
-`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.
72
77
-`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.
73
-
-`build-all-containers.sh`, a script to build multi-architecture images.
78
+
-`build-all-containers.sh`, a script to build multi-architecture images. It's the script that has been used to build the docker images for this Learning Path.
74
79
-`.devcontainer/devcontainer.json` for VS Code container support.
75
80
76
81
{{% notice Note %}}
77
82
From this point, all instructions assume that your current directory is
78
-
``code-examples/learning-paths/cross-platform/multiplying-matrices-with-sme2``, so ensure that you are in the correct directory before proceeding.
83
+
`code-examples/learning-paths/cross-platform/multiplying-matrices-with-sme2/`, so ensure that you are in the correct directory before proceeding.
79
84
{{% /notice %}}
80
85
86
+
The build system is `cmake` based and we will use `ninja` as the build tool in this learning path. If you don't have hardware with SME2 support available and are going to use **Docker-based emulation**, then there is nothing to do, as `cmake` and `ninja` have already been installed for you in the docker container. If you're going to target **Native SME2 hardware** or **Android with SME2 hardware**, you first have to install them if they are not already available on your system:
87
+
88
+
{{< tabpane code=true >}}
89
+
90
+
{{< tab header="Linux/Ubuntu" language="bash">}}
91
+
sudo apt install cmake ninja-build
92
+
{{< /tab >}}
93
+
94
+
{{< tab header="macOS" language="bash">}}
95
+
brew install cmake ninja
96
+
{{< /tab >}}
97
+
98
+
{{< /tabpane >}}
99
+
81
100
## Set up a system with native SME2 support {#native-sme2}
82
101
83
102
To run SME2 code natively, ensure your system includes SME2 hardware and uses a compiler version that supports SME2.
84
103
85
-
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``.
104
+
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`.
86
105
87
106
{{% notice Note %}}
88
-
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%}}
107
+
At the time of writing, macOS ships with `clang` version 17.0.0, which doesn't support SME2. Use a newer version, such as 21.1.4, available through Homebrew.
108
+
{{% /notice%}}
109
+
110
+
You can check your compiler version using the command: `clang --version` if it's alreay installed. If not, install `clang` using the instructions below, selecting either macOS or Linux/Ubuntu, depending on your setup:
111
+
112
+
{{< tabpane code=true >}}
113
+
114
+
{{< tab header="Linux/Ubuntu" language="bash">}}
115
+
sudo apt install clang
116
+
{{< /tab >}}
117
+
118
+
{{< tab header="macOS" language="bash">}}
119
+
brew install llvm
120
+
{{< /tab >}}
121
+
122
+
{{< /tabpane >}}
123
+
124
+
You are now all set to start hacking with SME2.
125
+
126
+
## Set up a system to target Android phones with SME2 support {#android-sme2}
127
+
128
+
Targeting an Android phone means you will have to cross-compile the code examples using Android's NDK. The easiest way is to install [Android Studio](https://developer.android.com/studio) on your system, then in `Android Studio` go to `Tools` > `SDK manager` in the menu, then select the `SDK Tools` tab and tick `NDK (Side by side)` as show in the picture below:
You can check your compiler version using the command:``clang --version``
132
+
Locate where the NDK has been installed on your machine and save the location to an `NDK` environment variable for use later when building the code examples. For example, on macOS, at the time of writing, the NDK is located in `/Users/$USER/Library/Android/sdk/ndk/29.0.14206865`:
Install Clang using the instructions below, selecting either macOS or Linux/Ubuntu, depending on your setup:
138
+
You will also need the `adb` (Android Debug Bridge) tool to upload and execute the programs on a mobile phone (with SME2 support).
95
139
96
140
{{< tabpane code=true >}}
97
141
98
-
{{< tab header="Linux/Ubuntu" language="bash">}}
99
-
sudo apt install clang
100
-
{{< /tab >}}
142
+
{{< tab header="Linux/Ubuntu" language="bash">}}
143
+
sudo apt install adb
144
+
{{< /tab >}}
101
145
102
-
{{< tab header="macOS" language="bash">}}
103
-
brew install llvm
104
-
{{< /tab >}}
146
+
{{< tab header="macOS" language="bash">}}
147
+
brew install android-platform-tools
148
+
{{< /tab >}}
105
149
106
150
{{< /tabpane >}}
107
151
108
-
You are now all set to start hacking with SME2.
152
+
The phone will have to be connected with a USB cable to your development machine in order for `adb` to work. Enable the `developper mode` on the Android phone, and connect it on your machine with the USB cable.
153
+
154
+
{{% notice Note %}}
155
+
You might have to perform some actions on the phone to enable the debug connection.
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.
173
+
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 with the help of `docker/build-my-container.sh` script.
117
174
118
-
If building manually, follow the instructions in the ``sme2-environment.docker`` file to install the required tools on your machine.
175
+
If building manually, follow the instructions in the `sme2-environment.docker` file to install the required tools on your machine.
119
176
120
177
### Install and verify Docker
121
178
@@ -127,10 +184,10 @@ To begin, start by checking that Docker is installed on your machine:
127
184
128
185
```BASH { output_lines="2" }
129
186
docker --version
130
-
Docker version 27.3.1, build ce12230
187
+
Docker version 28.5.1, build e180ab8
131
188
```
132
189
133
-
If the above command fails with an error message similar to "``docker: command not found``", then follow the steps from the [Docker install guide](/install-guides/docker/) to install Docker.
190
+
If the above command fails with an error message similar to "`docker: command not found`", then follow the steps from the [Docker install guide](/install-guides/docker/) to install Docker.
134
191
135
192
{{% notice Note %}}
136
193
You might need to log out and back in again or restart your machine for the changes to take
@@ -182,54 +239,65 @@ When a command is executed in the Docker container environment, you must prepend
182
239
it with instructions on the command line so that your shell executes it within
183
240
the container.
184
241
185
-
For example, to execute ``COMMAND ARGUMENTS`` in the SME2 Docker container, the
242
+
For example, to execute `COMMAND ARGUMENTS` in the SME2 Docker container, the
186
243
command line looks like this:
187
244
188
245
```BASH
189
-
docker run --rm -v "$PWD:/work"-w /work armswdev/sme2-learning-path:sme2-environment-v2 COMMAND ARGUMENTS
246
+
docker run --rm -v "$PWD:/work" armswdev/sme2-learning-path:sme2-environment-v3 COMMAND ARGUMENTS
190
247
```
191
248
192
249
This invokes Docker, using the
193
-
``armswdev/sme2-learning-path:sme2-environment-v2`` container image, and mounts
250
+
`armswdev/sme2-learning-path:sme2-environment-v3` container image, and mounts
inside the container to `/work` and runs `COMMAND ARGUMENTS` in this environment.
198
254
199
-
For example, to run ``make``, you need to enter:
255
+
For example, to run `echo Hello`, you need to enter:
200
256
201
-
```BASH
202
-
docker run --rm -v "$PWD:/work" -w /work armswdev/sme2-learning-path:sme2-environment-v2 make
257
+
```BASH { output_lines="2" }
258
+
docker run --rm -v "$PWD:/work" armswdev/sme2-learning-path:sme2-environment-v3 echo Hello
259
+
Hello
203
260
```
204
261
205
262
### Use an interactive Docker shell
206
263
207
-
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.
264
+
The standard `docker run` commands can be long and repetitive. To streamline
265
+
your workflow, you can start an interactive Docker session that allows you to
266
+
run commands directly --- without having to prepend docker run each time.
208
267
209
268
To launch an interactive shell inside the container, use the `-it` flag:
210
269
211
270
```BASH
212
-
docker run --rm -it -v "$PWD:/work"-w /work armswdev/sme2-learning-path:sme2-environment-v2
271
+
docker run --rm -it -v "$PWD:/work" armswdev/sme2-learning-path:sme2-environment-v3
213
272
```
214
273
215
274
You are now in the Docker container, and you can execute all commands directly. For
216
-
example, the ``make`` command can now be simply invoked with:
275
+
example, the `make` command can now be simply invoked with:
217
276
218
-
```BASH
219
-
make
277
+
```BASH { output_lines="2" }
278
+
echo Hello
279
+
Hello
220
280
```
221
281
222
-
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.
282
+
To exit the container, simply hit CTRL+D.
283
+
284
+
{{% notice Note %}}
285
+
The container is not persistent (it was invoked with `--rm`), so each invocation
286
+
will use a container freshly built from the image. All files in `/work` reside
287
+
outside the container though, so changes you make to them will be persistent
288
+
across sessions.
289
+
{{% /notice %}}
223
290
224
291
### Develop with Docker in Visual Studio Code
225
292
226
-
If you are using Visual Studio Code as your IDE, the container setup is already configured with `devcontainer/devcontainer.json`.
293
+
If you are using Visual Studio Code as your IDE, the container setup is already
294
+
configured with `devcontainer/devcontainer.json`.
227
295
228
296
Make sure you have the [Microsoft Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension installed.
229
297
230
298
Then select the **Reopen in Container** menu entry as shown below.
231
299
232
-
It automatically finds and uses ``.devcontainer/devcontainer.json``:
300
+
It automatically finds and uses `.devcontainer/devcontainer.json`:
233
301
234
302
![VSCode Docker alt-text#center](VSCode.png"Figure 1: Setting up the Docker container.")
0 commit comments