diff options
Diffstat (limited to 'README')
-rw-r--r-- | README | 381 |
1 files changed, 299 insertions, 82 deletions
@@ -1,11 +1,62 @@ | |||
1 | meta-intel | 1 | meta-intel |
2 | ========== | 2 | ========== |
3 | 3 | ||
4 | This is the location for Intel maintained BSPs. | 4 | This README file contains information on building and booting |
5 | meta-intel BSP layers. Please see the corresponding sections below | ||
6 | for details. | ||
5 | 7 | ||
6 | Please see the README files contained in the individual BSP layers for | 8 | |
7 | BSP-specific information. For details on the intel-common BSPs, see the | 9 | Yocto Project Compatible |
8 | conf/machine/README file. | 10 | ======================== |
11 | |||
12 | The BSPs contained in this layer are compatible with the Yocto Project | ||
13 | as per the requirements listed here: | ||
14 | |||
15 | https://www.yoctoproject.org/webform/yocto-project-compatible-registration | ||
16 | |||
17 | |||
18 | Dependencies | ||
19 | ============ | ||
20 | |||
21 | This 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 | |||
35 | Table 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 | |||
50 | I. Overview | ||
51 | =========== | ||
52 | |||
53 | This is the location for Intel-maintained BSPs. | ||
54 | |||
55 | For details on the intel-common and intel-quark BSPs, see the | ||
56 | information below. | ||
57 | |||
58 | For all others, please see the README files contained in the | ||
59 | individual BSP layers for BSP-specific information. | ||
9 | 60 | ||
10 | If you have problems with or questions about a particular BSP, please | 61 | If you have problems with or questions about a particular BSP, please |
11 | contact the maintainer listed in the MAINTAINERS file directly (cc:ing | 62 | contact 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 | |||
32 | you're wrong, it's not a big deal and the bug will be recategorized | 83 | you're wrong, it's not a big deal and the bug will be recategorized |
33 | upon triage. | 84 | upon triage. |
34 | 85 | ||
35 | Guidelines for submitting patches | ||
36 | ================================= | ||
37 | 86 | ||
38 | Please submit any patches against meta-intel BSPs to the meta-intel | 87 | II. Building and booting meta-intel BSP layers |
39 | mailing list (meta-intel@yoctoproject.org). Also, if your patches are | 88 | ============================================== |
40 | available via a public git repository, please also include a URL to | ||
41 | the repo and branch containing your patches as that makes it easier | ||
42 | for maintainers to grab and test your patches. | ||
43 | 89 | ||
44 | There are patch submission scripts available that will, among other | 90 | The following sections contain information on building and booting the |
45 | things, automatically include the repo URL and branch as mentioned. | 91 | BSPs contained in the meta-intel layer. |
46 | Please 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 | ||
50 | Regardless of how you submit a patch or patchset, the patches should | 93 | Note that these instructions specifically cover the intel-common and |
51 | at minimum follow the suggestions outlined in the 'How to Submit a | 94 | quark BSPs, which may or may not be applicable to other BSPs contained |
52 | Change' secion in the Yocto Project Development Manual. Specifically, | 95 | in this layer - if a given BSP contains its own README, that version |
53 | they should: | 96 | should 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 | 98 | a. 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 | 101 | In 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 | 102 | need to download the corresponding BSP tarball from the 'Board Support |
60 | appropriate, followed by a colon. Capitalize the first character | 103 | Package (BSP) Downloads' page of the Yocto Project website (or |
61 | of the summary (following the colon). | 104 | equivalently, check out the appropriate branch from the meta-intel git |
105 | repository, see below). For the intel-common and quark BSPs, those | ||
106 | tarballs would correspond to the following choices in the BSP | ||
107 | downloads section: | ||
62 | 108 | ||
63 | - For the body of the commit message, provide detailed information | 109 | - Intel-core2-32 Intel® Common Core BSP (Intel-core2-32) |
64 | that describes what you changed, why you made the change, and the | 110 | - Intel-core2-32 Intel® 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 | 113 | The 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 | 114 | carefully selected tune options and generic hardware support to cover |
69 | detailed description in the following format: [YOCTO #<bug-id>]. | 115 | the majority of current Intel CPUs and devices. The naming follows the |
116 | convention 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 | ||
118 | bit. | ||
70 | 119 | ||
71 | - Pay attention to line length - please don't allow any particular | 120 | Having done that, and assuming you extracted the BSP tarball contents |
72 | line in the commit message to stretch past 72 characters. | 121 | at the top-level of your yocto build tree, you can build a BSP image |
122 | by 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 | ||
78 | Doing a quick 'git log' in meta-intel will provide you with many | 126 | To enable a particular machine, you need to add a MACHINE line naming |
79 | examples of good example commits if you have questions about any | 127 | the BSP to the local.conf file: |
80 | aspect of the preferred format. | ||
81 | 128 | ||
82 | The meta-intel maintainers will do their best to review and/or pull in | 129 | MACHINE ?= "xxx" |
83 | a patch or patchset within 24 hours of the time it was posted. For | ||
84 | larger and/or more involved patches and patchsets, the review process | ||
85 | may take longer. | ||
86 | 130 | ||
131 | where 'xxx' is replaced by one of the following BSP names: | ||
87 | 132 | ||
88 | Intel-specific machine features | 133 | - intel-core2-32 |
89 | =============================== | ||
90 | 134 | ||
91 | The meta-intel layer makes some additional machine features available | 135 | This BSP is optimized for the Core2 family of CPUs as well as all |
92 | to BSPs. These machine features can be used in a BSP layer in the | 136 | Atom CPUs prior to the Silvermont core. |
93 | same way that machine features are used in other layers based on | ||
94 | oe-core, via the MACHINE_FEATURES variable. | ||
95 | 137 | ||
96 | Requirements | 138 | - intel-corei7-64 |
97 | ------------ | ||
98 | 139 | ||
99 | The 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 |
100 | when the meta-intel layer is included in the build configuration, and | 141 | well as Silvermont and later Atom CPUs, such as the Baytrail SoCs. |
101 | the meta-intel.inc file is included in the machine configuration of | ||
102 | that BSP. | ||
103 | 142 | ||
104 | To 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 | ||
111 | Once the above requirements are met, the machine features provided by | 147 | You should then be able to build an image as such: |
112 | the meta-intel layer will be available for the BSP to use. | 148 | |
149 | $ source oe-init-build-env | ||
150 | $ bitbake core-image-sato | ||
151 | |||
152 | At the end of a successful build, you should have a live image that | ||
153 | you can boot from a USB flash drive (see instructions on how to do | ||
154 | that below, in the section 'Booting the intel-common BSP images'). | ||
155 | |||
156 | As an alternative to downloading the BSP tarball, you can also work | ||
157 | directly from the meta-intel git repository. For each BSP in the | ||
158 | 'meta-intel' repository, there are multiple branches, one | ||
159 | corresponding to each major release starting with 'laverne' (0.90), in | ||
160 | addition to the latest code which tracks the current master (note that | ||
161 | not all BSPs are present in every release). Instead of extracting | ||
162 | a BSP tarball at the top level of your yocto build tree, you can | ||
163 | equivalently check out the appropriate branch from the meta-intel | ||
164 | repository at the same location. | ||
165 | |||
166 | b. Booting the intel-common BSP images | ||
167 | -------------------------------------- | ||
168 | |||
169 | If you downloaded the BSP tarball, you will find bootable images in | ||
170 | the /binary directory. If you've built your own image, either from | ||
171 | the downloaded BSP layer or from the meta-intel git repository, you'll | ||
172 | find the bootable image in the build/tmp/deploy/images/xxx directory, | ||
173 | where again 'xxx' refers to the machine name used in the build. | ||
113 | 174 | ||
114 | Building for Intel Quark X1000 microprocessor | 175 | The BSP /binary directory or build contains bootable live images, |
115 | --------------------------------------------- | 176 | which can be used to directly boot Yocto off of a USB flash drive. |
116 | 177 | ||
117 | To target the Intel Quark X1000. | 178 | Under Linux, insert a USB flash drive. Assuming the USB flash drive |
179 | takes device /dev/sdf, use dd to copy the live image to it. For | ||
180 | example: | ||
181 | |||
182 | # dd if=core-image-sato-intel-corei7-64.hddimg of=/dev/sdf | ||
183 | # sync | ||
184 | # eject /dev/sdf | ||
185 | |||
186 | This should give you a bootable USB flash device. Insert the device | ||
187 | into a bootable USB socket on the target, and power on. This should | ||
188 | result in a system booted to the Sato graphical desktop. | ||
189 | |||
190 | If you want a terminal, use the arrows at the top of the UI to move to | ||
191 | different pages of available applications, one of which is named | ||
192 | 'Terminal'. Clicking that should give you a root terminal. | ||
193 | |||
194 | If you want to ssh into the system, you can use the root terminal to | ||
195 | ifconfig the IP address and use that to ssh in. The root password is | ||
196 | empty, so to log in type 'root' for the user name and hit 'Enter' at | ||
197 | the Password prompt: and you should be in. | ||
198 | |||
199 | If you find you're getting corrupt images on the USB (it doesn't show | ||
200 | the syslinux boot: prompt, or the boot: prompt contains strange | ||
201 | characters), 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" | 205 | c. Booting the intel-quark BSP image on a Galileo board |
206 | ------------------------------------------------------- | ||
122 | 207 | ||
123 | 2. Build a target image of your choice. | 208 | If you downloaded the BSP tarball, you will find bootable images in |
209 | the /binary directory. If you've built your own image, either from | ||
210 | the downloaded BSP layer or from the meta-intel git repository, you'll | ||
211 | find the bootable image in the build/tmp/deploy/images/xxx directory, | ||
212 | where again 'xxx' refers to the machine name used in the build. | ||
124 | 213 | ||
125 | $ bitbake core-image-minimal | 214 | The Galileo board boots off of an SD card that has a special disk |
215 | layout. The 'wic' tool can be used to create an SD card adhering to | ||
216 | that format via the following steps. | ||
126 | 217 | ||
127 | 3. For the first time, you need to build parted-native too. (You will get an | 218 | If 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.) | 219 | an 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. | 223 | Use 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 | |
229 | Assuming 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: | 233 | If 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 | 239 | Write 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. | 243 | Insert the SD Card into the reference platform and power on. |
244 | |||
245 | |||
246 | III. Technical Miscellany | ||
247 | ========================= | ||
248 | |||
249 | The intel-common kernel package architecture | ||
250 | -------------------------------------------- | ||
251 | |||
252 | These BSPs use what we call the intel-common Linux kernel package | ||
253 | architecture. This includes core2-32-intel-common and | ||
254 | corei7-64-intel-common. These kernel packages can also be used by any | ||
255 | of the BSPs in meta-intel that choose to include the | ||
256 | intel-common-pkgarch.inc file. | ||
257 | |||
258 | To minimize the proliferation of vendor trees, reduce the sources we | ||
259 | must support, and consolidate QA efforts, all BSP maintainers are | ||
260 | encouraged to make use of the intel-common Linux kernel package | ||
261 | architecture. | ||
262 | |||
263 | Intel-specific machine features | ||
264 | ------------------------------- | ||
265 | |||
266 | The meta-intel layer makes some additional machine features available | ||
267 | to BSPs. These machine features can be used in a BSP layer in the | ||
268 | same way that machine features are used in other layers based on | ||
269 | oe-core, via the MACHINE_FEATURES variable. | ||
270 | |||
271 | Requirements | ||
272 | ++++++++++++ | ||
273 | |||
274 | The meta-intel-specific machine features are only available to a BSP | ||
275 | when the meta-intel layer is included in the build configuration, and | ||
276 | the meta-intel.inc file is included in the machine configuration of | ||
277 | that BSP. | ||
278 | |||
279 | To 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 | |||
286 | Once the above requirements are met, the machine features provided by | ||
287 | the meta-intel layer will be available for the BSP to use. | ||
152 | 288 | ||
153 | Available machine features | 289 | Available machine features |
154 | -------------------------- | 290 | ++++++++++++++++++++++++++ |
155 | 291 | ||
156 | Currently, the meta-intel layer makes the following set of | 292 | Currently, the meta-intel layer makes the following set of |
157 | Intel-specific machine features available: | 293 | Intel-specific machine features available: |
@@ -165,7 +301,7 @@ example: | |||
165 | MACHINE_FEATURES += "intel-ucode" | 301 | MACHINE_FEATURES += "intel-ucode" |
166 | 302 | ||
167 | Machine feature details | 303 | Machine 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 | |||
374 | IV. Tested Hardware | ||
375 | =================== | ||
376 | |||
377 | Of the BSPs currently included in meta-intel, the following have | ||
378 | passed initial testing with the intel-common BSPs: | ||
379 | |||
380 | intel-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 | |||
388 | intel-core2-32: | ||
389 | |||
390 | <currently under test> | ||
391 | |||
392 | If you are interested in a BSP not listed here, chances are we are | ||
393 | currently working on resolving some configuration issues with it. | ||
394 | Please check the bugzilla and check in with us on the meta-intel | ||
395 | mailing list. | ||
396 | |||
397 | |||
398 | V. Guidelines for submitting patches | ||
399 | ==================================== | ||
400 | |||
401 | Please submit any patches against meta-intel BSPs to the meta-intel | ||
402 | mailing list (meta-intel@yoctoproject.org). Also, if your patches are | ||
403 | available via a public git repository, please also include a URL to | ||
404 | the repo and branch containing your patches as that makes it easier | ||
405 | for maintainers to grab and test your patches. | ||
406 | |||
407 | There are patch submission scripts available that will, among other | ||
408 | things, automatically include the repo URL and branch as mentioned. | ||
409 | Please 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 | |||
413 | Regardless of how you submit a patch or patchset, the patches should | ||
414 | at minimum follow the suggestions outlined in the 'How to Submit a | ||
415 | Change' secion in the Yocto Project Development Manual. Specifically, | ||
416 | they 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 | |||
441 | Doing a quick 'git log' in meta-intel will provide you with many | ||
442 | examples of good example commits if you have questions about any | ||
443 | aspect of the preferred format. | ||
444 | |||
445 | The meta-intel maintainers will do their best to review and/or pull in | ||
446 | a patch or patchset within 24 hours of the time it was posted. For | ||
447 | larger and/or more involved patches and patchsets, the review process | ||
448 | may take longer. | ||
449 | |||
450 | Please see the meta-intel/MAINTAINERS file for the list of maintainers | ||
451 | and their specific areas; it's also a good idea to cc: the specific | ||
452 | maintainer, if applicable. | ||