Skip to content

Commit f080b22

Browse files
jenmwmsjhedberg
jenmwms
authored and
jhedberg
committed
boards: x86: Add basic documentation for Intel Elkhart Lake
Add initial documentation for the Elkhart Lake SoC and CRB board definition. Signed-off-by: Jennifer Williams <[email protected]>
1 parent 7c70032 commit f080b22

File tree

2 files changed

+322
-0
lines changed

2 files changed

+322
-0
lines changed

‎boards/x86/ehl_crb/doc/index.rst‎

Lines changed: 309 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,309 @@
1+
.. _ehl_crb:
2+
3+
Elkhart Lake CRB
4+
################
5+
6+
Overview
7+
********
8+
Elkhart Lake Reference Board (EHL CRB) is an example implementation of a
9+
compact single board computer with high performance for IoT edge devices.
10+
11+
This board configuration enables kernel support for the `EHL`_ board.
12+
13+
.. note::
14+
This board configuration works on the variant of `EHL`_
15+
boards containing Intel |reg| Atom |trade| SoC.
16+
17+
Hardware
18+
********
19+
20+
General information about the board can be found at the `EHL`_ website.
21+
22+
.. include:: ../../../../soc/x86/elkhart_lake/doc/supported_features.txt
23+
24+
25+
Connections and IOs
26+
===================
27+
28+
Refer to the `EHL`_ website for more information.
29+
30+
Programming and Debugging
31+
*************************
32+
Use the following procedures for booting an image on a EHL CRB board.
33+
34+
.. contents::
35+
:depth: 1
36+
:local:
37+
:backlinks: top
38+
39+
Creating a GRUB2 Boot Loader Image from a Linux Host
40+
====================================================
41+
42+
If you are having problems running an application using the preinstalled
43+
copy of GRUB, follow these steps to test on supported boards using a custom GRUB.
44+
45+
#. Install the requirements to build GRUB on your host machine.
46+
47+
On Ubuntu, type:
48+
49+
.. code-block:: console
50+
51+
$ sudo apt-get install bison autoconf libopts25-dev flex automake \
52+
pkg-config gettext autopoint
53+
54+
On Fedora, type:
55+
56+
.. code-block:: console
57+
58+
$ sudo dnf install gnu-efi bison m4 autoconf help2man flex \
59+
automake texinfo gettext-devel
60+
61+
#. Clone and build the GRUB repository using the script in Zephyr tree, type:
62+
63+
.. code-block:: console
64+
65+
$ cd $ZEPHYR_BASE
66+
$ ./boards/x86/common/scripts/build_grub.sh x86_64
67+
68+
#. Find the binary at
69+
:file:`$ZEPHYR_BASE/boards/x86/common/scripts/grub/bin/grub_x86_64.efi`.
70+
71+
Build Zephyr application
72+
========================
73+
74+
#. Build a Zephyr application; for instance, to build the ``hello_world``
75+
application on Elkhart Lake CRB:
76+
77+
.. zephyr-app-commands::
78+
:zephyr-app: samples/hello_world
79+
:board: ehl_crb
80+
:goals: build
81+
82+
.. note::
83+
84+
A stripped project image file named :file:`zephyr.strip` is automatically
85+
created in the build directory after the application is built. This image
86+
has removed debug information from the :file:`zephyr.elf` file.
87+
88+
Preparing the Boot Device
89+
=========================
90+
91+
Prepare a USB flash drive to boot the Zephyr application image on
92+
an Elkhart Lake CRB board.
93+
94+
#. Format the USB flash drive as FAT32.
95+
96+
On Windows, open ``File Explorer``, and right-click on the USB flash drive.
97+
Select ``Format...``. Make sure in ``File System``, ``FAT32`` is selected.
98+
Click on the ``Format`` button and wait for it to finish.
99+
100+
On Linux, graphical utilities such as ``gparted`` can be used to format
101+
the USB flash drive as FAT32. Alternatively, under terminal, find out
102+
the corresponding device node for the USB flash drive (for example,
103+
``/dev/sdd``). Execute the following command:
104+
105+
.. code-block:: console
106+
107+
$ mkfs.vfat -F 32 <device-node>
108+
109+
.. important::
110+
Make sure the device node is the actual device node for
111+
the USB flash drive. Or else you may erase other storage devices
112+
on your system, and will render the system unusable afterwards.
113+
114+
#. Create the following directories
115+
116+
:file:`efi`
117+
118+
:file:`efi/boot`
119+
120+
:file:`kernel`
121+
122+
#. Copy the kernel file :file:`zephyr/zephyr.strip` to the :file:`$USB/kernel` folder.
123+
124+
#. Copy your built version of GRUB to :file:`$USB/efi/boot/bootx64.efi`
125+
126+
#. Create :file:`$USB/efi/boot/grub.cfg` containing the following:
127+
128+
.. code-block:: console
129+
130+
set default=0
131+
set timeout=10
132+
133+
menuentry "Zephyr Kernel" {
134+
multiboot /kernel/zephyr.strip
135+
}
136+
137+
Booting the Elkhart Lake CRB Board
138+
==================================
139+
140+
Boot the Elkhart Lake CRB board from the boot device using GRUB2 via USB flash drive.
141+
142+
#. Insert the prepared boot device (USB flash drive) into the Elkhart Lake CRB board.
143+
144+
#. Connect the board to the host system using the serial cable and
145+
configure your host system to watch for serial data. See
146+
`EHL`_ website for more information.
147+
148+
.. note::
149+
On Windows, PuTTY has an option to set up configuration for
150+
serial data. Use a baud rate of 115200.
151+
152+
#. Power on the Elkhart Lake CRB board.
153+
154+
#. When the following output appears, press :kbd:`F7`:
155+
156+
.. code-block:: console
157+
158+
Press <DEL> or <ESC> to enter setup.
159+
160+
#. From the menu that appears, select the menu entry that describes
161+
that particular type of USB flash drive.
162+
163+
GRUB2 starts and a menu shows entries for the items you added
164+
to the file :file:`grub.cfg`.
165+
166+
#. Select the image you want to boot and press :guilabel:`Enter`.
167+
168+
When the boot process completes, you have finished booting the
169+
Zephyr application image.
170+
171+
.. note::
172+
You can safely ignore this message if it appears:
173+
174+
.. code-block:: console
175+
176+
WARNING: no console will be available to OS
177+
178+
179+
Booting the Elkhart Lake CRB Board over network
180+
===============================================
181+
182+
Build Zephyr image
183+
------------------
184+
185+
#. Follow `Build Zephyr application`_ steps to build Zephyr image.
186+
187+
Prepare Linux host
188+
------------------
189+
190+
#. Follow `Creating a GRUB2 Boot Loader Image from a Linux Host`_ steps
191+
to create grub binary.
192+
193+
#. Install DHCP, TFTP servers. For example ``dnsmasq``
194+
195+
.. code-block:: console
196+
197+
$ sudo apt-get install dnsmasq
198+
199+
#. Configure DHCP server. Configuration for ``dnsmasq`` is below:
200+
201+
.. code-block:: console
202+
203+
# Only listen to this interface
204+
interface=eno2
205+
dhcp-range=10.1.1.20,10.1.1.30,12h
206+
207+
#. Configure TFTP server.
208+
209+
.. code-block:: console
210+
211+
# tftp
212+
enable-tftp
213+
tftp-root=/srv/tftp
214+
dhcp-boot=grub_x86_64.efi
215+
216+
``grub_x86_64.efi`` is a grub binary created above.
217+
218+
#. Create the following directories inside TFTP root :file:`/srv/tftp`
219+
220+
.. code-block:: console
221+
222+
$ sudo mkdir -p /srv/tftp/EFI/BOOT
223+
$ sudo mkdir -p /srv/tftp/kernel
224+
225+
#. Copy the Zephyr image :file:`zephyr/zephyr.strip` to the
226+
:file:`/srv/tftp/kernel` folder.
227+
228+
.. code-block:: console
229+
230+
$ sudo cp zephyr/zephyr.strip /srv/tftp/kernel
231+
232+
#. Copy your built version of GRUB to :file:`/srv/tftp/grub_x86_64.efi`
233+
234+
#. Create :file:`/srv/tftp/EFI/BOOT/grub.cfg` containing the following:
235+
236+
.. code-block:: console
237+
238+
set default=0
239+
set timeout=10
240+
241+
menuentry "Zephyr Kernel" {
242+
multiboot /kernel/zephyr.strip
243+
}
244+
245+
#. TFTP root should be looking like:
246+
247+
.. code-block:: console
248+
249+
$ tree /srv/tftp
250+
/srv/tftp
251+
├── EFI
252+
│   └── BOOT
253+
│   └── grub.cfg
254+
├── grub_x86_64.efi
255+
└── kernel
256+
└── zephyr.strip
257+
258+
#. Restart ``dnsmasq`` service:
259+
260+
.. code-block:: console
261+
262+
$ sudo systemctl restart dnsmasq.service
263+
264+
Prepare Elkhart Lake CRB board for network boot
265+
-----------------------------------------------
266+
267+
#. Enable PXE network from BIOS settings.
268+
269+
.. code-block:: console
270+
271+
Advanced -> Network Stack Configuration -> Enable Network Stack -> Enable Ipv4 PXE Support
272+
273+
#. Make network boot as the first boot option.
274+
275+
.. code-block:: console
276+
277+
Boot -> Boot Option #1 : [Network]
278+
279+
Booting Elkhart Lake CRB
280+
------------------------
281+
282+
#. Connect the board to the host system using the serial cable and
283+
configure your host system to watch for serial data.
284+
285+
#. Power on the Elkhart Lake CRB board.
286+
287+
#. Verify that the board got an IP address:
288+
289+
.. code-block:: console
290+
291+
$ journalctl -f -u dnsmasq
292+
dnsmasq-dhcp[5386]: DHCPDISCOVER(eno2) 00:07:32:52:25:88
293+
dnsmasq-dhcp[5386]: DHCPOFFER(eno2) 10.1.1.28 00:07:32:52:25:88
294+
dnsmasq-dhcp[5386]: DHCPREQUEST(eno2) 10.1.1.28 00:07:32:52:25:88
295+
dnsmasq-dhcp[5386]: DHCPACK(eno2) 10.1.1.28 00:07:32:52:25:88
296+
297+
#. Verify that network booting is started:
298+
299+
.. code-block:: console
300+
301+
$ journalctl -f -u dnsmasq
302+
dnsmasq-tftp[5386]: sent /srv/tftp/grub_x86_64.efi to 10.1.1.28
303+
dnsmasq-tftp[5386]: sent /srv/tftp/EFI/BOOT/grub.cfg to 10.1.1.28
304+
dnsmasq-tftp[5386]: sent /srv/tftp/kernel/zephyr.strip to 10.1.1.28
305+
306+
#. When the boot process completes, you have finished booting the
307+
Zephyr application image.
308+
309+
.. _EHL: https://www.intel.com/content/www/us/en/products/docs/processors/embedded/enhanced-for-iot-platform-brief.html

‎soc/x86/elkhart_lake/doc/supported_features.txt‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
Supported Features
2+
==================
3+
4+
In addition to the standard architecture devices (HPET, local and I/O APICs,
5+
etc.), Zephyr supports the following Elkhart Lake-specific SoC devices:
6+
7+
* I2C
8+
9+
UART Serial Port Support
10+
-------------------------------------
11+
12+
The Elkhart Lake UARTs are NS16550-compatible. Baud rate of
13+
115.2kbps is supported.

0 commit comments

Comments
 (0)