diff --git a/packages/documentation/copy/en/embedded/Zephyr.md b/packages/documentation/copy/en/embedded/Zephyr.md index dfd142033..824df36ed 100644 --- a/packages/documentation/copy/en/embedded/Zephyr.md +++ b/packages/documentation/copy/en/embedded/Zephyr.md @@ -19,7 +19,6 @@ Arduino-support, which is `lfc`-centric. ## Prerequisites - Linux or macOS development system -- `lfc` v0.4.0 or greater - nrf52 Development Kit (optional) # Getting started @@ -106,9 +105,21 @@ You should now be able to build and emulate a simple Hello World! LF program: ``` cd application -west lf-build src/HelloWorld.lf -w "-t run" +lfc src/HelloWorld.lf -n +west build src-gen/HelloWorld -t run ``` -`HelloWorld.lf` sets the target property `platform: "Zephyr"` and `threading: false`. This tells `lfc` to create a Zephyr-compatible CMake project. In the example above the custom `west` command `lf-build` is used to first invoke `lfc` and then `west build` on the resulting generated sources. +`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: +``` +west lfc src/HelloWorld.lf --build "-t run" +``` + +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 @@ -118,38 +129,32 @@ the following installation guide ``` cd application -west lf-build src/NrfBlinky.lf -w "-b nrf52dk_nrf52832 -p always" +west lfc src/NrfBlinky.lf --build "-p always -b nrf52dk_nrf52832" west flash ``` -In this example we use the `-w` flag to pass additional flags to `west build`. In particular we inform `west` that we are targeting a the nrf52 with `-b nrf52dk_nrf52832`. We also tell west to clean the build directory first with `-p always`. +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. -# Kernel configuration options +# Zephyr configuration options The Lingua Franca Zephyr platform depends on some specific [Zephyr Kernel configurations](https://docs.zephyrproject.org/latest/build/kconfig/index.html#). For instance, the Counter drivers must be linked with the application to provide hi-resolution timing. These required configurations are stored in a file called `prj_lf.conf` which is copied to the generated `src-gen` folder by `lfc`. You can also supply your own configuration options in a file called `prj.conf` which -has to be located in the same folder as `west lf-build` is invoked from. -There is such a file located in `~/application` in the template. There is also a -file called `debug.conf` which is meant for containing debug options. Such -additional configuration files can also be passed to `west lf-build` through the -`--conf-overlays` options. E.g. `west lf-build -c debug.conf`. - -# The `lf-build` west command -The custom `lf-build` west command has already been used in previous sections. +has to be located in the same folder as `west lfc` is invoked from. +There is such a file located in `~/application` in the template. There is also +a `Kconfig` file. Both are copied into the `src-gen` folder when invoking +`west lfc`. + +# The `west lfc` command +The custom `lfc` west command has already been used in previous sections. It can be inspected in `scripts/lf_build.py`. -It invokes `lfc` on the provided LF source file. -It then invokes `west build` on the generated sources. -If you would like to pass forward arguments to the `west build` command do so -with the `-w` flag. E.g. `-w -b nrf52dk_nrf52832 -p always` passes information -about the dev-kit and also tells `west` to clean the build folder before -starting. -One of the important functions of `lf-build` is to parse a file called -`CompileDefinitions.txt` generated by `lfc`. This file contains all the compiler -definitions which should be defined for the program. `lf-build` passes all the -compiler definitions to the `west build` command. - -Please see `west lf-build -h` for more information and the `scripts/lf_build.py`. +It invokes `lfc` on the provided LF source file. It also copies `prj.conf` and `Kconfig` +into the src-gen directory before it, optionally, calls `west build` on the +resulting project. + +Please see `west lfc --help` for more information and the `scripts/lf_build.py`. # 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. @@ -157,20 +162,21 @@ In this section we will see how a LF program can be debugged while running in QE 1. Compile `HelloWorld.lf` for `qemu_cortex_m3` ``` cd application -west lf-build src/HelloWorld.lf -w "-b qemu_cortex_m3 -p always" +west lfc src/HelloWorld.lf --build "-b qemu_cortex_m3 -p always" ``` -Note that we here, unlike the very first example, explicitly tell `lf-build` 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. 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. 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/arm-zephyr-eabi/bin/arm-zephyr-eabi-gdb (gdb) arm-zephyr-eabi/bin/arm-zephyr-eabi-gdb (gdb) target remote localhost:1234 +(gdb) file build/zephyr/zephyr.elf (gdb) b main (gdb) c ``` @@ -189,7 +195,7 @@ This causes the emulation of threaded programs to appear as if the `fast` target ## Troubleshooting ### Multiple Zephyr installations -If the follwing warning is shown when invoking `west lf-build` 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"