README-AGL.md

   1 ?README-AGL.md: The Automotive Grade Linux Distribution
   2 ======================================================
   3
   4 AGL is creating an automotive specific Linux distribution (AGL UCB)
   5 that unifies the software that has been written in a number of places already,
   6 such as GENIVI and Tizen IVI.
   7
   8 The layer 'meta-agl' provides a minimal set of software
   9 to boot system of AGL Distribution. 'meta-agl' is the minimal
  10 core which is used build AGL profiles on top of it.
  11
  12 The reference UI is part of 'meta-agl-demo'.
  13
  14 Additional components like the security framework are part of 'meta-agl-extra'.
  15
  16 The AGL community appreciates feedback, ideas, suggestion, bugs and
  17 documentation just as much as code. Please join the irc conversation
  18 at the #automotive channel on irc.freenode.net and our mailing list.
  19
  20 For infomation for subscribing to the mailing list
  21     [automotive-discussions](http://lists.linuxfoundation.org/mailman/listinfo/automotive-discussions)
  22 For information about AGL Distribution, see the
  23     [AGL Distribution](https://wiki.automotivelinux.org/agl-distro)
  24 For information abount Getting started with AGL
  25     [here](https://wiki.automotivelinux.org/start/getting-started)
  26 For information about contributing to the AGL Distro
  27     [here](https://wiki.automotivelinux.org/agl-distro/contributing)
  28
  29 Quick start guide
  30 -----------------
  31
  32 The latest version is available at [AGL wiki](https://wiki.automotivelinux.org/agl-distro/source-code) for the following targets:
  33 * [QEMU](https://wiki.automotivelinux.org/agl-distro/source-code)
  34 * [Renesas Porter board](https://wiki.automotivelinux.org/start/building_for_the_renesas_r-car_m2)
  35 * [Raspberry Pi 2/3](https://wiki.automotivelinux.org/agl-distro/agl-raspberrypi)
  36
  37 To build an image from 'meta-agl'
  38
  39 1. Prepare repo:
  40      >      $ mkdir ~/bin
  41      >      $ export PATH=~/bin:$PATH
  42      >      $ curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
  43      >      $ chmod a+x ~/bin/repo
  44
  45 2. Get all layers:
  46      >      $ repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo
  47      >      $ repo sync
  48
  49 3. Check available targets and extensions, select target machine:
  50      >      $ source meta-agl/scripts/aglsetup.sh -h
  51      >      $ source meta-agl/scripts/aglsetup.sh -m porter
  52
  53 4. Build agl-image-ivi
  54      >      $ bitbake agl-image-ivi
  55
  56 To build the agl-demo-platform (as demo'ed @ALS) replace 3. and 4. with:
  57 3. Check available targets and extensions, select target machine:
  58      >      $ source meta-agl/scripts/aglsetup.sh -h
  59      >      $ source meta-agl/scripts/aglsetup.sh -m porter agl-demo [agl-appfw-smack] [agl-devel] [agl-netboot]
  60
  61 4. Build agl-demo-platform
  62      >      $ bitbake agl-demo-platform
  63 Note: this uses more layers and not only meta-agl
  64
  65 AGL Layers and dependencies:
  66 ----------------------------
  67 Check the README.md of the respective layers:
  68 - meta-agl              (= core, no UI)
  69 - meta-agl-demo    (= reference UI)
  70 - meta-agl-extra     (= extra components)
  71
  72 In addition, the reference hardware (Renesas R-Car Gen2 / porter) has this dependency:
  73
  74 URI: https://gerrit.automotivelinux.org/gerrit/AGL/meta-renesas
  75 > branch:   agl-1.0-bsp-1.8.0
  76 > tested revision: 82611ccadef36ab0b8a6fd6fb1cf055e115f1ef5
  77
  78
  79 Supported Machines
  80 ------------------
  81
  82 Reference hardware:
  83
  84 * QEMU (x86-64) - emulated machine: qemux86-64
  85 * Renesas R-Car Gen2 (R-Car M2) - machine: porter
  86
  87 Community contributed hardware:
  88
  89 * See: https://wiki.automotivelinux.org/agl-distro#supported_hardware
  90
  91
  92 Supported Target of bitbake
  93 ---------------------------
  94
  95 meta-agl:
  96
  97 * `agl-image-ivi` The baseline image of AGL Distributions (console only)
  98
  99 * `agl-image-minimal` For internal use to develop distribution (experimental)
 100 * `agl-image-weston`  For internal use to develop distribution (experimental)
 101
 102 meta-agl-demo:
 103
 104 * `agl-demo-platform` The demo/reference image (with graphical UI)
 105
 106 Run this command for a full list of machines, features and targets:
 107      >       $ source ./meta-agl/scripts/aglsetup.sh -h
 108
 109
 110 Supposed Directory Tree of Layers to build
 111 -------------------------------------------
 112
 113      >      $ repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo
 114      >      $ repo sync
 115      >      $ tree -L 1
 116         .
 117         |-- meta-agl
 118         |-- meta-agl-demo
 119         |-- meta-agl-devel
 120         |-- meta-agl-extra
 121         |-- meta-amb
 122         |-- meta-fsl-arm
 123         |-- meta-fsl-arm-extra
 124         |-- meta-intel
 125         |-- meta-intel-iot-security
 126         |-- meta-openembedded
 127         |-- meta-qcom
 128         |-- meta-qt5
 129         |-- meta-raspberrypi
 130         |-- meta-renesas
 131         |-- meta-rust
 132         |-- meta-security-isafw
 133         |-- meta-ti
 134         `-- poky
 135         18 directories, 0 files
 136
 137
 138 Build a QEMU image
 139 ------------------
 140
 141 You can build a QEMU image using the following steps:
 142
 143 (latest version here: https://wiki.automotivelinux.org/agl-distro/source-code)
 144 To build an image from 'meta-agl'
 145
 146 1. Prepare repo:
 147      >      $ mkdir ~/bin
 148      >      $ export PATH=~/bin:$PATH
 149      >      $ curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
 150      >      $ chmod a+x ~/bin/repo
 151
 152 2. Get all layers:
 153      >      $ repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo
 154      >      $ repo sync
 155
 156 3. Check available targets and extensions, select target machine:
 157      >      $ source meta-agl/scripts/aglsetup.sh -h
 158      >      $ source meta-agl/scripts/aglsetup.sh -m qemux86-64
 159
 160   Alternatively, to enable the reference UI feature ('agl-demo'):
 161      >      $ source meta-agl/scripts/aglsetup.sh -m qemux86-64 agl-demo
 162
 163   Alternatively, to also enable also the security framework ('agl-appfw-smack'):
 164      >      $ source meta-agl/scripts/aglsetup.sh -m qemux86-64 agl-demo agl agl-appfw-smack
 165
 166   Alternatively, to also enable debugging tools ('agl-devel') and the network-boot (nbd) capabilities ('agl-netboot'):
 167      >      $ source meta-agl/scripts/aglsetup.sh -m qemux86-64 agl-demo agl agl-appfw-smack agl-devel agl-netboot
 168
 169 4. Build agl-image-ivi
 170      >      $ bitbake agl-image-ivi
 171
 172   or alternatively, if you enabled the 'agl-demo' feature:
 173      >      $ bitbake agl-demo-platform
 174
 175  - If you want to run QEMU directly as VM in Virtual Box or your other favorite VM software then add this line to your "conf/local.conf" file.
 176      >      IMAGE_FSTYPES += "vmdk"
 177
 178 5. Run in the emulator
 179      >      $ runqemu agl-image-ivi qemux86-64
 180      >      or
 181      >      $ runqemu agl-demo-platform qemux86-64
 182
 183    For a large screen:
 184      >      $ runqemu agl-image-ivi qemux86-64 bootparams="uvesafb.mode_option=1280x720-32"
 185
 186    To extend the amount of memory, add to runqemu:
 187      qemuparams="-m 512"
 188      >      $ runqemu agl-image-ivi qemux86-64 qemuparame="-m 512" bootparams="uvesafb.mode_option=1280x720-32"
 189
 190
 191    To separate console from VGA screen (to avoid corrupt screen while booting),
 192    add to runqemu:
 193      serial
 194      >      $ runqemu agl-image-ivi qemux86-64 bootparams="uvesafb.mode_option=1280x720-32" serial
 195
 196         **Or use the virtual disk in Virtual Box from this location:**
 197         > tmp/deploy/images/qemux86-64/agl-demo-platform-qemux86-64.vmdk
 198
 199 6.  Some weston samples are available from weston terminal (click top left icon).
 200    Check the folder `/opt/AGL/ALS2016`.
 201
 202 Build a R-Car M2 (porter) image
 203 -------------------------------
 204
 205 ### Software setup
 206
 207 NOTE: You will need to download the matching binary driver package from renesas.
 208       As of this writing, the version from 20151228.
 209       The main URL to retrieve these is:
 210
 211  -   https://www.renesas.com/en-eu/solutions/automotive/rcar-demoboard.html
 212
 213       As of this writing, the necessary libary and driver packages linked to
 214       by above site are:
 215       - The subpage for the library is:
 216               - https://www.renesas.com/en-eu/software/D3017410.html (registration/login required)
 217
 218       - The sub-page for the driver is:
 219               - https://www.renesas.com/en-eu/media/secret/solutions/automotive/rcar-demoboard/R-Car_Series_Evaluation_Software_Package_of_Linux_Drivers-20151228.zip
 220
 221       !!! The files need to be in `${HOME}/Downloads` ( `$XDG_DOWNLOAD_DIR` ) !!!
 222
 223 #### Getting Source Code and Build image
 224
 225 (latest version here: https://wiki.automotivelinux.org/agl-distro/source-code)
 226 To build an image from 'meta-agl' only:
 227
 228 1. Prepare repo:
 229      >      $ mkdir ~/bin
 230      >      $ export PATH=~/bin:$PATH
 231      >      $ curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
 232      >      $ chmod a+x ~/bin/repo
 233
 234 2. Get all layers:
 235      >      $ repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo
 236      >      $ repo sync
 237
 238 3. Check available targets and extensions, select target machine:
 239      >      $ source meta-agl/scripts/aglsetup.sh -h
 240      >      $ source meta-agl/scripts/aglsetup.sh -m porter
 241
 242   Alternatively, to enable the reference UI:
 243      >      $ source meta-agl/scripts/aglsetup.sh -m porter agl-demo
 244
 245   Alternatively, to also enable also the security framework:
 246      >      $ source meta-agl/scripts/aglsetup.sh -m porter agl-demo agl agl-appfw-smack
 247
 248   Alternatively, to also enable debugging tools and the network-boot (nbd) capabilities:
 249      >      $ source meta-agl/scripts/aglsetup.sh -m porter agl-demo agl agl-appfw-smack agl-devel agl-netboot
 250
 251 4. (optional) edit conf/local.conf   )* see below
 252      >        $ vi conf/local.conf
 253
 254 5. Build agl-image-ivi
 255      >        $ bitbake agl-image-ivi
 256
 257   or alternatively, if you enabled the 'agl-demo' feature:
 258      >      $ bitbake agl-demo-platform
 259
 260
 261 )* :
 262
 263  4 .  Optional edits to conf/local.conf
 264
 265  *  If you want to use multimedia accelerations, uncomment
 266     manually 4 `IMAGE_INSTALL_append_porter` in conf/local.conf.
 267
 268     >     #IMAGE_INSTALL_append_porter = " \
 269     >     #    gstreamer1.0-plugins-bad-waylandsink \
 270     >     #    "
 271     >     #IMAGE_INSTALL_append_porter = " \
 272     >     #    gstreamer1.0-plugins-base-videorate \
 273     >     ...
 274     >     #"
 275     >     #IMAGE_INSTALL_append_porter = " \
 276     >     #    libegl libegl-dev libgbm-dev \
 277     >     ...
 278     >     #    "
 279     >     #IMAGE_INSTALL_append_porter = " \
 280     >     #    packagegroup-rcar-gen2-multimedia \
 281     >     ...
 282     >     #    "
 283
 284 * Also it is needed to uncomment this:
 285     >     #MACHINE_FEATURES_append = " multimedia"
 286
 287    This `multimedia` MACHINE_FEATURES enables the meta-renesas's specific multimedia configuration.
 288    The version of GStreamer1.0 which AGL distro will use is changed
 289    to 1.2.3 (meta-renesas prefers it) over 1.4.1 (meta-agl default)
 290    by this switch.
 291
 292 * If you want to install various Qt5 examples, add below
 293    configuration to your local.conf.
 294 >      IMAGE_INSTALL_append = " \
 295 >            packagegroup-agl-demo-qt-examples \
 296 >        "
 297 >        PACKAGECONFIG_append_pn-qtbase = " examples"
 298 >
 299 >  IMPORTANT NOTE:
 300 >        To run examples with wayland-egl plugin,
 301 >        use ``LD_PRELOAD=/usr/lib/libEGL.so <command>``.
 302 >        If not, programs should not launch by error,
 303 >        'EGL not available'.
 304
 305
 306 ### Deployment (SDCARD)
 307
 308 #### Instructions on the host
 309
 310 1. Format SD-Card and then, create single EXT4 partition on it.
 311
 312 2. Mount the SD-Card, for example `/media/$SDCARD_LABEL`.
 313
 314 3. Copy AGL root file system onto the SD-Card
 315    1. Go to build directory
 316          >     $ cd $AGL_TOP/build/tmp/deploy/images/porter
 317
 318    2. Extract the root file system into the SD-Card
 319          >     $ sudo tar --extract --numeric-owner --preserve-permissions --preserve-order \
 320          >                --totals --directory=/media/$SDCARD_LABEL --file=agl-image-ivi-porter.tar.bz2
 321
 322    3. Copy kernel and DTB into the `/boot` of the SD-Card
 323          >     $ sudo cp uImage uImage-r8a7791-porter.dtb /media/$SDCARD_LABEL/boot
 324
 325 4. After the copy finished, unmount SD-Card and insert it into the SD-Card slot of the porter board.
 326
 327 #### Instructions on the target
 328
 329 NOTE: There is details about porter board [here](http://elinux.org/R-Car/Boards/Porter).
 330
 331 NOTE: To boot weston on porter board, we need keyboard and mouse. (USB2.0 can be use for this)
 332
 333 ##### Change U-Boot parameters to boot from SD card
 334
 335 1. Power up the board and, using your preferred terminal emulator, stop the board's autoboot by hitting any key.
 336
 337   ``Debug serial settings are 38400 8N1. Any standard terminal emulator program can be used.**
 338
 339 2. Set the follow environment variables and save them
 340 >     => setenv bootargs_console console=ttySC6,${baudrate}
 341 >     => setenv bootargs_video vmalloc=384M video=HDMI-A-1:1024x768-32@60
 342 >     => setenv bootcmd_sd 'ext4load mmc 0:1 0x40007fc0 boot/uImage;ext4load mmc 0:1 0x40f00000 boot/uImage-r8a7791-porter.dtb'
 343 >     => setenv bootcmd 'setenv bootargs ${bootargs_console} ${bootargs_video} root=/dev/mmcblk0p1 rw rootfstype=ext4;run bootcmd_sd;bootm 0x40007fc0 - 0x40f00000'
 344 >     => saveenv
 345
 346 ##### Boot from SD card
 347
 348 1. After board reset, U-Boot is started and after a countdown, ...
 349    Linux boot message should be displayed. Please wait a moment.
 350
 351 2. Then weston is booted automatically, and weston-terminal appears.
 352
 353 3. Have fun! :)
 354
 355 ### Deployment (TFTP/NFS)
 356
 357 NOTE: These instructions are based on Embedded Linux Wiki, [here](http://www.elinux.org/R-Car/Boards/Yocto#Loading_kernel_via_TFTP_and_rootfs_via_NFS). And a Debian (wheezy, ip: 192.168.30.70) is used as the host for this instructions.
 358
 359 #### Instructions on the host
 360 1. Setup a TFTP server
 361    1. Install necessary packages
 362          >     $ sudo apt-get install tftp tftpd-hpa
 363
 364    2. Go to build directory, and copy kernel and DTB into TFTP server root (default server dir: /srv/tftp)
 365          >     $cd  $AGL_TOP/build/tmp/deploy/images/porter
 366          >     $ sudo cp uImage uImage-r8a7791-porter.dtb /srv/tftp
 367
 368    3. Verify TFTP server is working
 369          >     $ ls uImage
 370            ls: cannot access uImage: No such file or directory
 371
 372          >     $ cd /tmp/
 373          >     $ tftp 192.168.30.70
 374          >     tftp> get uImage
 375          >     Received 3583604 bytes in 0.2 seconds
 376          >     tftp> q
 377          >     $ ls uImage
 378          >     uImage
 379
 380 2. set NFS server
 381    1. Install necessary packages
 382          >     $ sudo apt-get install nfs-kernel-server nfs-common
 383
 384    2. Go to build directory, and extract the root file system into a dedicated directory (here we use /nfs/porter)
 385          >     $ cd $AGL_TOP/build/tmp/deploy/images/porter
 386          >     $ sudo mkdir -p /nfs/porter
 387          >      $ sudo tar --extract --numeric-owner --preserve-permissions --preserve-order \
 388          >       --totals --directory=/nfs/porter --file=agl-demo-platform-porter.tar.bz2
 389
 390    3. Edit /etc/exports
 391          >     $ sudo vi /etc/exports
 392          Add
 393          >
 394          >     /nfs/porter      *(rw,no_subtree_check,sync,no_root_squash,no_all_squash)
 395          >
 396         Save the file and exit.
 397
 398    4. Restart nfs service
 399          >     $ sudo service nfs-kernel-server restart
 400
 401    5. Verify NFS server is working
 402          >     $ sudo mount -t nfs 192.168.30.70:/nfs/porter /tmp/
 403          >     $ ls /tmp
 404          >     bin  boot  dev  etc  home  lib  media  mnt  proc  run  sbin  sys  tmp  usr  var
 405
 406 #### Instructions on the target board
 407
 408 NOTE: There is details about porter board [here](http://elinux.org/R-Car/Boards/Porter).
 409
 410 NOTE: To boot weston on porter board, we need keyboard and mouse. (USB2.0 can be use for this)
 411
 412 ##### Change U-Boot parameters to boot from TFTP/NFS
 413
 414 1. Power up the board and, using your preferred terminal emulator, stop the board's autoboot by hitting any key.
 415
 416   > Debug serial settings are 38400 8N1. Any standard terminal emulator program can be used.
 417
 418 2. Set the follow environment variables and save them
 419 >     => setenv ipaddr <board-ip>
 420 >     => setenv serverip <host-ip>
 421 >     => setenv bootargs_console console=ttySC6,${baudrate}
 422 >     => setenv bootargs_video vmalloc=384M video=HDMI-A-1:1024x768-32@60
 423 >     => setenv bootcmd_net 'tftp 0x40007fc0 uImage; tftp 0x40f00000 uImage-r8a7791-porter.dtb'
 424 >     => setenv bootcmd 'setenv bootargs ${bootargs_console} ${bootargs_video} ip=${ipaddr} root=/dev/nfs nfsroot=${serverip}:/nfs/porter,vers=3;run bootcmd_net;bootm 0x40007fc0 - 0x40f00000'
 425 >     => saveenv
 426
 427     Replace <board-ip> with a proper IP address for the board, like 192.168.30.60.
 428     Replace <host-ip> with the IP address of the host, here we use 192.168.30.70.
 429
 430 ##### Boot from TFTP/NFS
 431
 432 1. After board reset, U-Boot is started and after a countdown, ...
 433    Linux boot message should be displayed. Please wait a moment.
 434 2. Then weston is booted automatically, and weston-terminal appears.
 435 3. Have fun! :)
 436