Add full content for IntegrateWithZephyr.md, including west integration instructions

xtremekforever · rauhul · commit f63b2d3dca18 · 2025-05-23T14:30:07.000-07:00
diff --git a/Sources/EmbeddedSwift/Documentation.docc/SDKSupport/IntegrateWithZephyr.md b/Sources/EmbeddedSwift/Documentation.docc/SDKSupport/IntegrateWithZephyr.md
@@ -4,15 +4,15 @@
 
 For an introduction and motivation into Embedded Swift, please see "[A Vision for Embedded Swift](https://github.com/swiftlang/swift-evolution/blob/main/visions/embedded-swift.md)", a Swift Evolution document highlighting the main goals and approaches.
 
-Refer to the [nrfx-blink-sdk](../../../../nrfx-blink-sdk/) project for a complete working "blinky" example that can be used as a starting point. However, for a formal introduction to setting up a Swift Zephyr project and explanations into the various options, continue reading this document.
+The following document outlines how to setup a Swift to Zephyr project for an emulated ARM Cortex M0, explaining a few key concepts along the way. For a complete working example on real hardware, however, refer to the [nrfx-blink-sdk](../../../../nrfx-blink-sdk/) project that is compatible with nRF or other boards.
 
 ## Zephyr Setup
 
 Before setting up a Swift project that works with Zephyr, you need to setup dependencies and a Zephyr workspace as per the [Getting Started Guide](https://docs.zephyrproject.org/latest/develop/getting_started/index.html). Regardless of your platform (macOS or Linux), ensure that you can build the blinky example without errors before starting with Swift integration:
 
 ```bash
 cd ~/zephyrproject/zephyr
-west build -p always -b <your-board-name> samples/basic/blinky
+west build -p always -b reel_board samples/basic/blinky
 ```
 
 By default, the `main` revision of the Zephyr sources are checked out when calling `west init`, which contains pre-release and development changes that may cause instability and changing APIs that are not desirable. To checkout a specific release version of Zephyr, use the following commands:
@@ -43,12 +43,13 @@ SwiftZephyrProject/prj.conf
 
 These are the minimum required files in order to build a Zephyr project. By convention, source files should be placed in the src/ subdirectory, but this is not a hard requirement. Also, `prj.conf` is required even if it is empty, or the project will not build.
 
-Inside of `src/BridgingHeader.h`, add the following content as a minimum:
+Inside of `src/BridgingHeader.h`, add the following content:
 
 ```c
 #pragma once
 
 #include <autoconf.h>
+#include <zephyr/kernel.h>
 ```
 
 The `src/Main.swift` file must contain a `static func main()` as follows:
@@ -57,12 +58,17 @@ The `src/Main.swift` file must contain a `static func main()` as follows:
 @main
 struct Main {
   static func main() {
-    // code
+    print("Hello Zephyr from Swift!")
+
+    while true {
+      k_msleep(1000)
+      print("Loop")
+    }
   }
 }
 ```
 
-Since Embedded Swift requires posix_memalign to be defined, add the following to `src/Stubs.c` to define it:
+Since Embedded Swift requires `posix_memalign` to be defined, add the following to `src/Stubs.c` to define it:
 
 ```c
 #include <stdlib.h>
@@ -86,6 +92,12 @@ posix_memalign(void **memptr, size_t alignment, size_t size)
 }
 ```
 
+Finally, add the following line to `prj.conf` so that the output of `print()` statements is sent to stdout:
+
+```conf
+CONFIG_STDOUT_CONSOLE=y
+```
+
 ### CMakeLists.txt Setup
 
 The `CMakeLists.txt` setup is more involved and complex since target, compilation flags, and library linking must be specified for Swift. First, some initial setup and flags:
@@ -101,11 +113,11 @@ set(CMAKE_Swift_COMPILATION_MODE wholemodule)
 project(SwiftZephyrProject Swift)
 ```
 
