-
Notifications
You must be signed in to change notification settings - Fork 4
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
84 additions
and
63 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,103 +1,124 @@ | ||
| # Zephyr SDK {#appnote_zephyr_sdk} | ||
|
|
||
| > The following document describe the current organization with forks | ||
| > of Zephyr used by tinyCLUNX33 users. | ||
| > This approach has flaws, and is being replaced by the `tinyclunx33_sdk` | ||
| > as introduced on @ref appnote_firmware.. | ||
| [Source](https://github.com/tinyvision-ai-inc/zephyr_private/) | | ||
| [Example](https://github.com/tinyvision-ai-inc/tinyclunx33_zephyr_example/) | | ||
| [Release](https://github.com/tinyvision-ai-inc/tinyclunx33_zephyr_example/releases/) | ||
|
|
||
| On the [RTL Reference Design](rtl_reference_design.md) of the FPGA, there is the a RISC-V soft-CPU integrated. | ||
| This allows to run a firmware, and an RTOS such as [Zephyr](https://docs.zephyrproject.org/) with an USB stack and USB drivers. | ||
| The firmware is loaded into the flash after the FPGA image, and the RISC-V soft CPU starts it. | ||
| <div class="grid"> | ||
| [Source](https://github.com/tinyvision-ai-inc/tinyvision_zephyr_sdk/) | ||
| [Example project](https://github.com/tinyvision-ai-inc/tinyclunx33_zephyr_example/) | ||
| [Example binaries](https://github.com/tinyvision-ai-inc/tinyclunx33_zephyr_example/releases/) | ||
| </div> | ||
|
|
||
|  | ||
|
|
||
|
|
||
| ## Features | ||
|
|
||
| - A Driver for Lattice USB23 | ||
| - The Zephyr USB stack | ||
| - An UVC device class | ||
| - UART for debug logs over the FTDI (on the devkit) | ||
| - I2C control for sensors | ||
| - Any other driver alrelady present on Zephyr | ||
| - etc. (about anything Zephyr can do) | ||
|
|
||
|
|
||
| ## Getting started | ||
|
|
||
| Follow the Zephyr guide up to the point to build the "blinky" example: | ||
| ## Repositories | ||
|
|
||
| <https://docs.zephyrproject.org/latest/develop/getting_started/index.html> | ||
| - [`zephyr`](https://github.com/tinyvision-ai-inc/zephyr): | ||
| A public **fork of Zephyr** is maintained for contributing patches to the Zephyr Project: the | ||
| `usb3` branch contains modifications that are required for the tinyCLUNX33 to work with USB3, | ||
| and are in the process of being upstreamed. | ||
| For everything else, the upstream Zephyr repository is used unchanged. | ||
|
|
||
| Follow the extra steps for any tinyCLUNX33 example: | ||
| - [`tinyvision_zephyr_sdk`](https://github.com/tinyvision-ai-inc/tinyvision_zephyr_sdk) | ||
| The **tinyVision Zephyr SDK** contains additional drivers implemented by tinyVision.ai | ||
| that are compatible with upstream Zephyr, which will also be upstreamed in the long term. | ||
| This allows shipping features long before, without forking the entire Zephyr project. | ||
|
|
||
| <https://github.com/tinyvision-ai-inc/tinyclunx33_zephyr_example/> | ||
|
|
||
| Or follow this longer step-by-step guide including both the install of Zephyr tools and the build process. | ||
| - [`tinyclunx33_zephyr_example`](https://github.com/tinyvision-ai-inc/tinyclunx33_zephyr_example): | ||
| The **tinyCLUNX33 Zephyr Example** repository is a starting point for new applications, | ||
| and makes use of the tinyVision Zephyr SDK. | ||
|
|
||
| <https://github.com/tinyvision-ai-inc/tinyclunx33_zephyr_example/blob/main/README.ubuntu.md> | ||
| The dependencies are managed the | ||
| [`west.yml`](https://github.com/tinyvision-ai-inc/tinyclunx33_zephyr_example/blob/main/west.yml) | ||
| file. | ||
| The example repository contains a | ||
| [`west.yml`](https://github.com/tinyvision-ai-inc/tinyclunx33_zephyr_example/blob/main/west.yml) | ||
| that has all the dependencies correctly setup already, | ||
| and more can be added for integrating 3rd-party code, or splitting a larger codebase in modules. | ||
|
|
||
|
|
||
| ## Repositories organization | ||
| ## Building the firmware | ||
|
|
||
| Fork of Zephyr: how our development is organized | ||
| This guide uses the | ||
| [`tinyclunx33_zephyr_example`](https://github.com/tinyvision-ai-inc/tinyclunx33_zephyr_example) | ||
| sample application named `app_imx219`. | ||
|
|
||
| - [`zephyr_internal`](https://github.com/tinyvision-ai-inc/zephyr_internal): | ||
| There are several targets for building the firmware, depending on what platform you wish to build on: | ||
|
|
||
| where the development happens, the `zephyr_internal` branch acts as a `dev` branch | ||
| * **Shield:** `tinyclunx33_devkit_rev1`, `tinyclunx33_devkit_rev2`, `custom` | ||
| * **Board:** `tinyclunx33@rev1`, `tinyclunx33@rev2` | ||
| * **SoC:** `rtl008`, `rtl009`, `rtl010`, `custom` | ||
|
|
||
| - [`zephyr_private`](https://github.com/tinyvision-ai-inc/zephyr_private): | ||
| Assuming a SoM Rev2, a Devkit Rev2, and RTL010 being used: | ||
|
|
||
| releases of the `zephyr_internal` repo, the `zephyr_private` branch acts as a `main` branch. | ||
| You can ask the access to it to tinyVision.ai Inc. | ||
| 1. Follow the general Zephyr to setup the build environment for your platform: | ||
| <https://docs.zephyrproject.org/latest/develop/getting_started/index.html> | ||
|
|
||
| - [`zephyr_public`](https://github.com/tinyvision-ai-inc/zephyr): | ||
| 2. Reset the workspace directory you created from Zephyr's Getting Started Guide | ||
| ``` | ||
| cd ~/zephyrproject | ||
| rm -rf .west | ||
| ``` | ||
|
|
||
| only used for public contributions to Zephyr, and not relevant for using the tinyCLUNX33 at this time. | ||
| 3. Download the tinyCLUNX33 Zephyr example repository. | ||
| This will also download the tinyVision Zephyr SDK as a dependency: | ||
| ``` | ||
| west init -m https://github.com/tinyvision-ai-inc/tinyclunx33_zephyr_example | ||
| west update | ||
| ``` | ||
|
|
||
| Example repository: all you need to get started. | ||
| 4. Build a sample application from this example repository, for instance `app_imx219`. | ||
| You would have to choose the build target that matches the hardware you have: | ||
|
|
||
| - [`tinyclunx33_zephyr_example`](https://github.com/tinyvision-ai-inc/tinyclunx33_zephyr_example): | ||
| For example, this will build a firmware image for the tinyCLUNX33 SoM Rev2 on which the RTL010 was loaded, | ||
| assuming that the SoM is attached to the Devkit Rev2: | ||
|
|
||
| the top-level repository that contains the example, and points at the `zephyr_private` repo, downloaded in chain by the | ||
| [`west`](https://docs.zephyrproject.org/latest/develop/west/index.html) build tool. | ||
| ```console | ||
| cd ~/zephyrproject/tinyclunx33_zephyr_example/app_imx219// | ||
| west build --board tinyclunx33@rev2/rtl010 --shield tinyclunx33_devkit_rev2 | ||
| ``` | ||
|
|
||
| 5. Then, program the firmware into the devkit, with the DEBUG interface connected. | ||
| The `ecpprog` utility is integrated with `west` and can be called this way: | ||
|
|
||
| ## Release process | ||
| ```console | ||
| west flash | ||
| ``` | ||
|
|
||
| For transparency, here is how tinyVision.ai performs a new [release](https://github.com/tinyvision-ai-inc/tinyclunx33_zephyr_example/releases/) internally: | ||
| See also [SoM Flash](som_flash.md) for other flash programming options. | ||
|
|
||
| 1. Build and test every example using the `zephyr_internal` repo and `zephyr_internal` branch, | ||
| and commit as needed to fix the exapmles. | ||
| You should now be able to see messages through the UART interface, | ||
| a new USB Video Class (UVC) interface showing-up on your operating system, | ||
| and if an IMX219 image sensor is connected, a video stream coming out of it. | ||
|
|
||
| 2. Once all the examples work, run [`blobify.sh`](https://github.com/tinyvision-ai-inc/zephyr_private/blob/zephyr_private/drivers/usb/udc/blobify.sh) | ||
| to obfuscate the function names from [`udc_usb23blob.c`](https://github.com/tinyvision-ai-inc/zephyr_internal/blob/zephyr_internal/drivers/usb/udc/udc_usb23blob.c). | ||
|
|
||
| 3. Build any example another time to generate [`udc_usb23blob.c.obj`](https://github.com/tinyvision-ai-inc/zephyr_private/blob/zephyr_private/drivers/usb/udc/udc_usb23blob.c.obj) | ||
| and commit it on the `zephyr_internal_blob` branch. | ||
| ## Including the SDK into your existing project | ||
|
|
||
| 4. Import the content of the `zephyr_internal_blob` branch onto `zephyr_private` with `git checkout zephyr_private` then `git checkout --no-overlay zephyr_internal_blob`. | ||
| In case your application was started without using the SDK, you may be interested in adding it as a dependency in | ||
| [`west.yml`](https://github.com/tinyvision-ai-inc/tinyclunx33_zephyr_example/blob/main/west.yml), | ||
| by adding the following snippet at the bottom of the file: | ||
|
|
||
| 5. Remove the `udc_usb23blob.c` file and commit the result into the `zephyr_private` branch, | ||
| with a message indicating which commit of `zephyr_internal` this came from. | ||
| ``` | ||
| ... | ||
| 6. Re-test and re-build each example using the `zephyr_private` branch, and publish the generated files. | ||
| - name: tinyclunx33_sdk | ||
| url: [email protected]:tinyvision-ai-inc/zephyr_internal | ||
| revision: tinyclunx33_sdk | ||
| ``` | ||
|
|
||
|
|
||
| ## Troubleshooting | ||
|
|
||
| The first sign of life from the Zephyr RTOS coming from the board will happen over the FTDI UART interface, available by plugging the DEBUG USB cable. | ||
|
|
||
| Once a serial console viewer is connected to the second interface (often numbered #1, such as `/dev/ttyUSB1`), logs will be available to review what is going on. | ||
| The first sign of life from the Zephyr RTOS comes the UART interface, available by plugging the DEBUG USB cable. | ||
|
|
||
| In order to get early boot logs, you can hit the SW2 button which will reset the board but keep the serial console attached. | ||
|
|
||
| On the logging interface directly, the Zephyr shell is available with debug commands, except for the Shell example for which it goes over a separate `/dev/ttyACM0`. | ||
| Depending on firmware configuration (see `chosen { zephyr,shell-uart = ...; }` property of `build/zephyr/zephyr.dts`), | ||
| the Zephyr shell will be available over that same UART interface. | ||
| For the Shell example, this goes through the DATA USB port, `/dev/ttyACM0`. | ||
|
|
||
| These debug commands permit to review the internal state of the USB peripheral, using subcommands of `dwc3`. | ||
|
|
||
| These debug commands permit to review the internal state of the driver using subcommands of `usb23`. | ||
| Interactive help is given by entering the `help dwc3` comand. | ||
|
|
||
| Their usage is described with tab completion. | ||
| If nothing comes through the UART, see the | ||
| [FPGA troubleshooting](https://tinyclunx33.tinyvision.ai/som_fpga.html#autotoc_md67) | ||
| section. |