added to icefish

1 files changed, 354 insertions, 0 deletions

diff --git a/docs/getting-started/machines/intel.md b/docs/getting-started/machines/intel.md
index e69de29..252addc 100644
--- a/docs/getting-started/machines/intel.md
+++ b/docs/getting-started/machines/intel.md
@@ -0,0 +1,354 @@
+# Building for Most Intel 64-Bit Hardware Platforms

+

+Although the reference hardware used by the AGL Project is the 64-bit Open Source MinnowBoard,

+you can use the information found on the "[MinnowBoard wiki](https://minnowboard.org/)"

+to enable most 64-bit Intel Architecture (IA) platforms that use the 64-bit

+UEFI as the boot loader.

+In addition to the MinnowBoard, support for the

+[upCore & UpSquared boards](http://up-board.org/upsquared/specifications/) exists.

+MinnowBoard Max and Turbot are both 64-bit capable.

+

+If you are interested in creating ***applications*** to run on hardware booted

+using an image built with the AGL Project, see the following:

+

+* [Application Development Workflow](../app-workflow-intro.html)

+* [Developing Apps for AGL](https://wiki.automotivelinux.org/agl-distro/developer_resources_intel_apps)

+

+UEFI has significantly evolved and you should check that your hardware's

+firmware is up-to-date.

+You must make this check for MinnowBoard-Max platforms.

+You do not need to make this check for the MinnowBoard-Turbo, upCore, and UpSquared

+platforms:

+

+* [`https://firmware.intel.com/projects/minnowboard-max`](https://firmware.intel.com/projects/minnowboard-max)

+* Intel automotive Module Reference Board (MRB)

+

+  **NOTES:** By default, these MRBs ship with an Automotive

+  Fast Boot loader (ABL), which requires encrypted images.

+  You can ask Intel's "Engineering Sales support" for a special version

+  of the MRB that does not require an encrypted image.

+  You need this type of MRB in order to test AGL on the development board.

+  Contact your Intel technical support representative to get the non-signed

+  ABL firmware.

+

+

+## 1. Making Sure Your Build Environment is Correct

+

+The

+"[Initializing Your Build Environment](../image-workflow-initialize-build-environment.html)"

+section presented generic information for setting up your build environment

+using the `aglsetup.sh` script.

+If you are building for an Intel 64-bit platform, you need to specify some

+specific options when you run the script:

+

+```bash

+$ source meta-agl/scripts/aglsetup.sh \

+    -m intel-corei7-64 \

+    agl-devel agl-demo agl-appfw-smack agl-netboot agl-pipewire

+```

+

+The "-m" option specifies the "intel-corei7-64" machine.

+If you were building for a Joule developer kit, you would use the

+"-m joule" option.

+

+The list of AGL features used with script are appropriate for the AGL demo image suited

+for the Intel 64-bit target.

+The "agl-netboot" option creates the correct Initial RAM Filesystem (initramfs)

+image even if you do not boot from a network.

+

+## 2. Using BitBake

+

+This section shows the `bitbake` command used to build the AGL image.

+Before running BitBake to start your build, it is good to be reminded that AGL

+does provide pre-built images for developers that work with supported hardware.

+You can find these pre-built images on the

+[AGL Download web site](https://download.automotivelinux.org/AGL/release).

+

+For supported Intel images, the filenames have the following form:

+

+```

+<release-name>/<release-number>/intel-core17-64/deploy/images/intel-core17-64/bzImage-intel-corei7-64.bin

+```

+

+Start the build using the `bitbake` command.

+

+**NOTE:** An initial build can take many hours depending on your

+CPU and and Internet connection speeds.

+The build also takes approximately 100G-bytes of free disk space.

+

+For this example, the target is "agl-demo-platform":

+

+```bash

+  bitbake agl-demo-platform

+```

+

+The build process puts the resulting image in the Build Directory:

+

+```

+<build_directory>/tmp/deploy/images/intel-corei7-64/

+```

+

+An alternative method for building an image is to use the AGL SDK delivered in a Docker container.

+

+There is currently no SDK dedicated to IA but the SDK provided for the Porter Board can build an IA image without changes (just `aglsetup.sh` needs to call for Intel).

+

+See chapter 2 of [Porter QuickStart](http://iot.bzh/download/public/2016/sdk/AGL-Kickstart-on-Renesas-Porter-board.pdf "wikilink").

+

+## 3. Creating Bootable Media

+

+Typically, you use a USB stick, SD card, or HDD/SDD to create bootable media.

+It is possible, however, to install the AGL image onto Embedded MultiMediaCard

+(eMMC).

+eMMC provides card longevity at a low cost and is used in automotive infotainment

+systems, avionics displays, and industrial automation/HMI control applications

+to name a few.

+

+When creating bootable media,

+[Extended Attributes (`xattrs`)](https://linux-audit.com/using-xattrs-extended-attributes-on-linux/)

+are required for use with

+[Smack](https://en.wikipedia.org/wiki/Smack_(software)).

+This section describes using the `mkabl-agl.sh` or `mkefi-agl.sh` scripts

+to create bootable media.

+Use of either of these scripts include all required `xattrs`.

+

+**NOTE:** You can find detailed information on Smack at

+  [https://www.kernel.org/doc/Documentation/security/Smack.txt](https://www.kernel.org/doc/Documentation/security/Smack.txt).

+

+While the `mkabl-agl.sh` or `mkefi-agl.sh` scripts are recommended for creating

+your bootable media for Intel devices, other methods exist.

+If you use an alternative method (e.g. `tar`), be sure you take steps to copy

+`xattrs` as part of the image.

+See the

+"[Including Extended Attributes](../troubleshooting.html#including-extended-attributes)"

+section for more information.

+

+### USB Stick, SD Card, and HDD/SDD

+

+Depending on your target hardware, use a USB stick, an SD card, or an HDD/SDD.

+The creation process remains the same independently of the selected support.

+It does require to have access to a Linux machine with `sudo` or root password.

+

+Create a bootable SD card with the script [`mkefi-agl.sh`](https://gerrit.automotivelinux.org/gerrit/gitweb?p=AGL/meta-agl.git;a=blob_plain;f=scripts/mkefi-agl.sh;hb=HEAD).

+Use the "-v" option to check the available options.

+

+**NOTE:** If you are using an Intel Module Reference Board (MRB), you need to

+  use the

+  [`mkabl-agl.sh`](https://gerrit.automotivelinux.org/gerrit/gitweb?p=AGL/meta-agl.git;a=blob_plain;f=scripts/mkefi-agl.sh;hb=HEAD)

+  script instead of the `mkefi-agl.sh` script.

+

+Follow these steps to create your bootable media:

+

+1. **Insert Media Device:**

+   Insert your removable media into the corresponding interface.

+

+2. **Determine the Name of Your Media Device:**

+   Use the `lsblk` command to make sure you know the name of the device to which you will be writing.

+

+   ```bash

+     lsblk

+     # You want the name of the raw device and not the name of a partition on the media.

+     #(e.g. /dev/sdc or /dev/mmcblk0)

+   ```

+

+3. **Download the `mkefi-agl.sh` Script:**

+   You can find the script in the "meta-agl/scripts" folder of your AGL source files.

+

+   Alternatively, you can download the script from the following Git repository:

+

+   [https://github.com/dominig/mkefi-agl.sh](https://github.com/dominig/mkefi-agl.sh)

+

+4. **Create Your Bootable Media:**

+   Run the following to see `mkefi-agl.sh` usage information:

+

+   ```bash

+     ./mkefi-agl.sh -v

+   ```

+

+   Supply the name of your actual image and device name and run the script.

+   The following example assumes a USB device (e.g. `/dev/sdb`) and the image

+   `intel-corei7-64.hdd`:

+

+   ```bash

+   $ sudo ./mkefi-agl.sh intel-corei7-64.hdd /dev/sdb

+   # /dev/sdX is common for USB stick where "X" is "b".

+   # /dev/mmcblk0 is common for an integrated SD card reader in a notebook computer.

+   ```

+

+### Embedded MultiMediaCard (eMMC)

+

+It is possible to install the AGL image directly on the internal eMMC

+rather than a removable device such as a USB stick or SD card.

+To do so, requires the following steps:

+

+1. **Add Required Tools to Your AGL Image:**

+

+   Add a file named `site.conf` in your `build/conf` directory.

+   Make sure the file has the following content:

+

+   ```

+   INHERIT += "rm_work"

+   IMAGE_INSTALL_append = " linux-firmware-iwlwifi-7265d"

+   IMAGE_INSTALL_append = " parted e2fsprogs dosfstools"

+   IMAGE_INSTALL_append = " linux-firmware-i915 linux-firmware-ibt linux-firmware-iwlwifi-8000c"

+   ```

+   In addition to the previous statements, you need to add the

+   Intel Wireless WiFi Link (`iwlifi`) driver for your own device

+   as needed.

+

+2. **Rebuild Your Image**

+

+   Rebuild the AGL image by following the instructions in the

+   "[Using BitBake](../machines/intel.html#2-using-bitbake)"

+   step of this page.

+

+3. **Install the Rebuilt Image Onto a Removable Device**

+

+   Follow the steps previously described here to copy the new

+   image onto a removable device such as a USB stick.

+

+4. **Copy the Image from the USB Stick to Your Build Host's Home Directory**

+

+   Copy the image you just temporarily installed to the removable

+   device to your build host's home directory.

+   The process uses this image later for installation in the

+   eMMC.

+   For example, copy the image file created using the Yocto Project from

+   the build directory to your home directory:

+

+   ```bash

+   $ cp build/tmp/deploy/images/intel-corei7-64/agl-demo-platform-intel-corei7-64.wic.xz ~/

+   ```

+

+5. **Boot the AGL Image from the Removable Device**

+

+   You can see how to boot the image on the target device by

+   following the procedure in the next section.

+

+6. **Connect to Your Device that is Running the Image**

+

+   You need to use a Serial Link or SSH to connect to the device running

+   your image.

+

+7. **Determine the eMMC Device Name**

+

+   Be sure you know the name of the eMMC device.

+   Use the `lsblk` command.

+

+8. **Install the Image into the eMMC**

+

+   Use the `mkefi-agl.sh` Script to install the image into the eMMC.

+

+   ```

+   cat /proc/partitions

+   ```

+9. **Remove the USB or SD Boot Device**

+

+   Once your image is running on the booted device, you can remove the

+   media used to boot the hardware.

+

+10. **Reboot Your Device**

+

+    Cycle through a reboot process and the device will boot from the

+    eMMC.

+

+## 4. Booting the Image on the Target Device

+

+Be aware of the following when booting your device:

+

+* Interrupting the boot process is easier to achieve when

+  using a USB keyboard as opposed to a serial link.

+

+* During the boot process, USB hubs are not supported.

+  You need to connect any USB keyboard directly to your device's

+  USB socket.

+

+* It is recommended that you use F9 to permanently change the boot

+  order rather than interrupt the process for each subsequent boot.

+  Also, you must have your bootable media plugged in or connected

+  to the target device before you can permanently change the boot

+  order.

+

+* Booting from an SD card is faster as compared to booting from

+  a USB stick.

+  Use an SD card for better boot performance.

+

+* The MinnowBoard, many laptops, and NUC devices do not accept

+  USB3 sticks during the boot process.

+  Be sure your image is not on a USB3 stick.

+

+Use these steps to boot your device:

+

+1. Insert the bootable media that contains the AGL image into the target device.

+

+2. Power on the device.

+

+3. As the device boots, access the boot option screen.

+   You generally accomplish this with the F12 key during the power up operation.

+

+   **NOTE:** When booting a MinnowBoard, you can change the default boot

+   device by hitting F2 during initial UEFI boot.

+

+4. From the boot option screen, select your bootable media device.

+

+5. Save and exit the screen and let the device boot from your media.

+

+   **NOTE:**: Depending on the speed of your removable media, the first boot might

+   not complete.

+   If this is the case, reboot the device a second time.

+   It is common with USB sticks that you need to boot a couple of times.

+

+   For Intel devices, the serial console is configured and activated at the rate of 115200 bps.

+

+## 5. Miscellaneous Information

+

+Following is information regarding serial debug ports, serial cables, and

+port names for connected displays.

+

+### Serial Debug Port

+

+Serial debug port IDs vary across hardware platforms.

+By default, when you build an AGL image for an Intel target such as the

+Minnowboard, Module Reference Board (MRB), or Up board, the serial debug

+ports are as follows:

+

+* MinnowBoard uses `/dev/ttyS0`

+* MRB uses `/dev/ttyS2`

+* Up boards the `/dev/ttyS0` serial port is difficult to access.

+  Using `/dev/ttyS4` is preferred, which is routed on the Arduino

+  connector.

+  See the [Up2 Pin Specification]( http://www.up-board.org/wp-content/uploads/2017/11/UP-Square-DatasheetV0.5.pdf)

+  for more information.

+

+Depending on your particular hardware, you might need to change the

+configuration in your bootloader, which is located in the EFI partition.

+

+### Serial Debug Cable

+

+On the MinnowBoard, the serial debug cable is an FTDI serial cable.

+You can learn more [here](https://minnowboard.org/tutorials/best-practice-serial-connection).

+

+Up Boards use the same FDDI 3.3V adapter as does the MinnowBoard.

+However, the pin out is not adjacent and requires split pins.

+

+### Port Names and Connected Displays

+

+Port naming can change across hardware platforms and connected displays.

+The simplest way to determine the port name used for a connected display

+is to check the after the initial boot process completes.

+You can make this check in the `systemd` journal as follows:

+

+```bash

+$ journalctl | grep Output

+```

+

+**NOTE:** Output for the

+[`journalctl`](https://www.freedesktop.org/software/systemd/man/journalctl.html)

+command generates only when a real display is connected to the connector on the board.

+The file holding that configuration is `/etc/xdg/weston/weston.ini`.

+

+Common Display names for Intel platforms are the following:

+

+* `HDMI-A-1`

+* `HDMI-A-2`

+* `LVDS-1`

+