1.. zephyr:board:: nsim 2 3Overview 4******** 5 6This platform can be used to run Zephyr RTOS on the widest possible range of ARC processors in 7simulation with `Designware ARC nSIM`_ or run same images on FPGA prototyping platform `HAPS`_. The 8platform includes the following features: 9 10* ARC processor core, which implements ARCv2 or ARCv3 ISA, please refer to 11 :ref:`here <hardware_arch_arc_support_status>` for a complete list of ARC processor families which 12 currently supported 13* Virtual serial console (a standard ``ns16550`` UART model) 14 15ARC processors are known for being highly customizable and some but not all of the configurations 16are currently supported in the Zephyr RTOS for ARC, again please refer to 17:ref:`here <hardware_arch_arc_support_status>` for a complete list of supported features. 18 19There are multiple supported sub-configurations for that platform. Some but not all of currently 20available configurations are listed below: 21 22* ``nsim/nsim_em`` - ARC EM core v4.0 with two register banks, FastIRQ's, MPUv2, DSP options and 23 XY-memory 24* ``nsim/nsim_em7d_v22`` - ARC EM core v3.0 with one register bank and FastIRQ's 25* ``nsim/nsim_em11d`` - ARC EM core v4.0 with one register bank, no FastIRQ's, MPUv2, DSP options and 26 XY-memory 27* ``nsim/nsim_sem`` - ARC EM core v4.0 with secure features (thus "SEM", i.e. Secure EM) and MPUv4 28* ``nsim/nsim_hs`` - ARCv2 HS core v2.1 with two register banks, FastIRQ's and MPUv3 29* ``nsim/nsim_hs/smp`` - Dual-core ARCv2 HS core v2.1 with two register banks, FastIRQ's and MPUv3 30* ``nsim/nsim_vpx5`` - ARCv2 VPX5 core, close to vpx5_integer_full template 31* ``nsim/nsim_hs5x`` - 32-bit ARCv3 HS core with rich set of options 32* ``nsim/nsim_hs6x`` - 64-bit ARCv3 HS core with rich set of options 33* ``nsim/nsim_hs5x/smp/12cores`` - SMP 12 cores 32-bit ARCv3 HS platform 34* ``nsim/nsim_hs6x/smp/12cores`` - SMP 12 cores 64-bit ARCv3 HS platform 35 36.. _board_arc_nsim_prop_args_files: 37 38It is recommended to look at precise description of a particular sub-configuration in either 39``.props`` or ``.args`` files in :zephyr_file:`boards/snps/nsim/arc_classic/support/` directory to understand 40which options are configured and so will be used on invocation of the simulator. 41 42In case of single-core configurations it would be ``.props`` file which contains configuration 43for nSIM simulator and ``.args`` file which contains configuration for MetaWare debugger (MDB). 44Note that these files contain identical HW configuration and meant to be used with the corresponding 45tool: ``.props`` file for nSIM simulator and ``.args`` file for MDB (which internally uses nSIM for 46simulation anyway). 47 48.. hint:: 49 If different behavior is observed during execution or debugging of a particular application 50 (especially after creation of a new board or modification of the existing one) make sure features 51 defined in ``.props`` and ``.args`` are semantically identical (unfortunately options of 52 nSIM & MDB don't exactly match, so care should be taken). 53 54I.e. for the single-core ``nsim/nsim_hs5x`` platform there are 55:zephyr_file:`boards/snps/nsim/arc_classic/support/nsim_hs5x.props` and 56:zephyr_file:`boards/snps/nsim/arc_classic/support/mdb_hs5x.args`. 57 58For the multi-core configurations there is only ``.args`` file as the multi-core configuration 59can only be instantiated with help of MDB. 60 61I.e. for the multi-core ``nsim/nsim_hs5x/smp`` platform there is only 62:zephyr_file:`boards/snps/nsim/arc_classic/support/mdb_hs5x_smp.args`. 63 64.. warning:: 65 All nSIM/MDB configurations are used for demo and testing purposes. They are not meant to 66 represent any real system and so might be renamed, removed or modified at any point. 67 68Programming and Debugging 69************************* 70 71Required Hardware and Software 72============================== 73 74To run single-core Zephyr RTOS applications in simulation on this board, 75either `DesignWare ARC nSIM`_ or `DesignWare ARC Free nSIM`_ is required. 76 77To run multi-core Zephyr RTOS applications in simulation on this board, 78`DesignWare ARC nSIM`_ and MetaWare Debugger from `ARC MWDT`_ are required. 79 80To run Zephyr RTOS applications on FPGA-based `HAPS`_ platform, 81MetaWare Debugger from `ARC MWDT`_ is required as well as the HAPS platform itself. 82 83Building & Running Sample Applications 84====================================== 85 86Most board sub-configurations support building with both GNU and ARC MWDT toolchains, however 87there might be exceptions from that, especially for newly added targets. You can check supported 88toolchains for the sub-configurations in the corresponding ``.yaml`` file. 89 90I.e. for the ``nsim/nsim_hs5x`` board we can check :zephyr_file:`boards/snps/nsim/arc_classic/nsim_nsim_hs5x.yaml` 91 92The supported toolchains are listed in ``toolchain:`` array in ``.yaml`` file, where we can find: 93 94* **zephyr** - implies ARC GNU toolchain from Zephyr SDK. You can find more information about 95 Zephyr SDK :ref:`here <toolchain_zephyr_sdk>`. 96* **cross-compile** - implies ARC GNU cross toolchain, which is not a part of Zephyr SDK. Note that 97 some (especially new) sub-configurations may declare ``cross-compile`` toolchain support without 98 ``zephyr`` toolchain support because corresponding target CPU support hasn't been added to Zephyr 99 SDK yet. You can find more information about its usage here: :ref:`here <other_x_compilers>`. 100* **arcmwdt** - implies proprietary ARC MWDT toolchain. You can find more information about its 101 usage here: :ref:`here <toolchain_designware_arc_mwdt>`. 102 103.. note:: 104 Note that even if both GNU and MWDT toolchain support is declared for the target some tests or 105 samples can be only built with either GNU or MWDT toolchain due to some features limited to a 106 particular toolchain. 107 108Use this configuration to run basic Zephyr applications and kernel tests in 109nSIM, for example, with the :zephyr:code-sample:`synchronization` sample: 110 111.. zephyr-app-commands:: 112 :zephyr-app: samples/synchronization 113 :host-os: unix 114 :board: nsim_em 115 :goals: flash 116 117This will build an image with the synchronization sample app, boot it using 118nSIM, and display the following console output: 119 120.. code-block:: console 121 122 *** Booting Zephyr OS build zephyr-v3.2.0-3948-gd351a024dc87 *** 123 thread_a: Hello World from cpu 0 on nsim! 124 thread_b: Hello World from cpu 0 on nsim! 125 thread_a: Hello World from cpu 0 on nsim! 126 thread_b: Hello World from cpu 0 on nsim! 127 thread_a: Hello World from cpu 0 on nsim! 128 129 130.. note:: 131 To exit the simulator, use :kbd:`Ctrl+]`, then :kbd:`Ctrl+c` 132 133.. _board_arc_nsim_verbose_build: 134 135.. tip:: 136 You can get more details about the building process by running build in verbose mode. It can be 137 done by passing ``-v`` flag to the west: ``west -v build -b nsim_hs samples/synchronization`` 138 139You can run applications built for ``nsim`` board not only on nSIM simulation itself, but also on 140FPGA based HW platform `HAPS`_. To run previously built application on HAPS do: 141 142.. code-block:: console 143 144 west flash --runner mdb-hw 145 146.. note:: 147 To run on HAPS, in addition to proper build and flash Zephyr image, you need setup HAPS itself 148 as well as flash proper built FPGA image (aka .bit-file). This instruction doesn't cover those 149 steps, so you need to follow HAPS manual. 150 151Debugging 152========= 153 154.. _board_arc_nsim_debugging_mwdt: 155 156Debugging with MDB 157------------------ 158 159.. note:: 160 We strongly recommend to debug with MetaWare debugger (MDB) because it: 161 162 * Supports wider range of ARC hardware features 163 * Allows to debug both single-core and multi-core ``nsim`` targets. 164 * Allows to debug on `HAPS`_ platform. 165 166You can use the following command to start GUI debugging when running application on nSIM simulator 167(regardless if single- or multi-core configuration is used): 168 169.. code-block:: console 170 171 west debug --runner mdb-nsim 172 173You can use the following command to start GUI debugging when running application on `HAPS`_ 174platform: 175 176.. code-block:: console 177 178 west debug --runner mdb-hw 179 180.. tip:: 181 The ``west debug`` (as well as ``west flash``) is just a wrapper script and so it's possible to 182 extract the exact commands which are called in it by running it in verbose mode. For that you 183 need to pass ``-v`` flag to the wrapper. For example, if you run the following command: 184 185 .. code-block:: console 186 187 west -v debug --runner mdb-nsim 188 189 it will produce the following output (the ``nsim/nsim_hs5x/smp`` configuration was used for that 190 example): 191 192 .. code-block:: console 193 194 < *snip* > 195 -- west debug: using runner mdb-nsim 196 runners.mdb-nsim: mdb -pset=1 -psetname=core0 -nooptions -nogoifmain -toggle=include_local_symbols=1 -nsim @/path/zephyr/boards/snps/nsim/support/mdb_hs5x_smp.args /path/zephyr/build/zephyr/zephyr.elf 197 runners.mdb-nsim: mdb -pset=2 -psetname=core1 -prop=download=2 -nooptions -nogoifmain -toggle=include_local_symbols=1 -nsim @/path/zephyr/boards/snps/nsim/support/mdb_hs5x_smp.args /path/zephyr/build/zephyr/zephyr.elf 198 runners.mdb-nsim: mdb -multifiles=core1,core0 -OKN 199 200 From that output it's possible to extract MDB commands used for setting-up the GUI debugging 201 session: 202 203 .. code-block:: console 204 205 mdb -pset=1 -psetname=core0 -nooptions -nogoifmain -toggle=include_local_symbols=1 -nsim @/path/zephyr/boards/snps/nsim/support/mdb_hs5x_smp.args /path/zephyr/build/zephyr/zephyr.elf 206 mdb -pset=2 -psetname=core1 -prop=download=2 -nooptions -nogoifmain -toggle=include_local_symbols=1 -nsim @/path/zephyr/boards/snps/nsim/support/mdb_hs5x_smp.args /path/zephyr/build/zephyr/zephyr.elf 207 mdb -multifiles=core1,core0 -OKN 208 209 Then it's possible to use them directly or in some machinery if required. 210 211 .. warning:: 212 It is strongly recommended to not rely on the mdb command line options listed above but 213 extract it yourself for your configuration. 214 215 .. note:: 216 In case of execution or debugging with MDB on multi-core configuration on nSIM 217 simulator without ``west flash`` and ``west debug`` wrappers it's necessary to 218 set :envvar:`NSIM_MULTICORE` environment variable to ``1``. If you are using ``west flash`` or 219 ``west debug`` it's done automatically by wrappers. 220 221 Without :envvar:`NSIM_MULTICORE` environment variable set to 1, MDB will simulate 2 separate 222 ARC cores which don't share any memory regions with each other and so SMP-enabled code won't 223 work as expected. 224 225Debugging with GDB 226------------------ 227 228.. note:: 229 Debugging on nSIM via GDB is only supported on single-core configurations (which use standalone 230 nSIM). However if it's possible to launch application on multi-core nsim target that means you 231 can simply :ref:`debug with MDB debugger <board_arc_nsim_debugging_mwdt>`. 232 It's the nSIM with ARC GDB restriction, real HW multi-core ARC targets can be debugged with ARC 233 GDB. 234 235.. note:: 236 Currently debugging with GDB is not supported on `HAPS`_ platform. 237 238.. note:: 239 The normal ``west debug`` command won't work for debugging applications using nsim boards 240 because both the nSIM simulator and the debugger (either GDB or MDB) use the same console for 241 input / output. 242 In case of GDB debugger it's possible to use a separate terminal windows for GDB and nSIM to 243 avoid intermixing their output. For the MDB debugger simply use GUI mode. 244 245After building your application, open two terminal windows. In terminal one, use nSIM to start a GDB 246server and wait for a remote connection with following command: 247 248.. code-block:: console 249 250 west debugserver --runner arc-nsim 251 252In terminal two, connect to the GDB server using ARC GDB. You can find it in Zephyr SDK: 253 254* for the ARCv2 targets you should use :file:`arc-zephyr-elf-gdb` 255* for the ARCv3 targets you should use :file:`arc64-zephyr-elf-gdb` 256 257This command loads the symbol table from the elf binary file, for example the 258:file:`build/zephyr/zephyr.elf` file: 259 260.. code-block:: console 261 262 arc-zephyr-elf-gdb -ex 'target remote localhost:3333' -ex load build/zephyr/zephyr.elf 263 264Now the debug environment has been set up, and it's possible to debug the application with gdb 265commands. 266 267Modifying the configuration 268*************************** 269 270If modification of existing nsim configuration is required or even there's a need in creation of a 271new one it's required to maintain alignment between 272 273* Zephyr OS configuration 274* nSIM & MDB configuration 275* GNU & MWDT toolchain compiler options 276 277.. note:: 278 The ``.tcf`` configuration files are not supported by Zephyr directly. There are multiple 279 reasons for that. ``.tcf`` perfectly suits building of bare-metal single-thread application - 280 in that case all the compiler options from ``.tcf`` are passed to the compiler, so all the HW 281 features are used by the application and optimal code is being generated. 282 The situation is completely different when multi-thread feature-rich operation system is 283 considered. Of course it is still possible to build all the code with all the 284 options from ``.tcf`` - but that may be far from optimal solution. For example, such approach 285 require so save & restore full register context for all tasks (and sometimes even for 286 interrupts). And for DSP-enabled or for FPU-enabled systems that leads to dozens of extra 287 registers save and restore even if the most of the user and kernel tasks don't actually use 288 DSP or FPU. Instead we prefer to fine-tune the HW features usage which (with all its pros) 289 require us to maintain them separately from ``.tcf`` configuration. 290 291 292Zephyr OS configuration 293======================= 294 295Zephyr OS configuration is defined via Kconfig and Device tree. These are non ARC-specific 296mechanisms which are described in :ref:`board porting guide <board_porting_guide>`. 297 298It is advised to look for ``<board_name>_defconfig``, ``<board_name>.dts`` and 299``<board_name>.yaml`` as an entry point for board configuration. 300 301nSIM configuration 302================== 303 304nSIM configuration is defined in :ref:`props and args files <board_arc_nsim_prop_args_files>`. 305Generally they are identical to the values from corresponding ``.tcf`` configuration with few 306exceptions: 307 308* The UART model is added (to both ``.props`` and ``.args`` files). 309* Options to fine-tuned MDB behavior are added (to ``.args`` files only) to disable MDB profiling 310 and fine-tune MDB behavior on multi-core systems. 311 312GNU & MWDT toolchain compiler options 313===================================== 314 315The hardware-specific compiler options are set in corresponding SoC cmake file. For ``nsim`` board 316it is :zephyr_file:`soc/snps/nsim/arc_classic/CMakeLists.txt`. 317 318For the GNU toolchain the basic configuration is set via ``-mcpu`` which is defined in generic code 319and based on the selected CPU model via Kconfig. It still can be forcefully set to required value 320on SoC level. 321 322For the MWDT toolchain all hardware-specific compiler options are set directly in SoC 323``CMakeLists.txt``. 324 325.. note:: 326 The non hardware-specific compiler options like optimizations, library selections, C / C++ 327 language options are still set in Zephyr generic code. It could be observed by 328 :ref:`running build in verbose mode <board_arc_nsim_verbose_build>`. 329 330References 331********** 332 333.. target-notes:: 334 335.. _Designware ARC nSIM: https://www.synopsys.com/dw/ipdir.php?ds=sim_nsim 336.. _DesignWare ARC Free nSIM: https://www.synopsys.com/cgi-bin/dwarcnsim/req1.cgi 337.. _HAPS: https://www.synopsys.com/verification/prototyping/haps.html 338.. _ARC MWDT: https://www.synopsys.com/dw/ipdir.php?ds=sw_metaware 339
