diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/documentation.md | 17 | ||||
| -rw-r--r-- | docs/sections/building.md | 13 | ||||
| -rw-r--r-- | docs/sections/customizing.md | 12 | ||||
| -rw-r--r-- | docs/sections/deployment.md | 77 | ||||
| -rw-r--r-- | docs/sections/memory_considerations.md | 2 | ||||
| -rw-r--r-- | docs/sections/timing_adapters.md | 5 | ||||
| -rw-r--r-- | docs/sections/troubleshooting.md | 2 |
7 files changed, 84 insertions, 44 deletions
diff --git a/docs/documentation.md b/docs/documentation.md index 7258928..41c0642 100644 --- a/docs/documentation.md +++ b/docs/documentation.md @@ -42,12 +42,15 @@ Before starting the setup process, please make sure that you have: - An Arm® MPS3 FPGA prototyping board and components for FPGA evaluation or a `Fixed Virtual Platform` binary: - An MPS3 board loaded with Arm® Corstone™-300 (`AN552`) or Corstone™-310 reference package (`AN555`). See - <https://developer.arm.com/downloads/-/download-fpga-images>. You + [Download FPGA Images](https://developer.arm.com/downloads/-/download-fpga-images). You must have a USB connection between your machine and the MPS3 board - for UART menu and for deploying the application. - - `Arm® Corstone™-300` based FVP for MPS3 is available from: - <https://developer.arm.com/tools-and-software/open-source-software/arm-platforms-software/arm-ecosystem-fvps>. - - `Arm® Corstone™-310` based FVP is available under Arm® Virtual Hardware: <https://www.arm.com/products/development-tools/simulation/virtual-hardware> + - Both `Arm® Corstone™-300` and `Arm® Corstone™-310` based FVPs for MPS3 are available from: + [Arm® Ecosystem FVPs](https://developer.arm.com/tools-and-software/open-source-software/arm-platforms-software/arm-ecosystem-fvps) + and as [Arm® Virtual Hardware](https://www.arm.com/products/development-tools/simulation/virtual-hardware) +- An Arm® MPS4 `Fixed Virtual Platform` binary to try the latest `Arm® Corstone™-315` reference platform. This can also + be downloaded from [Arm® Ecosystem FVPs](https://developer.arm.com/tools-and-software/open-source-software/arm-platforms-software/arm-ecosystem-fvps) + page. > **Note:**: There are two Arm® Corstone™-300 implementations available for the MPS3 FPGA board - application > notes `AN547` and `AN552`. We are aligned with the latest application note `AN552`. However, the application built @@ -326,9 +329,9 @@ For further information, please see: - [Deployment](./sections/deployment.md#deployment) - [Fixed Virtual Platform](./sections/deployment.md#fixed-virtual-platform) - - [Setting up the MPS3 Corstone-300 FVP](./sections/deployment.md#setting-up-the-mps3-arm-corstone_300-fvp) - - [Deploying on an FVP emulating MPS3](./sections/deployment.md#deploying-on-an-fvp-emulating-mps3) - - [MPS3 board](./sections/deployment.md#mps3-board) + - [Installing an FVP](./sections/deployment.md#installing-an-fvp) + - [Deploying on an FVP](./sections/deployment.md#deploying-on-an-fvp) + - [MPS3 FPGA board](./sections/deployment.md#mps3-fpga-board) - [Deployment on MPS3 board](./sections/deployment.md#deployment-on-mps3-board) ## Implementing custom ML application diff --git a/docs/sections/building.md b/docs/sections/building.md index d20e570..775f71a 100644 --- a/docs/sections/building.md +++ b/docs/sections/building.md @@ -175,13 +175,16 @@ The build parameters are: - `TARGET_PLATFORM`: The target platform to execute the application on: - `mps3` (default) + - `mps4` - `native` - `simple_platform` -- `TARGET_SUBSYSTEM`: The target platform subsystem. Specifies the design implementation for the deployment target. For - both, the MPS3 FVP and the MPS3 FPGA, this must be left to the default value of SSE-300: - - `sse-300` (default - [Arm® Corstone™-300](https://developer.arm.com/ip-products/subsystem/corstone/corstone-300)) - - `sse-310` (The FVP is available via Arm Virtual Hardware (AVH) hosted on AWS) +- `TARGET_SUBSYSTEM`: The target platform subsystem. Specifies the design implementation for the deployment target. + For `mps3` target these sub-systems are available: + - `sse-300`: this is the default, see [Arm® Corstone™-300](https://developer.arm.com/Processors/Corstone-300) + - `sse-310`: See [Arm® Corstone™-310](https://developer.arm.com/Processors/Corstone-310) + For `mps4` target: + - `sse-315`: See [Arm® Corstone™-315](https://developer.arm.com/Processors/Corstone-315) - `CMAKE_TOOLCHAIN_FILE`: This built-in CMake parameter can be used to override the default toolchain file used for the build. All the valid toolchain files are located in the scripts directory. For example, see: @@ -483,7 +486,7 @@ cmake .. \ Default CMake configuration behaviour looks for input samples, for each use case, in the default directory. All these inputs are baked-in into the application. If the number of files baked in is greater than one, a user menu is displayed on the application output, where the user is expected to enter their chosen option. See more here: -[Deploying on an FVP emulating MPS3](./deployment.md#deploying-on-an-fvp-emulating-mps3). +[Deploying on an FVP emulating MPS3](./deployment.md#deploying-on-an-fvp). To configure the project to use single input for each use case, CMake option `USE_SINGLE_INPUT` can be set to `ON`. This will result in each use case automatically running with predefined input data, thus removing the need for the diff --git a/docs/sections/customizing.md b/docs/sections/customizing.md index 42be12a..1a5e3ce 100644 --- a/docs/sections/customizing.md +++ b/docs/sections/customizing.md @@ -536,8 +536,8 @@ However, for clarity, here is the full list of available functions: ## Reading user input from console -The platform package under HAL must provide an implementation for a function `GetLine`. This is then wrapped by HAL to -expose a function called `hal_get_user_input`. +The platform package under HAL must provide an implementation for a function `GetLine`. This is then wrapped by HAL to +expose a function called `hal_get_user_input`. ```C++ char ch_input[128]; @@ -672,7 +672,7 @@ Platform build configuration script must have 2 functions: The function `set_platform_global_defaults` must set `PLATFORM_DRIVERS_DIR` variable ```cmake - set(PLATFORM_DRIVERS_DIR "${HAL_PLATFORM_DIR}/mps3" PARENT_SCOPE) + set(PLATFORM_DRIVERS_DIR "${MLEK_HAL_PLATFORM_DIR}/mps3" PARENT_SCOPE) ``` location of the platform library sources. @@ -774,9 +774,9 @@ function like this: ```cmake 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 + ${PARSED_TARGET_NAME} # Target + ${CMAKE_CURRENT_FUNCTION_LIST_DIR}/${TARGET_SUBSYSTEM} # Linker scripts directory path + ${LINKER_SCRIPT_NAME}) # Name of the file without suffix ``` Please see existing platforms sources and build scripts for more details. diff --git a/docs/sections/deployment.md b/docs/sections/deployment.md index 15a58c3..e556eb9 100644 --- a/docs/sections/deployment.md +++ b/docs/sections/deployment.md @@ -2,10 +2,10 @@ - [Deployment](./deployment.md#deployment) - [Fixed Virtual Platform](./deployment.md#fixed-virtual-platform) - - [Setting up the MPS3 Arm Corstone-300 FVP](./deployment.md#setting-up-the-mps3-arm-corstone_300-fvp) - - [Deploying on an FVP emulating MPS3](./deployment.md#deploying-on-an-fvp-emulating-mps3) + - [Installing an FVP](./deployment.md#installing-an-fvp) + - [Deploying on an FVP](./deployment.md#deploying-on-an-fvp) - [Running the FVP without the UI](./deployment.md#running-the-fvp-without-the-ui) - - [MPS3 board](./deployment.md#mps3-board) + - [MPS3 FPGA board](./deployment.md#mps3-fpga-board) - [MPS3 board top-view](./deployment.md#mps3-board-top_view) - [Deployment on MPS3 board](./deployment.md#deployment-on-mps3-board) @@ -27,22 +27,23 @@ Please ensure that you download the correct archive from the list under Arm® Co - Emulates MPS3 board and *not* for MPS2 FPGA board, - Contains support for Arm® Ethos™-U55 and Ethos™-U65 processors. -### Setting up the MPS3 Arm Corstone-300 FVP +### Installing an FVP -To install the FVP: +To install an FVP: -- Unpack the archive. +- Unpack the archive downloaded from [Arm® Ecosystem FVPs](https://developer.arm.com/tools-and-software/open-source-software/arm-platforms-software/arm-ecosystem-fvps). -- Run the installation script in the extracted package: - - `./FVP_Corstone_SSE-300.sh` +- Run the installation script in the extracted package. For example, `Arm® Corstone™-300` package will have + `FVP_Corstone_SSE-300.sh`. - Follow the instructions to install the FVP to your required location. -### Deploying on an FVP emulating MPS3 +> **Note**: The installation process is the same for other FVPs (Arm® Corstone™-310 and Corstone™-315) too. + +### Deploying on an FVP This section assumes that the FVP has been installed (see -[Setting up the MPS3 Arm Corstone-300 FVP](./deployment.md#setting-up-the-mps3-arm-corstone-300-fvp)) +[Installing an FVP](./deployment.md#installing-an-fvp)) to the home directory of the user: `~/FVP_Corstone_SSE-300`. The installation, typically, has the executable under `~/FVP_Corstone_SSE-300/model/<OS>_<compiler-version>/` directory. For the example below, we assume it is: `~/FVP_Corstone_SSE-300/models/Linux64_GCC-6.4`. @@ -51,7 +52,7 @@ For Arm Virtual Hardware, the installation paths are different (see Arm Virtual [Useful Links](./arm_virtual_hardware.md#useful-links) section). > **NOTE**: The commandline arguments for the FVP mentioned below are valid for FVPs (and AVH) for -> both Arm® Corstone™-300 and Corstone™-310. +> Arm® Corstone™-300, Corstone™-310 and Corstone™-315. To run a use-case on the FVP, from the [Build directory](../sections/building.md#create-a-build-directory): @@ -100,13 +101,21 @@ The FVP supports many command-line parameters, such as: The number signifies the 8x8 MACs that are performed per cycle-count and that are available on the hardware. - - `cpu0.CFGITCMSZ`: The ITCM size for the *Cortex-M* CPU. The size of ITCM is *pow(2, CFGITCMSZ - 1)* KB - - `cpu0.CFGDTCMSZ`: The DTCM size for the *Cortex-M* CPU. The size of DTCM is *pow(2, CFGDTCMSZ - 1)* KB - - `mps3_board.telnetterminal0.start_telnet`: Starts the telnet session if nothing connected. - - `mps3_board.uart0.out_file`: Sets the output file to hold the data written by the UART. Use `'-'` to send all output - to `stdout` and is empty by default). - - `mps3_board.uart0.shutdown_on_eot`: Shut down the simulation when an `EOT (ASCII 4)` char is transmitted. - - `mps3_board.visualisation.disable-visualisation`: Enables, or disables, visualization and is disabled by default. + - For `MPS3` based FVPs: + - `cpu0.CFGITCMSZ`: The ITCM size for the *Cortex-M* CPU. The size of ITCM is *pow(2, CFGITCMSZ - 1)* KB + - `cpu0.CFGDTCMSZ`: The DTCM size for the *Cortex-M* CPU. The size of DTCM is *pow(2, CFGDTCMSZ - 1)* KB + - `mps3_board.telnetterminal0.start_telnet`: Starts the telnet session if nothing connected. + - `mps3_board.uart0.out_file`: Sets the output file to hold the data written by the UART. Use `'-'` to send all output + to `stdout` and is empty by default). + - `mps3_board.uart0.shutdown_on_eot`: Shut down the simulation when an `EOT (ASCII 4)` char is transmitted. + - `mps3_board.visualisation.disable-visualisation`: Enables, or disables, visualization and is disabled by default. + - For `MPS4` based FVPs, the equivalent parameters for the list above are: + - `mps4_board.subsystem.cpu0.CFGITCMSZ` + - `mps4_board.subsystem.cpu0.CFGDTCMSZ` + - `mps4_board.telnetterminal0.start_telnet` + - `mps4_board.uart0.out_file` + - `mps4_board.uart0.shutdown_on_eot` + - `mps4_board.visualisation.disable-visualisation` and `vis_hdlcd.disable_visualisation`. To start the model in `128` mode for *Ethos-U55*: @@ -136,8 +145,8 @@ The FVP supports many command-line parameters, such as: ### Running the FVP without the UI -If there is a need to run the FVP without the UI (e.g running the FVP inside of a docker container), -it can be done as follows: +If there is a need to run the FVP without the UI (e.g. running the FVP inside a Docker container), +it can be done as follows. Add `-C mps3_board.visualisation.disable-visualisation=1` and `-C mps3_board.telnetterminal0.start_telnet=0` to the command line arguments when starting the FVP. For example: @@ -148,15 +157,37 @@ FVP_install_location/models/Linux64_GCC-6.4/FVP_Corstone_SSE-300_Ethos-U55 \ -C mps3_board.telnetterminal0.start_telnet=0 \ ./bin/mps3-sse-300/ethos-u-<use_case>.axf ``` +For an `MPS4` FVP, the arguments are similar. For example: +```commandline +FVP_install_location/models/Linux64_GCC-9.3/FVP_Corstone_SSE-315 \ + -C mps4_board.visualisation.disable-visualisation=1 \ + -C vis_hdlcd.disable_visualisation=1 \ + -C mps4_board.telnetterminal0.start_telnet=0 \ + ./bin/mps4-sse-315/ethos-u-<use_case>.axf + ``` -Once the FVP reports waiting on telnet connections, connect to the first serverport from another terminal. +Once the FVP reports waiting on telnet connections, connect to the first server port from another terminal. Assuming the FVP has the telnet server running at the default port 5000, connect to it by: ```commandline telnet localhost 5000 ``` -## MPS3 board +For applications that are configured with `USE_SINGLE_INPUT` CMake option, there is no interaction on telnet needed and +the application output can be directed to standard output by using an FVP option: + +- `-C mps3_board.uart0.out_file='-'` for MPS3 based FVPs, OR +- `-C mps4_board.uart0.out_file='-'` for MPS4 based FVPs. + +> **NOTE**: Dockerfile, provided within the repository, contains useful environment variables pre-assigned with +> above arguments. These can be used directly from command-line. For example, to run MPS4 Arm® Corstone™-315 based +> application within the Docker container, the following command can be used to run the FVP in headless mode. +> +> ```commandline +> ${FVP_315_U65} -a <path/to/ethos-u-<use_case>.axf> ${FVP_315_ARGS} +> ``` + +## MPS3 FPGA board > **Note:** Before proceeding, make sure that you have the MPS3 board powered on, and a USB A to B cable connected > between your machine and the MPS3. The connector on the MPS3 is marked as "Debug USB". diff --git a/docs/sections/memory_considerations.md b/docs/sections/memory_considerations.md index b8d1c25..30b36ac 100644 --- a/docs/sections/memory_considerations.md +++ b/docs/sections/memory_considerations.md @@ -290,6 +290,6 @@ used by a Vela optimized neural network model, then the Arm® *Ethos™-U* NPU w A bigger region of memory for storing the neural network model is placed in the DDR, or flash, region under `LOAD_REGION_1`. The two load regions are necessary as the motherboard configuration controller of the MPS3 limits the load size at address `0x00000000` to 1MiB. This has implications on how the application **is deployed** on MPS3, as -explained under the following section: [Deployment on MPS3](./deployment.md#mps3-board). +explained under the following section: [Deployment on MPS3](./deployment.md#mps3-fpga-board). The next section of the documentation covers: [Troubleshooting](troubleshooting.md). diff --git a/docs/sections/timing_adapters.md b/docs/sections/timing_adapters.md index b5d6e98..24f2fc9 100644 --- a/docs/sections/timing_adapters.md +++ b/docs/sections/timing_adapters.md @@ -161,4 +161,7 @@ not support the feature. Additionally - base addresses of timer adapters blocks | 3 | User memory | 0x4170_3000/0x5170_3000 | 4KB | This is why the evaluation kit is configured with timing adapters disabled altogether (parameter -`ETHOS_U_NPU_TIMING_ADAPTER_ENABLED` set to `OFF`) for Corstone-310 target platform. +`ETHOS_U_NPU_TIMING_ADAPTER_ENABLED` set to `OFF`) for Corstone-310 target platform. + +> **NOTE**: Arm® Corstone™-315 reference platforms do not use timing adapters. Therefore, like for +Arm® Corstone™-310, they are force-disabled in the CMake configuration. diff --git a/docs/sections/troubleshooting.md b/docs/sections/troubleshooting.md index 6841e62..180f62d 100644 --- a/docs/sections/troubleshooting.md +++ b/docs/sections/troubleshooting.md @@ -51,7 +51,7 @@ For example, if the `accelerator-config` from the Vela command was `ethos-u55-12 `ethos-u55-256`, the FVP must be executed with additional command line parameter to instruct it to emulate the 256 MACs configuration instead. -The [deploying on an FVP emulating MPS3](./deployment.md#deploying-on-an-fvp-emulating-mps3) page provides guidance +The [deploying on an FVP](./deployment.md#deploying-on-an-fvp) page provides guidance on how to instruct the FVP to change the number of MACs units. Note that when the FVP is launched and the application starts executing, various parameters about the system are |