summaryrefslogtreecommitdiffstats
path: root/README
diff options
context:
space:
mode:
authorTom Zanussi <tom.zanussi@linux.intel.com>2016-04-29 00:10:43 (GMT)
committerSaul Wold <sgw@linux.intel.com>2016-04-29 14:15:27 (GMT)
commit70a1429dfecfea1c22613e736e9bd7fe342dc14a (patch)
tree9b767a3aeee61f8e698c4e456e802eeb2f7fb402 /README
parentd9727db3e7957d4842e4afeeeaa6420d5d2cfa7d (diff)
downloadmeta-intel-70a1429dfecfea1c22613e736e9bd7fe342dc14a.tar.gz
README: Add build and boot instructions and restructure
The intel-common README in conf/machine/README doesn't describe how to build an intel-common BSP, and with the removal of the machine-specific BSPs, there's no longer any instructions at all for a user to learn how to build and boot a meta-intel BSP. This commit generalizes and adds those instructions back but this time to the top-level README, which is also cleaned up and given a table of contents to make it more useful. It also moves the content from conf/machine/README to the top-level README; conf/machine/README will be removed in another patch. Signed-off-by: Tom Zanussi <tom.zanussi@linux.intel.com> Signed-off-by: Saul Wold <sgw@linux.intel.com>
Diffstat (limited to 'README')
-rw-r--r--README381
1 files changed, 299 insertions, 82 deletions
diff --git a/README b/README
index 63960c2..d2098a9 100644
--- a/README
+++ b/README
@@ -1,11 +1,62 @@
1meta-intel 1meta-intel
2========== 2==========
3 3
4This is the location for Intel maintained BSPs. 4This README file contains information on building and booting
5meta-intel BSP layers. Please see the corresponding sections below
6for details.
5 7
6Please see the README files contained in the individual BSP layers for 8
7BSP-specific information. For details on the intel-common BSPs, see the 9Yocto Project Compatible
8conf/machine/README file. 10========================
11
12The BSPs contained in this layer are compatible with the Yocto Project
13as per the requirements listed here:
14
15 https://www.yoctoproject.org/webform/yocto-project-compatible-registration
16
17
18Dependencies
19============
20
21This layer depends on:
22
23 URI: git://git.openembedded.org/bitbake
24 branch: master
25
26 URI: git://git.openembedded.org/openembedded-core
27 layers: meta
28 branch: master
29
30 URI: git://git.yoctoproject.org/meta-intel
31 layers: intel
32 branch: master
33
34
35Table of Contents
36=================
37
38 I. Overview
39 II. Building and booting meta-intel BSP layers
40 a. Building the intel-common and quark BSP layers
41 b. Booting the intel-common BSP images
42 c. Booting the intel-quark BSP image on a Galileo board
43 III. Technical Miscellany
44 The intel-common kernel package architecture
45 Intel-specific machine features
46 IV. Tested Hardware
47 V. Guidelines for submitting patches
48
49
50I. Overview
51===========
52
53This is the location for Intel-maintained BSPs.
54
55For details on the intel-common and intel-quark BSPs, see the
56information below.
57
58For all others, please see the README files contained in the
59individual BSP layers for BSP-specific information.
9 60
10If you have problems with or questions about a particular BSP, please 61If you have problems with or questions about a particular BSP, please
11contact the maintainer listed in the MAINTAINERS file directly (cc:ing 62contact the maintainer listed in the MAINTAINERS file directly (cc:ing
@@ -32,126 +83,211 @@ submit the bug against the most likely category for the problem - if
32you're wrong, it's not a big deal and the bug will be recategorized 83you're wrong, it's not a big deal and the bug will be recategorized
33upon triage. 84upon triage.
34 85
35Guidelines for submitting patches
36=================================
37 86
38Please submit any patches against meta-intel BSPs to the meta-intel 87II. Building and booting meta-intel BSP layers
39mailing list (meta-intel@yoctoproject.org). Also, if your patches are 88==============================================
40available via a public git repository, please also include a URL to
41the repo and branch containing your patches as that makes it easier
42for maintainers to grab and test your patches.
43 89
44There are patch submission scripts available that will, among other 90The following sections contain information on building and booting the
45things, automatically include the repo URL and branch as mentioned. 91BSPs contained in the meta-intel layer.
46Please see the Yocto Project Development Manual sections entitled
47'Using Scripts to Push a Change Upstream and Request a Pull' and
48'Using Email to Submit a Patch' for details.
49 92
50Regardless of how you submit a patch or patchset, the patches should 93Note that these instructions specifically cover the intel-common and
51at minimum follow the suggestions outlined in the 'How to Submit a 94quark BSPs, which may or may not be applicable to other BSPs contained
52Change' secion in the Yocto Project Development Manual. Specifically, 95in this layer - if a given BSP contains its own README, that version
53they should: 96should be used instead, and these instructions can be ignored.
54 97
55 - Include a 'Signed-off-by:' line. A commit can't legally be pulled 98a. Building the intel-common and quark BSP layers
56 in without this. 99-------------------------------------------------
57 100
58 - Provide a single-line, short summary of the change. This short 101In order to build an image with BSP support for a given release, you
59 description should be prefixed by the BSP or recipe name, as 102need to download the corresponding BSP tarball from the 'Board Support
60 appropriate, followed by a colon. Capitalize the first character 103Package (BSP) Downloads' page of the Yocto Project website (or
61 of the summary (following the colon). 104equivalently, check out the appropriate branch from the meta-intel git
105repository, see below). For the intel-common and quark BSPs, those
106tarballs would correspond to the following choices in the BSP
107downloads section:
62 108
63 - For the body of the commit message, provide detailed information 109 - Intel-core2-32 Inte Common Core BSP (Intel-core2-32)
64 that describes what you changed, why you made the change, and the 110 - Intel-core2-32 Inte Common Core BSP (Intel-quark)
65 approach you used. 111 - Intel-corei7-64 Intel® Common Core BSP (Intel-corei7-64)
66 112
67 - If the change addresses a specific bug or issue that is associated 113The intel-* BSPs, also known as the intel-common BSPs, provide a few
68 with a bug-tracking ID, include a reference to that ID in your 114carefully selected tune options and generic hardware support to cover
69 detailed description in the following format: [YOCTO #<bug-id>]. 115the majority of current Intel CPUs and devices. The naming follows the
116convention of intel-<TUNE>-<BITS>, where TUNE is the gcc cpu-type
117(used with mtune and march typically) and BITS is either 32 bit or 64
118bit.
70 119
71 - Pay attention to line length - please don't allow any particular 120Having done that, and assuming you extracted the BSP tarball contents
72 line in the commit message to stretch past 72 characters. 121at the top-level of your yocto build tree, you can build a BSP image
122by adding the location of the meta-intel layer to bblayers.conf e.g.:
73 123
74 - For any non-trivial patch, provide information about how you 124 yocto/meta-intel \
75 tested the patch, and for any non-trivial or non-obvious testing
76 setup, provide details of that setup.
77 125
78Doing a quick 'git log' in meta-intel will provide you with many 126To enable a particular machine, you need to add a MACHINE line naming
79examples of good example commits if you have questions about any 127the BSP to the local.conf file:
80aspect of the preferred format.
81 128
82The meta-intel maintainers will do their best to review and/or pull in 129 MACHINE ?= "xxx"
83a patch or patchset within 24 hours of the time it was posted. For
84larger and/or more involved patches and patchsets, the review process
85may take longer.
86 130
131where 'xxx' is replaced by one of the following BSP names:
87 132
88Intel-specific machine features 133 - intel-core2-32
89===============================
90 134
91The meta-intel layer makes some additional machine features available 135 This BSP is optimized for the Core2 family of CPUs as well as all
92to BSPs. These machine features can be used in a BSP layer in the 136 Atom CPUs prior to the Silvermont core.
93same way that machine features are used in other layers based on
94oe-core, via the MACHINE_FEATURES variable.
95 137
96Requirements 138 - intel-corei7-64
97------------
98 139
99The meta-intel-specific machine features are only available to a BSP 140 This BSP is optimized for Nehalem and later Core and Xeon CPUs as
100when the meta-intel layer is included in the build configuration, and 141 well as Silvermont and later Atom CPUs, such as the Baytrail SoCs.
101the meta-intel.inc file is included in the machine configuration of
102that BSP.
103 142
104To make these features available for your machine, you will need to: 143 - intel-quark
105 144
106 1. include a configuration line such as the below in bblayers.conf 145 This BSP is optimized for Quark-based systems.
107 BBLAYERS += "<local path>/meta-intel"
108 2. include the following line in the machine configuration file
109 require conf/machine/include/meta-intel.inc
110 146
111Once the above requirements are met, the machine features provided by 147You should then be able to build an image as such:
112the meta-intel layer will be available for the BSP to use. 148
149 $ source oe-init-build-env
150 $ bitbake core-image-sato
151
152At the end of a successful build, you should have a live image that
153you can boot from a USB flash drive (see instructions on how to do
154that below, in the section 'Booting the intel-common BSP images').
155
156As an alternative to downloading the BSP tarball, you can also work
157directly from the meta-intel git repository. For each BSP in the
158'meta-intel' repository, there are multiple branches, one
159corresponding to each major release starting with 'laverne' (0.90), in
160addition to the latest code which tracks the current master (note that
161not all BSPs are present in every release). Instead of extracting
162a BSP tarball at the top level of your yocto build tree, you can
163equivalently check out the appropriate branch from the meta-intel
164repository at the same location.
165
166b. Booting the intel-common BSP images
167--------------------------------------
168
169If you downloaded the BSP tarball, you will find bootable images in
170the /binary directory. If you've built your own image, either from
171the downloaded BSP layer or from the meta-intel git repository, you'll
172find the bootable image in the build/tmp/deploy/images/xxx directory,
173where again 'xxx' refers to the machine name used in the build.
113 174
114Building for Intel Quark X1000 microprocessor 175The BSP /binary directory or build contains bootable live images,
115--------------------------------------------- 176which can be used to directly boot Yocto off of a USB flash drive.
116 177
117To target the Intel Quark X1000. 178Under Linux, insert a USB flash drive. Assuming the USB flash drive
179takes device /dev/sdf, use dd to copy the live image to it. For
180example:
181
182# dd if=core-image-sato-intel-corei7-64.hddimg of=/dev/sdf
183# sync
184# eject /dev/sdf
185
186This should give you a bootable USB flash device. Insert the device
187into a bootable USB socket on the target, and power on. This should
188result in a system booted to the Sato graphical desktop.
189
190If you want a terminal, use the arrows at the top of the UI to move to
191different pages of available applications, one of which is named
192'Terminal'. Clicking that should give you a root terminal.
193
194If you want to ssh into the system, you can use the root terminal to
195ifconfig the IP address and use that to ssh in. The root password is
196empty, so to log in type 'root' for the user name and hit 'Enter' at
197the Password prompt: and you should be in.
198
199If you find you're getting corrupt images on the USB (it doesn't show
200the syslinux boot: prompt, or the boot: prompt contains strange
201characters), try doing this first:
118 202
119 1. In conf/local.conf set the MACHINE type to be intel-quark. 203# dd if=/dev/zero of=/dev/sdf bs=1M count=512
120 204
121 MACHINE ??= "intel-quark" 205c. Booting the intel-quark BSP image on a Galileo board
206-------------------------------------------------------
122 207
123 2. Build a target image of your choice. 208If you downloaded the BSP tarball, you will find bootable images in
209the /binary directory. If you've built your own image, either from
210the downloaded BSP layer or from the meta-intel git repository, you'll
211find the bootable image in the build/tmp/deploy/images/xxx directory,
212where again 'xxx' refers to the machine name used in the build.
124 213
125 $ bitbake core-image-minimal 214The Galileo board boots off of an SD card that has a special disk
215layout. The 'wic' tool can be used to create an SD card adhering to
216that format via the following steps.
126 217
127 3. For the first time, you need to build parted-native too. (You will get an 218If you haven't already, you need to build parted-native. (You will get
128 error message when running wic script without it at later steps.) 219an error message when running the wic script if you haven't.)
129 220
130 $ bitbake parted-native 221 $ bitbake parted-native
131 222
132 4. Use the provided wic script to create an SD card image. 223Use the wic script to create an SD card image:
133 224
134 $ wic list images 225 $ wic list images
135 mkgalileodisk Create an Galileo Gen 1/2 disk image 226 mkgalileodisk Create an Galileo Gen 1/2 disk image
136 mkgummidisk Create an EFI disk image 227 mkgummidisk Create an EFI disk image
137 ... 228
229Assuming you want to boot the 'core-image-minimal' image:
138 230
139 $ wic create mkgalileodisk -e core-image-minimal 231 $ wic create mkgalileodisk -e core-image-minimal
140 232
141 wic script outputs the image and its location in success, something like: 233If successful, the wic script generates the image and prints its location:
142 ... 234
143 Info: The new image(s) can be found here: 235 Info: The new image(s) can be found here:
144 /var/tmp/wic/build/mkgalileodisk-201604211444-mmcblk0.direct 236 /var/tmp/wic/build/mkgalileodisk-201604211444-mmcblk0.direct
145 ... 237 ...
146 238
147 5. Write the output image to an SD Card 239Write the output image to an SD Card
148 240
149 $ sudo dd if=/path/to/image/mkgalileodisk-*-mmcblk0.direct of=/dev/your_sd_dev 241 $ sudo dd if=/path/to/image/mkgalileodisk-*-mmcblk0.direct of=/dev/your_sd_dev
150 242
151 6. Insert the SD Card into the reference platform and power on. 243Insert the SD Card into the reference platform and power on.
244
245
246III. Technical Miscellany
247=========================
248
249The intel-common kernel package architecture
250--------------------------------------------
251
252These BSPs use what we call the intel-common Linux kernel package
253architecture. This includes core2-32-intel-common and
254corei7-64-intel-common. These kernel packages can also be used by any
255of the BSPs in meta-intel that choose to include the
256intel-common-pkgarch.inc file.
257
258To minimize the proliferation of vendor trees, reduce the sources we
259must support, and consolidate QA efforts, all BSP maintainers are
260encouraged to make use of the intel-common Linux kernel package
261architecture.
262
263Intel-specific machine features
264-------------------------------
265
266The meta-intel layer makes some additional machine features available
267to BSPs. These machine features can be used in a BSP layer in the
268same way that machine features are used in other layers based on
269oe-core, via the MACHINE_FEATURES variable.
270
271Requirements
272++++++++++++
273
274The meta-intel-specific machine features are only available to a BSP
275when the meta-intel layer is included in the build configuration, and
276the meta-intel.inc file is included in the machine configuration of
277that BSP.
278
279To make these features available for your machine, you will need to:
280
281 1. include a configuration line such as the below in bblayers.conf
282 BBLAYERS += "<local path>/meta-intel"
283 2. include the following line in the machine configuration file
284 require conf/machine/include/meta-intel.inc
285
286Once the above requirements are met, the machine features provided by
287the meta-intel layer will be available for the BSP to use.
152 288
153Available machine features 289Available machine features
154-------------------------- 290++++++++++++++++++++++++++
155 291
156Currently, the meta-intel layer makes the following set of 292Currently, the meta-intel layer makes the following set of
157Intel-specific machine features available: 293Intel-specific machine features available:
@@ -165,7 +301,7 @@ example:
165 MACHINE_FEATURES += "intel-ucode" 301 MACHINE_FEATURES += "intel-ucode"
166 302
167Machine feature details 303Machine feature details
168----------------------- 304+++++++++++++++++++++++
169 305
170 * intel-ucode 306 * intel-ucode
171 307
@@ -233,3 +369,84 @@ Machine feature details
233 highly sensitive to target image size and which are not 369 highly sensitive to target image size and which are not
234 experiencing microcode-related issues might consider not 370 experiencing microcode-related issues might consider not
235 enabling this feature. 371 enabling this feature.
372
373
374IV. Tested Hardware
375===================
376
377Of the BSPs currently included in meta-intel, the following have
378passed initial testing with the intel-common BSPs:
379
380intel-corei7-64:
381
382 crystalforest-server
383 crystalforest-gladden
384 haswell-wc
385 nuc (Ivy Bridge and Haswell, manual audio config required)
386 sugarbay
387
388intel-core2-32:
389
390 <currently under test>
391
392If you are interested in a BSP not listed here, chances are we are
393currently working on resolving some configuration issues with it.
394Please check the bugzilla and check in with us on the meta-intel
395mailing list.
396
397
398V. Guidelines for submitting patches
399====================================
400
401Please submit any patches against meta-intel BSPs to the meta-intel
402mailing list (meta-intel@yoctoproject.org). Also, if your patches are
403available via a public git repository, please also include a URL to
404the repo and branch containing your patches as that makes it easier
405for maintainers to grab and test your patches.
406
407There are patch submission scripts available that will, among other
408things, automatically include the repo URL and branch as mentioned.
409Please see the Yocto Project Development Manual sections entitled
410'Using Scripts to Push a Change Upstream and Request a Pull' and
411'Using Email to Submit a Patch' for details.
412
413Regardless of how you submit a patch or patchset, the patches should
414at minimum follow the suggestions outlined in the 'How to Submit a
415Change' secion in the Yocto Project Development Manual. Specifically,
416they should:
417
418 - Include a 'Signed-off-by:' line. A commit can't legally be pulled
419 in without this.
420
421 - Provide a single-line, short summary of the change. This short
422 description should be prefixed by the BSP or recipe name, as
423 appropriate, followed by a colon. Capitalize the first character
424 of the summary (following the colon).
425
426 - For the body of the commit message, provide detailed information
427 that describes what you changed, why you made the change, and the
428 approach you used.
429
430 - If the change addresses a specific bug or issue that is associated
431 with a bug-tracking ID, include a reference to that ID in your
432 detailed description in the following format: [YOCTO #<bug-id>].
433
434 - Pay attention to line length - please don't allow any particular
435 line in the commit message to stretch past 72 characters.
436
437 - For any non-trivial patch, provide information about how you
438 tested the patch, and for any non-trivial or non-obvious testing
439 setup, provide details of that setup.
440
441Doing a quick 'git log' in meta-intel will provide you with many
442examples of good example commits if you have questions about any
443aspect of the preferred format.
444
445The meta-intel maintainers will do their best to review and/or pull in
446a patch or patchset within 24 hours of the time it was posted. For
447larger and/or more involved patches and patchsets, the review process
448may take longer.
449
450Please see the meta-intel/MAINTAINERS file for the list of maintainers
451and their specific areas; it's also a good idea to cc: the specific
452maintainer, if applicable.