diff --git a/docs/getting-started/image-workflow-build.md b/docs/getting-started/image-workflow-build.md index 13f542f..05a75b3 100644 --- a/docs/getting-started/image-workflow-build.md +++ b/docs/getting-started/image-workflow-build.md @@ -12,7 +12,6 @@ This section, provides links to topics with instructions needed to create images three types of supported platforms and for emulation using Quick EMUlator (QEMU) or VirtualBox: -* [Most Intel-based 64-Bit Boards](./machines/intel.html) -* [Emulation](./machines/qemu.html) +* [Most 64-Bit Boards QEMU/Intel](./machines/qemu.html) * [R Car Starter Kit Gen3 Board](./machines/renesas.html) * [Raspberry PI 2 or 3](./machines/raspberrypi.html) diff --git a/docs/getting-started/image-workflow-download-sw.md b/docs/getting-started/image-workflow-download-sw.md index e69de29..f4927dc 100644 --- a/docs/getting-started/image-workflow-download-sw.md +++ b/docs/getting-started/image-workflow-download-sw.md @@ -0,0 +1,108 @@ +# 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 master -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 1 + . + ├── build + ├── meta-agl + ├── meta-agl-demo + ├── meta-agl-devel + ├── meta-agl-extra + ├── meta-altera + ├── meta-boundary + ├── meta-freescale + ├── meta-freescale-3rdparty + ├── meta-freescale-distro + ├── meta-intel + ├── meta-intel-iot-security + ├── meta-oic + ├── meta-openembedded + ├── meta-qcom + ├── meta-qt5 + ├── meta-raspberrypi + ├── meta-renesas + ├── meta-renesas-rcar-gen3 + ├── meta-rust + ├── meta-sdl + ├── meta-security-isafw + ├── meta-ti + ├── meta-updater + ├── meta-virtualization + └── poky + ``` diff --git a/docs/getting-started/machines/qemu.md b/docs/getting-started/machines/qemu.md index af8d91e..3b427f5 100644 --- a/docs/getting-started/machines/qemu.md +++ b/docs/getting-started/machines/qemu.md @@ -1,11 +1,11 @@ -# Building for Emulation +# Building for Emulation and Intel x64 Building an image for emulation allows you to simulate your image without actual target hardware. This section describes the steps you need to take to build the AGL demo image for emulation using either Quick EMUlator (QEMU) or -VirtualBox. +VirtualBox and with Intel architectures. ## 1. Making Sure Your Build Environment is Correct @@ -59,8 +59,10 @@ By default, the build process puts the resulting image in the Build Directory: /tmp/deploy/images/qemux86-64/ e.g. - -/tmp/deploy/images/qemux86-64/agl-demo-platform-qemux86-64.vmdk.xz +QEMU: +/tmp/deploy/images/qemux86-64/agl-demo-platform-qemux86-64.vmdk.xz +Intel: +/tmp/deploy/images/qemux86-64/agl-demo-platform-crosssdk-qemux86-64-20200408171012.rootfs.wic.xz ``` **Note:** @@ -72,7 +74,10 @@ If you need to run it outside of the bitbake environment or need special setting hardware pass-through or the like, read on: -## 3. Deploying the AGL Demo Image +# Deploying the AGL Demo Image + + +## QEMU Deploying the image consists of decompressing the image and then booting it using either QEMU or VirtualBox. @@ -94,7 +99,6 @@ the image and prepare it for boot. The following steps show you how to boot the image with QEMU or VirtualBox. -#### QEMU Depending on your Linux distribution, use these commands to install QEMU: @@ -152,7 +156,7 @@ The image can be booted in such an environment by removing `-enable-kvm` from the qemu command line, however this will result in lower perfromance within the AGL demo. -#### VirtualBox +### VirtualBox Start by downloading and installing [VirtualBox](https://www.virtualbox.org/wiki/Downloads) 5.2.0 or later. @@ -169,3 +173,292 @@ Once VirtualBox is installed, follow these steps to boot the image: 9. Select the newly created **AGL QEMU** machine and click **Settings** 10. Go to the **System** tab and ensure **Enable EFI (special OSes only)** is enabled then click **OK** 11. With the **AGL QEMU** machine still selected, click **Start** to boot the virtual machine + +## Building for Most Intel 64-Bit Hardware Platforms + +Although the reference hardware used by the AGL Project are the 64-bit +[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. + +You do not need to make this check for the upCore, and UpSquared +platforms: + +* 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. + +### 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/qemux86-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` + + +