1.. _up_squared:
2
3UP Squared
4##########
5
6Overview
7********
8
9UP |sup2| (UP Squared) is an ultra compact single board computer with high
10performance and low power consumption. It features the latest Intel |reg| Apollo
11Lake Celeron |trade| and Pentium |trade| Processors with only 4W of Scenario Design Power and
12a powerful and flexible Intel |reg| FPGA Altera MAX 10 onboard.
13
14.. figure:: img/up_squared.jpg
15   :align: center
16   :alt: UP Squared
17
18   Up Squared (Credit: https://up-board.org)
19
20This board configuration enables kernel support for the `UP Squared`_ board.
21
22.. note::
23   This board configuration works on all three variants of `UP Squared`_
24   boards containing Intel |reg| Pentium |trade| SoC,
25   Intel |reg| Celeron |trade| SoC, or Intel |reg| Atom |trade| SoC.
26
27Hardware
28********
29
30General information about the board can be found at the `UP Squared`_ website.
31
32.. include:: ../../../../soc/x86/apollo_lake/doc/supported_features.txt
33
34GPIO
35----
36
37GPIOs are exposed through the HAT header, and can be referred using
38predefined macros such as ``UP2_HAT_PIN3``. The physical pins are
39connected to the on-board FPGA acting as level shifter. Therefore,
40to actually utilize these GPIO pins, the function of the pins and
41directions (input/output) must be set in the BIOS. This can be
42accomplished in BIOS, under menu ``Advanced``, and option
43``HAT Configurations``. When a corresponding pin is set to act as
44GPIO, there is an option to set the direction of the pin. This needs
45to be set accordingly for the GPIO to function properly.
46
47Connections and IOs
48===================
49
50Refer to the `UP Squared`_ website and `UP Squared Pinout`_ website
51for connection diagrams.
52
53Programming and Debugging
54*************************
55
56Use the following procedures for booting an image on a UP Squared board.
57
58.. contents::
59   :depth: 1
60   :local:
61   :backlinks: top
62
63Build Zephyr application
64========================
65
66#. Build a Zephyr application; for instance, to build the ``hello_world``
67   application on UP Squared:
68
69   .. zephyr-app-commands::
70      :zephyr-app: samples/hello_world
71      :board: up_squared
72      :goals: build
73
74   .. note::
75
76      A Zephyr EFI image file named :file:`zephyr.efi` is automatically
77      created in the build directory after the application is built.
78
79Preparing the Boot Device
80=========================
81
82Prepare a USB flash drive to boot the Zephyr application image on
83a UP Squared board.
84
85#. Refer to the `UP Squared Serial Console Wiki page
86   <https://wiki.up-community.org/Serial_console>`_ for instructions on how to
87   connect for serial console.
88
89#. Format the USB flash drive as FAT32.
90
91   On Windows, open ``File Explorer``, and right-click on the USB flash drive.
92   Select ``Format...``. Make sure in ``File System``, ``FAT32`` is selected.
93   Click on the ``Format`` button and wait for it to finish.
94
95   On Linux, graphical utilities such as ``gparted`` can be used to format
96   the USB flash drive as FAT32. Alternatively, under terminal, find out
97   the corresponding device node for the USB flash drive (for example,
98   ``/dev/sdd``). Execute the following command:
99
100   .. code-block:: console
101
102      $ mkfs.vfat -F 32 <device-node>
103
104   .. important::
105      Make sure the device node is the actual device node for
106      the USB flash drive. Or else you may erase other storage devices
107      on your system, and will render the system unusable afterwards.
108
109#. Copy the Zephyr EFI image file :file:`zephyr/zephyr.efi` to the USB drive.
110
111Booting the UP Squared Board
112============================
113
114Boot the UP Squared board to the EFI shell with USB flash drive connected.
115
116#. Insert the prepared boot device (USB flash drive) into the UP Squared board.
117
118#. Connect the board to the host system using the serial cable and
119   configure your host system to watch for serial data.  See
120   https://wiki.up-community.org/Serial_console.
121
122   .. note::
123      On Windows, PuTTY has an option to set up configuration for
124      serial data.  Use a baud rate of 115200.
125
126#. Power on the UP Squared board.
127
128#. When the following output appears, press :kbd:`F7`:
129
130   .. code-block:: console
131
132      Press <DEL> or <ESC> to enter setup.
133
134#. From the menu that appears, select the menu entry that describes
135   that particular EFI shell.
136
137#. From the EFI shell select Zephyr EFI image to boot.
138
139   .. code-block:: console
140
141      Shell> fs0:zephyr.efi
142
143   .. note::
144      You can safely ignore this message if it appears:
145
146      .. code-block:: console
147
148         WARNING: no console will be available to OS
149
150
151Booting the UP Squared Board over network
152=========================================
153
154Build Zephyr image
155------------------
156
157#. Follow `Build Zephyr application`_ steps to build Zephyr image.
158
159Prepare Linux host
160------------------
161
162#. Install DHCP, TFTP servers. For example ``dnsmasq``
163
164   .. code-block:: console
165
166      $ sudo apt-get install dnsmasq
167
168#. Configure DHCP server. Configuration for ``dnsmasq`` is below:
169
170   .. code-block:: console
171
172      # Only listen to this interface
173      interface=eno2
174      dhcp-range=10.1.1.20,10.1.1.30,12h
175
176#. Configure TFTP server.
177
178   .. code-block:: console
179
180      # tftp
181      enable-tftp
182      tftp-root=/srv/tftp
183      dhcp-boot=zephyr.efi
184
185   ``zephyr.efi`` is a Zephyr EFI binary created above.
186
187#. Copy the Zephyr EFI image :file:`zephyr/zephyr.efi` to the
188   :file:`/srv/tftp` folder.
189
190    .. code-block:: console
191
192       $ sudo cp zephyr/zephyr.efi /srv/tftp
193
194
195#. TFTP root should be looking like:
196
197   .. code-block:: console
198
199      $ tree /srv/tftp
200      /srv/tftp
201      └── zephyr.efi
202
203#. Restart ``dnsmasq`` service:
204
205   .. code-block:: console
206
207      $ sudo systemctl restart dnsmasq.service
208
209Prepare UP Squared board for network boot
210-----------------------------------------
211
212#. Enable PXE network from BIOS settings.
213
214   .. code-block:: console
215
216      Advanced -> Network Stack Configuration -> Enable Network Stack -> Enable Ipv4 PXE Support
217
218#. Make network boot as the first boot option.
219
220   .. code-block:: console
221
222      Boot -> Boot Option #1 : [Network]
223
224Booting UP Squared
225------------------
226
227#. Connect the board to the host system using the serial cable and
228   configure your host system to watch for serial data.  See
229   https://wiki.up-community.org/Serial_console.
230
231#. Power on the UP Squared board.
232
233#. Verify that the board got an IP address:
234
235   .. code-block:: console
236
237      $ journalctl -f -u dnsmasq
238      dnsmasq-dhcp[5386]: DHCPDISCOVER(eno2) 00:07:32:52:25:88
239      dnsmasq-dhcp[5386]: DHCPOFFER(eno2) 10.1.1.28 00:07:32:52:25:88
240      dnsmasq-dhcp[5386]: DHCPREQUEST(eno2) 10.1.1.28 00:07:32:52:25:88
241      dnsmasq-dhcp[5386]: DHCPACK(eno2) 10.1.1.28 00:07:32:52:25:88
242
243#. Verify that network booting is started:
244
245   .. code-block:: console
246
247      $ journalctl -f -u dnsmasq
248      dnsmasq-tftp[5386]: sent /srv/tftp/zephyr.efi to 10.1.1.28
249
250#. When the boot process completes, you have finished booting the
251   Zephyr application image.
252
253.. _UP Squared: https://www.up-board.org/upsquared/specifications
254
255.. _UP Squared Pinout: https://wiki.up-community.org/Pinout
256