Skip to content

Commit

Permalink
Merge pull request zephyrproject-rtos#5 from finikorg/thesof-zephyr
Browse files Browse the repository at this point in the history 
docs: Update README.md to SOF audio sample
  • Loading branch information
@Vudentz
Vudentz authored Aug 14, 2019
2 parents 6d198e0 + 3c2b980 commit 6c2b616
Showing 1 changed file with 62 additions and 71 deletions.
133 changes: 62 additions & 71 deletions samples/audio/sof/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,60 +5,51 @@
## Build SDK for the board

To build the board we need to use yet another toolchain. Get source here:
https://github.com/dcpleung/sdk-ng.git and check out branch intel_apl_adsp.
https://github.com/dcpleung/sdk-ng.git and check out branch `intel_apl_adsp`.

```
```bash
$ git clone https://github.com/dcpleung/sdk-ng.git
$ cd sdk-ng
$ git checkout intel_apl_adsp
```

Build crosstool-ng with command:

```
```bash
$ ./go.sh xtensa_intel_apl_adsp
```

After build we need to set Zephyr environment variable with:

```
```bash
export ZEPHYR_TOOLCHAIN_VARIANT=xtools
export XTOOLS_TOOLCHAIN_PATH=<...>/sdk-ng/build/output/
```

## Build Zephyr kernel

Get source from repository
[https://github.com/jhedberg/zephyr.git](https://github.com/jhedberg/zephyr.git)
and make checkout branch up_squared_adsp.
Get source from repository https://github.com/thesofproject/zephyr.git
and make checkout master branch.

**_Note: While Johan is on vacation the latest code should be in the PR
[https://github.com/jhedberg/zephyr/pull/3](https://github.com/jhedberg/zephyr/pull/3)
or here:
[https://github.com/finikorg/zephyr/commits/up_squared_adsp](https://github.com/finikorg/zephyr/commits/up_squared_adsp)_**
Please refer to [Clone the Zephyr Repositories](https://docs.zephyrproject.org/latest/getting_started/index.html#clone-the-zephyr-repositories)
for more information.

```
$ git clone https://github.com/jhedberg/zephyr.git
$ cd zephyr
$ west init
```bash
$ west init zephyrproject -m https://github.com/thesofproject/zephyr.git
$ cd zephyrproject
$ west update
$ git checkout up_squared_adsp
```

