1.. zephyr:board:: emsdp
2
3Overview
4********
5
6The DesignWare® ARC® EM Software Development Platform (SDP) is a flexible platform
7for rapid software development on ARC EM processor-based subsystems. It is intended
8to accelerate software development and debug of ARC EM processors and subsystems for
9a wide range of ultra-low power embedded applications such as IoT, sensor fusion,
10and voice applications.
11
12For details about the board, see: `DesignWare ARC EM Software Development Platform
13(EM SDP) <https://www.synopsys.com/dw/ipdir.php?ds=arc-em-software-development-platform>`__
14
15
16Hardware
17********
18
19The EM Software Development Platform supports different core configurations, such as EM4,
20EM5D, EM6, EM7D, EM7D+ESP, EM9D, EM11D. The core must be supplied as the variant of the base
21board which takes the form ``emsdp/<core>`` whereby core is ``emsdp_em4`` for EM4,
22``emsdp_em5D`` for EM5D, ``emsdp_em6`` for EM6, ``emsdp_em7d`` for EM7D, ``emsdp_em7d_esp``
23for EM7D+ESP, ``emsdp_em9d`` for EM9D and ``emsdp_em11d`` for EM11D.
24
25The following table shows the hardware features supported for different core configuration:
26
27+-----------+-----+-----+------+------+----------+------+-------+
28| Features  | EM4 | EM6 | EM5D | EM7D | EM7D_ESP | EM9D | EM11D |
29+===========+=====+=====+======+======+==========+======+=======+
30| Caches    | N   | Y   | N    | Y    | Y        | N    | Y     |
31+-----------+-----+-----+------+------+----------+------+-------+
32| DSP       | N   | N   | Y    | Y    | Y        | Y    | Y     |
33+-----------+-----+-----+------+------+----------+------+-------+
34| XY Memory | N   | N   | N    | N    | N        | Y    | Y     |
35+-----------+-----+-----+------+------+----------+------+-------+
36| Secure    | N   | N   | N    | N    | Y        | N    | N     |
37+-----------+-----+-----+------+------+----------+------+-------+
38
39The table below shows which drivers are currently available in Zephyr.
40
41+-----------+------------+-------+-----------------------+
42| Interface | Controller | EMSDP | Driver/Component      |
43+===========+============+=======+=======================+
44| SDIO      | on-chip    |   N   | SD-card controller    |
45+-----------+------------+-------+-----------------------+
46| UART      | Arduino +  |   Y   | serial port-polling;  |
47|           | 3 Pmods    |       | serial port-interrupt |
48+-----------+------------+-------+-----------------------+
49| SPI       | Arduino +  |   Y   | spi                   |
50|           | Pmod + adc |       |                       |
51+-----------+------------+-------+-----------------------+
52| ADC       | 1 Pmod     |   N   | adc (via spi)         |
53+-----------+------------+-------+-----------------------+
54| I2C       | Arduino +  |   N   | i2c                   |
55|           | Pmod       |       |                       |
56+-----------+------------+-------+-----------------------+
57| GPIO      | Arduino +  |   Y   | gpio                  |
58|           | Pmod + Pin |       |                       |
59+-----------+------------+-------+-----------------------+
60| PWM       | Arduino +  |   N   | pwm                   |
61|           | Pmod       |       |                       |
62+-----------+------------+-------+-----------------------+
63| I2S       | on-chip    |   N   | Audio interface       |
64+-----------+------------+-------+-----------------------+
65
66Support two 32 MByte Quad-SPI Flash memory, one only contains FPGA image, the other
67one is user SPI-FLASH, which is connected via SPI bus and its sample can be found in
68``samples/drivers/spi_flash``.
69
70To configure the FPGA, The ARC EM SDP offers a single USB 2.0 host port, which is
71both used to access the FPGAs configuration memory and as a DEBUG/ UART port.
72
73When connected using the USB cable to a PC, the ARC EM SDP presents itself as a mass
74storage device. This allows an FPGA configuration bitstream to be dragged and dropped into
75the configuration memory. The FPGA bitstream is automatically loaded into the FPGA device
76upon power-on reset, or when the configuration button is pressed.
77
78For hardware feature details, refer to : `ARC EM Software Development Platform
79<https://embarc.org/project/arc-em-software-development-platform-sdp/>`__
80
81Peripheral driver test and sample
82=================================
83
84``tests/drivers/spi/spi_loopback``: verify DesignWare SPI driver. No need to connect
85MISO with MOSI, DW SPI register is configured to internally connect them. This test
86use two different speed to verify data transfer with asynchronous functionality.
87Note: DW SPI only available on SPI0 and SPI1.
88
89``samples/drivers/spi_flash``: Verfiy DW SPI and SPI-FLASH on SPI1. First erase the
90whole flash then write 4 byte data to the flash. Read from the flash and compare the
91result with buffer to check functionality.
92
93Pinmux interface
94================
95
96The following pinmux peripheral module standards are supported:
97
98* Digilent Pmod (3x)
99
100The ARC EM SDP features three 12-pin Pmod connectors: Pmod_A, Pmod_B, and Pmod_C.
101The functionality of the Pmod connectors is programmable and includes GPIO, UART, SPI,
102I2C, and PWM (Note: support two type UART Pmod interface: UARTA is newer version).
103Multiplexing is controlled by software using the PMOD_MUX_CTRL register.
104
105* Arduino (1x)
106
107The ARC EM SDP provides an Arduino shield interface. Multiplexing is controlled by software
108using the ARDUINO_MUX_CTRL register. Note: some IO must be programmed in group and can't be
109set individually, for details see Table 9 in `EM Software Development Platform user guide`_.
110
111* MikroBUS (1x)
112
113Note that since the controllers that are mapped to the MikroBUS are shared with the Arduino
114controllers, and therefore the MikroBUS functions are only available when the Arduino
115multiplexer ARDUINO_MUX_CTRL is in the default mode (GPIO).
116
117Programming and Debugging
118*************************
119
120Required Hardware and Software
121==============================
122
123To use Zephyr RTOS applications on the EM Software Development Platform board,
124a few additional pieces of hardware are required.
125
126* A micro USB cable to connect the computer.
127
128* A universal switching power adaptor (110-240V AC to 12 DC),
129  provided in the package, which used to power the board.
130
131* :ref:`The Zephyr SDK <toolchain_zephyr_sdk>`
132
133* Terminal emulator software for use with the USB-UART. Suggestion:
134  `Putty Website`_.
135
136* (optional) A collection of Pmods, Arduino modules, or Mikro modules.
137  See `Digilent Pmod Modules`_ or develop your custom interfaces to attach
138  to the Pmod connector.
139
140Set up the EM Software Development Platform
141===========================================
142
143To run Zephyr application on EM Software Development Platform, you need to
144setup the board correctly.
145
146* Connect the 12V DC power supply to your board.
147
148* Connect the digilent usb cable from your host to the board.
149
150Set up Zephyr Software
151======================
152
153Building Sample Applications
154==============================
155
156You can try many of the sample applications or tests, but let us discuss
157the one called :zephyr:code-sample:`hello_world`.
158It is found in :zephyr_file:`samples/hello_world`.
159
160Configuring
161-----------
162
163You may need to write a prj_arc.conf file if the sample doesn't have one.
164Next, you can use the menuconfig rule to configure the target. By specifying
165``emsdp`` as the board configuration, you can select the ARC EM Software
166Development Platform board support for Zephyr, note that the core also need to
167be supplied, for example for the em7d:
168
169.. zephyr-app-commands::
170   :board: emsdp/emsdp_em7d
171   :zephyr-app: samples/hello_world
172   :goals: menuconfig
173
174
175Building
176--------
177
178You can build an application in the usual way.  Refer to
179:ref:`build_an_application` for more details. Here is an example for
180:zephyr:code-sample:`hello_world` for the em4.
181
182.. zephyr-app-commands::
183   :board: emsdp/emsdp_em4
184   :zephyr-app: samples/hello_world
185   :maybe-skip-config:
186   :goals: build
187
188Connecting Serial Output
189=========================
190
191In the default configuration, Zephyr's EM Software Development Platform images
192support serial output via the USB-UART on the board. To enable serial output:
193
194* Open a serial port emulator (i.e. on Linux minicom, putty, screen, etc)
195
196* Specify the tty driver name, for example, on Linux this may be
197  :file:`/dev/ttyUSB0`
198
199* Set the communication settings to:
200
201
202========= =====
203Parameter Value
204========= =====
205Baud:     115200
206Data:     8 bits
207Parity:    None
208Stopbits:  1
209========= =====
210
211Debugging
212==========
213
214Using the latest version of Zephyr SDK(>=0.9), you can debug and flash IoT
215Development Kit directly.
216
217One option is to build and debug the application using the usual
218Zephyr build system commands, for example for the em6
219
220.. zephyr-app-commands::
221   :board: emsdp/emsdp_em6
222   :app: <my app>
223   :goals: debug
224
225At this point you can do your normal debug session. Set breakpoints and then
226'c' to continue into the program.
227
228The other option is to launch a debug server, as follows.
229
230.. zephyr-app-commands::
231   :board: emsdp/emsdp_em6
232   :app: <my app>
233   :goals: debugserver
234
235Then connect to the debug server at the EM Software Development Platform from a
236second console, from the build directory containing the output :file:`zephyr.elf`.
237
238.. code-block:: console
239
240   $ cd <my app>
241   $ $ZEPHYR_SDK_INSTALL_DIR/sysroots/x86_64-pokysdk-linux/usr/bin/ \
242      arc-zephyr-elf/arc-zephyr-elf-gdb zephyr.elf
243   (gdb) target remote localhost:3333
244   (gdb) load
245   (gdb) b main
246   (gdb) c
247
248Flashing
249========
250
251If you just want to download the application to the EM Software Development
252Platform's CCM and run, you can do so in the usual way.
253
254.. zephyr-app-commands::
255   :board: emsdp/emsdp_em6
256   :app: <my app>
257   :goals: flash
258
259This command still uses openocd and gdb to load the application elf file to EM
260Software Development Platform, but it will load the application and immediately run.
261If power is removed, the application will be lost since it wasn't written to flash.
262
263Most of the time you will not be flashing your program but will instead debug
264it using openocd and gdb. The program can be download via the USB cable into
265the code and data memories.
266
267References
268**********
269
270.. target-notes::
271
272.. _EM Software Development Platform user guide:
273   https://www.synopsys.com/dw/ipdir.php?ds=arc-em-software-development-platform
274
275.. _Digilent Pmod Modules:
276   http://store.digilentinc.com/pmod-modules
277
278.. _Putty website:
279   http://www.putty.org
280