diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 481 |
1 files changed, 481 insertions, 0 deletions
@@ -0,0 +1,481 @@ +meta-intel +========== + +This README file contains information on building and booting +meta-intel BSP layers. Please see the corresponding sections below +for details. + + +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: 1.34 + + URI: git://git.openembedded.org/openembedded-core + layers: meta + branch: rocko + + +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 + Benefits of using meta-intel + 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 +the Yocto mailing list puts it in the archive and helps other people +who might have the same questions in the future), but please try to do +the following first: + + - look in the Yocto Project Bugzilla + (http://bugzilla.yoctoproject.org/) to see if a problem has + already been reported + + - look through recent entries of the meta-intel + (https://lists.yoctoproject.org/pipermail/meta-intel/) and Yocto + (https://lists.yoctoproject.org/pipermail/yocto/) mailing list + archives to see if other people have run into similar problems or + had similar questions answered. + +If you believe you have encountered a bug, you can open a new bug and +enter the details in the Yocto Project Bugzilla +(http://bugzilla.yoctoproject.org/). If you're relatively certain +that it's a bug against the BSP itself, please use the 'Yocto Project +Components: BSPs | meta-intel' category for the bug; otherwise, please +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. + + +II. Building and booting meta-intel BSP layers +============================================== + +The following sections contain information on building and booting the +BSPs contained in the meta-intel layer. + +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. + +a. Building the intel-common and quark BSP layers +------------------------------------------------- + +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: + + - 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) + +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. + +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.: + + yocto/meta-intel \ + +To enable a particular machine, you need to add a MACHINE line naming +the BSP to the local.conf file: + + 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 an 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 image to it. For example: + + $ dd if=core-image-sato-intel-corei7-64.wic 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 can boot off of either an SD card or USB storage +media that has a special disk layout. The 'wic' tool can be used to +create directly bootable images for either of the two formats via the +following steps. As of meta-intel 6.0-morty-2.2 or newer, wic images are +created automatically during build time, and the manual use of wic is +not necessary. By default, the galileodisk-sd wic kickstart file is used, +which targets SD cards. This can be changed by setting the WKS_FILE to +something else in local.conf, such as the following: + +WKS_FILE = “galileodisk-usb” + +If your build is successful, a .wic image will be created in the usual +deploy directory. Write this image to an SD card: + + $ sudo dd if=/path/to/image/image-name.wic of=/dev/your_sd_dev + $ sync + $ sudo eject /dev/your_sd_dev + +Insert the SD card into the Galileo and power on. + +The Galileo board can boot from an hddimg formatted USB drive as well, +but currently only live-boot, and not installation, is supported. +An image in hddimg format is generated when you build the quark BSP. +You can follow the procedure in II.b to use dd command to prepare your USB +drive, then press F7 key during startup to bring up the boot option menu. +Choose the UEFI USB boot option for the drive to boot the system. If the board +already passes this stage and show a grub boot menu, you can press 'c' +key and then type "quit" in grub shell. The board should come back to +the UEFI boot menu. + +III. Technical Miscellany +========================= + +Benefits of using meta-intel +---------------------------- + +Using meta-intel has the following benefits over a generic BSP: + +tune flags +++++++++++ +intel-* MACHINEs each have different compilation flags appropriate for their +targeted hardware sets. intel-corei7-64 has tune flags appropriate for modern +64-bit Intel Core i microarchitecture, and includes instruction sets up to +SSE4.2. intel-core2-32 has tune flags appropriate for legacy 32-bit Intel Core2 +microarchitecture, and includes instruction sets up to SSE3. intel-quark +contains a subset of the intel-core2-32 instruction set, as quark does not +support prefix locking instructions. + +linux-intel kernel +++++++++++++++++++ +The linux-intel kernel is an initiative to bring better Intel(R) hardware +support to the current LTS linux kernel. It contains a base LTS kernel with +additional backports from upstream Intel drivers. In addition, a default kernel +config containing most features found on Intel boards is supplied via the +yocto-kernel-cache. + +graphics stack +++++++++++++++ +Meta-intel provides the latest Intel Graphics Linux Stack drivers to support +Intel hardware as defined by the https://01.org/linuxgraphics. + +Other software +++++++++++++++ + * intel ucode - provides the latest microcode updates for Intel processors + + * thermald - which proactively controls thermal, using P-states, T-states, and +the Intel power clamp driver. +(https://01.org/linux-thermal-daemon/documentation/introduction-thermal-daemon) + + * RMC - Runtime Machine Configuration, which allows the bootload to determine +board and CPU information in order to set specific kernel command line +information at startup. + +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: + + * intel-ucode + +These machine features can be included by listing them in the +MACHINE_FEATURES variable in the machine configuration file. For +example: + + MACHINE_FEATURES += "intel-ucode" + +Machine feature details ++++++++++++++++++++++++ + + * intel-ucode + + This feature provides support for microcode updates to Intel + processors. The intel-ucode feature runs at early boot and uses + the microcode data file added by the feature into the BSP's + initrd. It also puts the userland microcode-updating tool, + iucode_tool, into the target images along with the microcode data + file. + + Q. Why might a user want to enable the intel-ucode feature? + + A. Intel releases microcode updates to correct processor behavior + as documented in the respective processor specification + updates. While the normal approach to getting such microcode + updates is via a BIOS upgrade, this can be an administrative + hassle and not always possible in the field. The intel-ucode + feature enables the microcode update capability present in the + Linux kernel. It provides an easy path for upgrading processor + microcode without the need to change the BIOS. If the feature + is enabled, it is also possible to update the existing target + images with a newer microcode update in the future. + + Q. How would a user bundle only target-specific microcode in the + target image? + + A. The Intel microcode data file released by Intel contains + microcode updates for multiple processors. If the BSP image is + meant to run on only a certain subset of processor types, a + processor-specific subset of microcode can be bundled into the + target image via the UCODE_FILTER_PARAMETERS variable. This + works by listing a sequence of iucode-tool parameters in the + UCODE_FILTER_PARAMETERS variable, which in this case will + select only the specific microcode relevant to the BSP. For + more information on the underlying parameters refer to the + iucode-tool manual page at http://manned.org/iucode-tool + + To define a set of parameters for microcode-filtering via the + UCODE_FILTER_PARAMETERS variable, one needs to identify the + cpuid signatures of all the processors the BSP is meant to run + on. One way to determine the cpuid signature for a specific + processor is to build and run an intel-ucode-feature-enabled + image on the target hardware, without first assigning any value + to the UCODE_FILTER_PARAMETERS variable, and then once the + image is booted, run the "ucode_tool -S" command to have the + ucode tool scan the system for processor signatures. These + signatures can then be used in the UCODE_FILTER_PARAMETERS + variable in conjunction with -s parameter. For example, for + the fri2 BSP, the cpuid can be determined as such: + + [root@fri2 ~]# iucode_tool -S + iucode_tool: system has processor(s) with signature 0x00020661 + + Given that output, a suitable UCODE_FILTER_PARAMETERS variable + definition could be specified in the machine configuration as + such: + + UCODE_FILTER_PARAMETERS = "-s 0x00020661" + + Q. Are there any reasons a user might want to disable the + intel-ucode feature? + + A. The microcode data file and associated tools occupy a small + amount of space (a few KB) on the target image. BSPs which are + highly sensitive to target image size and which are not + experiencing microcode-related issues might consider not + enabling this feature. + + +IV. Tested Hardware +=================== + +The following undergo regular basic testing with their respective MACHINE types. +Note that both 64-bit and 32-bit firmware is available for the MinnowBoard +Turbot, so it is tested against both intel-corei7-64 and intel-core2-32. + +intel-corei7-64: + NUC6i5SYH + MinnowBoard Turbot + Braswell RVP + +intel-core2-32: + MinnowBoard Turbot + +Intel-quark: + Galileo 2 + + +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 'Submitting a Change +to the Yocto Project' section 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. |