-The following flags have been curated to work well with the `armv7em-none-none-eabi` target with `swiftc`. Some flags may need to change depending on the chosen target:
+Next, set the compiler target to the arch you are building for. For this example we use `armv6m-none-none-eabi` which is compatible with the [Cortex-M0](https://docs.zephyrproject.org/latest/boards/qemu/cortex_m0/doc/index.html) which we will compile for in a later step. The `mfloat-abi=soft`, `-fshort-enums`, and `-fno-pic` flags are specifically for 32-bit arm architectures, so for other architectures they can be removed. However, the other flags and required for building Swift for Embedded and against Zephyr:
 
 ```cmake
-# Use the armv7em-none-none-eabi target triple for Swift
-set(CMAKE_Swift_COMPILER_TARGET armv7em-none-none-eabi)
+# Use the armv6m-none-none-eabi target triple for Swift
+set(CMAKE_Swift_COMPILER_TARGET armv6m-none-none-eabi)
 
 # Set global Swift compiler flags
 add_compile_options(
@@ -176,3 +188,122 @@ target_include_directories(app_swift PRIVATE
 # Link the Swift target into the primary target
 target_link_libraries(app PRIVATE app_swift)
 ```
+
+### Building and Running
+
+To build the project, ensure that the Zephyr workspace is sourced first:
+
+```bash
+source ~/zephyrproject/.venv/bin/activate
+```
+
+Run the following command to configure the project with CMake:
+
+```console
+(.venv)> cmake -B build -G Ninja -DBOARD=qemu_cortex_m0 -DUSE_CCACHE=0 .
+Loading Zephyr default modules (Zephyr base (cached)).
+...
+-- Configuring done (7.6s)
+-- Generating done (0.2s)
+-- Build files have been written to: ~/SwiftZephyrProject/build
+```
+
+Then, the project can be built using `cmake --build`:
+
+```console
+(.venv)> cmake --build build
+[1/135] Preparing syscall dependency handling
+
+[2/135] Generating include/generated/zephyr/version.h
+-- Zephyr version: 4.1.0 (~/zephyrproject/zephyr), build: v4.1.0
+[130/135] Linking C executable zephyr/zephyr_pre0.elf
+~/zephyr-sdk-0.17.0/arm-zephyr-eabi/bin/../lib/gcc/arm-zephyr-eabi/12.2.0/../../../../arm-zephyr-eabi/bin/ld.bfd: warning: orphan section `.swift_modhash' from `app/libapp.a(Main.swift.obj)' being placed in section `.swift_modhash'
+[135/135] Linking C executable zephyr/zephyr.elf
+~/zephyr-sdk-0.17.0/arm-zephyr-eabi/bin/../lib/gcc/arm-zephyr-eabi/12.2.0/../../../../arm-zephyr-eabi/bin/ld.bfd: warning: orphan section `.swift_modhash' from `app/libapp.a(Main.swift.obj)' being placed in section `.swift_modhash'
+Memory region         Used Size  Region Size  %age Used
+           FLASH:       14674 B       256 KB      5.60%
+             RAM:        4032 B        16 KB     24.61%
+        IDT_LIST:          0 GB        32 KB      0.00%
+Generating files from ~/SwiftZephyrProject/build/zephyr/zephyr.elf for board: qemu_cortex_m0
+```
+
+Finally, to run the example in the qemu emulator, use `ninja run`:
+
+```console
+(.venv)> ninja -C build run
+ninja: Entering directory `build'
+[0/1] To exit from QEMU enter: 'CTRL+a, x'[QEMU] CPU: cortex-m0
+*** Booting Zephyr OS build v4.1.0 ***
+Hello Zephyr from Swift!
+Loop
+Loop
+Loop
+```
+
+Congrats, you now have a Swift project running using Zephyr!
+
+## West Integration
+
+Up to now we have setup a project that works perfectly fine when used with just CMake and Ninja. However, projects can also be integrated with West, which is the official CLI tool used for Zephyr projects. To use `west`, start by adding a `west.yml` file to the root of the project:
+
+```yml
+manifest:
+  remotes:
+    - name: zephyrproject-rtos
+      url-base: https://github.com/zephyrproject-rtos
+
+  projects:
+    - name: zephyr
+      remote: zephyrproject-rtos
+      revision: v4.1.0
+      import:
+        name-allowlist:
+          - cmsis  # required by the ARM port
+```
+
+It is recommended to set the `revision` to a tagged version of Zephyr instead of always getting the main revision, which could have changing APIs.
+
+Next, set the `ZEPHYR_BASE` environment variable to tell `west` where the Zephyr workspace is located:
+
+```bash
+(.venv)> export ZEPHYR_BASE=~/zephyrproject/zephyr
+```
+
+This could even be set as a global env variable for the user in `~/.bashrc` or `~/.zshrc` if desired.
+
+With this, `west` commands now can be run instead of having to use `cmake` and `ninja` to build and run:
+
+```bash
+(.venv)> west build -b qemu_cortex_m0 . -p always
+...
+(.venv)> west build -t run
+-- west build: running target run
+[0/1] To exit from QEMU enter: 'CTRL+a, x'[QEMU] CPU: cortex-m0
+*** Booting Zephyr OS build v4.1.0 ***
+Hello Zephyr from Swift!
+Loop
+Loop
+Loop
+Loop
+```
+
+This setup may also desirable since `west flash` is also available and can be used instead of invoking the flashing tools manually.
+
+If compiling a firmware for a real/physical board such as the `nrf52840dk/nrf52840`, `west flash` will work if the SEGGER J-Link host tools are installed. As an example, with the [nrfx-blink-sdk](../../../../nrfx-blink-sdk/) project:
+
+```console
+> cd nrfx-blink-sdk
+> source ~/zephyrproject/.venv/bin/activate
+(.venv)> export ZEPHYR_BASE=~/zephyrproject/zephyr
+(.venv)> west build -b nrf52840dk/nrf52840 . -p always
+...
+(.venv)> west flash -r jlink
+-- west flash: rebuilding
+ninja: no work to do.
+-- west flash: using runner jlink
+-- runners.jlink: reset after flashing requested
+-- runners.jlink: JLink version: 8.26
+-- runners.jlink: Flashing file: ~/swift-embedded-examples/nrfx-blink-sdk/build/zephyr/zephyr.hex
+```
+
+The `-r jlink` param is needed for this example to use the J-Link tools instead of using `nrfjprog`, which is the default for this board and also [deprecated](https://www.nordicsemi.com/Products/Development-tools/nRF-Command-Line-Tools).
