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=ext3;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 4. (Optional) This is how to test and play multimedia contents with acceleration.
 356
 357     1. Boot porter without mouse and keyboard, it avoid to boot weston automatically.
 358        For now, when running weston, V4L2 deosn't work correctly, so we have to
 359        stop weston first (GST plugin `waylandsink` also doesn't work correctly for now).
 360
 361     2. Execute these instructions
 362
 363             # Set the mixer
 364 >     $ export LD_LIBRARY_PATH="/lib:/usr/lib:/usr/local/lib:"^
 365
 366             # Set the mixer
 367 >     $ amixer set "LINEOUT Mixer DACL" on
 368 >     $ amixer set "DVC Out" 10
 369 >
 370 >     $ modprobe -a mmngr mmngrbuf s3ctl uvcs_cmn vspm fdpm
 371 >
 372 >     $ media-ctl -d /dev/media0 -r
 373 >     $ media-ctl -d /dev/media0 -l '"vsp1.2 rpf.0":1 -> "vsp1.2 uds.0":0 [1]'
 374 >     $ media-ctl -d /dev/media0 -l '"vsp1.2 uds.0":1 -> "vsp1.2 wpf.0":0 [1]'
 375 >     $ media-ctl -d /dev/media0 -l '"vsp1.2 wpf.0":1 -> "vsp1.2 lif":0 [1]'
 376 >     $ media-ctl -d /dev/media0 -V '"vsp1.2 rpf.0":0 [fmt:AYUV32/1920x1080]'
 377 >     $ media-ctl -d /dev/media0 -V '"vsp1.2 rpf.0":1 [fmt:AYUV32/1920x1080]'
 378 >     $ media-ctl -d /dev/media0 -V '"vsp1.2 uds.0":0 [fmt:AYUV32/1920x1080]'
 379 >     $ media-ctl -d /dev/media0 -V '"vsp1.2 uds.0":1 [fmt:AYUV32/640x480]'
 380 >     $ media-ctl -d /dev/media0 -V '"vsp1.2 wpf.0":0 [fmt:AYUV32/640x480]'
 381 >     $ media-ctl -d /dev/media0 -V '"vsp1.2 wpf.0":1 [fmt:ARGB32/640x480]'
 382 >     $ media-ctl -d /dev/media0 -V '"vsp1.2 lif":0 [fmt:ARGB32/640x480]'
 383 >
 384 >                 # in case R-Car M2 (HDMI - DU1 - vspd0)
 385 >                 $ modetest -M rcar-du -s 10@8:1280x720@AR24 -d -P '8@19:640x480+100+200@XR24' &
 386
 387 After these command, Test pattern will show on display connected to porter's HDMI port.
 388
 389 Then, you can play H264(MP4) movie like this:
 390
 391 >     $ gst-launch-1.0 filesrc location=./sample.mp4  ! qtdemux name=d d. ! \
 392 >            queue ! omxh264dec no-copy=true ! v4l2sink device=/dev/video1 \
 393 >            io-mode=userptr d. ! queue ! faad ! alsasink device=hw:0,0
 394
 395
 396 ### Deployment (TFTP/NFS)
 397
 398 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.
 399
 400 #### Instructions on the host
 401 1. Setup a TFTP server
 402    1. Install necessary packages
 403          >     $ sudo apt-get install tftp tftpd-hpa
 404
 405    2. Go to build directory, and copy kernel and DTB into TFTP server root (default server dir: /srv/tftp)
 406          >     $cd  $AGL_TOP/build/tmp/deploy/images/porter
 407          >     $ sudo cp uImage uImage-r8a7791-porter.dtb /srv/tftp
 408
 409    3. Verify TFTP server is working
 410          >     $ ls uImage
 411            ls: cannot access uImage: No such file or directory
 412
 413          >     $ cd /tmp/
 414          >     $ tftp 192.168.30.70
 415          >     tftp> get uImage
 416          >     Received 3583604 bytes in 0.2 seconds
 417          >     tftp> q
 418          >     $ ls uImage
 419          >     uImage
 420
 421 2. set NFS server
 422    1. Install necessary packages
 423          >     $ sudo apt-get install nfs-kernel-server nfs-common
 424
 425    2. Go to build directory, and extract the root file system into a dedicated directory (here we use /nfs/porter)
 426          >     $ cd $AGL_TOP/build/tmp/deploy/images/porter
 427          >     $ sudo mkdir -p /nfs/porter
 428          >      $ sudo tar --extract --numeric-owner --preserve-permissions --preserve-order \
 429          >       --totals --directory=/nfs/porter --file=agl-demo-platform-porter.tar.bz2
 430
 431    3. Edit /etc/exports
 432          >     $ sudo vi /etc/exports
 433          Add
 434          >
 435          >     /nfs/porter      *(rw,no_subtree_check,sync,no_root_squash,no_all_squash)
 436          >
 437         Save the file and exit.
 438
 439    4. Restart nfs service
 440          >     $ sudo service nfs-kernel-server restart
 441
 442    5. Verify NFS server is working
 443          >     $ sudo mount -t nfs 192.168.30.70:/nfs/porter /tmp/
 444          >     $ ls /tmp
 445          >     bin  boot  dev  etc  home  lib  media  mnt  proc  run  sbin  sys  tmp  usr  var
 446
 447 #### Instructions on the target board
 448
 449 NOTE: There is details about porter board [here](http://elinux.org/R-Car/Boards/Porter).
 450
 451 NOTE: To boot weston on porter board, we need keyboard and mouse. (USB2.0 can be use for this)
 452
 453 ##### Change U-Boot parameters to boot from TFTP/NFS
 454
 455 1. Power up the board and, using your preferred terminal emulator, stop the board's autoboot by hitting any key.
 456
 457   > Debug serial settings are 38400 8N1. Any standard terminal emulator program can be used.
 458
 459 2. Set the follow environment variables and save them
 460 >     => setenv ipaddr <board-ip>
 461 >     => setenv serverip <host-ip>
 462 >     => setenv bootargs_console console=ttySC6,${baudrate}
 463 >     => setenv bootargs_video vmalloc=384M video=HDMI-A-1:1024x768-32@60
 464 >     => setenv bootcmd_net 'tftp 0x40007fc0 uImage; tftp 0x40f00000 uImage-r8a7791-porter.dtb'
 465 >     => 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'
 466 >     => saveenv
 467
 468     Replace <board-ip> with a proper IP address for the board, like 192.168.30.60.
 469     Replace <host-ip> with the IP address of the host, here we use 192.168.30.70.
 470
 471 ##### Boot from TFTP/NFS
 472
 473 1. After board reset, U-Boot is started and after a countdown, ...
 474    Linux boot message should be displayed. Please wait a moment.
 475 2. Then weston is booted automatically, and weston-terminal appears.
 476 3. Have fun! :)
 477