IC:

Introduction

There are two kinds of examples in the SDK.

  • Application examples

  • Peripheral examples

This chapter illustrates the contents of examples and how to build example source code.

Items

Path

Description

Application example

{SDK}\component\example

xml, ssl, …

Peripheral example

{SDK}\component\example\peripheral

ADC, UART, I2C, SPI, Timer, …

The peripheral examples are demos of peripherals. Most examples consist of raw and mbed folders, you can choose raw or mbed demos as you like.

Items

Path

Description

mbed

{SDK}\component\example\peripheral\{peripheral}\mbed

mbed APIs are used.

raw

{SDK}\component\example\peripheral\{peripheral}\raw

Low-level driver APIs are used.

In each folder of example, there are C source files, header files, CMakeLists.txt and README.md. You should check for detailed configurations of the example according to README.md.

Note

The examples are shared by all Realtek SoC, so you need to refer to README.md for detailed information of different ICs.

  • README.md: Technical documentation with:

    • Example description

    • HW configurations

    • Software configurations

    • Expected behavior

    • Support ICs

The entry function of example is app_example(), and each example has its own app_example().

The app_example() in main.c under {SDK}\amebaxxx_gcc_project\project_xxx\src is compiled with weak properties. When the example is built, app_example() in the example file is marked as a strong symbol, and app_example() in the main.c file will be ignored.

_WEAK void app_example(void)
{

}

// default main
int main(void)
{
   ...
   app_example();
   ...
   /* enable schedule, start kernel */
   vTaskStartSchedule();
}

The examples normally run on KM4. To run example, you only need to:

  1. Check software and hardware settings in README.md of the example. If the user needs to configure the project, you can execute ./menuconfig.py -f /.../prj.conf to configure it. For an introduction to prj.conf, see conf file introduction. Execute in the terminal:

    ./menuconfig.py -f ../component/example/.../prj.conf
    
  2. Add compile options ./build.py -a {example folder name} when building the project, and replace {example folder name} with the specific folder name of this example. The path of {example folder name} includes the directory above CMakeLists.txt.

Application Example

For example, if you want to build xml example to start an xml example thread, you need to:

  1. Set the macro in SDK according to README.md in {SDK}\component\example\xml

    SDK
      └── component                   include FreeRTOS、SoC、mbed API、Wi-Fi、network
          ├── ...
          └── example                 application example
              ├── peripheral          All peripheral drivers and module codes used by the application
              ├── ssl
              ├── storage
              ├── ...
              └── xml
                  ├── app_example.c
                  ├── CMakeLists.txt
                  ├── example_xml.c
                  ├── example_xml.h
                  └── README.md
    
  2. Enter ./build.py -a xml for terminal.

    ./build.py -a xml
    

Peripheral Example

For example, if you want to build peripheral/raw/I2C/raw_i2c_dma_mode example to start an peripheral/raw/I2C/raw_i2c_dma_mode example thread, you need to:

  1. Set the macro in SDK according to README.md in {SDK}\component\example\xml\peripheral\raw\I2C\raw_i2c_dma_mode

    SDK
      └── component                   include FreeRTOS、SoC、mbed API、Wi-Fi、network
          ├── ...
          └── example                 application example
              ├── ...
              ├── peripheral          All peripheral drivers and module codes used by the application
              │   ├── mbed
              │   └── raw
              │       ├── ...
              │       └── I2C
              │           ├── ...
              │           └── raw_i2c_dma_mode
              │               ├── app_example.c
              │               ├── CMakeLists.txt
              │               ├── example_raw_i2c_dma_mode.c
              │               ├── example_i2c_ext.h
              │               └── README.md
              ├── ssl
              ├── storage
              └── xml
    
  2. Enter ./build.py -a raw_i2c_dma_mode for terminal.

    ./build.py -a raw_i2c_dma_mode