boards: fvp_baser_aemv8r: doc: debug with Arm DS

Add document about debugging with Arm Development Studio and some
description. Standardize the names.

Signed-off-by: Qi Feng <qi.feng@arm.com>

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

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=<path/to/fvp/dir>
-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