MIRRORS/meta-intel
1
0
Fork 0
mirror of git://git.yoctoproject.org/meta-intel.git synced 2025-07-19 12:59:03 +02:00
Code Issues Actions Packages Projects Releases Wiki Activity

README: Add build and boot instructions and restructure

Browse Source 
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>
This commit is contained in:
Tom Zanussi 2016-04-28 19:10:43 -05:00 committed by Saul Wold
parent d9727db3e7
commit 70a1429dfe
1 changed files with 304 additions and 87 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

391
README
View File

@ -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,61 +83,185 @@ 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-core2-32
This BSP is optimized for the Core2 family of CPUs as well as all
Atom CPUs prior to the Silvermont core.
- intel-corei7-64
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.
- intel-quark
This BSP is optimized for Quark-based systems.
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.
The BSP /binary directory or build contains bootable live images,
which can be used to directly boot Yocto off of a USB flash drive.
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:
# dd if=/dev/zero of=/dev/sdf bs=1M count=512
c. Booting the intel-quark BSP image on a Galileo board
-------------------------------------------------------
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.
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.
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
Use the wic script to create an SD card image:
$ 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
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
...
Write the output image to an SD Card
$ sudo dd if=/path/to/image/mkgalileodisk-*-mmcblk0.direct of=/dev/your_sd_dev
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
@ -94,7 +269,7 @@ 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
@ -111,47 +286,8 @@ To make these features available for your machine, you will need to:
Once the above requirements are met, the machine features provided by
the meta-intel layer will be available for the BSP to use.
Building for Intel Quark X1000 microprocessor
---------------------------------------------
To target the Intel Quark X1000.
1. In conf/local.conf set the MACHINE type to be intel-quark.
MACHINE ??= "intel-quark"
2. Build a target image of your choice.
$ bitbake core-image-minimal
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.)
$ bitbake parted-native
4. Use the provided wic script to create an SD card image.
$ wic list images
mkgalileodisk Create an Galileo Gen 1/2 disk image
mkgummidisk Create an EFI disk image
...
$ wic create mkgalileodisk -e core-image-minimal
wic script outputs the image and its location in success, something like:
...
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
$ 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.
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.