diff options
| -rw-r--r-- | README | 381 |
1 files changed, 299 insertions, 82 deletions
@@ -1,11 +1,62 @@ meta-intel ========== -This is the location for Intel maintained BSPs. +This README file contains information on building and booting +meta-intel BSP layers. Please see the corresponding sections below +for details. -Please see the README files contained in the individual BSP layers for -BSP-specific information. For details on the intel-common BSPs, see the -conf/machine/README file. + +Yocto Project Compatible +======================== + +The BSPs contained in this layer are compatible with the Yocto Project +as per the requirements listed here: + + https://www.yoctoproject.org/webform/yocto-project-compatible-registration + + +Dependencies +============ + +This layer depends on: + + URI: git://git.openembedded.org/bitbake + branch: master + + URI: git://git.openembedded.org/openembedded-core + layers: meta + branch: master + + URI: git://git.yoctoproject.org/meta-intel + layers: intel + branch: master + + +Table of Contents +================= + + I. Overview + II. Building and booting meta-intel BSP layers + a. Building the intel-common and quark BSP layers + b. Booting the intel-common BSP images + c. Booting the intel-quark BSP image on a Galileo board + III. Technical Miscellany + The intel-common kernel package architecture + Intel-specific machine features + IV. Tested Hardware + V. Guidelines for submitting patches + + +I. Overview +=========== + +This is the location for Intel-maintained BSPs. + +For details on the intel-common and intel-quark BSPs, see the +information below. + +For all others, please see the README files contained in the +individual BSP layers for BSP-specific information. If you have problems with or questions about a particular BSP, please 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 you're wrong, it's not a big deal and the bug will be recategorized upon triage. -Guidelines for submitting patches -================================= -Please submit any patches against meta-intel BSPs to the meta-intel -mailing list (meta-intel@yoctoproject.org). Also, if your patches are -available via a public git repository, please also include a URL to -the repo and branch containing your patches as that makes it easier -for maintainers to grab and test your patches. +II. Building and booting meta-intel BSP layers +============================================== -There are patch submission scripts available that will, among other -things, automatically include the repo URL and branch as mentioned. -Please see the Yocto Project Development Manual sections entitled -'Using Scripts to Push a Change Upstream and Request a Pull' and -'Using Email to Submit a Patch' for details. +The following sections contain information on building and booting the +BSPs contained in the meta-intel layer. -Regardless of how you submit a patch or patchset, the patches should -at minimum follow the suggestions outlined in the 'How to Submit a -Change' secion in the Yocto Project Development Manual. Specifically, -they should: +Note that these instructions specifically cover the intel-common and +quark BSPs, which may or may not be applicable to other BSPs contained +in this layer - if a given BSP contains its own README, that version +should be used instead, and these instructions can be ignored. - - Include a 'Signed-off-by:' line. A commit can't legally be pulled - in without this. +a. Building the intel-common and quark BSP layers +------------------------------------------------- - - Provide a single-line, short summary of the change. This short - description should be prefixed by the BSP or recipe name, as - appropriate, followed by a colon. Capitalize the first character - of the summary (following the colon). +In order to build an image with BSP support for a given release, you +need to download the corresponding BSP tarball from the 'Board Support +Package (BSP) Downloads' page of the Yocto Project website (or +equivalently, check out the appropriate branch from the meta-intel git +repository, see below). For the intel-common and quark BSPs, those +tarballs would correspond to the following choices in the BSP +downloads section: - - For the body of the commit message, provide detailed information - that describes what you changed, why you made the change, and the - approach you used. + - Intel-core2-32 Intel® Common Core BSP (Intel-core2-32) + - Intel-core2-32 Intel® Common Core BSP (Intel-quark) + - Intel-corei7-64 Intel® Common Core BSP (Intel-corei7-64) - - If the change addresses a specific bug or issue that is associated - with a bug-tracking ID, include a reference to that ID in your - detailed description in the following format: [YOCTO #<bug-id>]. +The intel-* BSPs, also known as the intel-common BSPs, provide a few +carefully selected tune options and generic hardware support to cover +the majority of current Intel CPUs and devices. The naming follows the +convention of intel-<TUNE>-<BITS>, where TUNE is the gcc cpu-type +(used with mtune and march typically) and BITS is either 32 bit or 64 +bit. - - Pay attention to line length - please don't allow any particular - line in the commit message to stretch past 72 characters. +Having done that, and assuming you extracted the BSP tarball contents +at the top-level of your yocto build tree, you can build a BSP image +by adding the location of the meta-intel layer to bblayers.conf e.g.: - - For any non-trivial patch, provide information about how you - tested the patch, and for any non-trivial or non-obvious testing - setup, provide details of that setup. + yocto/meta-intel \ -Doing a quick 'git log' in meta-intel will provide you with many -examples of good example commits if you have questions about any -aspect of the preferred format. +To enable a particular machine, you need to add a MACHINE line naming +the BSP to the local.conf file: -The meta-intel maintainers will do their best to review and/or pull in -a patch or patchset within 24 hours of the time it was posted. For -larger and/or more involved patches and patchsets, the review process -may take longer. + MACHINE ?= "xxx" +where 'xxx' is replaced by one of the following BSP names: -Intel-specific machine features -=============================== + - intel-core2-32 -The meta-intel layer makes some additional machine features available -to BSPs. These machine features can be used in a BSP layer in the -same way that machine features are used in other layers based on -oe-core, via the MACHINE_FEATURES variable. + This BSP is optimized for the Core2 family of CPUs as well as all + Atom CPUs prior to the Silvermont core. -Requirements ------------- + - intel-corei7-64 -The meta-intel-specific machine features are only available to a BSP -when the meta-intel layer is included in the build configuration, and -the meta-intel.inc file is included in the machine configuration of -that BSP. + This BSP is optimized for Nehalem and later Core and Xeon CPUs as + well as Silvermont and later Atom CPUs, such as the Baytrail SoCs. -To make these features available for your machine, you will need to: + - intel-quark - 1. include a configuration line such as the below in bblayers.conf - BBLAYERS += "<local path>/meta-intel" - 2. include the following line in the machine configuration file - require conf/machine/include/meta-intel.inc + This BSP is optimized for Quark-based systems. -Once the above requirements are met, the machine features provided by -the meta-intel layer will be available for the BSP to use. +You should then be able to build an image as such: + + $ source oe-init-build-env + $ bitbake core-image-sato + +At the end of a successful build, you should have a live image that +you can boot from a USB flash drive (see instructions on how to do +that below, in the section 'Booting the intel-common BSP images'). + +As an alternative to downloading the BSP tarball, you can also work +directly from the meta-intel git repository. For each BSP in the +'meta-intel' repository, there are multiple branches, one +corresponding to each major release starting with 'laverne' (0.90), in +addition to the latest code which tracks the current master (note that +not all BSPs are present in every release). Instead of extracting +a BSP tarball at the top level of your yocto build tree, you can +equivalently check out the appropriate branch from the meta-intel +repository at the same location. + +b. Booting the intel-common BSP images +-------------------------------------- + +If you downloaded the BSP tarball, you will find bootable images in +the /binary directory. If you've built your own image, either from +the downloaded BSP layer or from the meta-intel git repository, you'll +find the bootable image in the build/tmp/deploy/images/xxx directory, +where again 'xxx' refers to the machine name used in the build. -Building for Intel Quark X1000 microprocessor ---------------------------------------------- +The BSP /binary directory or build contains bootable live images, +which can be used to directly boot Yocto off of a USB flash drive. -To target the Intel Quark X1000. +Under Linux, insert a USB flash drive. Assuming the USB flash drive +takes device /dev/sdf, use dd to copy the live image to it. For +example: + +# dd if=core-image-sato-intel-corei7-64.hddimg of=/dev/sdf +# sync +# eject /dev/sdf + +This should give you a bootable USB flash device. Insert the device +into a bootable USB socket on the target, and power on. This should +result in a system booted to the Sato graphical desktop. + +If you want a terminal, use the arrows at the top of the UI to move to +different pages of available applications, one of which is named +'Terminal'. Clicking that should give you a root terminal. + +If you want to ssh into the system, you can use the root terminal to +ifconfig the IP address and use that to ssh in. The root password is +empty, so to log in type 'root' for the user name and hit 'Enter' at +the Password prompt: and you should be in. + +If you find you're getting corrupt images on the USB (it doesn't show +the syslinux boot: prompt, or the boot: prompt contains strange +characters), try doing this first: - 1. In conf/local.conf set the MACHINE type to be intel-quark. +# dd if=/dev/zero of=/dev/sdf bs=1M count=512 - MACHINE ??= "intel-quark" +c. Booting the intel-quark BSP image on a Galileo board +------------------------------------------------------- - 2. Build a target image of your choice. +If you downloaded the BSP tarball, you will find bootable images in +the /binary directory. If you've built your own image, either from +the downloaded BSP layer or from the meta-intel git repository, you'll +find the bootable image in the build/tmp/deploy/images/xxx directory, +where again 'xxx' refers to the machine name used in the build. - $ bitbake core-image-minimal +The Galileo board boots off of an SD card that has a special disk +layout. The 'wic' tool can be used to create an SD card adhering to +that format via the following steps. - 3. For the first time, you need to build parted-native too. (You will get an - error message when running wic script without it at later steps.) +If you haven't already, you need to build parted-native. (You will get +an error message when running the wic script if you haven't.) - $ bitbake parted-native + $ bitbake parted-native - 4. Use the provided wic script to create an SD card image. +Use the wic script to create an SD card image: - $ wic list images + $ wic list images mkgalileodisk Create an Galileo Gen 1/2 disk image mkgummidisk Create an EFI disk image - ... + +Assuming you want to boot the 'core-image-minimal' image: $ wic create mkgalileodisk -e core-image-minimal - wic script outputs the image and its location in success, something like: - ... +If successful, the wic script generates the image and prints its location: + Info: The new image(s) can be found here: /var/tmp/wic/build/mkgalileodisk-201604211444-mmcblk0.direct ... - 5. Write the output image to an SD Card +Write the output image to an SD Card $ sudo dd if=/path/to/image/mkgalileodisk-*-mmcblk0.direct of=/dev/your_sd_dev - 6. Insert the SD Card into the reference platform and power on. +Insert the SD Card into the reference platform and power on. + + +III. Technical Miscellany +========================= + +The intel-common kernel package architecture +-------------------------------------------- + +These BSPs use what we call the intel-common Linux kernel package +architecture. This includes core2-32-intel-common and +corei7-64-intel-common. These kernel packages can also be used by any +of the BSPs in meta-intel that choose to include the +intel-common-pkgarch.inc file. + +To minimize the proliferation of vendor trees, reduce the sources we +must support, and consolidate QA efforts, all BSP maintainers are +encouraged to make use of the intel-common Linux kernel package +architecture. + +Intel-specific machine features +------------------------------- + +The meta-intel layer makes some additional machine features available +to BSPs. These machine features can be used in a BSP layer in the +same way that machine features are used in other layers based on +oe-core, via the MACHINE_FEATURES variable. + +Requirements +++++++++++++ + +The meta-intel-specific machine features are only available to a BSP +when the meta-intel layer is included in the build configuration, and +the meta-intel.inc file is included in the machine configuration of +that BSP. + +To make these features available for your machine, you will need to: + + 1. include a configuration line such as the below in bblayers.conf + BBLAYERS += "<local path>/meta-intel" + 2. include the following line in the machine configuration file + require conf/machine/include/meta-intel.inc + +Once the above requirements are met, the machine features provided by +the meta-intel layer will be available for the BSP to use. Available machine features --------------------------- +++++++++++++++++++++++++++ Currently, the meta-intel layer makes the following set of Intel-specific machine features available: @@ -165,7 +301,7 @@ example: MACHINE_FEATURES += "intel-ucode" Machine feature details ------------------------ ++++++++++++++++++++++++ * intel-ucode @@ -233,3 +369,84 @@ Machine feature details highly sensitive to target image size and which are not experiencing microcode-related issues might consider not enabling this feature. + + +IV. Tested Hardware +=================== + +Of the BSPs currently included in meta-intel, the following have +passed initial testing with the intel-common BSPs: + +intel-corei7-64: + + crystalforest-server + crystalforest-gladden + haswell-wc + nuc (Ivy Bridge and Haswell, manual audio config required) + sugarbay + +intel-core2-32: + + <currently under test> + +If you are interested in a BSP not listed here, chances are we are +currently working on resolving some configuration issues with it. +Please check the bugzilla and check in with us on the meta-intel +mailing list. + + +V. Guidelines for submitting patches +==================================== + +Please submit any patches against meta-intel BSPs to the meta-intel +mailing list (meta-intel@yoctoproject.org). Also, if your patches are +available via a public git repository, please also include a URL to +the repo and branch containing your patches as that makes it easier +for maintainers to grab and test your patches. + +There are patch submission scripts available that will, among other +things, automatically include the repo URL and branch as mentioned. +Please see the Yocto Project Development Manual sections entitled +'Using Scripts to Push a Change Upstream and Request a Pull' and +'Using Email to Submit a Patch' for details. + +Regardless of how you submit a patch or patchset, the patches should +at minimum follow the suggestions outlined in the 'How to Submit a +Change' secion in the Yocto Project Development Manual. Specifically, +they should: + + - Include a 'Signed-off-by:' line. A commit can't legally be pulled + in without this. + + - Provide a single-line, short summary of the change. This short + description should be prefixed by the BSP or recipe name, as + appropriate, followed by a colon. Capitalize the first character + of the summary (following the colon). + + - For the body of the commit message, provide detailed information + that describes what you changed, why you made the change, and the + approach you used. + + - If the change addresses a specific bug or issue that is associated + with a bug-tracking ID, include a reference to that ID in your + detailed description in the following format: [YOCTO #<bug-id>]. + + - Pay attention to line length - please don't allow any particular + line in the commit message to stretch past 72 characters. + + - For any non-trivial patch, provide information about how you + tested the patch, and for any non-trivial or non-obvious testing + setup, provide details of that setup. + +Doing a quick 'git log' in meta-intel will provide you with many +examples of good example commits if you have questions about any +aspect of the preferred format. + +The meta-intel maintainers will do their best to review and/or pull in +a patch or patchset within 24 hours of the time it was posted. For +larger and/or more involved patches and patchsets, the review process +may take longer. + +Please see the meta-intel/MAINTAINERS file for the list of maintainers +and their specific areas; it's also a good idea to cc: the specific +maintainer, if applicable. |