Intel Troubleshooting: Integrated info with Intel build process

I took the information from the "Troubleshooting" section for
Intel devices and dispersed it within the section for building
Intel devices.  Much of the information was redundant and
could easily fit all within the topic of Intel devices.

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>

1 files changed, 190 insertions, 9 deletions

diff --git a/docs/getting-started/machines/intel.md b/docs/getting-started/machines/intel.md
index 4f2756b..3222793 100644
--- a/docs/getting-started/machines/intel.md
+++ b/docs/getting-started/machines/intel.md
@@ -6,7 +6,7 @@ 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://www.up-board.org/upsquared/) exists.
-MinnowBoard Max and Turbot as well as Joule are both 64-bit capable.
+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:
@@ -14,13 +14,23 @@ using an image built with the AGL Project, see the following:
 * [Application Development Workflow](../app-workflow-intro.html/overview)
 * [Developing Apps for AGL](https://wiki.automotivelinux.org/agl-distro/developer_resources_intel_apps)
 
-UEFI has significantly evolved and you will likely want to check that your hardware's
+UEFI has significantly evolved and you should check that your hardware's
 firmware is up-to-date.
-You should make this check for both the MinnowBoard-Max and the Joule platforms.
-You do not need to make this check for the MinnowBoard-Turbo and Up platforms:
+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)
-* [`https://software.intel.com/en-us/flashing-the-bios-on-joule`](https://software.intel.com/en-us/flashing-the-bios-on-joule)
+* 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
 
@@ -88,12 +98,26 @@ See chapter 2 of [Porter QuickStart](http://iot.bzh/download/public/2016/sdk/AGL
 
 ## 3. Creating Bootable Media
 
-Depending on your target hardware you will use an USB stick, an SD card or a HDD/SDD.
+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.
+
+### 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)
-check the available options with the -v option. mkefi-agl.sh -v
+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.
 
 1. **Insert Media Device:**
    Insert your removable media into the corresponding interface.
@@ -131,9 +155,109 @@ check the available options with the -v option. mkefi-agl.sh -v
    # /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#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
 
-Follow these steps to boot your 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.
 
@@ -142,6 +266,9 @@ Follow these steps to boot your image on the target 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.
@@ -152,3 +279,57 @@ Follow these steps to boot your image on the target device:
    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`
+