[meta-intel] [PATCH 1/3] README: Add build and boot instructions and restructure
Tom Zanussi
tom.zanussi at linux.intel.com
Thu Apr 28 17:10:43 PDT 2016
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 at linux.intel.com>
---
README | 381 +++++++++++++++++++++++++++++++++++++++++++++++++++--------------
1 file changed, 299 insertions(+), 82 deletions(-)
diff --git a/README b/README
index 63960c2..d2098a9 100644
--- a/README
+++ b/README
@@ -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 at 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 at 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.
--
1.9.3
More information about the meta-intel
mailing list