1.. _ehl_crb:
2
3Elkhart Lake CRB
4################
5
6Overview
7********
8Elkhart Lake Reference Board (EHL CRB) is an example implementation of a
9compact single board computer with high performance for IoT edge devices.
10
11This 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
17Hardware
18********
19
20General information about the board can be found at the `EHL`_ website.
21
22.. include:: ../../../../soc/x86/elkhart_lake/doc/supported_features.txt
23
24
25Connections and IOs
26===================
27
28Refer to the `EHL`_ website for more information.
29
30Programming and Debugging
31*************************
32Use the following procedures for booting an image on a EHL CRB board.
33
34.. contents::
35   :depth: 1
36   :local:
37   :backlinks: top
38
39Build Zephyr application
40========================
41
42#. Build a Zephyr application; for instance, to build the ``hello_world``
43   application on Elkhart Lake CRB:
44
45   .. zephyr-app-commands::
46      :zephyr-app: samples/hello_world
47      :board: ehl_crb
48      :goals: build
49
50   .. note::
51
52      A Zephyr EFI image file named :file:`zephyr.efi` is automatically
53      created in the build directory after the application is built.
54
55Preparing the Boot Device
56=========================
57
58Prepare a USB flash drive to boot the Zephyr application image on
59an Elkhart Lake CRB board.
60
61#. Format the USB flash drive as FAT32.
62
63   On Windows, open ``File Explorer``, and right-click on the USB flash drive.
64   Select ``Format...``. Make sure in ``File System``, ``FAT32`` is selected.
65   Click on the ``Format`` button and wait for it to finish.
66
67   On Linux, graphical utilities such as ``gparted`` can be used to format
68   the USB flash drive as FAT32. Alternatively, under terminal, find out
69   the corresponding device node for the USB flash drive (for example,
70   ``/dev/sdd``). Execute the following command:
71
72   .. code-block:: console
73
74      $ mkfs.vfat -F 32 <device-node>
75
76   .. important::
77      Make sure the device node is the actual device node for
78      the USB flash drive. Or else you may erase other storage devices
79      on your system, and will render the system unusable afterwards.
80
81#. Copy the Zephyr EFI image file :file:`zephyr/zephyr.efi` to the USB drive.
82
83Booting the Elkhart Lake CRB Board
84==================================
85
86Boot the Elkhart Lake CRB board to the EFI shell with USB flash drive connected.
87
88#. Insert the prepared boot device (USB flash drive) into the Elkhart Lake CRB board.
89
90#. Connect the board to the host system using the serial cable and
91   configure your host system to watch for serial data.  See
92   `EHL`_ website for more information.
93
94   .. note::
95      On Windows, PuTTY has an option to set up configuration for
96      serial data.  Use a baud rate of 115200.
97
98#. Power on the Elkhart Lake CRB board.
99
100#. When the following output appears, press :kbd:`F7`:
101
102   .. code-block:: console
103
104      Press <DEL> or <ESC> to enter setup.
105
106#. From the menu that appears, select the menu entry that describes
107   that particular EFI shell.
108
109#. From the EFI shell select Zephyr EFI image to boot.
110
111   .. code-block:: console
112
113      Shell> fs0:zephyr.efi
114
115Booting the Elkhart Lake CRB Board over network
116===============================================
117
118Build Zephyr image
119------------------
120
121#. Follow `Build Zephyr application`_ steps to build Zephyr image.
122
123Prepare Linux host
124------------------
125
126#. Install DHCP, TFTP servers. For example ``dnsmasq``
127
128   .. code-block:: console
129
130      $ sudo apt-get install dnsmasq
131
132#. Configure DHCP server. Configuration for ``dnsmasq`` is below:
133
134   .. code-block:: console
135
136      # Only listen to this interface
137      interface=eno2
138      dhcp-range=10.1.1.20,10.1.1.30,12h
139
140#. Configure TFTP server.
141
142   .. code-block:: console
143
144      # tftp
145      enable-tftp
146      tftp-root=/srv/tftp
147      dhcp-boot=zephyr.efi
148
149   ``zephyr.efi`` is a Zephyr EFI binary created above.
150
151#. Copy the Zephyr EFI image :file:`zephyr/zephyr.efi` to the
152   :file:`/srv/tftp` folder.
153
154    .. code-block:: console
155
156       $ cp zephyr/zephyr.efi /srv/tftp/
157
158#. Restart ``dnsmasq`` service:
159
160   .. code-block:: console
161
162      $ sudo systemctl restart dnsmasq.service
163
164Prepare Elkhart Lake CRB board for network boot
165-----------------------------------------------
166
167#. Enable boot from PXE. Go to EFI shell and make sure that the first boot
168   option is ``UEFI PXEv4``.
169
170   .. code-block:: console
171
172      Shell> bcfg boot dump
173      Option: 00. Variable: Boot0007
174        Desc    - UEFI PXEv4 (MAC:6805CABC1997)
175        DevPath - PciRoot(0x0)/Pci(0x1C,0x0)/Pci(0x0,0x0)/MAC(6805CABC1997,0x0)/IPv4(0.0.0.0)
176        Optional- Y
177      ...
178
179#. If UEFI PXEv4 is not the first boot option use ``bcfg boot mv`` command to
180   change boot order
181
182   .. code-block:: console
183
184      Shell> bcfg boot mv 7 0
185
186Booting Elkhart Lake CRB
187------------------------
188
189#. Connect the board to the host system using the serial cable and
190   configure your host system to watch for serial data.
191
192#. Power on the Elkhart Lake CRB board.
193
194#. Verify that the board got an IP address:
195
196   .. code-block:: console
197
198      $ journalctl -f -u dnsmasq
199      dnsmasq-dhcp[5386]: DHCPDISCOVER(eno2) 00:07:32:52:25:88
200      dnsmasq-dhcp[5386]: DHCPOFFER(eno2) 10.1.1.28 00:07:32:52:25:88
201      dnsmasq-dhcp[5386]: DHCPREQUEST(eno2) 10.1.1.28 00:07:32:52:25:88
202      dnsmasq-dhcp[5386]: DHCPACK(eno2) 10.1.1.28 00:07:32:52:25:88
203
204#. Verify that network booting is started:
205
206   .. code-block:: console
207
208      $ journalctl -f -u dnsmasq
209      dnsmasq-tftp[5386]: sent /srv/tftp/zephyr.efi to 10.1.1.28
210
211#. When the boot process completes, you have finished booting the
212   Zephyr application image.
213
214.. _EHL: https://www.intel.com/content/www/us/en/products/docs/processors/embedded/enhanced-for-iot-platform-brief.html
215