1.. _xt-sim:
2
3Xtensa simulator
4################
5
6Overview
7********
8
9The Xtensa processor architecture is a configurable, extensible, and
10synthesizable 32-bit RISC processor core. Processor and SOC vendors can select
11from various processor options and even create customized instructions in
12addition to a base ISA to tailor the processor for a particular application.
13
14For more information, see https://ip.cadence.com/ipportfolio/tensilica-ip/xtensa-customizable
15
16.. figure:: img/xt-sim.jpg
17     :align: center
18     :alt: Xtensa Xplorer (Eclipse base frontend for xt-sim)
19
20     Xtensa Xplorer
21
22Hardware
23********
24
25The following Xtensa cores are officially supported:
26
27- sample_controller
28
29System Clock
30============
31
32Xtensa cores can be configured to use either internal or external timers.
33The frequency of the clock under simulation is set to 25MHz.
34
35System requirements
36*******************
37
38Prerequisites
39=============
40A Linux host system is required for Xtensa development work.
41We recommend using a __``Debian 9.x (Stretch)``__ or recent __``Ubuntu``__
42releases (with multilib support).
43
44Only Xtensa tools version ``RF-2016.4-linux`` or later are officially
45supported. Other versions may work but are not supported by Cadence Systems Inc.
46
47In order to set up the Zephyr OS build system, a Linux 32-bit GCC compiler must
48be installed on the building linux box. Install GCC if needed either by
49downloading ``Zephyr SDK`` or by using your distribution package manager.
50
51On Debian/Ubuntu systems, you can install ``gcc-multilib`` package as follows:
52
53.. code-block:: console
54
55    #aptitude install gcc-multilib # Or what ever package manager (apt, apt-get, ...)
56
57Set up build environment
58========================
59
60We recommend you create a ``~/.zephyrrc`` file, a shell script that shall be
61sourced each time before you start working on Zephyr.
62You can use the following code to create that file:
63
64.. code-block:: console
65
66    $ cat > ~/.zephyrrc
67    if test "${CROSS}" = xcc
68    then
69    	export ARCH=xtensa
70    	export BOARD=xt-sim
71        export ZEPHYR_TOOLCHAIN_VARIANT=xcc
72    	export XTENSA_TOOLS_PATH=/opt/xtensa/XtDevTools/install/tools/RG-2016.4-linux/XtensaTools
73    	export XTENSA_BUILDS_PATH=/opt/xtensa/XtDevTools/install/builds/RG-2016.4-linux
74    	#export XTENSA_BUILD_DIR= #Keep empty to use default directory
75    	export EMU_PLATFORM=xt-run
76    elif test "${CROSS}" = zephyr-xtensa
77    then
78    	export ARCH=xtensa
79    	export BOARD=qemu
80    	export ZEPHYR_TOOLCHAIN_VARIANT=zephyr
81    	export ZEPHYR_SDK_INSTALL_DIR=/opt/xtensa/zephyr-sdk-64-INTERNAL-11-22-2016
82    elif test "${CROSS}" = zephyr-x86
83    then
84    	export ARCH=x86
85    	export BOARD=qemu_x86
86    	export ZEPHYR_TOOLCHAIN_VARIANT=zephyr
87    	export ZEPHYR_SDK_INSTALL_DIR=/opt/xtensa/zephyr-sdk-64-INTERNAL-11-22-2016
88    else
89    	echo "Unsupported compiler '${CROSS}' defined by environment variable CROSS"
90    fi
91
92Once the ``~/.zephyrrc`` file is created, you can start working. However, each
93time you start a new shell you will need to execute the following commands
94before you can compile anything:
95
96.. code-block:: console
97
98    $ cd path/to/zephyr # replace path/to by a real path
99    $ CROSS=xcc source zephyr-env.sh # Select xcc as compiler
100
101Adding a user-defined Xtensa core
102=================================
103Add your own core to the list of supported cores as follows:
104
105.. code-block:: console
106
107    $ XTENSA_CORE=myCore
108    $ $(which echo) -e "config ${XTENSA_CORE}\n\tbool \"${XTENSA_CORE} core\"\n" >> "soc/xtensa/Kconfig.cores"
109
110Create a folder for that core:
111
112.. code-block:: console
113
114    $ mkdir soc/xtensa/${XTENSA_CORE}
115
116Create and copy to that folder a custom linker script (more on linker script in next section):
117
118.. code-block:: console
119
120    $ cp  linker.ld  soc/xtensa/${XTENSA_CORE}/linker.ld
121
122Add a Makefile:
123
124.. code-block:: console
125
126    $ echo "obj-y = soc.o" > soc/xtensa/${XTENSA_CORE}/Makefile
127
128Add Zephyr specific sections to the linker script.
129The file "soc/xtensa/linker_more.ld" contains Zephyr-specific linker
130sections that should be added to the default linker script linker.ld (inside
131SECTIONS region). If you are not using a linker script, you must create one
132and add these sections. The memory segment and PHDR should be replaced by
133appropriate values.
134
135The linker script should be named ``linker.ld`` and placed in the directory
136``soc/xtensa/${XTENSA_CORE}``.
137
138Configuring build
139=================
140
141.. zephyr-app-commands::
142   :zephyr-app: samples/hello_world
143   :goals: menuconfig
144
145Below is an example of usage for typical configuration:
146
1471. Select ``Architecture``
148    a. Select ``Xtensa architecture``
1492. Select ``XTENSA core Selection``
150    a. Select appropriate core (example ``hifi3_bd5 core``)
1513. Select ``XTENSA Options``
152    a. Set ``Hardware clock cycles per second`` to appropriate value
153    b. Set ``The path to Xtensa tool`` to appropriate value
154    c. Set ``The version of Xtensa tool`` to appropriate version
155    d. Set ``Xtensa build directory`` to appropriate  value
1564. Select ``Board Selection``
157    a. Select ``Xtensa Development ISS``
1585. Select ``Device Drivers``
159    a. Uncheck ``Serial Drivers``
1606. Select ``Compile and Link Features``
161	a. Set compiler configuration and build options correctly to project requirements
1627. Hit ``Exit`` and confirm saving the changes.
163
164You may need to change other options in menuconfig depending on his project
165specific needs.
166
167Compiling and running
168=====================
169The Xtensa executable can be run in the simulator either with a standalone core,
170or with a core connected to simulated peripherals.
171
172Build and run as follows:
173
174.. zephyr-app-commands::
175   :goals: run
176
177References
178**********
179
180.. _Xtensa tools: https://ip.cadence.com/support/sdk-evaluation-request
181