automotive-grade-linux · fnstzl · Aug 3, 2020
diff --git a/docs/getting-started-book.yml b/docs/getting-started-book.yml
@@ -39,9 +39,9 @@ books:
     - url: "getting-started/machines/qemu.md"
       name: Building for Emulation
     - url: "getting-started/machines/renesas.md"
-      name: Build for R Car Starter Kit gen3 board
+      name: Building for R-Car Starter Kit gen3 board
     - url: "getting-started/machines/raspberrypi.md"
-      name: Build for Raspberry PI 3/4
+      name: Building for Raspberry Pi 3/4
 -
     id: troubleshooting
     order: 51

diff --git a/docs/getting-started/image-workflow-download-sw.md b/docs/getting-started/image-workflow-download-sw.md
@@ -0,0 +1,189 @@
+# 2 Downloading AGL Software
+
+Once you have determined the build host can build an AGL image,
+you need to download the AGL source files.
+The AGL source files, which includes the Yocto Project layers, are
+maintained on the AGL Gerrit server.
+For information on how to create accounts for Gerrit, see the
+[Getting Started with AGL](https://wiki.automotivelinux.org/start/getting-started)
+wiki page.
+
+The remainder of this section provides steps on how to download the AGL source files:
+
+1. **Define Your Top-Level Directory:**
+   You can define an environment variable as your top-level AGL workspace folder.
+   Following is an example that defines the `$HOME/workspace_agl` folder using
+   an environment variable named "AGL_TOP":
+
+   ```bash
+   $ export AGL_TOP=$HOME/workspace_agl
+   $ mkdir -p $AGL_TOP
+   ```
+
+2. **Download the `repo` Tool and Set Permissions:**
+   AGL Uses the `repo` tool for managing repositories.
+   Use the following commands to download the tool and then set its
+   permissions to allow for execution:
+
+   ```bash
+   $ mkdir -p ~/bin
+   $ export PATH=~/bin:$PATH
+   $ curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
+   $ chmod a+x ~/bin/repo
+   ```
+
+   **NOTE:** See the
+   "[Repo Command Reference](https://source.android.com/setup/develop/repo)"
+   for more information on the `repo` tool.
+
+3. **Download the AGL Source Files:**
+   Depending on your development goals, you can either download the
+   latest stable AGL release branch, or the "cutting-edge" (i.e. "master"
+   branch) files.
+
+   * **Stable Release:**
+     Using the latest stable release gives you a solid snapshot of the
+     latest know release.
+     The release is static, tested, and known to work.
+     To download the latest stable release branch (i.e. Halibut 8.0), use
+     the following commands:
+
+     ```bash
+     $ cd $AGL_TOP
+     $ repo init -b icefish -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo
+     $ repo sync
+     ```
+
+   * **Cutting-Edge Files:**
+     Using the "cutting-edge" AGL files gives you a snapshot of the
+     "master" directory.
+     The resulting local repository you download is dynamic and can become
+     out-of-date with the upstream repository depending on community contributions.
+     The advantage of using "cutting-edge" AGL files is that you have the
+     absolute latest features, which are often under development, for AGL.
+
+     To download the "cutting-edge" AGL files, use the following commands:
+
+     ```bash
+     $ cd $AGL_TOP
+     $ repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo
+     $ repo sync
+     ```
+
+   Once you `sync` the repository, you have the AGL files in the form of
+   "layers" (e.g. `meta-*` folders).
+   You also have the `poky` repository in your AGL workspace.
+
+   Listing out the resulting directory structure appears as follows:
+
+   ```
+   $ tree -L 2
+.
+|-- bsp
+|   |-- meta-altera
+|   |-- meta-boundary
+|   |-- meta-freescale
+|   |-- meta-freescale-3rdparty
+|   |-- meta-intel
+|   |-- meta-qcom
+|   |-- meta-raspberrypi
+|   |-- meta-rcar
+|   |-- meta-renesas-rcar-gen3
+|   |-- meta-rtlwifi
+|   |-- meta-sancloud
+|   |-- meta-synopsys
+|   `-- meta-ti
+|-- external
+|   |-- alexa-auto-sdk
+|   |-- meta-clang
+|   |-- meta-gplv2
+|   |-- meta-openembedded
+|   |-- meta-qt5
+|   |-- meta-sdl
+|   |-- meta-security
+|   |-- meta-spdxscanner
+|   |-- meta-updater
+|   |-- meta-updater-qemux86-64
+|   |-- meta-updater-raspberrypi
+|   |-- meta-virtualization
+|   `-- poky
+|-- meta-agl
+|   |-- README-AGL.md
+|   |-- README.md
+|   |-- agl-layers-overview.md
+|   |-- docs
+|   |-- meta-agl
+|   |-- meta-agl-bsp
+|   |-- meta-agl-distro
+|   |-- meta-agl-profile-cluster
+|   |-- meta-agl-profile-cluster-qt5
+|   |-- meta-agl-profile-core
+|   |-- meta-agl-profile-graphical
+|   |-- meta-agl-profile-graphical-qt5
+|   |-- meta-agl-profile-hud
+|   |-- meta-agl-profile-telematics
+|   |-- meta-agl.md
+|   |-- meta-app-framework
+|   |-- meta-netboot
+|   |-- meta-security
+|   |-- scripts
+|   `-- templates
+|-- meta-agl-cluster-demo
+|   |-- README.md
+|   |-- conf
+|   |-- recipes-config
+|   |-- recipes-connectivity
+|   |-- recipes-demo-hmi
+|   |-- recipes-graphics
+|   |-- recipes-platform
+|   `-- templates
+|-- meta-agl-demo
+|   |-- README.md
+|   |-- classes
+|   |-- conf
+|   |-- docs
+|   |-- meta-agl-demo.md
+|   |-- recipes-apis
+|   |-- recipes-config
+|   |-- recipes-connectivity
+|   |-- recipes-core
+|   |-- recipes-demo-hmi
+|   |-- recipes-devtools
+|   |-- recipes-graphics
+|   |-- recipes-kernel
+|   |-- recipes-multimedia
+|   |-- recipes-navigation
+|   |-- recipes-platform
+|   |-- recipes-qt
+|   |-- recipes-sdl
+|   |-- recipes-support
+|   `-- templates
+|-- meta-agl-devel
+|   |-- ATTIC
+|   |-- README.md
+|   |-- docs
+|   |-- meta-agl-devel.md
+|   |-- meta-agl-profile-graphical-html5
+|   |-- meta-audio-soundmanager-framework
+|   |-- meta-gstrecorder-rcar-gen3
+|   |-- meta-oem-extra-libs
+|   |-- meta-pipewire
+|   |-- meta-speech-framework
+|   `-- templates
+|-- meta-agl-extra
+|   |-- meta-blsched
+|   `-- templates
+`-- meta-agl-telematics-demo
+    |-- README.md
+    |-- conf
+    |-- recipes-config
+    |-- recipes-connectivity
+    |-- recipes-core
+    |-- recipes-demo
+    |-- recipes-navigation
+    |-- recipes-platform
+    `-- templates
+
+94 directories, 10 files
+
+   ```
diff --git a/docs/getting-started/machines/intel.md b/docs/getting-started/machines/intel.md
@@ -0,0 +1,179 @@
+# Building for Most Intel 64-Bit Hardware Platforms
+
+Most 64-bit capable x86 hardware will run AGL just fine (e.g. Laptop w/ touchscreen).
+For development, we recommend the
+[upCore & UpSquared boards](http://up-board.org/upsquared/specifications/).
+
+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.
+
+## 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-netboot
+```
+
+The "-m" option specifies the "intel-corei7-64" machine.
+
+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-corei7-64/deploy/images/intel-corei7-64/agl-demo-platform-crosssdk-intel-corei7-64.wic.xz
+```
+
+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.
+
+
+## 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.
+
+You can write the `wic.xz` image after extraction with `dd` or `etcher`.
+Or you use `bmaptool` which does not require extraction.
+
+Note: for `bmaptool`, also download the `.wic.bmap` file as well.
+
+## 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.
+
+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, the serial debug
+ports are as follows:
+
+* 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
+
+Most development boards use a standard serial debug cable (e.g. 3.3V FTDI serial cable).
+Up Boards use the same FTDI 3.3V adapter.
+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`
+