From e166755b86a6f2d56cd9101dad85f2801f4279c5 Mon Sep 17 00:00:00 2001 From: Lee Chee Yang Date: Fri, 19 Apr 2024 09:39:40 +0800 Subject: documentation: update and restructure README Update README content, reference and links. Also, split and convert this into multiple markdown files. Signed-off-by: Lee Chee Yang Signed-off-by: Anuj Mittal --- documentation/building_and_booting.md | 134 ++++++++++++++++++++++++++++++++++ documentation/reporting_bugs.md | 22 ++++++ documentation/submitting_patches.md | 26 +++++++ documentation/tested_hardware.md | 24 ++++++ 4 files changed, 206 insertions(+) create mode 100644 documentation/building_and_booting.md create mode 100644 documentation/reporting_bugs.md create mode 100644 documentation/submitting_patches.md create mode 100644 documentation/tested_hardware.md (limited to 'documentation') diff --git a/documentation/building_and_booting.md b/documentation/building_and_booting.md new file mode 100644 index 00000000..478a4fb0 --- /dev/null +++ b/documentation/building_and_booting.md @@ -0,0 +1,134 @@ +### Building the Intel BSP layers + +The intel-common BSP 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--, where +TUNE is the gcc cpu-type (used with mtune and march typically) and BITS +is either 32 bit or 64 bit. + +In order to build an image with BSP support for a given release, you +need to clone the meta-intel layer from git repository: +``` +git clone https://git.yoctoproject.org/meta-intel +``` + +Check out the appropriate branch or release tags. The branch name and tags +would align with Yocto Project +[Release Codenames](https://wiki.yoctoproject.org/wiki/Releases). +Assuming meta-intel repository is cloned at the top-level of +OE-Core build tree, you can build a BSP image by adding the location of +the meta-intel layer to bblayers.conf: +``` +BBLAYERS = " \ + /openembedded-core/meta \ + /openembedded-core/meta-intel " +``` + +To enable a particular machine, add a MACHINE line naming the BSP +to the local.conf file: +``` +MACHINE ?= "intel-corei7-64" +``` + +where this can be replaced by other MACHINE types available: + + - 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-skylake-64 + + This BSP uses [x86-64-v3 tuning](https://gcc.gnu.org/onlinedocs/gcc/x86-Options.html). + +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. + + +## Booting the intel-common BSP images + +If you've built your own image, you'll find the bootable +image in the build/tmp/deploy/images/{MACHINE} directory, where +'MACHINE' 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 +``` + +## 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}.rootfs.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. + + diff --git a/documentation/reporting_bugs.md b/documentation/reporting_bugs.md new file mode 100644 index 00000000..04a4d47f --- /dev/null +++ b/documentation/reporting_bugs.md @@ -0,0 +1,22 @@ +## Reporting bugs + +If you have problems with or questions about a particular BSP, please +contact the maintainer listed in the [Maintainer](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/g/meta-intel/messages) + and [Yocto Archives](https://lists.yoctoproject.org/g/yocto/messages) 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](https://bugzilla.yoctoproject.org/). +If you're relatively certain that it's a bug against the BSP itself, please use the +'BSPs | 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. + diff --git a/documentation/submitting_patches.md b/documentation/submitting_patches.md new file mode 100644 index 00000000..41a039bd --- /dev/null +++ b/documentation/submitting_patches.md @@ -0,0 +1,26 @@ +## Guidelines for submitting patches + +Please submit any patches against meta-intel BSPs to the +[meta-intel mailing list](https://lists.yoctoproject.org/g/meta-intel) +(email: 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. + +The patches should follow the suggestions outlined in the +[Yocto Project and OpenEmbedded Contributor Guide](https://docs.yoctoproject.org/dev/contributor-guide/index.html). +In addition, 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 patch sets within 24 hours of the time it was posted. For +larger and/or more involved patches and patch sets, the review process +may take longer. + +Please see the [MAINTAINERS](MAINTAINERS.md) for the list of maintainers. It's also +a good idea to cc: the maintainer, if applicable. diff --git a/documentation/tested_hardware.md b/documentation/tested_hardware.md new file mode 100644 index 00000000..48a25ab4 --- /dev/null +++ b/documentation/tested_hardware.md @@ -0,0 +1,24 @@ +## Tested Hardware + +The following undergo regular basic testing with their respective MACHINE types. + +- intel-corei7-64: + * Alder Lake-P + * Alder Lake-S + * Alder Lake-PS + * Elkhart Lake + * Metor Lake-P + * Raptor Lake-P + * Tiger Lake + +- intel-skylake-64: + * Alder Lake-P + * Alder Lake-S + * Alder Lake-PS + * Elkhart Lake + * Metor Lake-P + * Raptor Lake-P + * Tiger Lake + +- intel-core2-32: + * MinnowBoard Turbot -- cgit v1.2.3-54-g00ecf