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 <chee.yang.lee@intel.com>
Signed-off-by: Anuj Mittal <anuj.mittal@intel.com>

6 files changed, 238 insertions, 470 deletions

diff --git a/README b/README
deleted file mode 100644
index ca2c5041..00000000
--- a/README
+++ /dev/null
@@ -1,470 +0,0 @@
-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
-
-  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
-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, 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 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 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-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.
-
-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}.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.
-
-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
-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:
-    Alder Lake-P
-    Alder Lake-S
-    Elkhart Lake
-    Kaby Lake
-    Raptor Lake-P
-    Tiger Lake
-
-intel-skylake-64:
-    Alder Lake-P
-    Alder Lake-S
-    Elkhart Lake
-    Kaby Lake
-    Raptor Lake-P
-    Tiger Lake
-
-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.
diff --git a/README.md b/README.md
new file mode 100644
index 00000000..b3b5e60b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,32 @@
+# meta-intel
+
+OpenEmbedded/Yocto BSP layer for Intel platforms.
+
+## Dependencies
+
+This layer primarily depends on OpenEmbedded-Core (OE-Core). However, certain
+recipes may require additional layers to support optional features or
+programming languages not supported by OE-Core. Such recipes are located within
+the `dynamic-layers` directory.
+
+Base dependencies:
+- [Bitbake](https://git.openembedded.org/bitbake)
+- [OE-Core](https://git.openembedded.org/openembedded-core)
+
+Dynamic additional dependencies:
+
+- [meta-openembedded](https://git.openembedded.org/meta-openembedded/tree/meta-oe)
+- [meta-python](https://git.openembedded.org/meta-openembedded/tree/meta-python)
+- [meta-clang](https://github.com/kraj/meta-clang.git)
+
+
+## Contents
+
+- [Building and booting meta-intel BSP layers](documentation/building_and_booting.md)
+- [Intel oneAPI DPC++/C++ Compiler](documentation/dpcpp-compiler.md)
+- [Tested Hardware](documentation/tested_hardware.md)
+- [Guidelines for submitting patches](documentation/submitting_patches.md)
+- [Reporting bugs](documentation/reporting_bugs.md)
+- [Reporting security bugs](SECURITY.md)
+- [Maintainers](MAINTAINERS)
+
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-<TUNE>-<BITS>, 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