Move DISTRO_VERSION to 5.0.2
[AGL/meta-agl.git] / 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