Although the BSP is based on intel_s1000_crb compiler and tools described for the board does not produce working code. Instead use xtools described in the chapter [Build SDK for the board].
Although the BSP is based on `intel_s1000_crb` compiler and tools described for
the board does not produce working code. Instead use xtools described in the
chapter [Build SDK for the board](#build-sdk-for-the-board).

Build hello_world modified sample and we can use built zephyr.elf.
Build `hello_world` modified sample and we can use built zephyr.elf.

```
```bash
$ west build -b up_squared_adsp samples/hello_world/
```

**_Note: At the moment default west might fail, so please use exact 0.6.0 version with_**

```
$ pip3 install --user west==0.6.0
```

We would be using zephyr/zephyr.elf later on.

## Build SOF image
Expand All @@ -67,90 +58,89 @@ From the SOF image we need ROM for booting with SOF Qemu and bootloader (startup

For building SOF we need to build special toolchain.

Follow instructions here: [https://thesofproject.github.io/latest/getting_started/build-guide/build-from-scratch.html](https://thesofproject.github.io/latest/getting_started/build-guide/build-from-scratch.html)
Follow instructions here: https://thesofproject.github.io/latest/getting_started/build-guide/build-from-scratch.html.

But it is enough to build toolchain only for Apollo Lake and skip others.

When it comes to building actual firmware we use the following configuration:

```
```bash
$ cd ~/work/sof/sof
$ ./scripts/xtensa-build-all.sh -d -r apl
```

Where -d for debug and -r for building ROM which is needed for Qemu to start with.
Where `-d` for debug and `-r` for building ROM which is needed for Qemu to start with.

The built images of **ROM**, **bootloader** and SOF **kernel** are located in
**build_apl_gcc/src/arch/xtensa**.
The built images of `ROM`, `bootloader` and SOF `kernel` are located in
`build_apl_gcc/src/arch/xtensa`.

### Build SOF image with Docker

As an alternative, SOF provides a docker image that contains all required toolchains.

Refer the following page for more details:

[https://thesofproject.github.io/latest/getting_started/build-guide/build-with-docker.html](https://thesofproject.github.io/latest/getting_started/build-guide/build-with-docker.html#)
Refer the following page for more details: https://thesofproject.github.io/latest/getting_started/build-guide/build-with-docker.html

At first, install docker image.

```
```bash
$ docker pull thesofproject/sof
$ docker tag thesofproject/sof sof
```

Run docker image with the script.

```
```bash
$ cd ~/work/sof/sof
$ ./scripts/docker-run.sh ./scripts/xtensa-build-all.sh -d -r apl
```

Or run docker with bash and run the command from there

```
```bash
$ ./scripts/docker-run.sh bash
```

Now in docker shell
Now in docker shell run

```
```bash
$ ./scripts/xtensa-build-all.sh -d -r apl
```

## Create rimage (*.ri)

The image is created with rimage tool (found inside SOF project). The sequence
is taken from **src/arch/xtensa/CMakeLists.txt**.
is taken from `src/arch/xtensa/CMakeLists.txt`.

```
```bash
$ cd ~/work/sof/sof
$ xtensa-apl-elf-objcopy -O binary build_apl_gcc/src/platform/apollolake/base_module mod-apl.bin
$ xtensa-apl-elf-objcopy --add-section .module=mod-apl.bin --set-section-flags .module=load,readonly ../zephyr/build/zephyr/zephyr.elf
$ build_apl_gcc/rimage_ep/build/rimage -o sof-apl.ri -p sof-apl.ldc -m apl -k rimage/keys/otc_private_key.pem -i 3 build_apl_gcc/src/arch/xtensa/bootloader-apl ../zephyr/build/zephyr/zephyr.elf
```

The image created **sof-apl.ri** is our final image we can use on Qemu or on up_squared ADSP.
The image created `sof-apl.ri` is our final image we can use on Qemu or on `up_squared` ADSP.

### Create rimage with Docker

Same SOF docker image can be used to create the rimage.

Copy the **zephyr.elf,** built from [Build Zephyr Kernel] section, to sof
source directory, so it can be accessed in the docker environment.
Copy the `zephyr.elf`, built from [Build Zephyr Kernel](#build-zephyr-kernel)
section, to sof source directory, so it can be accessed in the docker
environment.

```
```bash
$ cd ~/work/sof/sof
$ mkdir zephyr
$ cp <zephyr dir>/build/zephyr/zephyr.elf zephyr/
```

Run SOF docker image and build the image

```
```bash
$ cd ~/work/sof/sof
$ ./scripts/docker-run.sh bash
#
# Now shell in docker
# Now in the docker shell
#
$ xtensa-apl-elf-objcopy -O binary build_apl_gcc/src/platform/apollolake/base_module mod-apl.bin
$ xtensa-apl-elf-objcopy --add-section .module=mod-apl.bin --set-section-flags .module=load,readonly zephyr/zephyr.elf
Expand All @@ -162,21 +152,21 @@ $ build_apl_gcc/rimage_ep/build/rimage -o sof-apl.ri -p sof-apl.ldc -m apl -k ri
## Install SOF Qemu

This is Qemu with SOF patches for the APL xtensa. It is capable of running
exactly the same code as a real hardware (ADSP on up_squared).
exactly the same code as a real hardware (ADSP on `up_squared`).

### Get Qemu with docker

```
```bash
$ docker pull thesofproject/sofqemu
$ docker tag thesofproject/sofqemu sofqemu
```

### Build Qemu from local sources

Instructions are taken from docker build configuration in
**scripts/docker_build/sof_qemu/Dockerfile**
`scripts/docker_build/sof_qemu/Dockerfile`

```
```bash
$ git clone https://github.com/thesofproject/qemu.git
$ cd qemu
$ git checkout sof-stable
Expand All @@ -188,36 +178,36 @@ $ make

### Run image on Qemu

```
```bash
$ cd qemu
$ ./xtensa-softmmu/qemu-system-xtensa -cpu broxton -M adsp_bxt -nographic -kernel ../sof.git/sof-apl.ri -rom ../sof.git/build_apl_gcc/src/arch/xtensa/rom-apl.bin -s -S -semihosting
```

Note that **-s** is a _shorthand for -gdb tcp::1234_ and **-S** is to _freeze
Note that `-s` is a _shorthand for -gdb tcp::1234_ and `-S` is to _freeze
CPU at startup and use ‘c’ to start execution_. Skip these options to run
without debugger.

Note that **-semihosting** enables logging to qemu console using simcall
Note that `-semihosting` enables logging to qemu console using simcall
instructions with xtensa simulator backend.

Use the **sof-apl.ri **created in the “_Create rimage_” section.
Use the `sof-apl.ri` created in the [Create rimage](#create-rimage-ri) section.

Using helper script:

```
```bash
$ ./xtensa-host.sh apl -d -k ../sof/sof-apl.ri -r ../sof/build_apl_gcc/src/arch/xtensa/rom-apl.bin
```

Where **sof-apl.ri** is an image created with rimage tool combining bootloader
and kernel, **rom-apl.bin** - is ROM image which should do the same boot
Where `sof-apl.ri` is an image created with rimage tool combining bootloader
and kernel, `rom-apl.bin` - is ROM image which should do the same boot
sequence as xtensa DSP. Since we can run exactly the same images on Qemu and on
a real **up_squared** hardware we can use this Qemu for early development.
a real `up_squared` hardware we can use this Qemu for early development.

### Run image with Docker Qemu

Use the following script to run the SOF Qemu docker image.

```
```bash
$ cd ~/work/sof/sof
$ ./scripts/docker-qemu.sh bash
```
Expand All @@ -229,13 +219,13 @@ Then follow the commands above.
Communication between Qemu running Zephyr and host Linux can be done through
/dev/shm. For example if Zephyr code in the sample does something like

```
```cpp
mailbox_sw_reg_write(SRAM_REG_ROM_STATUS, 0xabbac0fe);
```
In the Linux host we can verify value written with:
```
```bash
$ hexdump -C /dev/shm/qemu-bridge-hp-sram-mem | grep e000
0000e000 fe c0 ba ab 00 00 00 00 50 01 00 00 00 00 00 00 |........P.......|
```
Expand All @@ -244,53 +234,54 @@ $ hexdump -C /dev/shm/qemu-bridge-hp-sram-mem | grep e000

Connect gdb with:

```
```bash
$ xtensa-apl-elf-gdb build_apl_gcc/sof
```

Connect GUI frontend **nemiver** with:

```
```bash
$ nemiver --gdb-binary=/home/niko/work/sof/xtensa-apl-elf/bin/xtensa-apl-elf-gdb --remote=localhost:1234 build_apl_gcc/sof
```

Connect **DDD** frontend with:

```
```bash
$ ddd --debugger xtensa-apl-elf-gdb build_apl_gcc/sof
```

To connect to the target you can use script:

```
```bash
$ cat script.gdb
target remote :1234
```

Run it with gdb script with:

```
```bash
$ gdb --command=script.gdb ....
```

# Using image on up_squared board
# Using image on `up_squared` board

At the moment only up_squared board is supported.
At the moment only `up_squared` board is supported.

## Prerequisites and Setup instructions

Please refer to [https://thesofproject.github.io/latest/getting_started/setup/setup_up_2_board.html](https://thesofproject.github.io/latest/getting_started/setup/setup_up_2_board.html) for prerequitites and instructions.
Please refer to https://thesofproject.github.io/latest/getting_started/setup/setup_up_2_board.html
for prerequitites and instructions.

## Run image on ADSP

After copying **sof-apl.ri** into **/lib/firmware/intel/sof** SOF kernel module
After copying `sof-apl.ri` into `/lib/firmware/intel/sof` SOF kernel module
should initialize and start ADSP.

# Logging

## Using xtensa simulator backend

Xtensa simulator backend, already present in Zephyr, uses “simcall”
Xtensa simulator backend, already present in Zephyr, uses `simcall`
instructions to print to qemu console, so it works only in qemu. You should be
able to select this backend for this board.

Expand Down

0 comments on commit 6c2b616

Please sign in to comment.