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