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