6 files changed, 313 insertions, 38 deletions

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/dpcpp-compiler.md b/documentation/dpcpp-compiler.md
new file mode 100644
index 00000000..b709a685
--- /dev/null
+++ b/documentation/dpcpp-compiler.md
@@ -0,0 +1,107 @@
+Intel(R) oneAPI DPC++/C++ Compiler (ICX) toolchain
+==========================================================================
+
+Get Started with the Intel oneAPI DPC++/C++ Compiler:
+
+https://www.intel.com/content/www/us/en/developer/tools/oneapi/dpc-compiler.html#
+
+
+Getting Started
+===============
+
+Clone the required layers and include them in bblayers.conf:
+
+```
+git clone https://git.openembedded.org/openembedded-core
+git clone https://git.openembedded.org/bitbake
+git clone https://git.openembedded.org/meta-openembedded
+git clone https://github.com/kraj/meta-clang.git
+git clone https://git.yoctoproject.org/meta-intel
+
+$ source openembedded-core/oe-init-build-env
+
+$ bitbake-layers add-layer ../meta-openembedded/meta-oe/
+$ bitbake-layers add-layer ../meta-intel
+$ bitbake-layers add-layer ../meta-clang
+```
+
+Distro
+======
+
+Note that oneAPI DPC++/C++ compiler currently only works when the vendor string is "oe".
+
+```
+DISTRO ?= "nodistro"
+```
+
+MACHINE configuration
+=====================
+
+```
+MACHINE ?= "intel-skylake-64"
+```
+
+Package installation
+====================
+
+```
+# To include OpenCL driver that might be needed when compiling SYCL programs, include:
+IMAGE_INSTALL:append = " intel-compute-runtime intel-graphics-compiler"
+
+# To install only runtime libraries, include:
+IMAGE_INSTALL:append = " intel-oneapi-dpcpp-cpp-runtime intel-oneapi-dpcpp-cpp-runtime-dev"
+
+# To install the toolchain, include:
+IMAGE_INSTALL:append = " intel-oneapi-dpcpp-cpp intel-oneapi-dpcpp-cpp-dev"
+```
+in local.conf.
+
+Build an image
+==============
+
+```
+$ bitbake core-image-minimal
+```
+
+Including oneAPI C++/DPC++ compiler in generated SDK toolchain
+==============================================================
+
+The compiler is not included in the generated SDK by default. If it is expected to be part of SDK, add ICXSDK = "1" in local.conf:
+
+```
+ICXSDK = "1"
+```
+
+Generate SDK:
+```
+bitbake core-image-minimal -c populate_sdk
+```
+
+
+To setup PATH variables on target
+=================================
+
+Once image is booted successfully, some variables would need to be exported to make sure compiler can be used:
+
+```
+$ source /opt/intel/oneapi/compiler/2022.1.0/env/vars.sh
+
+$ mkdir -p /lib64
+
+$ ln -sf /lib/ld-linux-x86-64.so.2 /lib64/ld-linux-x86-64.so.2
+```
+
+Build application and run
+=========================
+
+To compile a sycl application, for example:
+
+```
+$ icpx --target=x86_64-oe-linux -fsycl simple-sycl-app.c -o simple-sycl-app
+```
+
+To run:
+
+```
+$ ./simple-sycl-app
+```
diff --git a/documentation/reporting_bugs.md b/documentation/reporting_bugs.md
new file mode 100644
index 00000000..5fbc3d27
--- /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](../README.md#maintainers) section 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/secureboot/README b/documentation/secureboot/README
deleted file mode 100644
index 3d5703bb..00000000
--- a/documentation/secureboot/README
+++ /dev/null
@@ -1,38 +0,0 @@
-Currently, only one implementation of Secure Boot is available out of the box,
-which is using a single signed EFI application to directly boot the kernel with
-an optional initramfs.
-
-This can be added to your build either through local.conf, or via your own
-custom image recipe.
-
-If you are adding it via local.conf, set the following variables:
-
-IMAGE_FEATURES += "secureboot"
-WKS_FILE = "generic-bootdisk.wks.in"
-SECURE_BOOT_SIGNING_KEY = "/path/to/your/signing/key"
-SECURE_BOOT_SIGNING_CERT = "/path/to/your/signing/cert"
-IMAGE_CLASSES += "uefi-comboapp"
-
-If working with an image recipe, you can inherit uefi-comboapp directly instead
-of using the IMAGE_CLASSES variable.
-
-The signing keys and certs can be created via openssl commands. Here's an
-example:
-openssl req -new -x509 -newkey rsa:2048 -subj "/CN=your-subject/" -keyout \
-your-key.key -out your-key.crt -days 365 -nodes -sha256
-openssl x509 -in your-key.crt -out your-key.cer -outform DER
-
-The .crt file is your SECURE_BOOT_SIGNING_CERT, and the .key file is your
-SECURE_BOOT_SIGNING_KEY.
-
-You should enroll the .crt key in your firmware under the PK, KEK, and DB
-options (methods are different depending on your firmware). If a key should ever
-become invalid, enroll it under DBX to blacklist it.
-
-The comboapp can be further manipulated in a number of ways. You can modify the
-kernel command line via the APPEND variable, you can change the default UUID via
-the DISK_SIGNATURE_UUID variable, and you can modify the contents of the
-initramfs via the INITRD_IMAGE or INITRD_LIVE variables.
-
-A simple Secure Boot enabled image used for testing can be viewed at:
-common/recipes-selftest/images/secureboot-selftest-image-signed.bb
diff --git a/documentation/submitting_patches.md b/documentation/submitting_patches.md
new file mode 100644
index 00000000..f36c4b08
--- /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](../README.md#maintainers) section 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