diff options
Diffstat (limited to 'docs/sections/customizing.md')
| -rw-r--r-- | docs/sections/customizing.md | 109 |
1 files changed, 97 insertions, 12 deletions
diff --git a/docs/sections/customizing.md b/docs/sections/customizing.md index 3bf9b26..17b8040 100644 --- a/docs/sections/customizing.md +++ b/docs/sections/customizing.md @@ -16,6 +16,7 @@ - [Reading user input from console](./customizing.md#reading-user-input-from-console) - [Output to MPS3 LCD](./customizing.md#output-to-mps3-lcd) - [Building custom use-case](./customizing.md#building-custom-use_case) + - [Adding custom platform support](./customizing.md#adding-custom-platform-support) This section describes how to implement a custom Machine Learning application running on Arm® *Corstone™-300* based FVP or on the Arm® MPS3 FPGA prototyping board. @@ -35,23 +36,38 @@ The following sign indicates the important conventions to apply: As mentioned in the [Repository structure](../documentation.md#repository-structure) section, project sources are: ```tree +├── dependencies ├── docs │ ├── ... │ └── Documentation.md +├── model_conditioning_examples ├── resources │ └── img_class │ └── ... +├── /resources_downloaded/ +│ └── img_class +│ └── ... ├── scripts -│ └── ... +│ ├── platforms +│ │ ├── mps3 +│ │ ├── native +│ │ └── simple_platform +│ └── ... ├── source -│ ├── application -│ │ ├── hal -│ │ ├── main -│ │ └── tensorflow-lite-micro -│ └── use_case -│ └──img_class -├── CMakeLists.txt -└── Readme.md +│ ├── application +│ │ ├── main +│ │ └── tensorflow-lite-micro +│ ├── hal +│ ├── log +│ ├── math +│ ├── profiler +│ └── use_case +│ └── <usecase_name> +│ ├── include +│ ├── src +│ └── usecase.cmake +├── tests +└── CMakeLists.txt ``` Where the `source` folder contains C/C++ sources for the platform and ML applications. Common code related to the @@ -342,13 +358,14 @@ Now define the `main_loop` function with the signature described in [Main loop f ```C++ #include "hal.h" +#include "log_macros.h" void main_loop(hal_platform& platform) { printf("Hello world!"); } ``` -The preceeding code is already a working use-case. If you compile and run it (see [Building custom usecase](./customizing.md#building-custom-use-case)), +The preceding code is already a working use-case. If you compile and run it (see [Building custom usecase](./customizing.md#building-custom-use-case)), then the application starts and prints a message to console and exits straight away. You can now start filling this function with logic. @@ -415,6 +432,7 @@ For example: ```C++ #include "HelloWorldModel.hpp" +#include "log_macros.h" bool arm::app::HelloWorldModel::EnlistOperations() { @@ -483,6 +501,7 @@ The following code adds inference invocation to the main loop function: ```C++ #include "hal.h" #include "HelloWorldModel.hpp" +#include "log_macros.h" void main_loop(hal_platform& platform) { @@ -548,7 +567,7 @@ The code snippet has several important blocks: data type. ```C++ - Const uint32_t tensorSz = outputTensor->bytes ; + Const uint32_t tensorSz = outputTensor->bytes; const uint8_t *outputData = tflite::GetTensorData<uint8>(outputTensor); ``` @@ -570,7 +589,7 @@ profiler.PrintProfilingResult(); ## Printing to console -The preceding examples used some function to print messages to the console. +The preceding examples used some function to print messages to the console. To use them, include `log_macros.h` header. However, for clarity, here is the full list of available functions: @@ -711,3 +730,69 @@ As a result, the file `ethos-u-hello_world.axf` is created. The MPS3 build also directory with binaries and the file `sectors/images.txt` to be copied to the MicroSD card on the board. The next section of the documentation covers: [Testing and benchmarking](testing_benchmarking.md). + +## Adding custom platform support + +Platform build configuration script `build_configuration.cmake` is the main build entry point for platform sources. +It is used by top level CMakeLists.txt script to add a platform into the public build stream. +Platform build configuration script must have 2 functions: + * `set_platform_global_defaults` - to set platform source locations and other build options. + * `platform_custom_post_build` - to execute specific post build steps. + +The function `set_platform_global_defaults` must set `PLATFORM_DRIVERS_DIR` variable +``` + set(PLATFORM_DRIVERS_DIR "${HAL_PLATFORM_DIR}/mps3" PARENT_SCOPE) +``` +location of the platform library sources. + +> **Convention:** The default search path for platform build configuration scripts is in `scripts/cmake/platforms`. +> The directory name for a platform configuration script is also used as a value for `TARGET_PLATFORM` +> build option. For example: +> `scripts/cmake/platforms/my_platform` results in having `my_platform` as a `TARGET_PLATFORM` option for the build. + +The function `platform_custom_post_build` could be used to add platform specific post use-case application build steps. + +Repository's root level CMakeLists.txt calls common utility function `add_platform_build_configuration(TARGET_PLATFORM ${TARGET_PLATFORM})` +to add given target platform to the build stream. The function finds the script and includes +`build_configuration.cmake` file. After that public build can invoke +* `set_platform_global_defaults` +* `platform_custom_post_build` +for a specified platform. + +New platform sources, that are pointed to by `PLATFORM_DRIVERS_DIR` variable, could be placed anywhere, conventional location +is `source/hal/platform`. Platform must be a separate CMake project with CMakeLists.txt script and build into a static +library `libplatform-drivers.a`. +HAL expects platform to have `platfrom_drivers.h` header file with required interfaces for included peripherals. + +If the new platform uses existing cmsis device project then it should be linked with it like this: +``` + target_link_libraries(${PLATFORM_DRIVERS_TARGET} PUBLIC cmsis_device) +``` +Cmsis device exposes an entry point `--entry Reset_Handler` as a link interface. + +If the new platform defines custom cmsis device and has custom application entry point, +it must tell linker about it like this: +``` + target_link_options(${PLATFORM_DRIVERS_TARGET} INTERFACE --entry <custom handler name>) +``` + +Most of the ML use-case applications use UART and LCD, thus it is a hard requirement to implement at least stubs for +those. UART driver must implement functions from `uart_stdout.h` header. LCD driver must provide implementation for +functions declared in `glcd_mps3.h` header. For stubs examples, please, see simple platform sources. + +If the new platform does not use UART, it is possible to run application with semi-hosting enabled - printf +statements will be shown in the host machine console. Please, comment out all content of the +`source/hal/profiles/bare-metal/bsp/retarget.c` file in this case. + +Examples of the UART and LCD drivers implementation could be found here: `source/hal/components`. + +Linker scripts for armclang and GCC should be added. The location of the files is on your discretion. The new +platform build configuration script must add it in the `platform_custom_post_build` function like this: +``` + add_linker_script( + ${PARSED_TARGET_NAME} # Target + ${CMAKE_SCRIPTS_DIR}/platforms/mps3 # linker scripts directory path + ${LINKER_SCRIPT_NAME}) # Name of the file without suffix +``` + +Please see existing platforms sources and build scripts for more details.
\ No newline at end of file |