diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 367 |
1 files changed, 315 insertions, 52 deletions
@@ -1,11 +1,57 @@ 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 + + URI: git://git.openembedded.org/openembedded-core + layers: meta + branch: master + + +Table of Contents +================= + + I. Overview + II. Building and booting meta-intel BSP layers + a. Building the intel-common BSP layers + b. Booting the intel-common BSP images + c. Building the installer image + 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, 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 +78,205 @@ 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, 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 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 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-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. + +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'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. + +Under Linux, insert a USB flash drive. Assuming the USB flash drive +takes device /dev/sdf, use dd to copy the image to it. Before the image +can be burned onto a USB drive, it should be un-mounted. Some Linux distros +may automatically mount a USB drive when it is plugged in. Using USB device +/dev/sdf as an example, find all mounted partitions: + $ mount | grep sdf + +and un-mount those that are mounted, for example: + + $ umount /dev/sdf1 + $ umount /dev/sdf2 + +Now burn the image onto the USB drive: + + $ sudo dd if=core-image-sato-intel-corei7-64.wic of=/dev/sdf status=progress + $ 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. Building the installer image +----------------------------------------------- + +If you plan to install your image to your target machine, you can build a wic +based installer image instead of default wic image. To build it, you need to +add below configuration to local.conf : + + WKS_FILE = "image-installer.wks.in" + IMAGE_FSTYPES_append = " ext4" + IMAGE_TYPEDEP_wic = "ext4" + INITRD_IMAGE_LIVE="core-image-minimal-initramfs" + do_image_wic[depends] += "${INITRD_IMAGE_LIVE}:do_image_complete" + do_rootfs[depends] += "virtual/kernel:do_deploy" + IMAGE_BOOT_FILES_append = "\ + ${KERNEL_IMAGETYPE} \ + microcode.cpio \ + ${IMGDEPLOYDIR}/${IMAGE_BASENAME}-${MACHINE}.ext4;rootfs.img \ + ${@bb.utils.contains('EFI_PROVIDER', 'grub-efi', 'grub-efi-bootx64.efi;EFI/BOOT/bootx64.efi', '', d)} \ + ${@bb.utils.contains('EFI_PROVIDER', 'grub-efi', '${IMAGE_ROOTFS}/boot/EFI/BOOT/grub.cfg;EFI/BOOT/grub.cfg', '', d)} \ + ${@bb.utils.contains('EFI_PROVIDER', 'systemd-boot', 'systemd-bootx64.efi;EFI/BOOT/bootx64.efi', '', d)} \ + ${@bb.utils.contains('EFI_PROVIDER', 'systemd-boot', '${IMAGE_ROOTFS}/boot/loader/loader.conf;loader/loader.conf ', '', d)} \ + ${@bb.utils.contains('EFI_PROVIDER', 'systemd-boot', '${IMAGE_ROOTFS}/boot/loader/entries/boot.conf;loader/entries/boot.conf', '', d)} " + +Burn the wic image onto USB flash device, insert the device to target machine +and power on. This should start the installation process. + +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. + +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) + +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 +284,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 @@ -104,15 +294,15 @@ 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" + BBLAYERS += "<local path>/meta-intel" 2. include the following line in the machine configuration file - require conf/machine/include/meta-intel.inc + 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: @@ -123,10 +313,10 @@ 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_FEATURES += "intel-ucode" Machine feature details ------------------------ ++++++++++++++++++++++++ * intel-ucode @@ -178,7 +368,7 @@ Machine feature details the fri2 BSP, the cpuid can be determined as such: [root@fri2 ~]# iucode_tool -S - iucode_tool: system has processor(s) with signature 0x00020661 + 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 @@ -194,3 +384,76 @@ 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 +=================== + +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 + NUC7i7BNH + Coffee Lake-H + +intel-core2-32: + MinnowBoard Turbot + + +V. Guidelines for submitting patches +==================================== + +Please submit any patches against meta-intel BSPs to the meta-intel +mailing list (meta-intel@lists.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. |