1.. _debug_with_arm_ds:
2
3Debug with Arm DS
4#################
5
6Install Arm DS
7**************
8
9Please refer to the official Arm Development Studio Page [1]_ for details. Here
10``Version: 2020.b Build: 2020110909`` is used in the following example.
11
12.. image:: images/version-info.jpg
13   :align: center
14   :alt: Arm DS Version
15
16Download Arm FVP BaseR AEMv8-R
17******************************
18
19Please refer to official FVP page [2]_ for download instructions. Here ``$FVP_D``
20is used to indicate which directory is FVP located.
21
22Use DS perspective
23******************
24
25From menu choose ``Window -> Perspective -> Open Perspective -> Other...``:
26
27.. image:: images/perspective-choose-other.jpg
28   :align: center
29   :alt: Arm DS Perspective choose Other...
30
31In the opened window, choose ``Development Studio (default)``:
32
33.. image:: images/perspective-choose-ds.jpg
34   :align: center
35   :alt: Arm DS Perspective choose DS
36
37Create a new configuration database
38***********************************
39
40Create a new configuration database by selecting ``File -> New -> Other... -> Configuration Database``:
41
42.. image:: images/create-new-configuration-database.jpg
43   :align: center
44   :alt: Arm DS create new configuration database
45
46Choose a name for the database. Here ``Zephyr`` is used:
47
48.. image:: images/create-new-configuration-database_database-name.jpg
49   :align: center
50   :alt: Arm DS create new configuration database: choose database name
51
52Click ``Finish`` and the new configuration database can be seen in ``Project Explorer``:
53
54.. image:: images/create-new-configuration-database_shown-in-project-explorer.jpg
55   :align: center
56   :alt: Arm DS create new configuration database: shown in project explorer
57
58Create a new model configuration
59********************************
60
61Right click ``Zephyr`` in ``Project Explorer``, choose ``New -> Model Configuration``:
62
63.. image:: images/create-new-model-configuration.jpg
64   :align: center
65   :alt: Arm DS create new model configuration
66
67In the opened window:
68
691. Choose ``Iris`` for ``Model Interface``, then ``Next >``.
702. Choose ``Launch and connect to specific model``, then ``Next >``.
713. Set ``Model Path`` to ``$FVP_D/FVP_BaseR_AEMv8R``, then ``Finish``.
72
73.. image:: images/create-new-model-configuration_model-path.jpg
74   :align: center
75   :alt: Arm DS create new model configuration: set model path
76
77Then in ``FVP_BaseR_AEMv8R`` tab, change ``ARMAEMv8-R_`` to ``V8R64-Generic``,
78click ``Save`` and then click ``Import``:
79
80.. image:: images/create-new-model-configuration_model-use-V8R64-Generic.jpg
81   :align: center
82   :alt: Arm DS create new model configuration: import
83
84Create a new launch configuration
85*********************************
86
87From ``Project Explorer``, right click ``FVP_BaseR_AEMv8R`` and select ``Debug as -> Debug configurations...``:
88
89.. image:: images/create-new-launch-configuration_context-menu.jpg
90   :align: center
91   :alt: Arm DS create new launch configuration: context menu
92
93Select ``Generic Arm C/C++ Application`` and click ``New launch configuration`` button.
94A new configuration named ``New_configuration`` will be created.
95
961. In ``Connection`` tab:
97
98   - In ``Select target`` box, select ``Imported -> FVP_BaseR_AEMv8R -> Bare Metal Debug -> ARMAEMv8-R_MP_0``
99   - In ``Connections`` box, set ``Model parameters`` to::
100
101       -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
102
103     These parameters are passed to ``FVP_BaseR_AEMv8R`` when launches. Run ``FVP_BaseR_AEMv8R --help``
104     to see all command line options. Run ``FVP_BaseR_AEMv8R --list-params`` to see all supported parameters.
105     The file ``zephyr.elf`` specified by ``-a`` is the binary built from Zephyr.
106
107.. image:: images/create-new-launch-configuration_connection.jpg
108   :align: center
109   :alt: Arm DS create new launch configuration: connection
110
1112. In ``Files`` tab:
112
113   In ``Files`` box, set ``Load symbols from file`` to full path of ``zephyr.elf`` that you built.
114
115.. image:: images/create-new-launch-configuration_files.jpg
116   :align: center
117   :alt: Arm DS create new launch configuration: files
118
1193. In ``Debugger`` tab:
120
121   - In ``Run control`` box, check ``Execute debugger commands`` and insert::
122
123       add-symbol-file "/home/fengqi/zephyrproject/build/zephyr/zephyr.elf" EL1S:0
124
125     Replace ``/home/fengqi/zephyrproject/build/zephyr/zephyr.elf`` with your local path.
126
127   - In ``Paths`` box, set ``Source search directory`` to the path to Zephyr source code.
128
129.. image:: images/create-new-launch-configuration_debugger.jpg
130   :align: center
131   :alt: Arm DS create new launch configuration: debugger
132
133After all these changes are made, click ``Apply``, then click ``Debug``. DS will
134launch ``FVP_BaseR_AEMv8R`` and connect to it. You can see a new session is
135connected in ``Debug Control`` window.
136
137.. image:: images/DS-debug-working.jpg
138   :align: center
139   :alt: Arm DS working
140
141References
142**********
143
144.. target-notes::
145
146.. [1] https://developer.arm.com/tools-and-software/embedded/arm-development-studio
147.. [2] https://developer.arm.com/tools-and-software/simulation-models/fixed-virtual-platforms/arm-ecosystem-models
148