Zephyr SDK Introduction

In this document, “Zephyr SDK” refers to the complete Zephyr development workspace (a west multi-repository environment) that Realtek provides for the Ameba platform. It is not the same as the official Zephyr SDK toolchain (compilers, etc.) released by the Zephyr project.

SDK consists of the following components:

SDK       west top-level directory
├── .west      west locates the top-level west.yml based on .west/config
├── bootloader source code of the MCUboot secure bootloader
├── manifests  contains the west-managed manifest file west.yml
├── modules    essential modules, including Ameba peripheral driver libraries, crypto/mbedtls libraries, etc.
├── nuwa.py -> tools/meta_tools/nuwa.py symbolic link, a wrapper around west commands provided by SDK
├── tools      contains .py scripts for meta boot and binary concatenation, as well as the imagetool download utility
└── zephyr     main Zephyr directory, including the Zephyr OS kernel, board support packages, sample applications, and test cases

SDK Directory Structure

The Zephyr directory is synchronized from the open-source real-time operating system Zephyr OS on GitHub (currently using Zephyr kernel version v4.4.1). Its source tree structure is as follows:

SDK/zephyr
├── arch     CPU architecture-specific code, e.g., ARM/RISC-V
├── boards   board-specific definitions, such as various Ameba EVB development boards
├── cmake    CMake configuration files and scripts required to build Zephyr applications
├── doc      official Zephyr documentation (offline copy)
├── drivers  device driver code, e.g., Ameba SPI driver
├── dts      DeviceTree source files (hardware initialization configurations for SoCs)
├── include  public Zephyr API header files
├── kernel   Zephyr OS kernel source code
├── lib      library code, including a minimal standard C library
├── misc     miscellaneous utility modules
├── modules  directory for third-party modules integrated into Zephyr (non-west modules), providing Kconfig definitions
├── samples  official Zephyr sample applications
├── scripts  scripts used for building and testing
├── share    architecture-independent auxiliary data, currently includes the Zephyr CMake package
├── soc      SoC-level definitions and default configurations
├── subsys   Zephyr subsystem implementations, e.g., USB Device Stack, File System, etc.
└── tests    official Zephyr test suites

boards

Currently, SDK provides board support for five EVB development boards of the Ameba series, structured as follows:

SDK/zephyr/boards
├── realtek
    ├── rtl8721f_evb
    ├── rtl872xda_evb
    ├── rtl872xd_evb
    ├── pke8721daf_c13_f10
    └── rtl8730e_evb

drivers

The Zephyr driver structure adapted in SDK is as follows:

SDK/zephyr/drivers
├── adc
├── audio
├── can
├── clock_control
├── console
├── counter
├── display
├── dma
├── entropy
├── ethernet
├── flash
├── gpio
├── hwinfo
├── i2c
├── i2s
├── input        capacitive touch (captouch) input driver
├── led_strip
├── mipi_dbi
├── pinctrl
├── pwm
├── rtc
├── sdhc
├── sensor       temperature (thermal) sensor driver
├── serial
├── spi
├── usb
├── watchdog
└── wifi

dts

The DeviceTree initialization configuration structure in SDK is as follows:

SDK/zephyr/dts
├── arm
│   └── realtek
│       ├── amebad      hardware initialization configuration for rtl872xd_evb
│       ├── amebadplus  hardware initialization configuration for rtl872xda_evb and pke8721daf_c13_f10
│       ├── amebag2     hardware initialization configuration for rtl8721f_evb
│       └── amebasmart  hardware initialization configuration for rtl8730e_evb
├── bindings            contains .yaml files describing the meaning of properties in each DeviceTree node

For more information about DeviceTree, refer to the DTS Introduction section under Zephyr Development.

samples

SDK provides official sample source code for drivers and applications, structured as follows:

SDK/zephyr/samples
├── basic           basic example applications
├── drivers         peripheral driver-related examples
├── hello_world     the classic Zephyr "Hello World" example
└── subsys          examples for Zephyr subsystems (e.g., USB)

Taking hello_world as an example:

hello_world
├── CMakeLists.txt  CMake build script
├── prj.conf        project configuration file
├── README.rst      project documentation
└── src
    └── main.c      application source code

tests

SDK provides test suites for Zephyr APIs, structured as follows:

SDK/zephyr/tests
├── benchmarks    performance benchmark tests for OS kernel APIs
├── drivers       API tests for peripheral drivers
├── kernel        API tests for the OS kernel
└── subsys        API tests for Zephyr subsystems (e.g., power management, storage)

modules Directory Structure

The modules directory is generated by west’s multi-repository management system. It mainly holds the external modules managed by west. These modules are independent Git repositories, defined jointly by manifests/west.yml and the zephyr/west.yml it imports. It includes third-party or Zephyr community-maintained standalone subsystems such as hal_* (Hardware Abstraction Layer), crypto/mbedtls, fs/fatfs, etc. The structure is as follows:

SDK/modules
├── crypto
│   └── mbedtls              mbedtls cryptographic library
├── fs
│   ├── fatfs                FatFs file system
│   └── littlefs             littlefs file system
├── hal
│   ├── cmsis                CMSIS library
│   └── realtek              Realtek peripheral driver library
├── lib
│   ├── gui                  LVGL graphics library
│   └── zcbor                CBOR encoding/decoding library
└── tee
    ├── tf-a                 ARM Trusted Firmware-A (secure boot firmware)
    └── tf-m                 ARM Trusted Firmware-M (secure firmware framework)

The SDK/modules/hal/realtek directory corresponds to the hal_realtek repository managed by west; its actual checkout path is determined by the path field in west.yml. This repository contains the peripheral driver libraries for the Ameba series of chips. Files under the Ameba directory originate from ameba-rtos and are periodically synchronized into the hal_realtek repository. Its structure is as follows:

SDK/modules/hal/realtek
├── ameba
│   ├── amebaxxx
│   │   ├── include     common header files such as platform_autoconf.h
│   │   ├── ld          linker scripts
│   │   └── source      peripheral driver source code for this chip
│   ├── common
│   │   ├── bluetooth   Bluetooth protocol stack source code
│   │   ├── include     common Ameba header files
│   │   ├── loader      loader-related source code
│   │   ├── os_wrapper  OS abstraction layer code
│   │   ├── rtk_coex    Bluetooth and Wi-Fi coexistence source code
│   │   ├── usb         USB device stack source code
│   │   └── wifi        Wi-Fi protocol stack source code
│   ├── scripts         helper scripts, e.g. toolchain installation and binary blob updates
│   └── usrcfg
│       ├── amebaxxx    default configuration files for various Ameba chip models
│       └── common      common Ameba configuration files
└── zephyr
   └── module.yml       module description file informing Zephyr’s build system (CMake) how to locate, include, and compile this specific module