diff options
Diffstat (limited to 'docs/getting-started/machines/intel.md')
| -rw-r--r-- | docs/getting-started/machines/intel.md | 400 |
1 files changed, 284 insertions, 116 deletions
diff --git a/docs/getting-started/machines/intel.md b/docs/getting-started/machines/intel.md index 34957a8..3658408 100644 --- a/docs/getting-started/machines/intel.md +++ b/docs/getting-started/machines/intel.md @@ -1,186 +1,354 @@ -# Running AGL on Intel MinnowBoard (and most Intel 64 bits HW) +# Building for Most Intel 64-Bit Hardware Platforms -## Scope +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. -This documentation is aiming at people who want to run Automotive Grade -Linux (AGL) on Intel Hardware (HW). -While the reference HW used by AGL project is the Open Source MinnowBoard, this documentation [MinnowBoard wiki](https://minnowboard.org/) can be used to enable most of 64-bit Intel Architecture (IA) platforms using UEFI as boot loader. -In addition to the MinnowBoard, support for the [upCore & UpSquared boards](http://www.up-board.org/upsquared/) has been added. -You need to run the 64-bit version of the UEFI bootloader. -MinnowBoard Max and Turbot as well as Joule 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: -**Note**: This page is more focused on those who want to create bespoke AGL images and BSPs. +* [Application Development Workflow](../app-workflow-intro.html) +* [Developing Apps for AGL](https://wiki.automotivelinux.org/agl-distro/developer_resources_intel_apps) -If you are interested in creating ***applications*** to run on AGL, please visit the [Developing Apps for AGL](https://wiki.automotivelinux.org/agl-distro/developer_resources_intel_apps) documentation. +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: -UEFI has evolved a lot recently and you likely want to check that your HW firmware is up-to-date, this is mandatory for both the MinnowBoard-Max and the Joule. Not required on Minnowboard-Turbo and Up boards. +* [`https://firmware.intel.com/projects/minnowboard-max`](https://firmware.intel.com/projects/minnowboard-max) +* Intel automotive Module Reference Board (MRB) -[`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) + **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. -## Where to find an AGL bootable image -### Download a ready made image +## 1. Making Sure Your Build Environment is Correct -AGL provides ready made images for developers. -You will find them on [AGL Download web site](https://download.automotivelinux.org/AGL/release) -image are located in YourPreferedRelease/intel-corei7-64/deploy/images/intel-corei7-64/ -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 +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: -### Building an AGL image from scratch using Yocto - -**Note**: an alternative method for building an image is to use the AGL SDK delivered in a Docker container. +```bash +$ source meta-agl/scripts/aglsetup.sh \ + -m intel-corei7-64 \ + agl-devel agl-demo agl-appfw-smack agl-netboot agl-audio-4a-framework +``` -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). +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. -See chapter 2 of [Porter QuickStart](http://iot.bzh/download/public/2016/sdk/AGL-Kickstart-on-Renesas-Porter-board.pdf "wikilink"). +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. -#### Download AGL source code +## 2. Using BitBake -Downloading the AGL sources from the various Git repositories is automated with the `repo` tool. Basic steps to download the AGL source code is described below and for more advanced topics involving the `repo` tool, please refer to the [`repo` documentation](https://source.android.com/source/using-repo.html "wikilink"). +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). -To install the `repo` tool: +For supported Intel images, the filenames have the following form: -```bash - mkdir -p ~/bin; - export PATH=~/bin:$PATH; - curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo; - chmod a+x ~/bin/repo; ``` +<release-name>/<release-number>/intel-core17-64/deploy/images/intel-core17-64/bzImage-intel-corei7-64.bin +``` + +Start the build using the `bitbake` command. -#### Configuring for the current *(older)* stable (Electric Eel 5.0.x) +**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 - cd AGL-5.0.x; - repo init -b eel -m default.xml -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo + bitbake agl-demo-platform ``` -#### Configuring for master (DD) +The build process puts the resulting image in the Build Directory: -```bash - cd AGL-master; - repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo; +``` +<build_directory>/tmp/deploy/images/intel-corei7-64/ ``` -Once that you repo is initialised either with the stable or WIP, you need to sync the repo to fetch the various git trees. +An alternative method for building an image is to use the AGL SDK delivered in a Docker container. -#### Downloading the configured AGL source code +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). -```bash - repo sync; -``` +See chapter 2 of [Porter QuickStart](http://iot.bzh/download/public/2016/sdk/AGL-Kickstart-on-Renesas-Porter-board.pdf "wikilink"). -#### Building the AGL distro +## 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. -You are now ready to initialise your Yocto build. -When running the command: +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. -```bash - source meta-agl/scripts/aglsetup.sh -h -``` +**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. -You will notice the Intel entries +Follow these steps to create your bootable media: -```bash - intel-corei7-64 - joule -``` +1. **Insert Media Device:** + Insert your removable media into the corresponding interface. -Simply select that entry to replace porter in the -m option. -**Note:** agl-netboot option is required to create the right initramfs even if you do not boot from a network +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 - source meta-agl/scripts/aglsetup.sh \ - -m intel-corei7-64 \ - -b build \ - agl-devel agl-demo agl-appfw-smack agl-netboot agl-audio-4a-framework -``` + ```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) + ``` -**Note:** use the option "-m joule" when building for a Joule developer Kit target. +3. **Download the `mkefi-agl.sh` Script:** + You can find the script in the "meta-agl/scripts" folder of your AGL source files. -Start the build **This can take several hours depending of your CPU and -internet connection and will required several GB on /tmp as well as on your build directory** + Alternatively, you can download the script from the following Git repository: -```bash - bitbake agl-demo-platform -``` + [https://github.com/dominig/mkefi-agl.sh](https://github.com/dominig/mkefi-agl.sh) -**Your newly baked disk image (.wic.xz) will be located at**: - `tmp/deploy/images/intel-corei7-64/` +4. **Create Your Bootable Media:** + Run the following to see `mkefi-agl.sh` usage information: -##### Alternative: Download a *ready made* image from AGL web site + ```bash + ./mkefi-agl.sh -v + ``` -The Continuous Integration (CI) process from AGL creates and publish daily and stable builds. -Pointers to both can be found in [AGL supported HW](https://wiki.automotivelinux.org/agl-distro) (see Reference BSP/Intel). + 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`: -Once you have validated your process you can start to play/work with the snapshot pointer. + ```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. + ``` -Note that snapshot build may not work. +### Embedded MultiMediaCard (eMMC) -Follow the directory: +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: -`intel-corei7-64/deploy/images/intel-corei7-64/` +1. **Add Required Tools to Your AGL Image:** -and download the file: + Add a file named `site.conf` in your `build/conf` directory. + Make sure the file has the following content: -`agl-demo-platform-intel-corei7-64.hddimg` + ``` + 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. -## Create a bootable media +2. **Rebuild Your Image** -Depending your target HW you will use an USB stick, an SD card or a 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. + Rebuild the AGL image by following the instructions in the + "[Using BitBake](../machines/intel.html#2-using-bitbake)" + step of this page. -### Insert you removable media in the corresponding interface +3. **Install the Rebuilt Image Onto a Removable Device** -### Check the device name where the media can be accessed with the command + Follow the steps previously described here to copy the new + image onto a removable device such as a USB stick. -```bash - lsblk - # Note that you want the name of the raw device not of a partition on the media - #(eg. /dev/sdc or /dev/mmcblk0) -``` +4. **Copy the Image from the USB Stick to Your Build Host's Home Directory** -### Download the script `mkefi-agl.sh` + 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: -This script is present in the directory meta-agl/scripts from blowfish 2.0.4 : [mkefi-agl.sh](https://gerrit.automotivelinux.org/gerrit/gitweb?p=AGL/meta-agl.git;a=blob_plain;f=scripts/mkefi-agl.sh;hb=HEAD) + ```bash + $ cp build/tmp/deploy/images/intel-corei7-64/agl-demo-platform-intel-corei7-64.wic.xz ~/ + ``` -Alternatively you can download it from the following Git repo: +5. **Boot the AGL Image from the Removable Device** -[https://github.com/dominig/mkefi-agl.sh](https://github.com/dominig/mkefi-agl.sh) + You can see how to boot the image on the target device by + following the procedure in the next section. -### check the available options +6. **Connect to Your Device that is Running the Image** -```bash - sh mkefi-agl.sh -v; -``` + You need to use a Serial Link or SSH to connect to the device running + your image. -### create your media with the command adjusted to your configuration +7. **Determine the eMMC Device Name** -```bash - sudo sh mkefi-agl.sh MyAglImage.hdd /dev/sdX - #/dev/sdX is common for USB stick, /dev/mmcblk0 for laptop integrated SD card reader -``` + 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. -## Boot the image on the target device +Use these steps to boot your device: -1. Insert the created media with the AGL image in the target device +1. Insert the bootable media that contains the AGL image into the target device. -1. Power on the device +2. Power on the device. -1. Select Change one off boot option (generally F12 key during power up) +3. As the device boots, access the boot option screen. + You generally accomplish this with the F12 key during the power up operation. -1. Select your removable device + **NOTE:** When booting a MinnowBoard, you can change the default boot + device by hitting F2 during initial UEFI boot. -1. Let AGL boot +4. From the boot option screen, select your bootable media device. -**Note:**: depending on the speed of the removable media, the first boot may not complete, in that case simply reboot the 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 +``` -This is quite common with USB2 sticks. +**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`. -By default the serial console is configured and activated at the rate of 115200 bps. +Common Display names for Intel platforms are the following: -## How to create your 1st AGL application +* `HDMI-A-1` +* `HDMI-A-2` +* `LVDS-1` -[Developing Apps for AGL](https://wiki.automotivelinux.org/agl-distro/developer_resources_intel_apps) |