Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update Zephyr docs #174

Merged
merged 3 commits into from
Oct 19, 2023
Merged

Update Zephyr docs #174

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
fe8927b
Update Zephyr docs
erlingrj Oct 19, 2023
913c3db
Apply suggestions from code review
erlingrj Oct 19, 2023
ab37932
Update packages/documentation/copy/en/embedded/Zephyr.md
erlingrj Oct 19, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 37 additions & 31 deletions packages/documentation/copy/en/embedded/Zephyr.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -118,59 +129,54 @@ 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.

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
```
Expand All @@ -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"
Expand Down
Loading