1.. _arty:
2
3Digilent Arty
4#############
5
6Overview
7********
8
9The `Digilent Arty`_ is a line of FPGA-based development boards aimed for makers
10and hobbyists. The Arty is available in several configurations, each with a
11different Xilinx FPGA (Spartan-7, Artix-7, or Zynq-7000 series).
12
13Each board is equipped with on-board JTAG for FPGA programming and debugging,
14LEDs, switches, buttons, DDR3 RAM, and QSPI flash for storing the FPGA
15bitstream.
16
17.. figure:: arty_a7-35.jpg
18   :align: center
19   :alt: Digilent Arty A7-35
20
21   Digilent Arty A7-35 (Credit: Digilent Inc)
22
23The Spartan-7 and Artix-7 based Arty board do not contain a CPU, but require a
24so-called soft processor to be instantiated within the FPGA in order to run
25Zephyr. The Zynq-7000 based Arty boards are not yet supported by Zephyr.
26
27ARM Cortex-M1/M3 DesignStart FPGA
28*********************************
29
30One way of instantiating soft processors on the Arty is using the `ARM
31DesignStart FPGA`_ Xilinx edition reference designs from ARM. Zephyr supports
32both the Cortex-M1 and the Cortex-M3 reference designs. The Cortex-M1 design
33targets either the Spartan-7 or Artix-7 based Arty boards, whereas the Cortex-M3
34design only targets the Artix-7 based boards. Zephyr only supports the Artix-7
35targeted designs for now.
36
37For more information about the ARM Cortex-M1/M3 DesignStart FPGA, see the
38following websites:
39
40- `Technical Resources for DesignStart FPGA`_
41- `Technical Resources for DesignStart FPGA on Xilinx`_
42- `ARM DesignStart FPGA Xilinx FAQs`_
43
44Supported Features
45==================
46
47The ``arty_a7/designstart_fpga_cortex_m1`` board configuration supports the following
48hardware features of the Cortex-M1 reference design:
49
50+-----------+------------+-------------------------------------+
51| Interface | Controller | Driver/Component                    |
52+===========+============+=====================================+
53| NVIC      | on-chip    | nested vector interrupt controller  |
54+-----------+------------+-------------------------------------+
55| SYSTICK   | on-chip    | systick                             |
56+-----------+------------+-------------------------------------+
57| GPIO      | on-chip    | gpio, non-interrupt                 |
58+-----------+------------+-------------------------------------+
59| UART      | on-chip    | serial port-polling;                |
60|           |            | serial port-interrupt               |
61+-----------+------------+-------------------------------------+
62| QSPI      | on-chip    | QSPI flash                          |
63+-----------+------------+-------------------------------------+
64
65The default configuration for the Cortex-M1 can be found in the defconfig file:
66:file:`boards/digilent/arty_a7/arty_a7_designstart_fpga_cortex_m1_defconfig`.
67
68In addition to the above, the ``arty_a7/designstart_fpga_cortex_m3`` board configuration
69supports the following hardware features of the Cortex-M3 reference design:
70
71+-----------+------------+-------------------------------------+
72| Interface | Controller | Driver/Component                    |
73+===========+============+=====================================+
74| MPU       | on-chip    | Memory Protection Unit              |
75+-----------+------------+-------------------------------------+
76
77The default configuration for the Cortex-M3 can be found in the defconfig file:
78:file:`boards/digilent/arty_a7/arty_a7_designstart_fpga_cortex_m3_defconfig`.
79
80Other hardware features are not currently supported by the port.
81
82System Clock
83============
84
85The Cortex-M1 reference design is configured to use the 100 MHz external
86oscillator on the board as CPU system clock whereas the Cortex-M3 reference
87design is configured for 50MHz CPU system clock.
88
89Serial Port
90===========
91
92The reference design contains one Xilinx UART Lite. This UART is configured as
93console and is accessible through the on-board JTAG adapter via USB connector
94``J10``.
95
96Connecting the Debug Probes
97===========================
98
99Two different debug probes are needed in order to program the board; the
100on-board Digilent JTAG connected to the FPGA, and an external Serial Wire Debug
101(SWD) capable debug probe connected to the ARM Cortex-M1 CPU.
102
103The on-board JTAG is used for configuring and debugging the Xilinx FPGA
104itself. It is available on USB connector ``J10``.
105
106The external SWD debug probe can be connected to connector ``J4`` (``nSRST`` on
107``IO39``, ``SWDIO`` on ``IO40``, and ``SWCLK`` on ``IO41``). Another option is
108to use the dedicated :ref:`v2c_daplink_shield`.
109
110Programming and Debugging
111*************************
112
113First, configure the FPGA with the selected reference design FPGA bitstream
114using Xilinx Vivado as described in the ARM Cortex-M1/Cortex-M3 DesignStart FPGA
115Xilinx edition user guide (available as part of the reference design download
116from `Technical Resources for DesignStart FPGA on Xilinx`_).
117
118Another option for configuring the FPGA with the reference design bitstream is
119to use the :ref:`openocd-debug-host-tools`:
120
121.. code-block:: console
122
123   openocd -f board/arty_s7.cfg -c "init;\
124        pld load 0 m1_for_arty_a7_reference.bit;\
125        shutdown"
126
127or:
128
129.. code-block:: console
130
131   openocd -f board/arty_s7.cfg -c "init;\
132        pld load 0 m3_for_arty_a7_reference.bit;\
133        shutdown"
134
135.. note::
136
137   The pre-built FPGA bitstream only works for Arty boards equipped with an
138   Artix-35T FPGA. For other Arty variants (e.g. the Arty A7-100) the bitstream
139   must be rebuilt.
140
141Next, build and flash applications as usual (see :ref:`build_an_application` and
142:ref:`application_run` for more details).
143
144Configuring a Console
145=====================
146
147The UART console is available via the on-board JTAG on USB connector
148``J10``. The on-board JTAG will enumerate as two USB serial ports. The UART is
149typically available on the second serial port.
150
151Use the following settings with your serial terminal of choice (minicom, putty,
152etc.):
153
154- Speed: 115200
155- Data: 8 bits
156- Parity: None
157- Stop bits: 1
158
159Flashing
160========
161
162Here is an example for building and flashing the :zephyr:code-sample:`hello_world` application
163for the Cortex-M1 reference design:
164
165.. zephyr-app-commands::
166   :zephyr-app: samples/hello_world
167   :board: arty_a7/designstart_fpga_cortex_m1
168   :goals: flash
169
170After flashing, you should see message similar to the following in the terminal:
171
172.. code-block:: console
173
174   *** Booting Zephyr OS build zephyr-v2.3.99  ***
175   Hello World! arty_a7
176
177The same procedure can be used for the Cortex-M3 reference design.
178
179Note, however, that the application was not persisted in flash memory by the
180above steps. It was merely written to internal block RAM in the FPGA. It will
181revert to the application stored in the block RAM within the FPGA bitstream
182the next time the FPGA is configured.
183
184The steps to persist the application within the FPGA bitstream are covered by
185the ARM Cortex-M1/M3 DesignStart FPGA Xilinx edition user guide. If the
186:kconfig:option:`CONFIG_BUILD_OUTPUT_BIN` is enabled and the `SiFive elf2hex`_ package
187is available, the build system will automatically generate a Verilog memory hex
188dump :file:`zephyr.mem` file suitable for initialising the block RAM using
189`Xilinx Vivado`_.
190
191Debugging
192=========
193
194Here is an example for the :zephyr:code-sample:`hello_world` application.
195
196.. zephyr-app-commands::
197   :zephyr-app: samples/hello_world
198   :board: arty_a7/designstart_fpga_cortex_m1
199   :goals: debug
200
201Step through the application in your debugger, and you should see a message
202similar to the following in the terminal:
203
204.. code-block:: console
205
206   *** Booting Zephyr OS build zephyr-v2.3.99  ***
207   Hello World! arty_a7
208
209.. _Digilent Arty:
210   https://store.digilentinc.com/arty
211
212.. _ARM DesignStart FPGA:
213   https://www.arm.com/resources/designstart/designstart-fpga
214
215.. _Technical Resources for DesignStart FPGA:
216   https://developer.arm.com/ip-products/designstart/fpga
217
218.. _Technical Resources for DesignStart FPGA on Xilinx:
219   https://developer.arm.com/ip-products/designstart/fpga/fpga-xilinx
220
221.. _ARM DesignStart FPGA Xilinx FAQs:
222   https://developer.arm.com/ip-products/designstart/fpga/fpga-xilinx-faqs
223
224.. _SiFive elf2hex:
225   https://github.com/sifive/elf2hex
226
227.. _Xilinx Vivado:
228   https://www.xilinx.com/products/design-tools/vivado.html
229