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