From b9337b186ca49f98e96924330e966393461d25cd Mon Sep 17 00:00:00 2001 From: Erling Rennemo Jellum Date: Sun, 22 Oct 2023 12:47:12 +0200 Subject: [PATCH 1/2] Apply Edwards suggestion, also add section on lfc-centric development --- .../documentation/copy/en/embedded/Zephyr.md | 113 +++++++++++++----- 1 file changed, 82 insertions(+), 31 deletions(-) diff --git a/packages/documentation/copy/en/embedded/Zephyr.md b/packages/documentation/copy/en/embedded/Zephyr.md index e1d7b22b0..2b124c9c9 100644 --- a/packages/documentation/copy/en/embedded/Zephyr.md +++ b/packages/documentation/copy/en/embedded/Zephyr.md @@ -24,21 +24,19 @@ Zephyr RTOS sources. - nrf52 Development Kit (optional) # Getting started -The first step is to set up a proper Zephyr development environment. This includes: -1. Installing dependencies -2. Installing Zephyr SDK - -Follow the relevant parts of the official [Zephyr Getting Started +The first step is to set up a proper Zephyr development environment. Follow the +steps in the **Install dependencies** and **Install Zephyr SDK** sections of the +official [Zephyr Getting Started Guide](https://docs.zephyrproject.org/latest/develop/getting_started/index.html). -**It is not necessary to perform the steps under "Get Zephyr and install Python -dependencies"**. These steps will be performed inside the LF Zephyr workspace we +Do not perform the steps under **Get Zephyr and install Python +dependencies**. These steps will be performed inside the LF Zephyr workspace we are going to create next. ## Setting up the LF Zephyr workspace -1. Clone the template repository +1. Clone the template repository into a workspace directory of Zephyr projects ``` -git clone https://github.com/lf-lang/lf-west-template lf-zephyr-workspace && cd lf-west +git clone https://github.com/lf-lang/lf-west-template lf-zephyr-workspace && cd lf-zephyr-workspace ``` 2. Setup and activate a virtual environment @@ -92,7 +90,7 @@ following: Our custom west-extension will invoke `lfc` and create a `src-gen` directory structured as a [Zephyr application](https://docs.zephyrproject.org/latest/develop/application/index.html). -Wish can then be built, emulated or flashed by `west`. +This generated project can then be built, emulated or flashed by `west`. @@ -105,18 +103,21 @@ cd apps/HelloWorld lfc src/HelloWorld.lf -n west build src-gen/HelloWorld -t run ``` -`HelloWorld.lf` has the target properties `platform: "Zephyr"` and `threading: false`. This tells `lfc` to create a Zephyr-compatible CMake project. Then we use `west` to build the -generated CMake project and to start an emulation. +`HelloWorld.lf` has the target properties `platform: "Zephyr"` and `threading: +false`. This tells `lfc` to create a Zephyr-compatible CMake project. Then we +use `west` to build the generated CMake project and to start an emulation. -To enable **west-centric** development we have added a custom west command, `west lfc`. -It is a wrapper around the original lfc but also copies the files `prj.conf` and `Kconfig` -into to generated project. It can also invoke `west build` directly. The above example -can be compiled and emulated with the following command: +To enable **west-centric** development we have added a custom west command, +`west lfc`. It is a wrapper around the original lfc but also copies the files +`prj.conf` and `Kconfig` into to generated project. It can also invoke `west +build` directly. The above example can be compiled and emulated with the +following command: ``` west lfc src/HelloWorld.lf --build "-t run" ``` -The string within the quotation marks after `--build` is passed on to `west build`. +The string within the quotation marks after `--build` is passed on to `west +build`. ## Nrf52 blinky In this example we will program a simple Blinky program onto an nrf52dk. This @@ -129,7 +130,8 @@ cd apps/NrfBliny west lfc src/NrfBlinky.lf --build "-p always -b nrf52dk_nrf52832" west flash ``` -In this example we use the `-p always` to tell west to do a clean build and `-b nrf52dk_nrf52832` to target the nrf52dk. These parameters are west-specific so +In this example we use the `-p always` to tell west to do a clean build and `-b +nrf52dk_nrf52832` to target the nrf52dk. These parameters are west-specific so refer to west documentation for more info. `west flash` is used to interact with `nrfjprog` and flash the application into the dev-board. @@ -143,7 +145,6 @@ west build -b nrf52dk_nrf52832 -p always west flash ``` - # Zephyr configuration options The Lingua Franca Zephyr platform depends on some specific [Zephyr Kernel configurations](https://docs.zephyrproject.org/latest/build/kconfig/index.html#). @@ -166,22 +167,66 @@ project. Please see `west lfc --help` for more information and the `scripts/lf_build.py`. +# LFC-centric development +In this guide we have shown how LF Zephyr apps can be developed in a +`west`-centric manner. It is also possible to target Zephyr in a `lfc`-centric +approach. When you give `lfc` a LF program with the `platform` target property +set to `Zephyr`, it will generate a Zephyr project that can be built with +`west`. For this to work, the environment variable `ZEPHYR_BASE` must be set to +point to the Zephyr RTOS sources. To demonstrate this, create a simple example +program: +``` +cat >> LfcCentricZephyr.lf << 'END' +target C { + platform: "Zephyr" +} +main reactor{ + reaction(startup) {= + lf_print("Hello World!"); + =} +} +END +``` + +If `west` is installed in a virtual environment, activate it, and set up the +environment. Assuming that the template is located at `/home/lf-zephyr-workspace` + +``` +source /home/lf-zephyr-workspace/.venv/bin/activate +export ZEPHYR_BASE=/home/lf-zephyr-workspace/deps/zephyr +lfc LfcCentricZephyr.lf +``` + +This will create a Zephyr project at `src-gen/LfcCentricZephyr` and invoke +the Zephyr toolchain to compile it. Since we have not specified any board, +the default, which is `qemu_cortex_m3`, is used. We can run an emulation of +the program with: +``` +cd src-gen/LfcCentricZephyr +west build -t run +``` + # Debugging LF Zephyr programs using QEMU and GDB -In this section we will see how a LF program can be debugged while running in QEMU emulation. +In this section we will see how a LF program can be debugged while running in +QEMU emulation. 1. Compile `HelloWorld.lf` for `qemu_cortex_m3` ``` cd apps/HelloWorld west lfc src/HelloWorld.lf --build "-b qemu_cortex_m3 -p always" ``` -Note that we here, unlike the very first example, explicitly tell `lfc` that we are targeting a `qemu_cortex_m3` platform. This is the default platform which is used unless another is specified. It is added here for clarity. +Note that we here, unlike the very first example, explicitly tell `lfc` that we +are targeting a `qemu_cortex_m3` platform. This is the default platform which is +used unless another is specified. It is added here for clarity. -2. In one terminal, start qemu as a debug server waiting for a local connection from `gdb` +2. In one terminal, start qemu as a debug server waiting for a local connection + from `gdb` ``` ninja -C build debugserver ``` -3. In another terminal start `gdb` and connect to the qemu server. Load the application image and run until main. +3. In another terminal start `gdb` and connect to the qemu server. Load the + application image and run until main. ``` /ZEPHYR_SDK_INSTALL_DIR/arm-zephyr-eabi/bin/arm-zephyr-eabi-gdb (gdb) target remote localhost:1234 @@ -196,15 +241,20 @@ From here you can step through the LF program. To get a more visual interface yo ``` ## Timing in QEMU emulations -The QEMU emulation is not cycle-accurate and implements optimizations such that if the system goes to sleep, like when the last active thread in the program calls `k_sleep()`, then the emulator fast-forwards time. -This does not affect the QEMU-emulation of the *unthreaded* runtime since it implements sleeping between events using *busy-waits*. -However, the *threaded* runtime sleeps between events using a call to `k_cond_timedwait` which has the side-effect that QEMU fast-forwards time. -This causes the emulation of threaded programs to appear as if the `fast` target property was set to `true`. +The QEMU emulation is not cycle-accurate and implements optimizations such that +if the system goes to sleep, like when the last active thread in the program +calls `k_sleep()`, then the emulator fast-forwards time. This does not affect +the QEMU-emulation of the *unthreaded* runtime since it implements sleeping +between events using *busy-waits*. However, the *threaded* runtime sleeps +between events using a call to `k_cond_timedwait` which has the side-effect that +QEMU fast-forwards time. This causes the emulation of threaded programs to +appear as if the `fast` target property was set to `true`. ## Troubleshooting ### Multiple Zephyr installations -If the following warning is shown when invoking `west lfc` or any other `west` command: +If the following warning is shown when invoking `west lfc` or any other `west` +command: ``` WARNING: ZEPHYR_BASE=/path/to/zephyr in the calling environment will be used, but the zephyr.base config option in /path/to/lf-west-template is "deps/zephyr" @@ -212,6 +262,7 @@ which implies a different ZEPHYR_BASE=/path/to/lf-west-template/deps/zephyr To disable this warning in the future, execute 'west config --global zephyr.base-prefer env' ``` -Then it means that you have multiple Zephyr repositories installed. -We do not recommend this as `west` will link the application with the Zephyr found in the CMake package registry. -Please refer to the Getting Started section to purge the system of old Zephyr installations. +Then it means that you have multiple Zephyr repositories installed. We do not +recommend this as `west` will link the application with the Zephyr found in the +CMake package registry. Please refer to the Getting Started section to purge the +system of old Zephyr installations. From 24c26dfcd773a76211e0bc85caf2970e6e209e6b Mon Sep 17 00:00:00 2001 From: Erling Rennemo Jellum Date: Sat, 28 Oct 2023 14:33:50 +0200 Subject: [PATCH 2/2] Typo --- packages/documentation/copy/en/embedded/Zephyr.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/documentation/copy/en/embedded/Zephyr.md b/packages/documentation/copy/en/embedded/Zephyr.md index 2b124c9c9..3ddbfd856 100644 --- a/packages/documentation/copy/en/embedded/Zephyr.md +++ b/packages/documentation/copy/en/embedded/Zephyr.md @@ -14,7 +14,7 @@ hardware. When developing LF programs for Zephyr we use a `west`-centric approach. Using `west`, which is the preferred build tool for Zephyr projects, requires structuring the code base and development flow as expected by `west`. We use a [T3 Forest -Topology](https://docs.zephyrproject.org/latest/develop/west/workspaces.html#west-t3). +Topology](https://docs.zephyrproject.org/latest/develop/west/workspaces.html#west-t3) for our workspace. This means that we create a workspace where multiple different LF Zephyr projects can be hosted together with a single copy of the Zephyr RTOS sources.