1.. _cyclonev_socdk:
2
3Intel® Cyclone® V SoC Development Kit
4#####################################
5
6Overview
7********
8
9
10The Zephyr kernel is supported on the Intel® Cyclone® V SoC Development Kit,
11using its Hard Processor System (HPS) CPU.
12
13.. figure:: img/cyclonev_socdk.jpg
14   :align: center
15   :alt: Intel's Cyclone® V SoC FPGA DevKit
16
17   Intel®'s Cyclone® V SoC FPGA DevKit  (Credit: Intel®)
18
19Hardware
20********
21
22Jumpers and DIP Switch settings
23===============================
24
25Recommended board settings are the same as the GSRD for Cyclone® V
26SoC Development Board.
27
28There are two sets of switches on the back of the board. Of particular
29importance is SW2. First, the board jumpers need to be configured as follows:
30
31* J5 : Open
32* J6 : Short
33* J7 : Short
34* J9 : Open
35* J13: Short
36* J16: Open
37* J26: Short pins 1-2
38* J27: Short pins 2-3
39* J28: Short pins 1-2
40* J29: Short pins 2-3
41* J30: Short pins 1-2
42* J31: Open
43
44Then, the board switches need to be configured as follows:
45
46* SW1: All OFF
47* SW2: All OFF
48* SW3: ON-OFF-ON-OFF-ON-ON
49* SW4: OFF-OFF-ON-ON
50
51Other switches are user switches, their position is application-specific.
52Refer to the development kit user manual for specifics about jumpers and switches
53
54Necessary Software
55==================
56
57You will need the Intel® Quartus® Prime SDK in order to work with this device. The
58`Intel® Quartus® Prime Lite Edition <https://www.intel.com/content/www/us/en/software-kit/684215/intel-quartus-prime-lite-edition-design-software-version-21-1-for-linux.html>`_
59for Linux may be obtained without charge.
60
61For your convenience using the SDK tools (such as ``quartus_pgm``),
62you should put the binaries provided by the SDK
63in your path. Below is an example, adjust ALTERA_BASE to where you installed the
64SDK:
65
66.. code-block:: console
67
68   export QUARTUS_ROOTDIR=/opt/intelFPGA_lite/21.1
69   export PATH=$PATH:$QUARTUS_ROOTDIR/quartus/bin:$QUARTUS_ROOTDIR/programmer/bin
70
71You may need to adjust your udev rules so that you can talk to the USB Blaster
72II peripheral, which is the built-in JTAG interface for this device.
73
74The following works for Ubuntu:
75
76.. code-block:: console
77
78   # For Altera USB-Blaster permissions.
79   SUBSYSTEM=="usb",\
80   ENV{DEVTYPE}=="usb_device",\
81   ATTR{idVendor}=="09fb",\
82   ATTR{idProduct}=="6010",\
83   MODE="0666",\
84   NAME="bus/usb/$env{BUSNUM}/$env{DEVNUM}",\
85   RUN+="/bin/chmod 0666 %c"
86   SUBSYSTEM=="usb",\
87   ENV{DEVTYPE}=="usb_device",\
88   ATTR{idVendor}=="09fb",\
89   ATTR{idProduct}=="6810",\
90   MODE="0666",\
91   NAME="bus/usb/$env{BUSNUM}/$env{DEVNUM}",\
92   RUN+="/bin/chmod 0666 %c"
93
94You can test connectivity with the SDK jtagconfig tool, you should see something
95like:
96
97.. code-block:: console
98
99   $ jtagconfig
100   1) USB-BlasterII [1-5]
101     4ba00477   SOCVHPS
102     02D020DD   5ZSEBA6(.|ES)/5CSEMA6/..
103
104
105Golden Reference Design
106=======================
107
108The Golden System Reference Design (GSRD) provides a set of essential hardware
109and software system componets that can be used as a starting point for various
110custom user designs.
111
112The Zephyr support for Cyclone® V SoC Development Kit is based on GSRD hardware.
113Please refer to `Intel® Cyclone® V SoC GSRD <https://rocketboards.org/foswiki/Documentation/CycloneVSoCGSRD>`_
114
115The hardware use for this release is based on Intel® Quartus® version 21.1
116the hardware files can be found `here <https://releases.rocketboards.org/release/2018.05/gsrd/hw/cv_soc_devkit_ghrd.tar.gz>`_
117
118The directory "cv_soc_devkit_ghrd" contains the necessary files to create
119a Intel® Quartus® project:
120
121* ghrd_top.v : top level Verilog (HDL) file for the GSRD
122* soc_system.qpf : Quartus® Prime Project File
123* soc_system.qsf : Quartus® Prime Settings File
124* soc_system.qsys : Platform Designer file (contains the SoC system)
125* soc_system.sopcinfo : SOPC Information file contains details about modules instantiated in the project, parameter names and values.
126* soc_system_timing.sdc : Synopsys Desing Constraint FILE.
127* output_files/soc_system.sof : FPGA configuration file.
128
129
130Flash this FPGA file (.sof) using the ``quartus_pgm`` SDK tool with the FPGA
131configuration file soc_system.sof:
132
133.. code-block:: console
134
135   $ quartus_pgm -m jtag -o "p;path/to/soc_system.sof"
136
137This system is composed by the HPS, ARM Cortex-A9. In this example the UART, timer,
138USB, I2C, DDR memory are exposed. Please double check the peripheral you intend to
139use have its corresponding driver support.
140You can find more information of the Cyclone® V SoC Devkit GSRD in RocketBoards
141or consult the "Cyclone® V Hard Processor System Technical Reference Manual"
142
143
144Console Output
145==============
146
14716550 UART
148----------
149
150By default, the kernel is configured to send console output to the 16550 UART.
151You can monitor this on your workstation by connecting to the top right mini USB
152port on the board (J8/UART) (it will show up in /dev as a ttyUSB node), and then running
153minicom/PuTTy with flow control disabled, 115200-8N1 settings.
154
155
156Programming and Debugging
157*************************
158
159Flashing
160========
161
162Flashing Kernel into the board
163------------------------------
164
165The usual ``flash`` target will work with the ``cyclonev_socdk`` board
166configuration. Here is an example for the :zephyr:code-sample:`hello_world`
167application.
168
169``Important!!!`` : Before flashing the board a ``preloader`` is required,
170you can download `cv_soc_devkit_ghrd.tar.gz <https://releases.rocketboards.org/release/2018.05/gsrd/hw/cv_soc_devkit_ghrd.tar.gz>`_,
171extract the file and copy ``cv_soc_devkit_ghrd/software/preloader/uboot-socfpga/spl/u-boot-spl``
172to :zephyr_file:`boards/intel/socfpga_std/cyclonev_socdk/support/`
173
174.. zephyr-app-commands::
175   :zephyr-app: samples/hello_world
176   :board: cyclonev_socdk
177   :goals: flash
178
179Refer to :ref:`build_an_application` and :ref:`application_run` for
180more details.
181
182This provisions the Zephyr kernel and the CPU configuration onto the board,
183using the customized OpenOCD runner script :zephyr_file:`scripts/west_commands/runners/intel_cyclonev.py`
184After it completes the kernel will immediately boot using the GSRD preloader.
185Notice that there a lot of helper files to ``flash`` the application with
186OpenOCD and GDB Debbuger (Zephyr SDK must be installed in your machine).
187This files should be located in :zephyr_file:`boards/intel/socfpga_std/cyclonev_socdk/support/` including:
188
189* blaster_6810.hex : USB-BlasterII firmware
190* tmp_preloader_dl_cmd.txt : GDB helper file to load the preloader
191* tmp_appli_dl_cmd.gdb : GDB helper file to load the zephyr.elf file
192* tmp_appli_debug_cmd.gdb : GDB helper file to load the zephyr.elf file while debugging
193* openocd.cfg : sources configuration files for OpenOCD
194* download_all.gdb : GDB helper file to load the preloader
195* u-boot-spl : Cyclone® V SoC DevKit GSRD preloader (copied from GSRD: cv_soc_devkit_ghrd.tar.gz)
196
197The following image shows the expected output (UART) after executing "west flash" using
198the "hello world" sample design:
199
200.. figure:: img/cyclonev_westflash.jpg
201   :align: center
202   :alt: UART output after "west flash" example
203
204   UART output after "west flash" example (Credit: Intel®)
205
206Debugging
207=========
208
209The Zephyr SDK includes a GDB server which can be used to debug a Cyclone® V
210SoC Development Kit board.
211You can either debug a running image that was flashed onto the device in User
212Flash Memory (UFM), or load an image over the JTAG using GDB.
213
214Debugging With Flashed Image
215----------------------------
216
217You can debug an application in the usual way.  Here is an example.
218
219.. zephyr-app-commands::
220   :zephyr-app: samples/hello_world
221   :board: cyclonev_socdk
222   :goals: debug
223
224You will see output similar to the following:
225
226.. code-block:: console
227
228   -- west debug: rebuilding
229   ninja: no work to do.
230   -- west debug: using runner intel_cyclonev
231   -- runners.intel_cyclonev: OpenOCD GDB server running on port 3333; no thread info available
232   Open On-Chip Debugger 0.11.0+dev-00244-g7e3dbbbe2 (2021-11-18-07:14)
233   Licensed under GNU GPL v2
234   For bug reports, read http://openocd.org/doc/doxygen/bugs.html
235   Info : only one transport option; autoselect 'jtag'
236   cycv_dbginit
237   Info : Listening on port 6666 for tcl connections
238   Info : Listening on port 4444 for telnet connections
239   Info : Altera USB-Blaster II (uninitialized) found
240   Info : Loading firmware...
241   Info : Waiting for reenumerate...
242   Info : Waiting for reenumerate...
243   Info : Altera USB-Blaster II found (Firm. rev. = 1.39)
244   Info : This adapter doesn't support configurable speed
245   Info : JTAG tap: fpgasoc.fpga.tap tap/device found: 0x02d020dd (mfg: 0x06e (Altera), part: 0x2d02, ver: 0x0)
246   Info : JTAG tap: fpgasoc.cpu tap/device found: 0x4ba00477 (mfg: 0x23b (ARM Ltd), part: 0xba00, ver: 0x4)
247   Info : DAP transaction stalled (WAIT) - slowing down
248   Info : DAP transaction stalled (WAIT) - slowing down
249   Info : fpgasoc.cpu.0: hardware has 6 breakpoints, 4 watchpoints
250   Info : starting gdb server for fpgasoc.cpu.0 on 3333
251   Info : Listening on port 3333 for gdb connections
252   Info : accepting 'gdb' connection on tcp/3333
253   Info : fpgasoc.cpu.0 rev 0, partnum c09, arch f, variant 3, implementor 41
254   Info : fpgasoc.cpu.0: MPIDR level2 0, cluster 0, core 0, multi core, no SMT
255   target halted in ARM state due to debug-request, current mode: Supervisor
256   cpsr: 0x600001d3 pc: 0x00002fa4
257   MMU: disabled, D-Cache: disabled, I-Cache: enabled
258   warning: No executable has been specified and target does not support
259   determining executable automatically.  Try using the "file" command.
260   0x00002fa4 in ?? ()
261   Restoring section .text (0xffff0000 to 0xffff6f84)
262   Info : DAP transaction stalled (WAIT) - slowing down
263   Warn : keep_alive() was not invoked in the 1000 ms timelimit. GDB alive packet not sent! (1469 ms). Workaround: increase "set remotetimeout" in GDB
264   Restoring section .rodata (0xffff6f84 to 0xffff8af9)
265   Restoring section .data (0xffff8b00 to 0xffff99d4)
266   Info : DAP transaction stalled (WAIT) - slowing down
267   Hardware assisted breakpoint 1 at 0xffff147e
268   Info : fpgasoc.cpu.0 rev 0, partnum c09, arch f, variant 3, implementor 41
269   fpgasoc.cpu.0 rev 0, partnum c09, arch f, variant 3, implementor 41
270
271   Temporary breakpoint 1, 0xffff147e in spl_boot_device ()
272   [Inferior 1 (Remote target) detached]
273   Info : dropped 'gdb' connection
274   shutdown command invoked
275   Open On-Chip Debugger 0.11.0+dev-00244-g7e3dbbbe2 (2021-11-18-07:14)
276   Licensed under GNU GPL v2
277   For bug reports, read http://openocd.org/doc/doxygen/bugs.html
278   Info : only one transport option; autoselect 'jtag'
279   cycv_dbginit
280   Info : Listening on port 6666 for tcl connections
281   Info : Listening on port 4444 for telnet connections
282   Info : Altera USB-Blaster II found (Firm. rev. = 1.39)
283   Info : This adapter doesn't support configurable speed
284   Info : JTAG tap: fpgasoc.fpga.tap tap/device found: 0x02d020dd (mfg: 0x06e (Altera), part: 0x2d02, ver: 0x0)
285   Info : JTAG tap: fpgasoc.cpu tap/device found: 0x4ba00477 (mfg: 0x23b (ARM Ltd), part: 0xba00, ver: 0x4)
286   Info : DAP transaction stalled (WAIT) - slowing down
287   Info : DAP transaction stalled (WAIT) - slowing down
288   Info : fpgasoc.cpu.0: hardware has 6 breakpoints, 4 watchpoints
289   Info : fpgasoc.cpu.0 rev 0, partnum c09, arch f, variant 3, implementor 41
290   Info : fpgasoc.cpu.0: MPIDR level2 0, cluster 0, core 0, multi core, no SMT
291   Info : starting gdb server for fpgasoc.cpu.0 on 3333
292   Info : Listening on port 3333 for gdb connections
293   Info : accepting 'gdb' connection on tcp/3333
294   warning: No executable has been specified and target does not support
295   determining executable automatically.  Try using the "file" command.
296   0xffff147c in ?? ()
297   warning: /home/demo/zephyrproject/zephyr/boards/intel/socfpga_std/cyclonev_socdk/support/tmp_appli_debug_cmd.gdb: No such file or directory
298   [Inferior 1 (Remote target) detached]
299   Info : dropped 'gdb' connection
300   shutdown command invoked
301   Open On-Chip Debugger 0.11.0+dev-00244-g7e3dbbbe2 (2021-11-18-07:14)
302   Licensed under GNU GPL v2
303   For bug reports, read http://openocd.org/doc/doxygen/bugs.html
304   Info : only one transport option; autoselect 'jtag'
305   cycv_dbginit
306   Info : Listening on port 6666 for tcl connections
307   Info : Listening on port 4444 for telnet connections
308   Info : Altera USB-Blaster II found (Firm. rev. = 1.39)
309   Info : This adapter doesn't support configurable speed
310   Info : JTAG tap: fpgasoc.fpga.tap tap/device found: 0x02d020dd (mfg: 0x06e (Altera), part: 0x2d02, ver: 0x0)
311   Info : JTAG tap: fpgasoc.cpu tap/device found: 0x4ba00477 (mfg: 0x23b (ARM Ltd), part: 0xba00, ver: 0x4)
312   Info : DAP transaction stalled (WAIT) - slowing down
313   Info : DAP transaction stalled (WAIT) - slowing down
314   Info : fpgasoc.cpu.0: hardware has 6 breakpoints, 4 watchpoints
315   Reading symbols from /home/demo/zephyrproject/zephyr/build/zephyr/zephyr.elf...
316   Info : fpgasoc.cpu.0 rev 0, partnum c09, arch f, variant 3, implementor 41
317   Info : fpgasoc.cpu.0: MPIDR level2 0, cluster 0, core 0, multi core, no SMT
318   Info : starting gdb server for fpgasoc.cpu.0 on 3333
319   Info : Listening on port 3333 for gdb connections
320   Remote debugging using :3333
321   Info : accepting 'gdb' connection on tcp/3333
322   main () at /home/demo/zephyrproject/zephyr/samples/hello_world/src/main.c:11
323   11              printk("Hello World! %s\n", CONFIG_BOARD);
324   (gdb)
325
326
327Try other examples
328==================
329There are varios examples that can be downloaded to the Cyclone® V SoC FPGA
330Development Kit Board. Try to ``blink`` an LED from the HPS side of the chip:
331
332.. zephyr-app-commands::
333   :zephyr-app: samples/basic/blinky
334   :board: cyclonev_socdk
335   :goals: flash
336
337.. figure:: img/cyclonev_blinky.jpg
338   :align: center
339   :alt: HPS LED0 blinking example
340
341   HPS LED0 blinking example (Credit: Intel®)
342
343Try writing characters to the LCD display connected to the i2c bus:
344
345.. zephyr-app-commands::
346   :zephyr-app: samples/drivers/lcd_cyclonev_socdk
347   :board: cyclonev_socdk
348   :goals: flash
349
350
351References
352**********
353
354* `Cyclone® V Hard Processor System Technical Reference Manual <https://www.intel.com/content/dam/www/programmable/us/en/pdfs/literature/hb/cyclone-v/cv_54001.pdf>`_
355* `Cyclone® V SoC Development Kit and Intel® SoC FPGA Embedded Development Suite <https://www.intel.com/content/www/us/en/products/details/fpga/development-kits/cyclone/v-sx.html>`_
356* `Cyclone® V SoC GSRD in RocketBoards.org <https://rocketboards.org/foswiki/Documentation/CycloneVSoCGSRD>`_
357* `Intel® FPGA Software Download Center <https://www.intel.com/content/www/us/en/collections/products/fpga/software/downloads.html>`_
358* `Embedded Peripherals IP User Guide <https://www.altera.com/content/dam/altera-www/global/en_US/pdfs/literature/ug/ug_embedded_ip.pdf>`_
359* `Quartus II Scripting Reference Manual <https://www.altera.com/content/dam/altera-www/global/en_US/pdfs/literature/manual/tclscriptrefmnl.pdf>`_
360