blob: 84c5afa909d05a94eff8beab8b2192b14a614424 [file] [log] [blame]
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001 Yocto Project Hardware Reference BSPs README
2 ============================================
3
4This file gives details about using the Yocto Project hardware reference BSPs.
5The machines supported can be seen in the conf/machine/ directory and are listed
6below. There is one per supported hardware architecture and these are primarily
7used to validate that the Yocto Project works on the hardware arctectures of
8those machines.
9
10If you are in doubt about using Poky/OpenEmbedded/Yocto Project with your hardware,
11consult the documentation for your board/device.
12
13Support for additional devices is normally added by adding BSP layers to your
14configuration. For more information please see the Yocto Board Support Package
15(BSP) Developer's Guide - documentation source is in documentation/bspguide or
16download the PDF from:
17
18 http://yoctoproject.org/documentation
19
20Note that these reference BSPs use the linux-yocto kernel and in general don't
21pull in binary module support for the platforms. This means some device functionality
22may be limited compared to a 'full' BSP which may be available.
23
24
25Hardware Reference Boards
26=========================
27
28The following boards are supported by the meta-yocto-bsp layer:
29
30 * Texas Instruments Beaglebone (beaglebone)
31 * Freescale MPC8315E-RDB (mpc8315e-rdb)
32 * Ubiquiti Networks EdgeRouter Lite (edgerouter)
33 * General IA platforms (genericx86 and genericx86-64)
34
35For more information see the board's section below. The appropriate MACHINE
36variable value corresponding to the board is given in brackets.
37
38Reference Board Maintenance
39===========================
40
41Send pull requests, patches, comments or questions about meta-yocto-bsps to poky@yoctoproject.org
42
43Maintainers: Kevin Hao <kexin.hao@windriver.com>
44 Bruce Ashfield <bruce.ashfield@windriver.com>
45
46Consumer Devices
47================
48
49The following consumer devices are supported by the meta-yocto-bsp layer:
50
51 * Intel x86 based PCs and devices (genericx86)
52 * Ubiquiti Networks EdgeRouter Lite (edgerouter)
53
54For more information see the device's section below. The appropriate MACHINE
55variable value corresponding to the device is given in brackets.
56
57
58
59 Specific Hardware Documentation
60 ===============================
61
62
63Intel x86 based PCs and devices (genericx86*)
64=============================================
65
66The genericx86 and genericx86-64 MACHINE are tested on the following platforms:
67
68Intel Xeon/Core i-Series:
69 + Intel NUC5 Series - ix-52xx Series SOC (Broadwell)
70 + Intel NUC6 Series - ix-62xx Series SOC (Skylake)
71 + Intel Shumway Xeon Server
72
73Intel Atom platforms:
74 + MinnowBoard MAX - E3825 SOC (Bay Trail)
75 + MinnowBoard MAX - Turbot (ADI Engineering) - E3826 SOC (Bay Trail)
76 - These boards can be either 32bot or 64bit modes depending on firmware
77 - See minnowboard.org for details
78 + Intel Braswell SOC
79
80and is likely to work on many unlisted Atom/Core/Xeon based devices. The MACHINE
81type supports ethernet, wifi, sound, and Intel/vesa graphics by default in
82addition to common PC input devices, busses, and so on.
83
84Depending on the device, it can boot from a traditional hard-disk, a USB device,
85or over the network. Writing generated images to physical media is
86straightforward with a caveat for USB devices. The following examples assume the
87target boot device is /dev/sdb, be sure to verify this and use the correct
88device as the following commands are run as root and are not reversable.
89
90USB Device:
91 1. Build a live image. This image type consists of a simple filesystem
92 without a partition table, which is suitable for USB keys, and with the
93 default setup for the genericx86 machine, this image type is built
94 automatically for any image you build. For example:
95
96 $ bitbake core-image-minimal
97
98 2. Use the "dd" utility to write the image to the raw block device. For
99 example:
100
101 # dd if=core-image-minimal-genericx86.hddimg of=/dev/sdb
102
103 If the device fails to boot with "Boot error" displayed, or apparently
104 stops just after the SYSLINUX version banner, it is likely the BIOS cannot
105 understand the physical layout of the disk (or rather it expects a
106 particular layout and cannot handle anything else). There are two possible
107 solutions to this problem:
108
109 1. Change the BIOS USB Device setting to HDD mode. The label will vary by
110 device, but the idea is to force BIOS to read the Cylinder/Head/Sector
111 geometry from the device.
112
113 2. Use a ".wic" image with an EFI partition
114
115 a) With a default grub-efi bootloader:
116 # dd if=core-image-minimal-genericx86-64.wic of=/dev/sdb
117
118 b) Use systemd-boot instead
119 - Build an image with EFI_PROVIDER="systemd-boot" then use the above
120 dd command to write the image to a USB stick.
121
122
123Texas Instruments Beaglebone (beaglebone)
124=========================================
125
126The Beaglebone is an ARM Cortex-A8 development board with USB, Ethernet, 2D/3D
127accelerated graphics, audio, serial, JTAG, and SD/MMC. The Black adds a faster
128CPU, more RAM, eMMC flash and a micro HDMI port. The beaglebone MACHINE is
129tested on the following platforms:
130
131 o Beaglebone Black A6
132 o Beaglebone A6 (the original "White" model)
133
134The Beaglebone Black has eMMC, while the White does not. Pressing the USER/BOOT
135button when powering on will temporarily change the boot order. But for the sake
136of simplicity, these instructions assume you have erased the eMMC on the Black,
137so its boot behavior matches that of the White and boots off of SD card. To do
138this, issue the following commands from the u-boot prompt:
139
140 # mmc dev 1
141 # mmc erase 0 512
142
143To further tailor these instructions for your board, please refer to the
144documentation at http://www.beagleboard.org/bone and http://www.beagleboard.org/black
145
146From a Linux system with access to the image files perform the following steps:
147
148 1. Build an image. For example:
149
150 $ bitbake core-image-minimal
151
152 2. Use the "dd" utility to write the image to the SD card. For example:
153
154 # dd core-image-minimal-beaglebone.wic of=/dev/sdb
155
156 3. Insert the SD card into the Beaglebone and boot the board.
157
158Freescale MPC8315E-RDB (mpc8315e-rdb)
159=====================================
160
161The MPC8315 PowerPC reference platform (MPC8315E-RDB) is aimed at hardware and
162software development of network attached storage (NAS) and digital media server
163applications. The MPC8315E-RDB features the PowerQUICC II Pro processor, which
164includes a built-in security accelerator.
165
166(Note: you may find it easier to order MPC8315E-RDBA; this appears to be the
167same board in an enclosure with accessories. In any case it is fully
168compatible with the instructions given here.)
169
170Setup instructions
171------------------
172
173You will need the following:
174* NFS root setup on your workstation
175* TFTP server installed on your workstation
176* Straight-thru 9-conductor serial cable (DB9, M/F) connected from your
177 PC to UART1
178* Ethernet connected to the first ethernet port on the board
179
180--- Preparation ---
181
182Note: if you have altered your board's ethernet MAC address(es) from the
183defaults, or you need to do so because you want multiple boards on the same
184network, then you will need to change the values in the dts file (patch
185linux/arch/powerpc/boot/dts/mpc8315erdb.dts within the kernel source). If
186you have left them at the factory default then you shouldn't need to do
187anything here.
188
189Note: To boot from USB disk you need u-boot that supports 'ext2load usb'
190command. You need to setup TFTP server, load u-boot from there and
191flash it to NOR flash.
192
193Beware! Flashing bootloader is potentially dangerous operation that can
194brick your device if done incorrectly. Please, make sure you understand
195what below commands mean before executing them.
196
197Load the new u-boot.bin from TFTP server to memory address 200000
198=> tftp 200000 u-boot.bin
199
200Disable flash protection
201=> protect off all
202
203Erase the old u-boot from fe000000 to fe06ffff in NOR flash.
204The size is 0x70000 (458752 bytes)
205=> erase fe000000 fe06ffff
206
207Copy the new u-boot from address 200000 to fe000000
208the size is 0x70000. It has to be greater or equal to u-boot.bin size
209=> cp.b 200000 fe000000 70000
210
211Enable flash protection again
212=> protect on all
213
214Reset the board
215=> reset
216
217--- Booting from USB disk ---
218
219 1. Flash partitioned image to the USB disk
220
221 # dd if=core-image-minimal-mpc8315e-rdb.wic of=/dev/sdb
222
223 2. Plug USB disk into the MPC8315 board
224
225 3. Connect the board's first serial port to your workstation and then start up
226 your favourite serial terminal so that you will be able to interact with
227 the serial console. If you don't have a favourite, picocom is suggested:
228
229 $ picocom /dev/ttyUSB0 -b 115200
230
231 4. Power up or reset the board and press a key on the terminal when prompted
232 to get to the U-Boot command line
233
234 5. Optional. Load the u-boot.bin from the USB disk:
235
236 => usb start
237 => ext2load usb 0:1 200000 u-boot.bin
238
239 and flash it to NOR flash as described above.
240
241 6. Load the kernel and dtb from the first partition of the USB disk:
242
243 => usb start
244 => ext2load usb 0:1 1000000 uImage
245 => ext2load usb 0:1 2000000 dtb
246
247 7. Set bootargs and boot up the device
248
249 => setenv bootargs root=/dev/sdb2 rw rootwait console=ttyS0,115200
250 => bootm 1000000 - 2000000
251
252
253--- Booting from NFS root ---
254
255Load the kernel and dtb (device tree blob), and boot the system as follows:
256
257 1. Get the kernel (uImage-mpc8315e-rdb.bin) and dtb (uImage-mpc8315e-rdb.dtb)
258 files from the tmp/deploy directory, and make them available on your TFTP
259 server.
260
261 2. Connect the board's first serial port to your workstation and then start up
262 your favourite serial terminal so that you will be able to interact with
263 the serial console. If you don't have a favourite, picocom is suggested:
264
265 $ picocom /dev/ttyUSB0 -b 115200
266
267 3. Power up or reset the board and press a key on the terminal when prompted
268 to get to the U-Boot command line
269
270 4. Set up the environment in U-Boot:
271
272 => setenv ipaddr <board ip>
273 => setenv serverip <tftp server ip>
274 => setenv bootargs root=/dev/nfs rw nfsroot=<nfsroot ip>:<rootfs path> ip=<board ip>:<server ip>:<gateway ip>:255.255.255.0:mpc8315e:eth0:off console=ttyS0,115200
275
276 5. Download the kernel and dtb, and boot:
277
278 => tftp 1000000 uImage-mpc8315e-rdb.bin
279 => tftp 2000000 uImage-mpc8315e-rdb.dtb
280 => bootm 1000000 - 2000000
281
282--- Booting from JFFS2 root ---
283
284 1. First boot the board with NFS root.
285
286 2. Erase the MTD partition which will be used as root:
287
288 $ flash_eraseall /dev/mtd3
289
290 3. Copy the JFFS2 image to the MTD partition:
291
292 $ flashcp core-image-minimal-mpc8315e-rdb.jffs2 /dev/mtd3
293
294 4. Then reboot the board and set up the environment in U-Boot:
295
296 => setenv bootargs root=/dev/mtdblock3 rootfstype=jffs2 console=ttyS0,115200
297
298
299Ubiquiti Networks EdgeRouter Lite (edgerouter)
300==============================================
301
302The EdgeRouter Lite is part of the EdgeMax series. It is a MIPS64 router
303(based on the Cavium Octeon processor) with 512MB of RAM, which uses an
304internal USB pendrive for storage.
305
306Setup instructions
307------------------
308
309You will need the following:
310* RJ45 -> serial ("rollover") cable connected from your PC to the CONSOLE
311 port on the device
312* Ethernet connected to the first ethernet port on the board
313
314If using NFS as part of the setup process, you will also need:
315* NFS root setup on your workstation
316* TFTP server installed on your workstation (if fetching the kernel from
317 TFTP, see below).
318
319--- Preparation ---
320
321Build an image (e.g. core-image-minimal) using "edgerouter" as the MACHINE.
322In the following instruction it is based on core-image-minimal. Another target
323may be similiar with it.
324
325--- Booting from NFS root / kernel via TFTP ---
326
327Load the kernel, and boot the system as follows:
328
329 1. Get the kernel (vmlinux) file from the tmp/deploy/images/edgerouter
330 directory, and make them available on your TFTP server.
331
332 2. Connect the board's first serial port to your workstation and then start up
333 your favourite serial terminal so that you will be able to interact with
334 the serial console. If you don't have a favourite, picocom is suggested:
335
336 $ picocom /dev/ttyS0 -b 115200
337
338 3. Power up or reset the board and press a key on the terminal when prompted
339 to get to the U-Boot command line
340
341 4. Set up the environment in U-Boot:
342
343 => setenv ipaddr <board ip>
344 => setenv serverip <tftp server ip>
345
346 5. Download the kernel and boot:
347
348 => tftp tftp $loadaddr vmlinux
349 => bootoctlinux $loadaddr coremask=0x3 root=/dev/nfs rw nfsroot=<nfsroot ip>:<rootfs path> ip=<board ip>:<server ip>:<gateway ip>:<netmask>:edgerouter:eth0:off mtdparts=phys_mapped_flash:512k(boot0),512k(boot1),64k@3072k(eeprom)
350
351--- Booting from USB disk ---
352
353To boot from the USB disk, you either need to remove it from the edgerouter
354box and populate it from another computer, or use a previously booted NFS
355image and populate from the edgerouter itself.
356
357Type 1: Use partitioned image
358-----------------------------
359
360Steps:
361
362 1. Remove the USB disk from the edgerouter and insert it into a computer
363 that has access to your build artifacts.
364
365 2. Flash the image.
366
367 # dd if=core-image-minimal-edgerouter.wic of=/dev/sdb
368
369 3. Insert USB disk into the edgerouter and boot it.
370
371Type 2: NFS
372-----------
373
374Note: If you place the kernel on the ext3 partition, you must re-create the
375 ext3 filesystem, since the factory u-boot can only handle 128 byte inodes and
376 cannot read the partition otherwise.
377
378 These boot instructions assume that you have recreated the ext3 filesystem with
379 128 byte inodes, you have an updated uboot or you are running and image capable
380 of making the filesystem on the board itself.
381
382
383 1. Boot from NFS root
384
385 2. Mount the USB disk partition 2 and then extract the contents of
386 tmp/deploy/core-image-XXXX.tar.bz2 into it.
387
388 Before starting, copy core-image-minimal-xxx.tar.bz2 and vmlinux into
389 rootfs path on your workstation.
390
391 and then,
392
393 # mount /dev/sda2 /media/sda2
394 # tar -xvjpf core-image-minimal-XXX.tar.bz2 -C /media/sda2
395 # cp vmlinux /media/sda2/boot/vmlinux
396 # umount /media/sda2
397 # reboot
398
399 3. Reboot the board and press a key on the terminal when prompted to get to the U-Boot
400 command line:
401
402 # reboot
403
404 4. Load the kernel and boot:
405
406 => ext2load usb 0:2 $loadaddr boot/vmlinux
407 => bootoctlinux $loadaddr coremask=0x3 root=/dev/sda2 rw rootwait mtdparts=phys_mapped_flash:512k(boot0),512k(boot1),64k@3072k(eeprom)