1.. zephyr:code-sample:: fpga-controller
2   :name: FPGA Controller
3
4   Load a bitstream into an FPGA and perform basic operations on it.
5
6Overview
7********
8This module is an FPGA driver that can easily load a bitstream, reset it, check its status, enable or disable the FPGA.
9This sample demonstrates how to use the FPGA driver API and the FPGA controller shell subsystem.
10Currently the sample works with `Quicklogic Quickfeather board`_.
11
12Requirements
13************
14
15* Zephyr RTOS
16  or
17* Zephyr RTOS with shell subsystem enabled (for shell application)
18* `Quicklogic Quickfeather board`_
19
20Building
21********
22
23For building on QuickLogic QuickFeather board:
24
25.. zephyr-app-commands::
26   :zephyr-app: samples/drivers/fpga/fpga_controller
27   :host-os: unix
28   :board: quick_feather
29   :goals: build
30
31
32To build the FPGA Controller shell application, use the supplied
33configuration file prj_shell.conf:
34
35.. zephyr-app-commands::
36   :zephyr-app: samples/drivers/fpga/fpga_controller
37   :host-os: unix
38   :board: quick_feather
39   :conf: prj_shell.conf
40   :goals: build
41   :compact:
42
43
44Running
45*******
46
47See :ref:`quickfeather` on how to load an image to the board.
48
49Sample output
50=============
51
52Once the board is programmed, the LED should alternately flash red and green.
53
54For the FPGA controller shell application, after connecting to the shell console you should see the following output:
55
56.. code-block:: console
57
58    Address of the bitstream (red): 0xADDR
59    Address of the bitstream (green): 0xADDR
60    Size of the bitstream (red): 75960
61    Size of the bitstream (green): 75960
62
63    uart:~$
64
65This sample is already prepared with bitstreams.
66After executing the sample, you can see at what address it is stored and its size in bytes.
67
68The FPGA controller command can now be used (``fpga load <device> <address> <size in bytes>``):
69
70.. code-block:: console
71
72    uart:~$ fpga load FPGA 0x2001a46c 75960
73    FPGA: loading bitstream
74
75
76The LED should start blinking (color depending on the selected bitstream).
77To upload the bitstream again you need to reset the FPGA:
78
79.. code-block:: console
80
81    uart:~$ fpga reset FPGA
82    FPGA: resetting FPGA
83
84You can also use your own bitstream.
85To load a bitstream into device memory, use `devmem load` command.
86It is important to use the -e option when sending a bitstream via `xxd`:
87
88.. code-block:: console
89
90    uart:~$ devmem load -e 0x10000
91    Loading...
92    Press ctrl-x + ctrl-q to stop
93
94Now, the loader is waiting for data.
95You can either type it directly from the console or send it from the host PC (replace `ttyX` with the appropriate one for your shell console):
96
97.. code-block:: console
98
99    xxd -p data > /dev/ttyX
100
101(It is important to use plain-style hex dump)
102Once the data is transferred, use `ctrl-x + ctrl-q` to quit loader.
103It will print the sum of the read bytes and return to the shell:
104
105.. code-block:: console
106
107    Number of bytes read: 75960
108    uart:~$
109
110Now the bitstream can be uploaded again.
111
112.. code-block:: console
113
114    uart:~$ fpga load FPGA 0x10000 75960
115    FPGA: loading bitstream
116
117References
118**********
119
120.. _Quicklogic Quickfeather board:
121   https://github.com/QuickLogic-Corp/quick-feather-dev-board
122