diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 486 |
1 files changed, 7 insertions, 479 deletions
@@ -1,481 +1,9 @@ -meta-intel -========== +meta-tlk +======== -This README file contains information on building and booting -meta-intel BSP layers. Please see the corresponding sections below -for details. +This layer makes the appropriate kernel modifications to enable a 10 day +time limit in the official BSP images produced using the Yocto Project +autobuilder, in order to encourage people to produce their own images +for production whilst still allowing the images to be useful for testing +and debugging. - -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. |