diff --git a/boards/arm64/fvp_baser_aemv8r/doc/debug-with-arm-ds.rst b/boards/arm64/fvp_baser_aemv8r/doc/debug-with-arm-ds.rst new file mode 100644 index 00000000000..4df72d60811 --- /dev/null +++ b/boards/arm64/fvp_baser_aemv8r/doc/debug-with-arm-ds.rst @@ -0,0 +1,145 @@ +.. _debug_with_arm_ds: + +Debug with Arm DS +################# + +Install Arm DS +************** + +Please refer to the official Arm Development Studio Page [1]_ for details. Here +``Version: 2020.b Build: 2020110909`` is used in the following example. + +.. image:: images/version-info.png + :scale: 70% + :alt: Arm DS Version + +Download Arm FVP BaseR AEMv8-R +****************************** + +Please refer to official FVP page [2]_ for download instructions. Here ``$FVP_D`` +is used to indicate which directory is FVP located. + +Use DS perspective +****************** + +From menu choose ``Window -> Perspective -> Open Perspective -> Other...``: + +.. image:: images/perspective-choose-other.png + :scale: 70% + :alt: Arm DS Perspective choose Other... + +In the opened window, choose ``Development Studio (default)``: + +.. image:: images/perspective-choose-ds.png + :scale: 70% + :alt: Arm DS Perspective choose DS + +Create a new configuration database +*********************************** + +Create a new configuration database by selecting ``File -> New -> Other... -> Configuration Database``: + +.. image:: images/create-new-configuration-database.png + :scale: 70% + :alt: Arm DS create new configuration database + +Choose a name for the database. Here ``Zephyr`` is used: + +.. image:: images/create-new-configuration-database_database-name.png + :scale: 70% + :alt: Arm DS create new configuration database: choose database name + +Click ``Finish`` and the new configuration database can be seen in ``Project Explorer``: + +.. image:: images/create-new-configuration-database_shown-in-project-explorer.png + :scale: 70% + :alt: Arm DS create new configuration database: shown in project explorer + +Create a new model configuration +******************************** + +Right click ``Zephyr`` in ``Project Explorer``, choose ``New -> Model Configuration``: + +.. image:: images/create-new-model-configuration.png + :scale: 70% + :alt: Arm DS create new model configuration + +In the opened window: + +1. Choose ``Iris`` for ``Model Interface``, then ``Next >``. +2. Choose ``Launch and connect to specific model``, then ``Next >``. +3. Set ``Model Path`` to ``$FVP_D/FVP_BaseR_AEMv8R``, then ``Finish``. + +.. image:: images/create-new-model-configuration_model-path.png + :scale: 70% + :alt: Arm DS create new model configuration: set model path + +Then in ``FVP_BaseR_AEMv8R`` tab, change ``ARMAEMv8-R_`` to ``V8R64-Generic``, +click ``Save`` and then click ``Import``: + +.. image:: images/create-new-model-configuration_model-use-V8R64-Generic.png + :scale: 70% + :alt: Arm DS create new model configuration: import + +Create a new launch configuration +********************************* + +From ``Project Explorer``, right click ``FVP_BaseR_AEMv8R`` and select ``Debug as -> Debug configurations...``: + +.. image:: images/create-new-launch-configuration_context-menu.png + :scale: 70% + :alt: Arm DS create new launch configuration: context menu + +Select ``Generic Arm C/C++ Application`` and click ``New launch configuration`` button. +A new configuration named ``New_configuration`` will be created. + +1. In ``Connection`` tab: + + - In ``Select target`` box, select ``Imported -> FVP_BaseR_AEMv8R -> Bare Metal Debug -> ARMAEMv8-R_MP_0`` + - In ``Connections`` box, set ``Model parameters`` to:: + + -C bp.dram.enable_atomic_ops=1 -C bp.sram.enable_atomic_ops=1 -C bp.refcounter.non_arch_start_at_default=1 -C gic_distributor.GICD_CTLR-DS-1-means-secure-only=1 -C gic_distributor.has-two-security-states=0 -C bp.vis.disable_visualisation=1 -C cluster0.has_aarch64=1 -a /home/fengqi/zephyrproject/build/zephyr/zephyr.elf + + These parameters are passed to ``FVP_BaseR_AEMv8R`` when launches. Run ``FVP_BaseR_AEMv8R --help`` + to see all command line options. Run ``FVP_BaseR_AEMv8R --list-params`` to see all supported parameters. + The file ``zephyr.elf`` specified by ``-a`` is the binary built from Zephyr. + +.. image:: images/create-new-launch-configuration_connection.png + :scale: 70% + :alt: Arm DS create new launch configuration: connection + +2. In ``Files`` tab: + + In ``Files`` box, set ``Load symbols from file`` to full path of ``zephyr.elf`` that you built. + +.. image:: images/create-new-launch-configuration_files.png + :scale: 70% + :alt: Arm DS create new launch configuration: files + +3. In ``Debugger`` tab: + + - In ``Run control`` box, check ``Execute debugger commands`` and insert:: + + add-symbol-file "/home/fengqi/zephyrproject/build/zephyr/zephyr.elf" EL1S:0 + + Replace ``/home/fengqi/zephyrproject/build/zephyr/zephyr.elf`` with your local path. + + - In ``Paths`` box, set ``Source search directory`` to the path to Zephyr source code. + +.. image:: images/create-new-launch-configuration_debugger.png + :scale: 70% + :alt: Arm DS create new launch configuration: debugger + +After all these changes are made, click ``Apply``, then click ``Debug``. DS will +launch ``FVP_BaseR_AEMv8R`` and connect to it. You can see a new session is +connected in ``Debug Control`` window. + +.. image:: images/DS-debug-working.png + :scale: 70% + :alt: Arm DS working + +References +********** + +.. [1] https://developer.arm.com/tools-and-software/embedded/arm-development-studio +.. [2] https://developer.arm.com/tools-and-software/simulation-models/fixed-virtual-platforms/arm-ecosystem-models diff --git a/boards/arm64/fvp_baser_aemv8r/doc/images/DS-debug-working.png b/boards/arm64/fvp_baser_aemv8r/doc/images/DS-debug-working.png new file mode 100644 index 00000000000..0c611e0dabe Binary files /dev/null and b/boards/arm64/fvp_baser_aemv8r/doc/images/DS-debug-working.png differ diff --git a/boards/arm64/fvp_baser_aemv8r/doc/images/create-new-configuration-database.png b/boards/arm64/fvp_baser_aemv8r/doc/images/create-new-configuration-database.png new file mode 100644 index 00000000000..f2e92f2a529 Binary files /dev/null and b/boards/arm64/fvp_baser_aemv8r/doc/images/create-new-configuration-database.png differ diff --git a/boards/arm64/fvp_baser_aemv8r/doc/images/create-new-configuration-database_database-name.png b/boards/arm64/fvp_baser_aemv8r/doc/images/create-new-configuration-database_database-name.png new file mode 100644 index 00000000000..6d5d0b76100 Binary files /dev/null and b/boards/arm64/fvp_baser_aemv8r/doc/images/create-new-configuration-database_database-name.png differ diff --git a/boards/arm64/fvp_baser_aemv8r/doc/images/create-new-configuration-database_shown-in-project-explorer.png b/boards/arm64/fvp_baser_aemv8r/doc/images/create-new-configuration-database_shown-in-project-explorer.png new file mode 100644 index 00000000000..5b950b13bb3 Binary files /dev/null and b/boards/arm64/fvp_baser_aemv8r/doc/images/create-new-configuration-database_shown-in-project-explorer.png differ diff --git a/boards/arm64/fvp_baser_aemv8r/doc/images/create-new-launch-configuration_connection.png b/boards/arm64/fvp_baser_aemv8r/doc/images/create-new-launch-configuration_connection.png new file mode 100644 index 00000000000..7db82252fbb Binary files /dev/null and b/boards/arm64/fvp_baser_aemv8r/doc/images/create-new-launch-configuration_connection.png differ diff --git a/boards/arm64/fvp_baser_aemv8r/doc/images/create-new-launch-configuration_context-menu.png b/boards/arm64/fvp_baser_aemv8r/doc/images/create-new-launch-configuration_context-menu.png new file mode 100644 index 00000000000..0d85c15f1b6 Binary files /dev/null and b/boards/arm64/fvp_baser_aemv8r/doc/images/create-new-launch-configuration_context-menu.png differ diff --git a/boards/arm64/fvp_baser_aemv8r/doc/images/create-new-launch-configuration_debugger.png b/boards/arm64/fvp_baser_aemv8r/doc/images/create-new-launch-configuration_debugger.png new file mode 100644 index 00000000000..764fef843da Binary files /dev/null and b/boards/arm64/fvp_baser_aemv8r/doc/images/create-new-launch-configuration_debugger.png differ diff --git a/boards/arm64/fvp_baser_aemv8r/doc/images/create-new-launch-configuration_files.png b/boards/arm64/fvp_baser_aemv8r/doc/images/create-new-launch-configuration_files.png new file mode 100644 index 00000000000..0b17c0986aa Binary files /dev/null and b/boards/arm64/fvp_baser_aemv8r/doc/images/create-new-launch-configuration_files.png differ diff --git a/boards/arm64/fvp_baser_aemv8r/doc/images/create-new-model-configuration.png b/boards/arm64/fvp_baser_aemv8r/doc/images/create-new-model-configuration.png new file mode 100644 index 00000000000..990640cb6f1 Binary files /dev/null and b/boards/arm64/fvp_baser_aemv8r/doc/images/create-new-model-configuration.png differ diff --git a/boards/arm64/fvp_baser_aemv8r/doc/images/create-new-model-configuration_model-path.png b/boards/arm64/fvp_baser_aemv8r/doc/images/create-new-model-configuration_model-path.png new file mode 100644 index 00000000000..9b08ed650b6 Binary files /dev/null and b/boards/arm64/fvp_baser_aemv8r/doc/images/create-new-model-configuration_model-path.png differ diff --git a/boards/arm64/fvp_baser_aemv8r/doc/images/create-new-model-configuration_model-use-V8R64-Generic.png b/boards/arm64/fvp_baser_aemv8r/doc/images/create-new-model-configuration_model-use-V8R64-Generic.png new file mode 100644 index 00000000000..0b2de806d27 Binary files /dev/null and b/boards/arm64/fvp_baser_aemv8r/doc/images/create-new-model-configuration_model-use-V8R64-Generic.png differ diff --git a/boards/arm64/fvp_baser_aemv8r/doc/images/perspective-choose-ds.png b/boards/arm64/fvp_baser_aemv8r/doc/images/perspective-choose-ds.png new file mode 100644 index 00000000000..f5a9348cecc Binary files /dev/null and b/boards/arm64/fvp_baser_aemv8r/doc/images/perspective-choose-ds.png differ diff --git a/boards/arm64/fvp_baser_aemv8r/doc/images/perspective-choose-other.png b/boards/arm64/fvp_baser_aemv8r/doc/images/perspective-choose-other.png new file mode 100644 index 00000000000..8e776d971d6 Binary files /dev/null and b/boards/arm64/fvp_baser_aemv8r/doc/images/perspective-choose-other.png differ diff --git a/boards/arm64/fvp_baser_aemv8r/doc/images/version-info.png b/boards/arm64/fvp_baser_aemv8r/doc/images/version-info.png new file mode 100644 index 00000000000..d92855e3ee2 Binary files /dev/null and b/boards/arm64/fvp_baser_aemv8r/doc/images/version-info.png differ diff --git a/boards/arm64/fvp_baser_aemv8r/doc/index.rst b/boards/arm64/fvp_baser_aemv8r/doc/index.rst index e99a212fdc5..59b9373df47 100644 --- a/boards/arm64/fvp_baser_aemv8r/doc/index.rst +++ b/boards/arm64/fvp_baser_aemv8r/doc/index.rst @@ -1,20 +1,31 @@ .. _fvp_baser_aemv8r: -ARM AEMv8R Fixed Virtual Platforms -################################## +Arm FVP BaseR AEMv8-R +##################### + +.. toctree:: + :maxdepth: 1 + + debug-with-arm-ds.rst Overview ******** -This board configuration will use ARM Fixed Virtual Platforms(FVP) to emulate -a generic Armv8-R 64-bit hardware platform. +This board configuration uses Armv8-R AEM FVP [1]_ to emulate a generic +Armv8-R [2]_ 64-bit hardware platform. -This configuration provides support for a generic Armv8-R 64-bit CPU and -these devices: +Fixed Virtual Platforms (FVP) are complete simulations of an Arm system, +including processor, memory and peripherals. These are set out in a +"programmer's view", which gives you a comprehensive model on which to build +and test your software. -* GICv3 interrupt controller -* ARM architected (Generic) timer -* PL011 UART controller +The Armv8-R AEM FVP is a free of charge Armv8-R Fixed Virtual Platform. It +supports the latest Armv8-R feature set. Please refer to FVP documentation +page [3]_ for more details about FVP. + +To Run the Fixed Virtual Platform simulation tool you must download "Armv8-R AEM +FVP" from Arm developer [1]_ (This might require the user to register) and +install it on your host PC. Hardware ******** @@ -31,13 +42,17 @@ The following hardware features are supported: +-----------------------+------------+----------------------+ | PL011 UART | on-chip | serial port | +-----------------------+------------+----------------------+ -| ARM GENERIC TIMER | on-chip | system clock | +| Arm GENERIC TIMER | on-chip | system clock | +-----------------------+------------+----------------------+ The kernel currently does not support other hardware features on this platform. +When FVP is launched with ``-a, --application FILE`` option, the kernel will be +loaded into DRAM region ``[0x0-0x7FFFFFFF]``. For more information, please refer +to the official Armv8-R AEM FVP memory map document [4]_. + Devices -======== +======= System Clock ------------ @@ -50,14 +65,11 @@ Serial Port This board configuration uses a single serial communication channel with the UART0. -Known Problems or Limitations -============================== - Programming and Debugging ************************* Use this configuration to build basic Zephyr applications and kernel tests in the -ARM FVP emulated environment, for example, with the :ref:`synchronization_sample`: +Arm FVP emulated environment, for example, with the :ref:`synchronization_sample`: .. zephyr-app-commands:: :zephyr-app: samples/synchronization @@ -65,25 +77,27 @@ ARM FVP emulated environment, for example, with the :ref:`synchronization_sample :board: fvp_baser_aemv8r :goals: build -This will build an image with the synchronization sample app. +This will build an image with the synchronization sample app. To run with FVP, +first set environment variable ``ARMFVP_BIN_PATH`` before using it. Then you +can run it with ``west build -t run``. -Run with FVP: -Set env ARMFVP_BIN_PATH before using it, -e.g. export ARMFVP_BIN_PATH= -NOTE: ARMFVP_BIN_PATH is the dir path. -ninja run or west build -t run +.. code-block:: bash + + export ARMFVP_BIN_PATH=/path/to/fvp/directory + west build -t run Debugging ========= Refer to the detailed overview about :ref:`application_debugging`. - -Networking -========== +See :ref:`debug_with_arm_ds` for how to debug with Arm Development Studio [5]_. References ********** -1. Arm Architecture Reference Manual Supplement - Armv8, for Armv8-R AArch64 architecture profile -2. AArch64 Exception and Interrupt Handling -3. https://developer.arm.com/tools-and-software/simulation-models/fixed-virtual-platforms +.. [1] https://developer.arm.com/tools-and-software/simulation-models/fixed-virtual-platforms/arm-ecosystem-models +.. [2] Arm Architecture Reference Manual Supplement - Armv8, for Armv8-R AArch64 architecture profile + https://developer.arm.com/documentation/ddi0600/latest/ +.. [3] https://developer.arm.com/tools-and-software/simulation-models/fixed-virtual-platforms/docs +.. [4] https://developer.arm.com/documentation/100964/1114/Base-Platform/Base---memory/BaseR-Platform-memory-map +.. [5] https://developer.arm.com/tools-and-software/embedded/arm-development-studio