diff --git a/docs/getting-started-book.yml b/docs/getting-started-book.yml index b6a40b9..db4b15e 100644 --- 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 index e69de29..0477bf3 100644 --- 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 index e69de29..0b0693c 100644 --- 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: + +``` +//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: + +``` +/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` +