diff options
| author |   Jan-Simon Möller <dl9pf@gmx.de> | 2020-03-02 23:04:22 +0100 |
|---|---|---|
| committer |   GitHub <noreply@github.com> | 2020-03-02 23:04:22 +0100 |
| commit | 53ca2a2e3a3e183616d4a060ef917e36eb2d23b5 (patch) | |
| tree | 0ae6224559314904492033378795bd21b96623d6 /agl-documentation/sdk-devkit/docs/part-1 | |
| parent | 4e7e82a279ffa322f31e0dfee8a4bad370878753 (diff) | |
| parent | aa9912660e08f8d406e74807bab476cc60dd9581 (diff) | |
Merge pull request #17 from dl9pf/for-master
Add agl-documentation subfolder into agl repo
Diffstat (limited to 'agl-documentation/sdk-devkit/docs/part-1')
29 files changed, 1124 insertions, 0 deletions
diff --git a/agl-documentation/sdk-devkit/docs/part-1/1_0_Abstract.md b/agl-documentation/sdk-devkit/docs/part-1/1_0_Abstract.md new file mode 100644 index 0000000..46bf74e --- /dev/null +++ b/agl-documentation/sdk-devkit/docs/part-1/1_0_Abstract.md @@ -0,0 +1,27 @@ +# Part 1 - Build AGL image from scratch + +## Abstract + +The AGL DevKit allows developers to rebuild a complete bootable image +and its associated SDK from source code.\ +It uses Yocto/Poky version 2.x with latest version of Renesas BSP and + enables low-level development of drivers and system services. + +The AGL DevKit contains: + +- This guide, which describes how to create a Docker container able to + build AGL images and associated SDKs.\ + The container is also suitable to build AGL Applications + independently of Yocto/Bitbake. +- Applications templates and demos available on Github, to start + developing various types of applications independently of Yocto: + - services + - native applications + - HTML5 applications + - ... +- A documentation guide "**AGL Devkit - Build your 1st AGL + Application**" which explains how to use the AGL SDK to create applications + based on templates. + +*This document focuses on building from scratch an AGL image for Porter +board, within a Docker container, and then install the associated SDK.* diff --git a/agl-documentation/sdk-devkit/docs/part-1/1_1-Deploy_image.md b/agl-documentation/sdk-devkit/docs/part-1/1_1-Deploy_image.md new file mode 100644 index 0000000..52319b1 --- /dev/null +++ b/agl-documentation/sdk-devkit/docs/part-1/1_1-Deploy_image.md @@ -0,0 +1,47 @@ +# Deploy an image using containers + +## Motivation + +The Yocto build environment is subject to many variations depending on: + +- Yocto/Poky/OpenEmbedded versions and revisions +- Specific layers required for building either the BSP or the whole distribution +- Host distribution and version [1] +- User environment + +In particular, some recent Linux host distributions (Ubuntu 15.x, Debian +8.x, OpenSUSE 42.x, CentOS 7.x) do not officially support building with +Yocto 2.0. +Unfortunately, there's no easy solution to solve this kind of +problem: + +- we will still observe for quite a long time a significant gap + between the latest OS versions and a fully certified build environment. + +To circumvent those drawbacks and get more deterministic results amongst +the AGL community of developers and integrators, using virtualization is +a good workaround. +A Docker container is now available for AGL images: + +- it is faster, easier and less error-prone to use a prepared Docker + container because it provides all necessary components to build and + deploy an AGL image, including a validated base OS, independently of the + user's host OS. + +Moreover, light virtualization mechanisms used by Docker +do not add much overhead when building: + +- performances are nearly equal to native mode. + +[1] *The list of validated host distros is defined in the Poky distro, in +the file `meta-yocto/conf/distro/poky.conf` and also at [http://www.yoctoproject.org/docs/2.0/ref-manual/ref-manual.html#detailed-supported-distros](http://www.yoctoproject.org/docs/2.0/ref-manual/ref-manual.html#detailed-supported-distros)* + +## Prerequisites + +To run an AGL Docker image, the following prerequisites must be +fulfilled: + +- You must run a 64-bit operating system, with administrative rights, +- Docker engine v1.8 or greater must be installed, +- An internet connection must be available to download the Docker + image on your local host. diff --git a/agl-documentation/sdk-devkit/docs/part-1/1_2-Setting-up-your_os.md b/agl-documentation/sdk-devkit/docs/part-1/1_2-Setting-up-your_os.md new file mode 100644 index 0000000..2420c68 --- /dev/null +++ b/agl-documentation/sdk-devkit/docs/part-1/1_2-Setting-up-your_os.md @@ -0,0 +1,217 @@ +# Setting up your operating system + +In this section, we describe the Docker installation procedure depending +on your host system. We will be focusing on the most popular systems; +for a full list of supported operating systems, please refer to Docker +online documentation: [https://docs.docker.com/](https://docs.docker.com/) + +## Linux (Ubuntu / Debian) + +At the time of writing, Docker project supports these Ubuntu/Debian +releases: + +- Ubuntu Yakkety 16.10 +- Ubuntu Xenial 16.04 LTS +- Ubuntu Trusty 14.04 LTS +- Debian 8.0 (64-bit) +- Debian 7.7 (64-bit) + +For an updated list of supported distributions, you can refer to the +Docker project website, at these locations: + +- [https://docs.docker.com/engine/installation/linux/debian/](https://docs.docker.com/engine/installation/linux/debian/) +- [https://docs.docker.com/engine/installation/linux/ubuntu/](https://docs.docker.com/engine/installation/linux/ubuntu/) + +Here are the commands needed to install the Docker engine on your local +host: + +```bash +sudo apt-get update +sudo apt-get install wget curl +wget -qO- https://get.docker.com/ | sh +``` + +This will register a new location in your "sources.list" file and +install the "docker.io" package and its dependencies: + +```bash +$ cat /etc/apt/sources.list.d/docker.list +$ deb [arch=amd64] https://apt.dockerproject.org/repo ubuntu-xenial main +$ docker --version +Docker version 17.03.0-ce, build 60ccb22 +``` + +It is then recommended to add your user to the new "docker" system +group: + +```bash +sudo usermod -aG docker *<your-login>* +``` + +... and after that, to log out and log in again to have these credentials +applied. + +You can reboot your system or start the Docker daemon using: + +```bash +sudo service docker start +``` + +If everything went right, you should be able to list all locally +available images using: + +```bash +$ docker images +REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE +``` + +In our case, no image is available yet, but the environment is ready to +go on. + +A SSH client must also be installed: + +```bash +sudo apt-get install openssh-client +``` + +## Windows © (7, 8, 8.1, 10) + +**WARNING: although Windows© can work for this purpose, not only are lots +of additional steps needed, but the build process performance itself is +suboptimal. Please consider moving to Linux for a better experience.** + +We will be downloading the latest Docker Toolbox at the following +location: + +[*https://www.docker.com/docker-toolbox*](https://www.docker.com/docker-toolbox) + +and by clicking on the "*Download (Windows)*" button: + +\ +We will answer "Yes", "Next" and "Install" in the next dialog boxes. + +{style width:60%;} + +{style width:48%; float:left; margin-right:0.3em} +{style width:48%; float:right} + + + +We can then start it by double-clicking on the "Docker Quickstart +Terminal" icon: + + + +It will take a certain amount time to setup everything, until this +banner appears: + + + +Docker Toolbox provides a 1 Gb RAM/20 Go HDD virtual machine; this is +clearly insufficient for our needs. Let us expand it to 4 Gb RAM/50 +HDD (*these are minimal values; feel free to increase them if your computer +has more physical memory and/or free space*) : + +```bash +export VBOXPATH=/c/Program\ Files/Oracle/VirtualBox/ +export PATH="$PATH:$VBOXPATH" + +docker-machine stop default + +VBoxManage.exe modifyvm default --memory 4096 +VBoxManage.exe createhd --filename build.vmdk --size 51200 --format VMDK +VBoxManage.exe storageattach default --storagectl SATA --port 2 --medium build.vmdk --type hdd + +docker-machine start default + +docker-machine ssh default "sudo /usr/local/sbin/parted --script /dev/sdb mklabel msdos" +docker-machine ssh default "sudo /usr/local/sbin/parted --script /dev/sdb mkpart primary ext4 1% 99%" +docker-machine ssh default "sudo mkfs.ext4 /dev/sdb1" +docker-machine ssh default "sudo mkdir /tmp/sdb1" +docker-machine ssh default "sudo mount /dev/sdb1 /tmp/sdb1" +docker-machine ssh default "sudo cp -ra /mnt/sda1/* /tmp/sdb1" + +docker-machine stop default + +VboxManage.exe storageattach default --storagectl SATA --port 2 --medium none +VboxManage.exe storageattach default --storagectl SATA --port 1 --medium build.vmdk --type hdd + +docker-machine start default +``` + +We will then finalize the setup: + +```bash +VboxManage.exe modifyvm default --natpf1 sshredir,tcp,127.0.0.1,2222,,2222 +docker-machine start default +docker-machine ssh default "echo mkdir /sys/fs/cgroup/systemd | sudo tee /var/lib/boot2docker/bootlocal.sh" +docker-machine restart default +``` + +A SSH client must also be installed. We will grab *PuTTY* at the +following URL: +[*http://the.earth.li/~sgtatham/putty/latest/x86/putty.exe*](http://the.earth.li/~sgtatham/putty/latest/x86/putty.exe) + +## Mac OS X © + +We will be downloading the latest Docker Toolbox at the following +location: +[https://www.docker.com/docker-toolbox](https://www.docker.com/docker-toolbox) + +and by clicking on the "*Download (Mac)*" button: + + + +We will answer "Continue" and "Install" in the next dialog boxes: + + + +{style width:80%;} +{style width:80%;} + +Then, when we go to our "Applications" folder, we now have a "Docker" +subfolder where we can start "Docker Quickstart Terminal": + + + +It will take a certain amount of time to setup everything, until this +banner appears: + + + +Docker Toolbox provides a 1 Gb RAM/20 Go HDD virtual machine; this is +clearly insufficient for our needs. Let us expand it to 4 Gb RAM/50 +HDD (*these are minimal values; feel free to increase them if your computer +has more physical memory and/or free space*) : + +```bash +docker-machine stop default + +VboxManage modifyvm default --memory 4096 +VboxManage createhd --filename build.vmdk --size 51200 --format VMDK +VboxManage storageattach default --storagectl SATA --port 2 --medium build.vmdk --type hdd + +docker-machine start default + +docker-machine ssh default "sudo /usr/local/sbin/parted --script /dev/sdb mklabel msdos" +docker-machine ssh default "sudo /usr/local/sbin/parted --script /dev/sdb mkpart primary ext4 1% 99%" +docker-machine ssh default "sudo mkfs.ext4 /dev/sdb1" +docker-machine ssh default "sudo mkdir /tmp/sdb1" +docker-machine ssh default "sudo mount /dev/sdb1 /tmp/sdb1" +docker-machine ssh default "sudo cp -ra /mnt/sda1/* /tmp/sdb1" + +docker-machine stop default + +VboxManage storageattach default --storagectl SATA --port 2 --medium none +VboxManage storageattach default --storagectl SATA --port 1 --medium build.vmdk --type hdd + +docker-machine start default +``` + +We will then finalize the setup: + +```bash +VboxManage modifyvm default --natpf1 sshredir,tcp,127.0.0.1,2222,,2222 +docker-machine ssh default "echo mkdir /sys/fs/cgroup/systemd | sudo tee /var/lib/boot2docker/bootlocal.sh" +docker-machine restart default +``` diff --git a/agl-documentation/sdk-devkit/docs/part-1/1_3-Install-agl-for-porter.md b/agl-documentation/sdk-devkit/docs/part-1/1_3-Install-agl-for-porter.md new file mode 100644 index 0000000..905eb2a --- /dev/null +++ b/agl-documentation/sdk-devkit/docs/part-1/1_3-Install-agl-for-porter.md @@ -0,0 +1,276 @@ +# Install AGL Yocto image for Porter board using Docker container + +## Overview + +This section gives details on a procedure which allows system developers +and integrators to set up a the build environment image on their local +host. + +The prepared environment is deployed and available thanks to lightweight +virtualization containers using Docker technology +(See [https://www.docker.com/](https://www.docker.com/)). +The pre-built image for AGL development activities is currently designed to be +accessed using SSH Protocol. + +## Download the docker image + +At the time of writing, we distribute the image as a compressed archive +which can be downloaded faster as its footprint is around 226 MB. You +can then import it into Docker with the following command: + +```bash +curl https://download.automotivelinux.org/AGL/snapshots/sdk/docker/docker_agl_worker-3.0.tar.xz | docker load +``` + +You can check that the new Docker image is available by running the +`docker images` command : + +```bash +$ docker images +REPOSITORY TAG IMAGE ID CREATED SIZE +docker.automotivelinux.org/agl/worker 3.0 18a6db4db383 2 months ago 925 MB +``` + +*Note*: if you want to rebuild from scratch this docker image, you should +use scripts located into `docker-worker-generator` repository. + +```bash +git clone https://gerrit.automotivelinux.org/gerrit/AGL/docker-worker-generator +``` + +Then, please refer to `README.md` file for more details. + +## Start the container + +<a id="anchor-start-container"></a> + +Once the image is available on your local host, you can start the +container and the SSH service. We'll also need a local directory on the +host to store bitbake mirrors (download cache and sstate cache): this +mirror helps to speed up builds. + +First, create a local directory and make it available to everyone: + +```bash +MIRRORDIR=<your path here, ~/mirror for example>; +mkdir -p $MIRRORDIR +chmod 777 $MIRRORDIR +``` + +Then we can start the docker image using the following command: + +```bash +docker run \ + --publish=2222:22 \ + --publish=8000:8000 \ + --publish=69:69/udp --publish=10809:10809 \ + --detach=true --privileged \ + --hostname=bsp-devkit --name=bsp-devkit \ + -v /sys/fs/cgroup:/sys/fs/cgroup:ro \ + -v $MIRRORDIR:/home/devel/mirror \ + docker.automotivelinux.org/agl/worker:3.0 +``` + +Then, you can check that the image is running with the following +command: + +```bash +$ docker ps +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +3126423788bd docker.automotivelinux.org/agl/worker:3.0 "/usr/bin/wait_for..." 2 seconds ago Up 2 seconds 0.0.0.0:2222->22/tcp, 0.0.0.0:69->69/udp, 0.0.0.0:8000->8000/tcp, 0.0.0.0:10809->10809/tcp bsp-devkit +``` + +The container is now ready to be used. A dedicated user has been +declared: + +- login: **devel** +- password: **devel** + +The following port redirections allow access to some services in the +container: + +- port 2222: SSH access using `ssh -p 2222 devel@localhost` +- port 8000: access to Toaster WebUI through [http://localhost:8000/](http://localhost:8000/) + when started (see Yocto documentation) +- ports 69 (TFTP) and 10809 (NBD): used for network boot (future enhancement) + +For easier operations, you can copy your ssh identity inside the +container: + +```bash +ssh-copy-id -p 2222 <devel@localhost> # password is 'devel' +``` + +## Connect to Yocto container through SSH + +The DevKit container provides a pre-built set of tools which can be +accessed through a terminal by using Secure Shell protocol (SSH). + +### Linux, Mac OS X © + +On Linux-based systems, you may need to install an SSH client. + +To launch the session, you can enter the following under Linux or Mac OS X: + +```bash +ssh -p 2222 devel@localhost +``` + +The password is "**devel**". You should obtain the following prompt +after success: + +```bash +devel@localhost's password: **devel** + +The programs included with the Debian GNU/Linux system are free +software; the exact distribution terms for each program are described in the +individual files in /usr/share/doc/*/copyright. + +Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent +permitted by applicable law. +[11:28:27] devel@bsp-devkit:~$ +``` + +### Windows © + +You will need *PuTTY*, downloaded during the setup +section. Run it using its icon: + +{style width:60px;} + +We can then connect to "**localhost**" on port +"**2222**". + +{style width:60%;} + +Credentials are the same as for Linux: user is "**devel**" with password +"**devel**". + +## Set up a persistent workspace + +<a id="anchor-setup-persist-wks"></a> + +AGL Docker image brings a set of tools and here we describe a way to +prepare a "shared directory" on your local host accessible from the +container. The aim of this shared directory is to allow your ongoing +developments to stay independent from the container upgrades. + +Please note this whole procedure is not mandatory, but highly +recommended as it will save disk space later when you will deploy the SD +card image on your target. + +### From Linux host using a shared directory + +Current docker implementation has a limitation about UID:GID mapping +between hosts and containers. In the long run, the planned mechanism is +to use the "user namespace" feature. But for now, we propose another +approach unfortunately less flexible. + +We can use a directory on the local host with a dedicated Unix group +using a common GID between the host and the container. This GID has been +fixed to "1664" ([see](https://en.wikipedia.org/wiki/Beer_in_France)) +and can be created on your linux host using the following commands: + +```bash +sudo groupadd --gid 1664 agl-sdk +sudo usermod -aG agl-sdk *<your-login>* +``` + +If this GID is already used on your local host, you will have to use it +for this sharing purpose as well. In case this is not possible, another +option to exchange workspace data can be the use of a network service +(like SSH, FTP) of the container and from your local host. + +Once the GID is ready to use, we can create a shared directory (not as +'root', but as your normal user): + +```bash +cd +mkdir $HOME/agl-workspace +sudo chgrp agl-sdk $HOME/agl-workspace +chmod ug+w $HOME/agl-workspace +``` + +And run the Docker image with the shared directory (new volume): + +```bash +$ docker run \ + --publish=2222:22 \ + --publish=8000:8000 \ + --publish=69:69/udp --publish=10809:10809 \ + --detach=true --privileged \ + --hostname=bsp-devkit --name=bsp-devkit \ + -v /sys/fs/cgroup:/sys/fs/cgroup:ro \ + -v $MIRRORDIR:/home/devel/mirror \ + -v $HOME/agl-workspace:/xdt/workspace \ <--- shared directory + docker.automotivelinux.org/agl/worker:3.0 +``` + +### From Windows © host using a shared directory + +We will create a shared directory for our user: + +```bash +mkdir /c/Users/$USERNAME/agl-workspace +``` + +And run the Docker image with the shared directory (new volume): + +```bash +$ docker run \ + --publish=2222:22 --publish=8000:8000 \ + --publish=69:69/udp --publish=10809:10809 \ + --detach=true --privileged --hostname=bsp-devkit \ + --name=bsp-devkit \ + -v /sys/fs/cgroup:/sys/fs/cgroup:ro \ + -v $MIRRORDIR:/home/devel/mirror \ + -v /c/Users/$USERNAME/agl-workspace:/xdt/workspace \ <--- shared directory + docker.automotivelinux.org/agl/worker:3.0 +``` + +### From the container using a remote directory (SSHFS) + +It's also possible to mount a remote directory inside the container if +the source host is running a ssh server. In that case, we will use a SSH +connection from the host to the container as a control link, and another +SSH connection from the container to the host as a data link. + +To do so, you can start the container normally as described in +[Start container chapter](#anchor-start-container), start an SSH session and +run the following commands to install the package "sshfs" inside the container: + +```bash +sudo apt-get update +sudo apt-get install -y sshfs +``` + +NB: sudo will ask for the password of the user "**devel**", which is +"**devel**". + +Now, if we want to mount the remote dir '/data/workspace' with user +'alice' on host 'computer42', then we would run: + +```bash +$ sshfs alice@computer42:/data/workspace -o nonempty $XDT_WORKSPACE +... +Password: <enter alice password on computer42> +``` + +NB: the directory on the remote machine must be owned by the remote user + +Verify that the mount is effective: + +```bash +$ df /xdt/workspace +Filesystem 1K-blocks Used Available Use% Mounted on +alice@computer42:/data/workspace 103081248 7138276 95612016 7% /xdt/workspace +``` + +From now, the files created inside the container in /xdt/workspace are +stored 'outside', in the shared directory with proper uid/gid. + +To unmount the shared directory, you can run: + +```bash +$sudo umount $XDT_WORKSPACE +``` diff --git a/agl-documentation/sdk-devkit/docs/part-1/1_4-Inside-the-container.md b/agl-documentation/sdk-devkit/docs/part-1/1_4-Inside-the-container.md new file mode 100644 index 0000000..3380b22 --- /dev/null +++ b/agl-documentation/sdk-devkit/docs/part-1/1_4-Inside-the-container.md @@ -0,0 +1,76 @@ +# Inside the container + +## Features + +Container features: + +- a Debian 8.5 based system with an SSH server listening on tcp/22, +- a dedicated user is defined to run the SSH session: **devel** + (password: **devel**) +- a script named "prepare_meta" for preparing the build environment + +## File system organization and shared volume + +The image has been designed with a dedicated file-system hierarchy. Here it is: + +```bash +devel@bsp-devkit:/$ **tree -L 2 /xdt** +/xdt +|-- build +| `-- conf +| |-- bblayers.conf +| |-- local.conf +| [snip] +|-- ccache +|-- downloads +|-- meta +| |-- agl-manifest +| |-- meta-agl +| |-- meta-agl-demo +| |-- meta-agl-extra +| |-- meta-amb +| |-- meta-intel +| |-- meta-intel-iot-security +| |-- meta-iot-agl +| |-- meta-oic +| |-- meta-openembedded +| |-- meta-qt5 +| |-- meta-renesas +| |-- meta-rust +| |-- meta-security-isafw +| `-- poky +|-- sdk +|-- sources +|-- sstate-cache +| |-- 00 +| |-- 01 +| |-- 02 +| |-- 03 +| |-- 04 +| |-- 05 +| |-- 06 +| |-- 07 + [snip] +`-- workspace +``` + +Noticeably, the BSP related features are located in the dedicated "/xdt" +directory. + +This directory contains sub-directories, and in particular the +following: + +- **build**: will contain the result of the build process, including + an image for the Porter board. +- **downloads**: (optional) contain the Yocto download cache, a + feature which will locally store the upstream projects sources codes + and which is fulfilled when an image is built for the first time. + When populated, this cache allow the user to built without any + connection to Internet. +- **meta**: contains the pre-selected Yocto layers required to built + the relevant AGL image for the Porter board. +- **sstate-cache**: (optional) contain the Yocto shared state + directory cache, a feature which store the intermediate output of + each task for each recipe of an image. This cache enhance the image + creation speed time by avoiding Yocto task to be run when they are + identical to a previous image creation. diff --git a/agl-documentation/sdk-devkit/docs/part-1/1_5-Build-image-Porter.md b/agl-documentation/sdk-devkit/docs/part-1/1_5-Build-image-Porter.md new file mode 100644 index 0000000..a13e9d3 --- /dev/null +++ b/agl-documentation/sdk-devkit/docs/part-1/1_5-Build-image-Porter.md @@ -0,0 +1,175 @@ +# Build an image for Porter board + +In this section, we will go on the image compilation for the Porter +board within the Docker container. + +## Download Renesas proprietary drivers + +For the Porter board, we first need to download the proprietary drivers +from Renesas web site. The evaluation version of these drivers can be +found here: + +[http://www.renesas.com/secret/r_car_download/rcar_demoboard.jsp](http://www.renesas.com/secret/r_car_download/rcar_demoboard.jsp) + +under the **Target hardware: R-Car H2, M2 and E2** section: + + + +Note that you have to register with a free account on MyRenesas and +accept the license conditions before downloading them. The operation is +fast and simple but nevertheless mandatory to access evaluation of non +open-source drivers for free. + +Once you register, you can download two zip files: store them in a +directory visible from the container, for example in the directory +`$MIRRORDIR/proprietary-renesas-r-car` (`$MIRRORDIR` was created +previously in section [Start the container](#anchor-start-container) and adjust +the permissions. The zip files should then be visible from the inside of the +container in `/home/devel/mirror`: + +```bash +$ chmod +r /home/devel/mirror/proprietary-renesas-r-car/*.zip +$ ls -l /home/devel/mirror/proprietary-renesas-r-car/ +total 8220 +-rw-r--r-- 1 1000 1000 6047383 Jul 11 11:03 R-Car_Series_Evaluation_Software_Package_for_Linux-20151228.zip +-rw-r--r-- 1 1000 1000 2394750 Jul 11 11:03 R-Car_Series_Evaluation_Software_Package_of_Linux_Drivers-20151228.zip +``` + +## Setup the build environment + +We should first prepare the environment to build images. + +This can be easily done thanks to a helper script named `prepare_meta`. +This script does the following: + +- check for an updated version at + [https://github.com/iotbzh/agl-manifest](https://github.com/iotbzh/agl-manifest) +- pull Yocto layers from git repositories, following a snapshot manifest +- setup build configuration (build/conf files) + +The following options are available: + +```bash +devel@bsp-devkit:~$ prepare_meta -h +prepare_meta [options] + +Options: + -f|--flavour <flavour[/tag_or_revision]> + what flavour to us + default: 'iotbzh' + possible values: 'stable','unstable','testing', 'iotbzh' ... see agl-manifest git repository + -o|--outputdir <destination_dir> + output directory where subdirectories will be created: meta, build, ... + default: current directory (.) + -l|--localmirror <directory> + specifies a local mirror directory to initialize meta, download_dir or sstate-cache + default: none + -r|--remotemirror <url> + specifies a remote mirror directory to be used at build time for download_dir or sstate-cache + default: none + -p|--proprietary <directory> + Directory containing Renesas proprietary drivers for RCar platform (2 zip files) + default: none + -e|--enable <option> + enable a specific option + available options: ccache, upgrade + -d|--disable <option> + disable a specific option + available options: ccache, upgrade + -t|--target <name> + target platform + default: porter + valid options: intel-corei7-64, qemux86, qemux86-64, wandboard + -h|--help + get this help + +Example: + prepare_meta -f iotbzh/master -o /tmp/xdt -l /ssd/mirror -p /vol/xdt/proprietary-renesas-rcar/ -t porter +``` + +In our case, we can start it with the following arguments: + +- build in `/xdt` (-o /xdt) +- build for porter board (`-t porter`) +- build the 'iotbzh' flavour (`-f iotbzh`), which contains the standard + AGL layers + security and app framework. Flavours are stored in the + agl-manifest repository. +- Use a local mirror (`-l <mirror path>`). This directory may + contain some directories generated in a previous build: `downloads`, + `sstate-cache`, `ccache`, `meta`. If found, the mirror directories + will be specified in configuration files. +- specify proprietary drivers location (`-p <drivers path>`) + +So we can run the helper script: + +```bash +devel@bsp-devkit:~$ prepare_meta -o /xdt -t porter -f rel2.0 -l /home/devel/mirror/ -p /home/devel/mirror/proprietary-renesas-r-car/ -e wipeconfig +[...] +=== setup build for porter +Using proprietary Renesas drivers for target porter +=== conf: build.conf +=== conf: download caches +=== conf: sstate caches +=== conf: local.conf +=== conf: bblayers.conf.inc -> bblayers.conf +=== conf: porter_bblayers.conf.inc -> bblayers.conf +=== conf: bblayers_proprietary.conf.inc is empty +=== conf: porter_bblayers_proprietary.conf.inc is empty +=== conf: local.conf.inc is empty +=== conf: porter_local.conf.inc is empty +=== conf: local_proprietary.conf.inc is empty +=== conf: porter_local_proprietary.conf.inc is empty +===================================================================== + +Build environment is ready. To use it, run: + +# source /xdt/meta/poky/oe-init-build-env /xdt/build + +then + +# bitbake agl-demo-platform +``` + +Now, the container shell is ready to build an image for Porter. + +## Launch the build + +To start the build, we can simply enter the indicated commands: + +```bash +devel@bsp-devkit:~$ . /xdt/build/agl-init-build-env +### Shell environment set up for builds. ### + +You can now run 'bitbake <target>' + +Common target are: + + agl-demo-platform + +devel@bsp-devkit:/xdt/build$ bitbake agl-demo-platform +[snip] +NOTE: Tasks Summary: Attempted 5108 tasks of which 4656 didn't need to +be rerun and all succeeded. + +Summary: There were 19 WARNING messages shown. +``` + +Without mirror, it will take a few hours to build all the required +component of the AGL distribution, depending on: your host machine CPU, +disk drives types and internet connection. + +## Updating the local mirror + +Optionally, at the end of the build, some directories may be synced to +the mirror dir, for future usage: + +- `/xdt/meta`: contains all layers used to build AGL +- `/xdt/downloads`: download cache (avoid fetching source from remote sites) +- `/xdt/sstate-cache`: binary build results (avoid recompiling sources) + +This can be done with the following command: + +```bash +$ for x in meta downloads sstate-cache; do rsync -Pav \ + --delete /xdt/$x /home/devel/mirror/$x; done +``` diff --git a/agl-documentation/sdk-devkit/docs/part-1/1_6-Porter-image-deployment.md b/agl-documentation/sdk-devkit/docs/part-1/1_6-Porter-image-deployment.md new file mode 100644 index 0000000..2c2bc2f --- /dev/null +++ b/agl-documentation/sdk-devkit/docs/part-1/1_6-Porter-image-deployment.md @@ -0,0 +1,257 @@ +# Porter image deployment on target + +Once the Porter image has been built with Yocto, we can deploy it on an +empty SD card to prepare its use on the target. + +## SD card image creation + +First, we need to generate an SD card disk image file. For this purpose, +a helper script is provided within the container. Here below is the way +to use it. + +### Linux, Mac OS X © + +```bash +cd /xdt/build +mksdcard /xdt/build/tmp/deploy/images/porter/agl-demo-platform-porter-20XXYYZZxxyyzz.rootfs.tar.bz2 /home/devel/mirror +``` + +### Windows © + +```bash +cd /xdt/build +sudo dd if=/dev/zero of=/sprs.img bs=1 count=1 seek=4G +sudo mkfs.ext4 /sprs.img +sudo mkdir /tmp/sprs +sudo mount /sprs.img /tmp/sprs +sudo mksdcard /xdt/build/tmp/deploy/images/porter/agl-demo-platform-porter-20XXYYZZxxyyzz.rootfs.tar.bz2 +/tmp/sprs/sdcard.img +xz -dc /tmp/sprs/sdcard.img.xz > $XDT_WORKSPACE/agl-demo-platform-porter-sdcard.img +``` + +You should get the following prompt during the `mksdcard` step: + +```bash +Creating the image agl-demo-platform-porter-sdcard.img ... +0+0 records in +0+0 records out +0 bytes (0 B) copied, 6.9187e-05 s, 0.0 kB/s +mke2fs 1.42.12 (29-Aug-2014) +Discarding device blocks: done +Creating filesystem with 524287 4k blocks and 131072 inodes +Filesystem UUID: 5307e815-9acd-480b-90fb-b246dcfb28d8 +Superblock backups stored on blocks: + 32768, 98304, 163840, 229376, 294912 + +Allocating group tables: done +Writing inode tables: done +Creating journal (8192 blocks): done +Writing superblocks and filesystem accounting information: done + +Extracting image tarball... +done + +Image agl-demo-platform-porter-sdcard.img created! + +Set the following uboot environment +setenv bootargs_console 'console=ttySC6,38400 ignore_loglevel' +setenv bootargs_video 'vmalloc=384M video=HDMI-A-1:1920x1080-32@60' +setenv bootargs_root 'root=/dev/mmcblk0p1 rootdelay=3 rw rootfstype=ext3 rootwait' +setenv bootmmc '1:1' +setenv bootcmd_sd 'ext4load mmc ${bootmmc} 0x40007fc0 boot/uImage+dtb' +setenv bootcmd 'setenv bootargs ${bootargs_console} ${bootargs_video} ${bootargs_root}; run bootcmd_sd; bootm 0x40007fc0' +saveenv + +NB: replace bootmmc value '1:1' with '0:1' or '2:1' to access the good slot + use 'ext4ls mmc XXX:1' to test access + +$ ls -lh $XDT_WORKSPACE +-rw-r--r-- 1 devel devel 2.0G Feb 15 14:13 agl-demo-platform-porter-sdcard.img + +``` + +After the disk image is created, we can copy it on the SD card itself +using an SD card adapter. To do so, we need to gain access to the SD +card image file from our host machine. + +If you already share a directory between your host machine and the +container (as described in section [Set up a persistent workspace](#anchor-setup-persist-wks)), +this state is already reached and you go directly on sections relating the SD +card image installation. + +Otherwise, you need to copy the SD card image file out of the container +and into your host machine using SSH protocol: + +- On Linux and Mac OS X hosts, you can use the `scp` command, which is part of + the OpenSSH project, +- On Windows hosts, you can use the + [`pscp.exe`](http://the.earth.li/~sgtatham/putty/latest/x86/pscp.exe) + binary, which is part of the [PuTTY project](http://www.putty.org/). + +## Deployment from a Linux or Mac OS X host + +Now that the SD card image is ready, the last step required is to +"flash" it onto the SD card itself. + +First, you need an SD card adapter connected to your host machine. +Depending on your adapter type and OS, the relevant block device can +change. Mostly, you can expect: + +- `/dev/sdX` block device; usually for external USB adapters on + Linux hosts. +- `/dev/mmcblkN`: when using a laptop internal adapter on Linux + hosts. +- `/dev/diskN`: on Mac OS X hosts. + +### Linux + +If you do not know which block device you should use, you can check the +kernel logs using the following command to figure out what is the +associated block devices: + +```bash +$ dmesg | grep mmcblk +$ dmesg | grep sd +[...snip...] +[1131831.853434] sd 6:0:0:0: [sdb] 31268864 512-byte logical blocks: (16.0 GB/14.9 GiB) +[1131831.853758] sd 6:0:0:0: [sdb] Write Protect is on +[1131831.853763] sd 6:0:0:0: [sdb] Mode Sense: 4b 00 80 08 +[1131831.854152] sd 6:0:0:0: [sdb] No Caching mode page found +[1131831.854157] sd 6:0:0:0: [sdb] Assuming drive cache: write through +[1131831.855174] sd 6:0:0:0: [sdb] No Caching mode page found +[1131831.855179] sd 6:0:0:0: [sdb] Assuming drive cache: write through +[...snip...] +$ +``` + +In this example, no `mmcblk` device where found, but a 16.0GB disk was +listed and can be accessed on **`/dev/sdb`** which in our case is the +physical SD card capacity. + +The command `lsblk` is also a good solution to explore block devices: + +```bash +$ lsblk +NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT +sda 8:0 0 931.5G 0 disk +|--sda1 8:1 0 8G 0 part / +|--sda2 8:2 0 16G 0 part [SWAP] +|--sda3 8:3 0 907.5G 0 part + |--vg0-usr 254:0 0 32G 0 lvm /usr + |--vg0-data 254:1 0 200G 0 lvm /data + |--vg0-home 254:2 0 100G 0 lvm /home + |--vg0-var 254:3 0 8G 0 lvm /var + |--vg0-docker 254:4 0 100G 0 lvm /docker +sdb 8:16 0 223.6G 0 disk +|--sdb1 8:17 0 223.6G 0 part /ssd +sdc 8:32 1 3.7G 0 disk <-- SD card plugged into USB card reader +|--sdc1 8:33 1 2G 0 part <-- +sr0 11:0 1 1024M 0 rom +``` + +In this example, the 4GB device `/dev/sdc` is listed as removable +(column RM) and corresponds to a SD Card plugged into an USB card +reader. + +Finally, as we know the block device which corresponds to our SD card, +we can raw-copy the image on it using the following command __**from your +host terminal**__ : (replace `/dev/sdZ` by the appropriate device) + +```bash +$ xzcat ~/mirror/agl-demo-platform-porter-20XXYYZZxxyyzz.raw.xz | sudo dd of=/dev/sdZ bs=1M +2048+0 records in +2048+0 records out +2147483648 bytes (2.0 GB) copied, 69 s, 39.2 MB/s +$ sync +``` + +This will take few minutes to copy and sync. You should not remove the +card from its slot until both commands succeed. + +Once it is finished, you can unplug the card and insert it in the +micro-SD card slot on the Porter board, and perform a power cycle to +start your new image on the target. + +__**NB:**__ The output format is also suitable to `bmaptool` utility (source +code available here: [https://github.com/01org/bmap-tools](https://github.com/01org/bmap-tools): +this significantly speeds up the copy as only relevant data are written on +the Sdcard (filesystem "holes" are not written). It's also supporting +direct access to URLs pointing to compressed images. + +### Mac OS X © + +If you do not know which block device you should use, you can use the +`diskutil` tool to list them: + +```bash +$ diskutil list +[...snip...] + +/dev/disk2 +#: TYPE NAME SIZE IDENTIFIER +0: Fdisk_partition_scheme 7.9 GB disk2 +1: Linux 7.9 GB disk2s1 +[...snip...] +$ +``` + +In this example, we have a 8.0GB disk which can be accessed on +**`/dev/disk2`** which in our case is the physical SD card capacity. + +Finally, as we know the block device which accesses our SD card, we can +raw-copy the image on it using the following command __from your host +terminal__: + +```bash +$ xzcat ~/mirror/agl-demo-platform-porter-20XXYYZZxxyyzz.raw.xz | sudo dd of=/dev/disk2 bs=1M +2048+0 records in +2048+0 records out +2147483648 bytes (2.0 GB) copied, 69 s, 39.2 MB/s +$ sync +``` + +This will take few minutes to copy and sync. You should not remove the +card from its slot until both commands succeed. + +Once it is finished, you can unplug the card and insert it in the +micro-SD card slot on the Porter board, and perform a power cycle to +start your new image on the target. + +## Deployment from a Windows host + +Now that the SD card image is ready, the last step required is to "flash" it +onto the SD card itself. + +First, you need an SD card adapter connected to your host machine. + +We will then use the `Win32DiskImager` program which we will download at +this URL: + +[http://sourceforge.net/projects/win32diskimager/](http://sourceforge.net/projects/win32diskimager/) + +and by clicking on this button: + + +We will then install it: + +{style width:48%; float:left; margin-right:0.3em} +{style width:48%; float:right} + +And then start it with its icon: + + +We can then click on the "blue folder" button to select our .img file +(uncompress the XZ image first using utilities like 7zip for example). + +**After having verified that the drive letter on the +right matches our SD card reader**, we click on the "**Write**" button +to start the flashing process. + + + +This will take few minutes to copy and sync. You should not remove the +card from its slot until both commands succeed. + +Once it is finished, you can unplug the card and insert it in the +micro-SD card slot on the Porter board, and perform a power cycle to +start your new image on the target. diff --git a/agl-documentation/sdk-devkit/docs/part-1/1_7-SDK-compilation-installation.md b/agl-documentation/sdk-devkit/docs/part-1/1_7-SDK-compilation-installation.md new file mode 100644 index 0000000..6fe789b --- /dev/null +++ b/agl-documentation/sdk-devkit/docs/part-1/1_7-SDK-compilation-installation.md @@ -0,0 +1,49 @@ +# AGL SDK compilation and installation + +Now that we have both a finalized development container and a deployed +Porter image, let us create and install the SDK (Software Development +Kit), so that we can develop new components for our image. + +Going back to the container, let's generate our SDK files: + +```bash +bitbake agl-demo-platform-crosssdk +``` + +This will take some time to complete. + +Alternatively, you can download a prebuilt SDK file suitable for AGL 2.0 +on automotivelinux website: + +```bash +mkdir -p /xdt/build/tmp/deploy/sdk +cd /xdt/build/tmp/deploy/sdk +wget https://download.automotivelinux.org/AGL/release/chinook/3.0.2/porter-nogfx/deploy/sdk/poky-agl-glibc-x86_64-core-image-minimal-cortexa15hf-neon-toolchain-3.0.0+snapshot.sh +``` + +Once you have the prompt again, let's install our SDK to its final +destination. For this, run the script `install_sdk` with the SDK +auto-installable archive as argument: + +```bash +install_sdk /xdt/build/tmp/deploy/sdk/poky-agl-glibc-x86_64-core-image-minimal-cortexa15hf-neon-toolchain-3.0.0+snapshot.sh +``` + +The SDK files should be now installed in `/xdt/sdk`: + +```bash +$ tree -L 2 /xdt/sdk +/xdt/sdk/ +|-- environment-setup-cortexa15hf-neon-agl-linux-gnueabi +|-- site-config-cortexa15hf-neon-agl-linux-gnueabi +|-- sysroots +| |-- cortexa15hf-neon-agl-linux-gnueabi +| |-- x86_64-aglsdk-linux +`-- version-cortexa15hf-neon-agl-linux-gnueabi +``` + +You can now use them to develop new services, and native/HTML +applications. + +Please refer to the document entitled "Build Your 1st AGL Application" +to learn how to do this. diff --git a/agl-documentation/sdk-devkit/docs/part-1/pictures/docker_install_macos_1.png b/agl-documentation/sdk-devkit/docs/part-1/pictures/docker_install_macos_1.png Binary files differnew file mode 100644 index 0000000..10036f1 --- /dev/null +++ b/agl-documentation/sdk-devkit/docs/part-1/pictures/docker_install_macos_1.png diff --git a/agl-documentation/sdk-devkit/docs/part-1/pictures/docker_install_macos_2.png b/agl-documentation/sdk-devkit/docs/part-1/pictures/docker_install_macos_2.png Binary files differnew file mode 100644 index 0000000..d720bb9 --- /dev/null +++ b/agl-documentation/sdk-devkit/docs/part-1/pictures/docker_install_macos_2.png diff --git a/agl-documentation/sdk-devkit/docs/part-1/pictures/docker_install_macos_3.png b/agl-documentation/sdk-devkit/docs/part-1/pictures/docker_install_macos_3.png Binary files differnew file mode 100644 index 0000000..5e9ec54 --- /dev/null +++ b/agl-documentation/sdk-devkit/docs/part-1/pictures/docker_install_macos_3.png diff --git a/agl-documentation/sdk-devkit/docs/part-1/pictures/docker_install_macos_4.png b/agl-documentation/sdk-devkit/docs/part-1/pictures/docker_install_macos_4.png Binary files differnew file mode 100644 index 0000000..3cf3e8e --- /dev/null +++ b/agl-documentation/sdk-devkit/docs/part-1/pictures/docker_install_macos_4.png diff --git a/agl-documentation/sdk-devkit/docs/part-1/pictures/docker_install_macos_5.png b/agl-documentation/sdk-devkit/docs/part-1/pictures/docker_install_macos_5.png Binary files differnew file mode 100644 index 0000000..d1c5b0d --- /dev/null +++ b/agl-documentation/sdk-devkit/docs/part-1/pictures/docker_install_macos_5.png diff --git a/agl-documentation/sdk-devkit/docs/part-1/pictures/docker_install_macos_6.png b/agl-documentation/sdk-devkit/docs/part-1/pictures/docker_install_macos_6.png Binary files differnew file mode 100644 index 0000000..80818e8 --- /dev/null +++ b/agl-documentation/sdk-devkit/docs/part-1/pictures/docker_install_macos_6.png diff --git a/agl-documentation/sdk-devkit/docs/part-1/pictures/docker_install_windows_1.png b/agl-documentation/sdk-devkit/docs/part-1/pictures/docker_install_windows_1.png Binary files differnew file mode 100644 index 0000000..cc412d0 --- /dev/null +++ b/agl-documentation/sdk-devkit/docs/part-1/pictures/docker_install_windows_1.png diff --git a/agl-documentation/sdk-devkit/docs/part-1/pictures/docker_install_windows_2.png b/agl-documentation/sdk-devkit/docs/part-1/pictures/docker_install_windows_2.png Binary files differnew file mode 100644 index 0000000..18ecf1a --- /dev/null +++ b/agl-documentation/sdk-devkit/docs/part-1/pictures/docker_install_windows_2.png diff --git a/agl-documentation/sdk-devkit/docs/part-1/pictures/docker_install_windows_3.png b/agl-documentation/sdk-devkit/docs/part-1/pictures/docker_install_windows_3.png Binary files differnew file mode 100644 index 0000000..29272b5 --- /dev/null +++ b/agl-documentation/sdk-devkit/docs/part-1/pictures/docker_install_windows_3.png diff --git a/agl-documentation/sdk-devkit/docs/part-1/pictures/docker_install_windows_4.png b/agl-documentation/sdk-devkit/docs/part-1/pictures/docker_install_windows_4.png Binary files differnew file mode 100644 index 0000000..1ff33e4 --- /dev/null +++ b/agl-documentation/sdk-devkit/docs/part-1/pictures/docker_install_windows_4.png diff --git a/agl-documentation/sdk-devkit/docs/part-1/pictures/docker_install_windows_5.png b/agl-documentation/sdk-devkit/docs/part-1/pictures/docker_install_windows_5.png Binary files differnew file mode 100644 index 0000000..a7f2c5b --- /dev/null +++ b/agl-documentation/sdk-devkit/docs/part-1/pictures/docker_install_windows_5.png diff --git a/agl-documentation/sdk-devkit/docs/part-1/pictures/docker_install_windows_6.png b/agl-documentation/sdk-devkit/docs/part-1/pictures/docker_install_windows_6.png Binary files differnew file mode 100644 index 0000000..685ddb9 --- /dev/null +++ b/agl-documentation/sdk-devkit/docs/part-1/pictures/docker_install_windows_6.png diff --git a/agl-documentation/sdk-devkit/docs/part-1/pictures/docker_install_windows_7.png b/agl-documentation/sdk-devkit/docs/part-1/pictures/docker_install_windows_7.png Binary files differnew file mode 100644 index 0000000..900ef44 --- /dev/null +++ b/agl-documentation/sdk-devkit/docs/part-1/pictures/docker_install_windows_7.png diff --git a/agl-documentation/sdk-devkit/docs/part-1/pictures/renesas_download.jpg b/agl-documentation/sdk-devkit/docs/part-1/pictures/renesas_download.jpg Binary files differnew file mode 100644 index 0000000..a4bdc29 --- /dev/null +++ b/agl-documentation/sdk-devkit/docs/part-1/pictures/renesas_download.jpg diff --git a/agl-documentation/sdk-devkit/docs/part-1/pictures/windows_putty_1.png b/agl-documentation/sdk-devkit/docs/part-1/pictures/windows_putty_1.png Binary files differnew file mode 100644 index 0000000..ecae750 --- /dev/null +++ b/agl-documentation/sdk-devkit/docs/part-1/pictures/windows_putty_1.png diff --git a/agl-documentation/sdk-devkit/docs/part-1/pictures/windows_putty_2.png b/agl-documentation/sdk-devkit/docs/part-1/pictures/windows_putty_2.png Binary files differnew file mode 100644 index 0000000..09ecd52 --- /dev/null +++ b/agl-documentation/sdk-devkit/docs/part-1/pictures/windows_putty_2.png diff --git a/agl-documentation/sdk-devkit/docs/part-1/pictures/windows_win32diskimager_1.png b/agl-documentation/sdk-devkit/docs/part-1/pictures/windows_win32diskimager_1.png Binary files differnew file mode 100644 index 0000000..2276c5b --- /dev/null +++ b/agl-documentation/sdk-devkit/docs/part-1/pictures/windows_win32diskimager_1.png diff --git a/agl-documentation/sdk-devkit/docs/part-1/pictures/windows_win32diskimager_2.png b/agl-documentation/sdk-devkit/docs/part-1/pictures/windows_win32diskimager_2.png Binary files differnew file mode 100644 index 0000000..2485849 --- /dev/null +++ b/agl-documentation/sdk-devkit/docs/part-1/pictures/windows_win32diskimager_2.png diff --git a/agl-documentation/sdk-devkit/docs/part-1/pictures/windows_win32diskimager_3.png b/agl-documentation/sdk-devkit/docs/part-1/pictures/windows_win32diskimager_3.png Binary files differnew file mode 100644 index 0000000..38d94e3 --- /dev/null +++ b/agl-documentation/sdk-devkit/docs/part-1/pictures/windows_win32diskimager_3.png diff --git a/agl-documentation/sdk-devkit/docs/part-1/pictures/windows_win32diskimager_4.png b/agl-documentation/sdk-devkit/docs/part-1/pictures/windows_win32diskimager_4.png Binary files differnew file mode 100644 index 0000000..68a5fa6 --- /dev/null +++ b/agl-documentation/sdk-devkit/docs/part-1/pictures/windows_win32diskimager_4.png diff --git a/agl-documentation/sdk-devkit/docs/part-1/pictures/windows_win32diskimager_5.png b/agl-documentation/sdk-devkit/docs/part-1/pictures/windows_win32diskimager_5.png Binary files differnew file mode 100644 index 0000000..e4aade2 --- /dev/null +++ b/agl-documentation/sdk-devkit/docs/part-1/pictures/windows_win32diskimager_5.png |
