1.. zephyr:board:: em_starterkit
2
3Overview
4********
5
6The DesignWare(R) ARC(R) EM Starter Kit is a low-cost, versatile solution
7enabling rapid software development and software debugging, and profiling
8for the ARC EM Family of processors. The EM Family includes the EM4, EM6,
9EM5D, EM7D, EM9D, and EM11D cores. The Zephyr RTOS can be used with the
10EM Starter Kit.
11
12The ARC EM Starter Kit consists of a hardware platform, including pre-installed
13FPGA images of different ARC EM processor configurations with peripherals.
14Documentation for this board can be found at `embARC website`_.
15
16See also this URL for details about the board:
17`Designware ARC EM Starter Kit website`_ .
18
19The latest version of EM Starter Kit is 2.3, developer can upgrade from
202.0/2.1/2.2 to 2.3 using latest firmware.
21The default configuration for EM Starter Kit boards can be found in
22:zephyr_file:`boards/snps/em_starterkit/`.
23
24The default SoC for this board supported in Zephyr is the EM9D.
25This configuration is a Harvard Architecture, with a separate
26instruction bus and data bus. Instruction memory is called ICCM
27and data memory is called DCCM. The configuration file for EM9D
28is found in :zephyr_file:`soc/snps/emsk/Kconfig.defconfig.em9d`.
29
30If you have a larger program, you can select the EM7D or EM11D, which gives
31access to 128KB DRAM with i-cache and d-cache. The configuration file for EM7D
32is found in :zephyr_file:`soc/snps/emsk/Kconfig.defconfig.em7d` and EM11D is
33found in :zephyr_file:`soc/snps/emsk/Kconfig.defconfig.em11d`.
34
35
36Hardware
37********
38Board Layout
39============
40
41The ARC EM Starter Kit main board has 6 Pmod connectors. These can be configured
42to support attachment of GPIO, I2C, UART or SPI devices.
43
44The board also has a 16MB SPI-FLASH and an SDCard for storage. There are 9 LEDs,
453 buttons, and 4 dip switches that can be used with GPIO.
46
47The Xilinx Spartan(R)-6 LX150 FPGA can auto-load one of 3 FPGA SoC bit files
48which have the EM7D, EM9D, or EM11D SoC.
49
50Documentation and general information for the board can be found at the
51`embARC website`_, which also includes some free sample software.
52
53
54Supported Firmware Versions
55===========================
56
57The EM Starter Kit has different versions, such as 1.0, 1.1, 2.0, 2.1,
582.2 and 2.3.
59In Zephyr, only firmware versions 2.2 and 2.3 are supported.
60
61Supported Features
62==================
63
64The Zephyr kernel supports multiple hardware features on the EM Starter Kit
65through the use of device drivers.
66
67The EM Starter Kit supports 6 Digilent Pmod(TM) Interfaces, which enables the
68use of a large variety of pluggable modules for storage, communications,
69sensors, displays, etc. With the Pmod interface, you can prototype your
70applications using the Zephyr RTOS.
71
72The table below shows which drivers are supported and which functionality can
73be found on which architectures:
74
75+-----------+------------+-----+-------+-----------------------+
76| Interface | Controller |EM9D | EM11D | Driver/Component      |
77+===========+============+=====+=======+=======================+
78| INT       | on-chip    | Y   | Y     | interrupt_controller  |
79+-----------+------------+-----+-------+-----------------------+
80| UART      | usb +      | Y   | Y     | serial port-polling;  |
81|           | 2 Pmods    |     |       | serial port-interrupt |
82+-----------+------------+-----+-------+-----------------------+
83| SPI       | 2 Pmods    | Y   | Y     | spi                   |
84+-----------+------------+-----+-------+-----------------------+
85| ADC       | n/a        | N   | N     | adc (can add via Pmod)|
86+-----------+------------+-----+-------+-----------------------+
87| I2C       | 2 Pmods    | Y   | Y     | i2c                   |
88+-----------+------------+-----+-------+-----------------------+
89| GPIO      | 6 Pmods    | Y   | Y     | gpio                  |
90+-----------+------------+-----+-------+-----------------------+
91| PWM       | n/a        | N   | N     | pwm                   |
92+-----------+------------+-----+-------+-----------------------+
93
94The board has 3 (debounced and interrupting) buttons for use with GPIO, 4 dip
95switches, 9 LEDs, SDCard on SPI, and a 16MB SPI-Flash memory.
96
97The SPI-FLASH driver is supported with sample, which can be found in
98``samples/drivers/spi_flash``.
99
100The SPI-Flash also holds 3 (or 4) separate FPGA CPU bit files, selectable via
101dip switch.
102
103The SPI-Flash is also programmed with a bootloader. The bootloader can copy a
104program image from SPI-Flash into executable memory. Zephyr initialization will
105copy the initialized data section to the data memory if CONFIG_XIP is used.
106
107
108Programming and Debugging
109*************************
110
111Required Hardware and Software
112==============================
113
114To use Zephyr RTOS applications on the EM Starter Kit board, a few additional
115pieces of hardware are required.
116
117* USB Cable (delivered as part of the ARC EM Starter Kit)
118
119* The USB cable provides power to the board; however, if the board is to run
120  standalone, the universal switching power adaptor (110-240V AC to 5V DC),
121  provided in the package, can be used to power the board.
122
123* :ref:`The Zephyr SDK <toolchain_zephyr_sdk>`
124
125* Terminal emulator software for use with the USB-UART. Suggestion:
126  `Putty Website`_.
127
128* (optional) A collection of Pmods.
129  See `Digilent Pmod Modules`_ or develop your custom interfaces to attach
130  to the Pmod connector.
131
132Set up the ARC EM Starter Kit
133=============================
134
135To run Zephyr application on correct arc core of EM Starter Kit, you need to
136setup the board correctly.
137
138* Connect the digilent usb cable from your host to the board.
139
140* Connect the 5V DC power supply to your board.
141
142* Select the core configuration of the board by choosing correct dip switch
143  SW1 settings, then press then FPGA configure button located above the letter
144  'C' of the ARC logo on the board.
145
146* Then the board will be reconfigured with selected core configuration, you
147  can download and debug Zephyr application now.
148
149* If you want to know more about how to use this board, you can take a look
150  at the `ARC EM Starter Kit User Guide`_.
151
152Set up Zephyr Software
153======================
154
155Since there are different firmware versions of EM Starter Kit, you need to
156choose the proper firmware version supported in Zephyr.
157
158Three different configurations exist for this board:
159
160* EM7D: em_starterkit_em7d_defconfig
161* EM9D: em_starterkit_defconfig
162* EM11D: em_starterkit_em11d_defconfig
163
164
165Building Sample Applications
166==============================
167
168You can try many of the sample applications or tests, but let us discuss
169the one called :zephyr:code-sample:`hello_world`.
170It is found in :zephyr_file:`samples/hello_world`.
171
172Configuring
173-----------
174
175You may need to write a prj_arc.conf file if the sample doesn't have one.
176Next, you can use the menuconfig rule to configure the target. By
177specifying ``em_starterkit`` as the board configuration, you can select the ARC
178EM Starter Kit board support for Zephyr.
179
180.. zephyr-app-commands::
181   :board: em_starterkit
182   :zephyr-app: samples/hello_world
183   :goals: menuconfig
184
185On this board you will also need to consider the "ARC SoC Selection" and set
186it either to EM9D or EM11D. To boot up the EM9D on the board, all dip
187switches should be UP except for switch 1. Other configuration choices
188are made in the normal way. To boot up the EM11D on the board,
189all dip switches should be UP except for switch 2. Next press the button
190above the letter C in the "ARC" logo on the silkscreen.
191
192Building
193--------
194
195You can build application in the usual way.  Refer to
196:ref:`build_an_application` for more details. Here is an example for
197:zephyr:code-sample:`hello_world`.
198
199.. zephyr-app-commands::
200   :board: em_starterkit
201   :zephyr-app: samples/hello_world
202   :maybe-skip-config:
203   :goals: build
204
205Connecting Serial Output
206=========================
207
208In the default configuration, Zephyr's EM Starter Kit images support
209serial output via the UART1 on the board.  To enable serial output:
210
211On your development environment, you will need to:
212
213* Open a serial port emulator (i.e. on Linux minicom, putty, screen, etc)
214* Specify the tty driver name, for example, on Linux this may be :file:`/dev/ttyUSB1`
215* Set the communication settings to:
216
217
218========= =====
219Parameter Value
220========= =====
221Baud:     115200
222Data:     8 bits
223Parity:    None
224Stopbits:  1
225========= =====
226
227Debugging
228==========
229
230Using the latest version of Zephyr SDK(>=0.9), you can debug and flash
231EM Starterkit directly.
232
233One option is to build and debug the application using the usual
234Zephyr build system commands.
235
236.. zephyr-app-commands::
237   :board: em_starterkit
238   :app: <my app>
239   :goals: debug
240
241At this point you can do your normal debug session. Set breakpoints and then
242'c' to continue into the program.
243
244The other option is to launch a debug server, as follows.
245
246.. zephyr-app-commands::
247   :board: em_starterkit
248   :app: <my app>
249   :goals: debugserver
250
251Then connect to the debug server at the EM Starter Kit from a second
252console, from the build directory containing the output :file:`zephyr.elf`.
253
254.. code-block:: console
255
256   $ cd <my app>
257   $ $ZEPHYR_SDK_INSTALL_DIR/arc-zephyr-elf/bin/arc-zephyr-elf-gdb zephyr.elf
258   (gdb) target remote localhost:3333
259   (gdb) load
260   (gdb) b main
261   (gdb) c
262
263Flashing
264========
265
266If you just want to download the application to the EM Starter Kit's CCM
267or DDR and run, you can do so in the usual way.
268
269.. zephyr-app-commands::
270   :board: em_starterkit
271   :goals: flash
272
273This command still uses openocd and gdb to load application elf file
274to EM Starter Kit, but it will load application and then run immediately.
275If power is lost, the application will also lost due to power loss.
276
277Most of the time you will not be flashing your program but will instead
278debug it using openocd and gdb. The program can be download via the USB
279cable into the code and data memories.
280
281When you are ready to deploy the program so that it boots up automatically
282on reset or power-up, you can follow the steps to place the program on
283SPI-FLASH.
284
285For instructions on how to write your program to SPI-FLASH,
286refer to the documentation on the ARC EM Starter Kit at the
287`embARC website`_, which includes instructions for how to place an
288executable image onto the SPI-FLASH in such a way that it is understood
289by the bootloader.
290
291Release Notes
292*************
293
294The following is a list of TODO items:
295
296* ``GH-2647``: Zephyr needs i-cache API (all targets)
297* ``GH-2230``: Zephyr ARC port doesn't yet support nested regular interrupts.
298* pinmux driver: Possibly it can be written to configure PMods too.
299
300References
301**********
302
303.. target-notes::
304
305.. _embARC website: https://www.embarc.org
306
307.. _Designware ARC EM Starter Kit website: https://www.synopsys.com/dw/ipdir.php?ds=arc_em_starter_kit
308
309.. _Digilent Pmod Modules: http://store.digilentinc.com/pmod-modules
310
311.. _Putty website: http://www.putty.org
312
313.. _ARC EM Starter Kit User Guide: https://www.synopsys.com/dw/ipdir.php?ds=arc_em_starter_kit
314