diff options
25 files changed, 938 insertions, 754 deletions
diff --git a/app-framework/index.md b/app-framework/index.md index f69b2ba..5690fda 100644 --- a/app-framework/index.md +++ b/app-framework/index.md @@ -47,7 +47,6 @@ Some bindings are available to quickstart new projects: The list is not exhaustive. ***Please add other bindings here !*** - ### Demos * Simple HTML5 Demos apps (ported from Tizen) on [github:iotbzh/afm-widget-examples](https://github.com/iotbzh/afm-widget-examples) @@ -72,11 +71,8 @@ To get the background and motivation on why Application Framework has been rewri * [this discussion](https://lists.linuxfoundation.org/pipermail/automotive-discussions/2016-October/002749.html) * [Linux Automotive Security](http://iot.bzh/download/public/2016/security/Linux-Automotive-Security-v10.pdf) - ### Comparison/Relationship with Tizen - - Tizen AGL ---------------------------------- App/OS isolation yes yes @@ -88,5 +84,3 @@ To get the background and motivation on why Application Framework has been rewri service as App** No yes Adding API *** core core or App Devel model bespoke Standard Web - - diff --git a/getting-started/customize_bitbake_conf.md b/getting-started/customize_bitbake_conf.md index dc7dc6b..fa466ca 100644 --- a/getting-started/customize_bitbake_conf.md +++ b/getting-started/customize_bitbake_conf.md @@ -1,14 +1,16 @@ # Customize AGL build + To customize the AGL build, you edit local.conf file, located in the build/conf directory. -``` +```bash edit $AGL_TOP/build/conf/local.conf ``` ## Buildhistory + The OpenEmbedded build system creates this directory when you enable the build history feature. -``` +```bash INHERIT += "buildhistory" BUILDHISTORY_COMMIT = "1" ``` @@ -16,27 +18,30 @@ BUILDHISTORY_COMMIT = "1" For more information please check [Here][buildhistory] ## Deletion of temporary workspace + Removes work files after the OpenEmbedded build system has finished with them. -``` +```bash INHERIT += "rm_work" ``` For more information please check [Here][rm_work] ## Share sstate cache + The directory for the shared state cache. -``` +```bash SSTATE_DIR = "${HOME}/workspace_agl/sstate-cache" ``` For more information please check [Here][share_sstatecache] ## Share Download directory + The central download directory used by the build process to store downloads. -``` +```bash DL_DIR = "${HOME}/workspace_agl/downloads" ``` diff --git a/getting-started/footers/intel-footer.md b/getting-started/footers/intel-footer.md index 191ff98..0c75128 100644 --- a/getting-started/footers/intel-footer.md +++ b/getting-started/footers/intel-footer.md @@ -1,47 +1,52 @@ ## BIOS update -Both the Joule and the Minnowboard require a BIOS upgrade. **Don t loose time trying without.**<br> -https://firmware.intel.com/projects/minnowboard-max<br> -https://software.intel.com/en-us/flashing-the-bios-on-joule + +Both the Joule and the Minnowboard require a BIOS upgrade. **Don t loose time trying without.** +<https://firmware.intel.com/projects/minnowboard-max> +<https://software.intel.com/en-us/flashing-the-bios-on-joule> ## Creating a bootable image -Multiple options are avaiable but dd and tar can very easily let you down due to the requirement to pass SMACK labels, create a proper UEFI configuration and a few other tricks.<br> -The script [mkefi-agl.sh](https://github.com/dominig/mkefi-agl.sh) has been done to help you.<br> -The option -h will print the help and the option -v will detailled the operation and ease any debug.<br> - -## Selecting the SD or USB to boot. -When booting a Minnowboard or a Joule you can change the default boot device by hitting F2 during initial UEFI boot. -It's easier to acheive it in the right time with a USB keyboard than via serial link. -During boot USB hub are not supported, you need to connect the keyboard directly in the USB socket.<br> -It's also preferable to use F9 and to change the boot order once for all.<br> + +Multiple options are avaiable but dd and tar can very easily let you down due to the requirement to pass SMACK labels, create a proper UEFI configuration and a few other tricks. +The script [mkefi-agl.sh](https://github.com/dominig/mkefi-agl.sh) has been done to help you. +The option -h will print the help and the option -v will detailled the operation and ease any debug. + +## Selecting the SD or USB to boot + +When booting a Minnowboard or a Joule you can change the default boot device by hitting F2 during initial UEFI boot. +It's easier to acheive it in the right time with a USB keyboard than via serial link. +During boot USB hub are not supported, you need to connect the keyboard directly in the USB socket. +It's also preferable to use F9 and to change the boot order once for all. Please note: You can only change the boot order, when a valid device is inserted in the corresponding port (USB or SD). -The Minnow, Joule, many laptops and NUCs will not accept to boot with some USB3 stick. If you have some trouble to get your USB3 stick detected during boot, swap it for a USB2. In anycase working with SD card is faster to flash and to boot. SD should be prefered.<br> +The Minnow, Joule, many laptops and NUCs will not accept to boot with some USB3 stick. If you have some trouble to get your USB3 stick detected during boot, swap it for a USB2. In anycase working with SD card is faster to flash and to boot. SD should be prefered. The Joule seems to refuse to boot with my SD-HC-I type cards while I had no problem with the Minnow. If you work with a Joule, use regular SD-HC (mode 4 and 10 work fine) - ## Serial debug Port -Serial debug port ID varies with the HW platform :<br> -By default AGL build Intel target as a Minnowboard where serial is /dev/ttyS0 <br> -On Joule and MRB the serial debug is /dev/ttyS2 <br> +Serial debug port ID varies with the HW platform : +By default AGL build Intel target as a Minnowboard where serial is /dev/ttyS0 +On Joule and MRB the serial debug is /dev/ttyS2 You may have to change the configuration in your boot loader which is located in the EFI partition. ## Serial debug cable -On the Minnowboard the serial cable is a FTDI serial cable. The wiring can be found [here](http://wiki.minnowboard.org/MinnowBoard_MAX_HW_Setup).<br> -On the Joule the serial connection is done via the micro USB cable which is not provided in the Developer kit. Details can be found [here](https://software.intel.com/en-us/node/667851).<br> +On the Minnowboard the serial cable is a FTDI serial cable. The wiring can be found [here](http://wiki.minnowboard.org/MinnowBoard_MAX_HW_Setup). +On the Joule the serial connection is done via the micro USB cable which is not provided in the Developer kit. Details can be found [here](https://software.intel.com/en-us/node/667851). Interface speed is 115200 bps, 8 bits, no parity, no flow control ## Which port name is used to define the connected display(s) -Port naming may change with HW platforms and connected display. The simplest is to check following the fist boot, in the systemd journal which display names are listed.<br> -``` +Port naming may change with HW platforms and connected display. The simplest is to check following the fist boot, in the systemd journal which display names are listed. + +```bash journalctl |grep Output ``` -**Note:** The Output information is only listed if a real Display is connected to the connector on the board.<br> -The file holding that configuration is /etc/xdg/weston/weston.ini<br> + +**Note:** The Output information is only listed if a real Display is connected to the connector on the board. +The file holding that configuration is /etc/xdg/weston/weston.ini Common Display name for Intel are + * HDMI-A-1 * HDMI-A-2 * LVDS-1 diff --git a/getting-started/footers/porter-footer.md b/getting-started/footers/porter-footer.md index 697ff39..7d1417d 100644 --- a/getting-started/footers/porter-footer.md +++ b/getting-started/footers/porter-footer.md @@ -5,7 +5,7 @@ If Weston fails to start double check : and verify that the output name and screen resolution matches the configured U-Boot environment. For example on Renesas Porter board rev 1.0 with screen resolution 1024x768: -``` +```bash [core] shell=desktop-shell.so backend=drm-backend.so @@ -21,4 +21,3 @@ mode=1024x768 #mode=1920x1080 #mode=173.00 1920 2048 2248 2576 1080 1083 1088 1120 -hsync +vsync ``` - diff --git a/getting-started/footers/raspberrypi-footer.md b/getting-started/footers/raspberrypi-footer.md index cb914dc..f5ff16f 100644 --- a/getting-started/footers/raspberrypi-footer.md +++ b/getting-started/footers/raspberrypi-footer.md @@ -2,7 +2,7 @@ Append to following lines to **conf/local.conf** to include libomxil under a commercial license to your build: -``` +```bash # For libomxil LICENSE_FLAGS_WHITELIST = "commercial" @@ -13,7 +13,7 @@ IMAGE_INSTALL_append = " libomxil" If you have Raspberry Pi official 7" touchscreen connected, you can rotate it with these lines in /etc/xdg/weston/weston.ini -``` +```bash root@raspberrypi3:/etc/xdg/weston# cat weston.ini [core] backend=drm-backend.so @@ -49,7 +49,7 @@ It is possible to debug AGL images on Raspberry Pi using 3.3V USB to serial cabl * Plug the USB connector of the cable to your computer and use your favorite tool for serial communication, for example on Ubuntu and other Linux distributions you may use screen: -``` +```bash sudo screen /dev/ttyUSB0 115200 ``` diff --git a/getting-started/machines/R-Car-Starter-Kit-gen3.md b/getting-started/machines/R-Car-Starter-Kit-gen3.md index 0385aa4..465ba58 100644 --- a/getting-started/machines/R-Car-Starter-Kit-gen3.md +++ b/getting-started/machines/R-Car-Starter-Kit-gen3.md @@ -24,17 +24,18 @@ The following documents may also be helpful: Before setting up the build environment, you need to download the proprietary drivers. * Download Renesas graphics drivers with a "click through" license from Renesas website [Link][rcar Linux Drivers] - * Under the Target hardware: **R-Car H3/M3** section. + * Under the Target hardware: **R-Car H3/M3** section. -#### Note: +**Note**: * You have to register with a free account on MyRenesas and accept the license conditions before downloading them the drivers. -The operation is fast and simple but nevertheless mandatory to access evaluation of non open-source drivers for free. -Once you registered, you can download two zip files. + The operation is fast and simple but nevertheless mandatory to access evaluation of non open-source drivers for free. + Once you registered, you can download two zip files. * The files must be stored into your download directory (usually $HOME/Downloads, pointed by $XDG_DOWNLOAD_DIR). + Here after is an example of the typical files downloaded at the time of writing: -``` +```bash test -f ${XDG_CONFIG_HOME:-~/.config}/user-dirs.dirs && source ${XDG_CONFIG_HOME:-~/.config}/user-dirs.dirs chmod a+r $XDG_DOWNLOAD_DIR/*.zip ls -1 $XDG_DOWNLOAD_DIR @@ -43,26 +44,25 @@ total 8220 -rw-r--r--. 1 1664 agl-sdk 2.7M Dec 8 15:24 R-Car_Gen3_Series_Evaluation_Software_Package_of_Linux_Drivers-20170427.zip ``` -## Setting up the build environment: +## Setting up the build environment Define the type of R-Car Starter Kit board as a variable: * for machine **h3ulcb** (Starter Kit Premier/H3) : - ``` + ```bash export MACHINE=h3ulcb ``` * for machine **m3ulcb** (Starter Kit Pro/M3): - ``` + ```bash export MACHINE=m3ulcb ``` - Now, init your build environment: -``` +```bash cd $AGL_TOP source meta-agl/scripts/aglsetup.sh -m $MACHINE -b build agl-devel agl-demo agl-netboot agl-appfw-smack agl-localdev ``` @@ -70,7 +70,7 @@ source meta-agl/scripts/aglsetup.sh -m $MACHINE -b build agl-devel agl-demo agl- **IMPORTANT NOTE**: Read the log to be sure you had no error during your setup. In case of missing graphics drivers, you could notice an error message as follow: -``` +```bash [snip] --- fragment /home/working/workspace_agl_master/meta-agl/templates/machine/h3ulcb/50_setup.sh /home/working/workspace_agl_master /home/working/workspace_agl_master/build_gen3 @@ -96,39 +96,40 @@ After this command, the working directory is changed to $AGL_TOP/build. Users may want to check that the board is correctly selected in the environment: -``` +```bash grep -w -e "^MACHINE =" $AGL_TOP/build/conf/local.conf MACHINE = "h3ulcb" or MACHINE = "m3ulcb" ``` -Configure for Release or Development: +Configure for Release or Development: + * development images contain extra tools for developer convenience, in particular: - * a debugger (gdb) - * some tweaks, including a disabled root password - * a SFTP server - * the TCF Agent for easier application deployment and remote debugging - * some extra system tools (usb, bluetooth ...) - * ... + * a debugger (gdb) + * some tweaks, including a disabled root password + * a SFTP server + * the TCF Agent for easier application deployment and remote debugging + * some extra system tools (usb, bluetooth ...) + * ... We explicitely activate these debug facilities by specifying the “agl-devel agl-netboot” feature. -## Build your image: +## Build your image The process to build an image is simple: -``` +```bash bitbake agl-demo-platform ``` When finished (it may take few hours), you should get the final result: -``` +```bash ls -l $AGL_TOP/build/tmp/deploy/images/$MACHINE ``` -#### Note +**Note**: In case of failure of the build it is safe to first check that the Linux distribution chosen for your host has been validated for version 2.2 of Yocto. # Booting AGL Image on R-Car Starter Kit Gen3 boards using a microSD card @@ -144,7 +145,7 @@ Then, for each build, the SD-card is merely rewritten and used to boot the confi Plug the microSD card and get its associated device by either running *`dmesg | tail -15`* or *`lsblk`*, for example: -``` +```bash dmesg | tail -15 [ 1971.462160] sd 6:0:0:0: [sdc] Mode Sense: 03 00 00 00 @@ -155,7 +156,7 @@ dmesg | tail -15 Here, the SD-card is attached to the device /dev/sdc. -``` +```bash lsblk NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT @@ -174,15 +175,16 @@ lsblk so you should repeat this operation each time you insert the microSD card to confirm the device name. In the example above, we see: + * the first SATA drive as 'sda'. * 'sdc' corresponds to the microSD card, and is also marked as removable device by *lsblk* which is a good confirmation. ### Partition and format the SD-card * Create an EXT4 partition on the SD-card using fdisk and set the MBR. -For example, if the microSD card is */dev/sdc*: + For example, if the microSD card is */dev/sdc*: -``` +```bash sudo fdisk /dev/sdc Welcome to fdisk (util-linux 2.27.1). @@ -214,14 +216,14 @@ sudo fdisk /dev/sdc * Initialize the ext4 partition using “mke2fs”; for example, if the microSD card is associated with *sdc*: -``` +```bash sudo mke2fs -t ext4 -O ^64bit /dev/sdc1 mke2fs 1.42.13 (17-May-2015) Creating filesystem with 3911168 4k blocks and 979200 inodes Filesystem UUID: 690804b9-6c7d-4bbb-b1c1-e9357efabc52 Superblock backups stored on blocks: - 32768, 98304, 163840, 229376, 294912, 819200, 884736, 1605632, 2654208 + 32768, 98304, 163840, 229376, 294912, 819200, 884736, 1605632, 2654208 Allocating group tables: done Writing inode tables: done @@ -240,7 +242,7 @@ Insert the SD-card into your build host: * In the next sample code, we'll suppose that the SD-card mount directory is stored in the variable $SDCARD. * For example, if the microSD card is associated with device *sdc*: -``` +```bash export SDCARD=/tmp/agl mkdir -p $SDCARD sudo mount /dev/sdc1 $SDCARD @@ -248,19 +250,19 @@ sudo mount /dev/sdc1 $SDCARD Go to your build directory: -``` +```bash cd $AGL_TOP/build/tmp/deploy/images/$MACHINE ``` Make sure the filesystem is empty: -``` +```bash sudo rm -rf ${SDCARD:-bad_dir}/* ``` **IMPORTANT NOTE**: Verify that **tar** version is 1.28 or newer: this is required to create extended attributes correctly on the SD-card, and in particular SMACK labels used to enforce security. Check with the following command: -``` +```bash tar --version tar (GNU tar) 1.28 [snip] @@ -268,51 +270,56 @@ tar (GNU tar) 1.28 If your distribution is up to date on this dependency, you can use the host tool directly. Let's define a variable for the following steps: -``` + +```bash TAR=$(which tar) ``` + Otherwise, a native up-to-date version of tar is also generated while building AGL distribution: -``` + +```bash TAR=$AGL_TOP/build/tmp/sysroots/x86_64-linux/usr/bin/tar-native/tar $TAR --version tar (GNU tar) 1.28 [snip] ``` + Copy Automotive Grade Linux (AGL) files onto the mircoSD card by extracting the root file system archive: -``` +```bash sudo $TAR --extract --xz --numeric-owner --preserve-permissions --preserve-order --totals \ --xattrs-include='*' --directory=$SDCARD --file=agl-demo-platform-h3ulcb.tar.xz ``` Copy Kernel Image and Device Tree Blob file into the **boot** directory: + * For machine h3ulcb (BSP >= 2.19): -``` +```bash sudo cp Image-r8a7795-es1-h3ulcb.dtb $SDCARD/boot/ ``` * For machine h3ulcb (BSP < 2.19): -``` +```bash sudo cp Image-r8a7795-h3ulcb.dtb $SDCARD/boot/ ``` * For machine m3ulcb: -``` +```bash sudo cp Image-r8a7796-m3ulcb.dtb $SDCARD/boot/ ``` Ensure the changes have been written to the disk: -``` +```bash sync ``` Unmount the microSD card: -``` +```bash sudo umount $SDCARD ``` @@ -321,27 +328,27 @@ sudo umount $SDCARD * Turn the board off using the power switch. * Insert the microSD-card. * Verify that you have plugged in, at least, the following: - * External monitor on HDMI port - * Input device (keyboard, mouse, touchscreen...) on USB port. + * External monitor on HDMI port + * Input device (keyboard, mouse, touchscreen...) on USB port. * Turn the board on using the power switch. -After a few seconds, you'll see the AGL splash screen on the display and you'll be able to log in on the console terminal or in the graphic screen. + After a few seconds, you'll see the AGL splash screen on the display and you'll be able to log in on the console terminal or in the graphic screen. # Serial Console Setup -## Install a serial client on your computer. +## Install a serial client on your computer This can be “screen”, “picocom”, “minicom”. The lighter of the 3 is “picocom” (it has less dependencies). -## Plug a USB cable from your computer to the serial CP2102 USB port (micro USB-A). +## Plug a USB cable from your computer to the serial CP2102 USB port (micro USB-A) With “dmesg” you can check the device created for the serial link. Usually, it's /dev/ttyUSB0 but the number may vary depending on other USB serial ports connected to the host. To get it, you must switch the board on. For example: -``` +```bash dmesg | tail [2097783.287091] usb 2-1.5.3: new full-speed USB device number 24 using ehci-pci [2097783.385857] usb 2-1.5.3: New USB device found, idVendor=0403, idProduct=6001 @@ -358,19 +365,19 @@ The link is attached to the device /dev/ttyUSB0. It is time to launch your serial client. Example: -``` +```bash picocom -b 115200 /dev/ttyUSB0 ``` or -``` +```bash minicom -b 115200 -D /dev/ttyUSB0 ``` or -``` +```bash screen /dev/ttyUSB0 115200 ``` @@ -378,7 +385,7 @@ screen /dev/ttyUSB0 115200 * For machine h3ulcb: -``` +```bash NOTICE: BL2: R-Car Gen3 Initial Program Loader(CA57) Rev.1.0.7 NOTICE: BL2: PRR is R-Car H3 ES1.1 NOTICE: BL2: LCM state is CM @@ -418,7 +425,7 @@ Hit any key to stop autoboot: 0 * For machine m3ulcb: -``` +```bash NOTICE: BL2: R-Car Gen3 Initial Program Loader(CA57) Rev.1.0.8 NOTICE: BL2: PRR is R-Car M3 ES1.0 NOTICE: BL2: LCM state is CM @@ -463,50 +470,50 @@ Follow the steps below to configure the boot from microSD card and to set screen * Turn the board on using the power switch. * Hit any key to stop autoboot (warning you have only few seconds). * Type **print** to check if you have correct parameters for booting your board: - * For machine m3ulcb: + * For machine m3ulcb: - ``` + ```bash => printenv - baudrate=115200 - bootargs=console=ttySC0,115200 root=/dev/mmcblk1p1 rootwait ro rootfstype=ext4 - bootcmd=run load_ker; run load_dtb; booti 0x48080000 - 0x48000000 - bootdelay=3 - fdt_high=0xffffffffffffffff - initrd_high=0xffffffffffffffff - load_dtb=ext4load mmc 0:1 0x48000000 /boot/Image-r8a7795-h3ulcb.dtb - load_ker=ext4load mmc 0:1 0x48080000 /boot/Image - stderr=serial - stdin=serial - stdout=serial - ver=U-Boot 2015.04 (Jun 09 2016 - 19:21:52) - - Environment size: 648/131068 bytes + baudrate=115200 + bootargs=console=ttySC0,115200 root=/dev/mmcblk1p1 rootwait ro rootfstype=ext4 + bootcmd=run load_ker; run load_dtb; booti 0x48080000 - 0x48000000 + bootdelay=3 + fdt_high=0xffffffffffffffff + initrd_high=0xffffffffffffffff + load_dtb=ext4load mmc 0:1 0x48000000 /boot/Image-r8a7795-h3ulcb.dtb + load_ker=ext4load mmc 0:1 0x48080000 /boot/Image + stderr=serial + stdin=serial + stdout=serial + ver=U-Boot 2015.04 (Jun 09 2016 - 19:21:52) + + Environment size: 648/131068 bytes ``` * For machine h3ulcb: - ``` + ```bash => printenv - baudrate=115200 - bootargs=console=ttySC0,115200 root=/dev/mmcblk1p1 rootwait ro rootfstype=ext4 - bootcmd=run load_ker; run load_dtb; booti 0x48080000 - 0x48000000 - bootdelay=3 - fdt_high=0xffffffffffffffff - filesize=cdeb - initrd_high=0xffffffffffffffff - load_dtb=ext4load mmc 0:1 0x48000000 /boot/Image-r8a7796-m3ulcb.dtb - load_ker=ext4load mmc 0:1 0x48080000 /boot/Image - stderr=serial - stdin=serial - stdout=serial - ver=U-Boot 2015.04 (Nov 30 2016 - 18:25:18) - - Environment size: 557/131068 bytes + baudrate=115200 + bootargs=console=ttySC0,115200 root=/dev/mmcblk1p1 rootwait ro rootfstype=ext4 + bootcmd=run load_ker; run load_dtb; booti 0x48080000 - 0x48000000 + bootdelay=3 + fdt_high=0xffffffffffffffff + filesize=cdeb + initrd_high=0xffffffffffffffff + load_dtb=ext4load mmc 0:1 0x48000000 /boot/Image-r8a7796-m3ulcb.dtb + load_ker=ext4load mmc 0:1 0x48080000 /boot/Image + stderr=serial + stdin=serial + stdout=serial + ver=U-Boot 2015.04 (Nov 30 2016 - 18:25:18) + + Environment size: 557/131068 bytes ``` * If not, copy line by line: - ``` + ```bash setenv bootargs console=ttySC0,115200 root=/dev/mmcblk1p1 rootwait ro rootfstype=ext4 setenv bootcmd run load_ker\; run load_dtb\; booti 0x48080000 - 0x48000000 setenv load_ker ext4load mmc 0:1 0x48080000 /boot/Image @@ -514,31 +521,31 @@ setenv load_ker ext4load mmc 0:1 0x48080000 /boot/Image * For machine h3ulcb (BSP >= 2.19): - ``` + ```bash setenv load_dtb ext4load mmc 0:1 0x48000000 /boot/Image-r8a7795-es1-h3ulcb.dtb ``` * For machine h3ulcb (BSP < 2.19): - ``` + ```bash setenv load_dtb ext4load mmc 0:1 0x48000000 /boot/Image-r8a7795-h3ulcb.dtb ``` * For machine m3ulcb: - ``` + ```bash setenv load_dtb ext4load mmc 0:1 0x48000000 /boot/Image-r8a7796-m3ulcb.dtb ``` * Finally save boot environment: - ``` + ```bash saveenv ``` * Now you can boot: -``` +```bash run bootcmd ``` @@ -548,7 +555,7 @@ After booting, you should see the wayland display on the external monitor and a * For machine h3ulcb: -``` +```bash Automotive Grade Linux 3.0.0+snapshot-20161201 h3ulcb ttySC0 h3ulcb login: root @@ -556,13 +563,14 @@ h3ulcb login: root * For machine m3ulcb: -``` +```bash Automotive Grade Linux 3.0.0+snapshot-20161201 m3ulcb ttySC0 m3ulcb login: root ``` Logging in on the console is easy: + * login is 'root' * password is empty (not asked) @@ -571,7 +579,7 @@ Logging in on the console is easy: If the board is connected to a local network using ethernet and if a DHCP server is able to distribute IP addresses, you can then determine the Gen3 board IP address and log in using ssh: -``` +```bash m3ulcb login: root Last login: Tue Dec 6 09:55:15 UTC 2016 on tty2 root@m3ulcb:~# ip -4 a @@ -586,7 +594,7 @@ root@m3ulcb:~# Here, IP address is 10.0.0.27. Logging in using SSH is easy: -``` +```bash $ ssh root@10.0.0.27 Last login: Tue Dec 6 10:01:11 2016 from 10.0.0.13 root@m3ulcb:~# cat /etc/os-release @@ -601,10 +609,10 @@ PRETTY_NAME="Automotive Grade Linux 3.0.0+snapshot-20161202 (chinook)" Detailed guides on how to build AGL for Renesas boards and using AGL SDK inside a ready-to-use Docker container: -* [AGL-Devkit-Build-your-1st-AGL-Application.pdf][Iot.bzh AGL-Devkit-Build-your-1st-AGL-Application] -Generic guide on how to build various application types (HTML5, native, Qt, QML, …) for AGL. -* [AGL-Devkit-HowTo_bake_a_service.pdf][Iot.bzh AGL_Phase2-Devkit-HowTo_bake_a_service] -Generic guide on how to add a new service in the BSP. +* [AGL-Devkit-Build-your-1st-AGL-Application.pdf][Iot.bzh AGL-Devkit-Build-your-1st-AGL-Application] + Generic guide on how to build various application types (HTML5, native, Qt, QML, …) for AGL. +* [AGL-Devkit-HowTo_bake_a_service.pdf][Iot.bzh AGL_Phase2-Devkit-HowTo_bake_a_service] + Generic guide on how to add a new service in the BSP. * [AGL-Kickstart-on-Renesas-Porter-Board.pdf][Iot.bzh AGL-Kickstart-on-Renesas-Porter-Board] * [AGL-Devkit-Image-and-SDK-for-Porter.pdf][Iot.bzh AGL-Devkit-Image-and-SDK-for-Porter] * [AGL Developer Website](http://docs.automotivelinux.org) diff --git a/getting-started/machines/intel.md b/getting-started/machines/intel.md index 6e29ab5..0c420d5 100644 --- a/getting-started/machines/intel.md +++ b/getting-started/machines/intel.md @@ -1,37 +1,43 @@ # Running AGL on Intel Minnowboard (and most Intel 64 bits HW) ## Scope + This documentation is aiming at people who want to run Automotive Grade Linux (AGL) on an Intel Hardware (HW). While the reference HW used by AGL project is the Open Source Minnowboard. This documentation [MinnowBoard wiki](https://minnowboard.org/) -can be used to enable most of 64 bits Intel Architecture (IA) using UEFI as boot loader.<br> +can be used to enable most of 64 bits Intel Architecture (IA) using UEFI as boot loader. In addition to the MinnowBoard, support for the the [Joule Developer Kit](https://software.intel.com/en-us/iot/hardware/joule/dev-kit) has been added. -You need to run the 64 bits version of the UEFI boot. +You need to run the 64 bits version of the UEFI boot. Minnowbaord Max and Turbo has well as the Joule are both 64 bits capable. -**Note** : - * This page is more focused on please willing to create bespoke AGL image and BSP. -If you are more interested by Apps creation, please visit [ Developing Apps for AGL](https://wiki.automotivelinux.org/agl-distro/developer_resources_intel_apps) +**Note**: + +* This page is more focused on please willing to create bespoke AGL image and BSP. + +If you are more interested by Apps creation, please visit [ Developing Apps for AGL](<https://wiki.automotivelinux.org/agl-distro/developer>_resources_intel_apps) UEFI has evolved a lot recently and you likely want to check that your HW firmware is up-to-date, this is mandatory for the Minnowboard and the Joule. -[`https://firmware.intel.com/projects/minnowboard-max`](https://firmware.intel.com/projects/minnowboard-max)<br> +[`https://firmware.intel.com/projects/minnowboard-max`](https://firmware.intel.com/projects/minnowboard-max) [`https://software.intel.com/en-us/flashing-the-bios-on-joule`](https://software.intel.com/en-us/flashing-the-bios-on-joule) ## Where to find an AGL bootable image -### Building an AGL image from scratch using Yocto. +### Building an AGL image from scratch using Yocto + +**Note**: + +* An alternative method for building an image is to use the AGL SDK delivered in a Docker container. -**Note:**: - * An alternative method for building an image is to use the AGL SDK delivered in a Docker container. There is currently no SDK dedicated to IA but the SDK provided for the Porter Board can build an IA image without changes (just aglsetup.sh needs to call for Intel). see chapter 2 of [Porter QuickStart](http://iot.bzh/download/public/2016/sdk/AGL-Kickstart-on-Renesas-Porter-board.pdf "wikilink"). #### Download AGL source code + Downloading the AGL sources from the various Git repositories is automated with the repo -tools [ to RepoDocumentation](https://source.android.com/source/using-repo.html "wikilink") +tools [to RepoDocumentation](https://source.android.com/source/using-repo.html "wikilink") To install the repo tool. @@ -48,12 +54,14 @@ To install the repo tool. cd AGL-3.0.x; repo init -b chinook -m default.xml -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo ``` + #### Configuring for master (DD) ```bash cd AGL-master; repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo; ``` + Once that you repo is initialised either with the stable or WIP, you need to sync the repo to fetch the various git trees. #### Downloading the configured AGL source code @@ -63,6 +71,7 @@ Once that you repo is initialised either with the stable or WIP, you need to syn ``` #### Building the AGL distro + You are now ready to initialise your Yocto build. When running the command: @@ -76,14 +85,17 @@ You will notice the Intel entries intel-corei7-64 joule ``` -Simply select that entry to replace porter in the -m option.<br> + +Simply select that entry to replace porter in the -m option. +**Note:** agl-netboot option is required to create the right initramfs even if you do not boot from a network ```bash source meta-agl/scripts/aglsetup.sh \ -m intel-corei7-64 \ -b build \ - agl-devel agl-demo agl-appfw-smack agl-netboot<br> + agl-devel agl-demo agl-appfw-smack agl-netboot ``` + **Note:** use the option "-m joule" when building for a Joule developer Kit target. Start the build **This can take several hours depending of your CPU and @@ -92,13 +104,14 @@ internet connection and will required several GB on /tmp as well as on your buil ```bash bitbake agl-demo-platform ``` -** Your newly baked disk image (.hddimg) will be located at **: + +**Your newly baked disk image (.hddimg) will be located at**: `tmp/deploy/images/intel-corei7-64/` ##### Alternative: Download a *ready made* image from AGL web site The Continuous Integration (CI) process from AGL creates and publish daily and stable builds. -Pointers to both can be found in [ AGL supported HW](https://wiki.automotivelinux.org/agl-distro) (see Reference BSP/Intel). +Pointers to both can be found in [AGL supported HW](https://wiki.automotivelinux.org/agl-distro) (see Reference BSP/Intel). Once you have validated your process you can start to play/work with the snapshot pointer. @@ -106,11 +119,11 @@ Note that snapshot build may not work. Follow the directory: -` intel-corei7-64/deploy/images/intel-corei7-64/` +`intel-corei7-64/deploy/images/intel-corei7-64/` and download the file: -` agl-demo-platform-intel-corei7-64.hddimg` +`agl-demo-platform-intel-corei7-64.hddimg` ## Create a bootable media @@ -118,7 +131,7 @@ Depending your target HW you will use an USB stick, an SD card or a HDD/SDD. The creation process remains the same independently of the selected support. It does require to have access to a Linux machine with sudo or root password. -### Insert you removable media in the corresponding interface. +### Insert you removable media in the corresponding interface ### Check the device name where the media can be accessed with the command @@ -127,17 +140,19 @@ It does require to have access to a Linux machine with sudo or root password. # Note that you want the name of the raw device not of a partition on the media #(eg. /dev/sdc or /dev/mmcblk0) ``` + ### Download the script mkefi-agl.sh + This script is present in the directory meta-agl/scripts from blowfish 2.0.4, alternatively you can download it from the following Git repo: [https://github.com/dominig/mkefi-agl.sh](https://github.com/dominig/mkefi-agl.sh) - ### check the available option ```bash sh mkefi-agl.sh -v; ``` + ### create your media with the command ajusted to your configuration ```bash @@ -157,11 +172,14 @@ This script is present in the directory meta-agl/scripts from blowfish 2.0.4, al 1. Let AGL boot -**Note:**: - * Depending on the speed of the removable media, the first boot may not complete, in that case simply reboot the device. -This is quite common with USB2 sticks. +**Note:**: + +* Depending on the speed of the removable media, the first boot may not complete, in that case simply reboot the device. + +This is quite common with USB2 sticks. + By default the serial console is configured and activated at the rate of 115200 bps. ## How to create your 1st AGL application -[ Developing Apps for AGL](https://wiki.automotivelinux.org/agl-distro/developer_resources_intel_apps) +[Developing Apps for AGL](https://wiki.automotivelinux.org/agl-distro/developer_resources_intel_apps) diff --git a/getting-started/machines/porter.md b/getting-started/machines/porter.md index f9b2624..8efe59d 100644 --- a/getting-started/machines/porter.md +++ b/getting-started/machines/porter.md @@ -1,5 +1,7 @@ # Renesas Porter Hardware setup + Here is a non exhaustive list of hardware parts that could be used to setup the Porter board development environment: + * Porter board with its power supply * mini USB-A cable for serial console * USB 2.0 Hub @@ -12,23 +14,29 @@ Here is a non exhaustive list of hardware parts that could be used to setup the For more information and latest news, please check [Here][R-car Porter]: - The following documents may also be helpful: + * Porter Hardware Manual [Link][Porter HardwareManual] * Porter (Rev B) Setup Manual [Link][PORTER SetupManual] -# Building the AGL Demo Platform for Renesas Porter +## Building the AGL Demo Platform for Renesas Porter + Before set up Build Environment you need to setup the proprietary drivers. + * Download Renesas graphics drivers with a "click through" license from Renesas website [Link][rcar demoboard] under the Target hardware: R-Car H2, M2 and E2 section. -#### Note: + +**Note**: + * that you have to register with a free account on MyRenesas and accept the license condition before downloading them. -The operation is fast and simple but nevertheless mandatory to access evaluation of non open-source drivers for free. -Once you registered, you can download two zip files. + The operation is fast and simple but nevertheless mandatory to access evaluation of non open-source drivers for free. + Once you registered, you can download two zip files. * The files must be store into directory ~/Downloads (or $XDG_DOWNLOAD_DIR). + Here after is an example of their names: -``` + +```bash chmod a+r $XDG_DOWNLOAD_DIR/*.zip ls -l $XDG_DOWNLOAD_DIR total 8220 @@ -36,18 +44,22 @@ total 8220 -rw-r--r-- 1 1000 1000 2394750 Jul 11 11:03 R-Car_Series_Evaluation_Software_Package_of_Linux_Drivers-20151228.zip ``` -### Set up Build Environment: +## Set up Build Environment + * To build AGL demo platform for Renesas Porter board use machine **porter** and feature **agl-demo**: -``` + +```bash cd $AGL_TOP source meta-agl/scripts/aglsetup.sh -m porter -b build agl-devel agl-demo agl-netboot agl-appfw-smack ``` -#### Note: +**Note**: + * **IMPORTANT** read the log to be sure to have any error during your setup. + In case the graphical drivers were not found, you could notice an error message as follow: -``` +```bash [snip] --- fragment /ssd/agl2016-for-kickstart-update/meta-agl/templates/machine/porter/50_setup.sh /ssd/agl2016-for-kickstart-update /ssd/agl2016-for-kickstart-update/build @@ -64,56 +76,72 @@ Generating setup file: /ssd/agl2016-for-kickstart-update/build/agl-init-build-en ------------ aglsetup.sh: Done [snip] ``` + * If you encounters this issue, or any other unwanted behavior, you can fix the error mentioned and then clean up by removing the “$AGL_TOP/build” directory then launch the procedure again. * After this command, the working directory is changed to $AGL_TOP/build. * Users may want to check that the board is correctly selected in the environment: -``` +```bash grep -w -e "^MACHINE =" $AGL_TOP/build/conf/local.conf MACHINE = "porter" ``` -* Configure for Release or Development: + +Configure for Release or Development: Development images require extra tools for developer convenience, in particular: - * a debugger (gdb) - * some tweaks, including a disabled root password - * a SFTP server - * the TCF Agent for easier application deployment and remote debugging - * ... + +* a debugger (gdb) +* some tweaks, including a disabled root password +* a SFTP server +* the TCF Agent for easier application deployment and remote debugging +* ... + We explicitely activate these Debug facilities by specifying the “agl-devel agl-netboot” feature. -### Build your image: +### Build your image + The process to build an image is simple: -``` + +```bash bitbake agl-demo-platform ``` + Once done, what may take up to few hours, you should get the end result in the directory: -``` + +```bash $AGL_TOP/build/tmp/deploy/images/porter. ``` -#### Note: + +**Note**: + * In case of failure of the build it is safe to first check that the Linux distribution chosen for your host has been validated for version 2.0 of Yocto. -# Booting AGL Demo Platform on Renesas Porter using a micro-SD card -#### NOTE: +## Booting AGL Demo Platform on Renesas Porter using a micro-SD card + +**Note**: + Porter boards have 2 SD slots: + * one for SD cards * another one for micro-SD cards. At the time of writing, we didn't succeed to boot a board using the SD slot with the current kernel (3.10): + * Only the micro-SD slot was usable. To boot the board using a micro-SD card, there are two operations that should be done prior to first initial boot: + * Create a SD-card with one ext3 partition, * Set up the board to boot on the SD-card. Then for each build, the SD-card is merely rewritten and used to boot the configured board. + ## Deployment ### Format the SD-card on the host * Plug microSD card and get its associated device by either running *dmesg | tail -15* or *lsblk*, for example: -``` +```bash dmesg | tail -15 [ 1971.462160] sd 6:0:0:0: [sdc] Mode Sense: 03 00 00 00 @@ -121,9 +149,10 @@ dmesg | tail -15 [ 1971.462278] sd 6:0:0:0: [sdc] Assuming drive cache: write through [ 1971.463870] sdc: sdc1 sdc2 ``` + Here, the SD-card is attached to the device sdc. -``` +```bash lsblk NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT @@ -137,16 +166,20 @@ lsblk ├─sdc1 8:33 1 40M 0 part └─sdc2 8:34 1 788M 0 part ``` -#### Note: + +**Note**: + * **WARNING** This is a critical operation, each computer is different and device can change during time, so do this operation each time you incert the microSD card. * In the **example** above, we see the first SATA drive as 'sda'. * In the **example** above, 'sdc' corresponds to the microSD card.* ### Format the SD-card -* Create EXT3 partition on the SD-card using fdisk and set the MBR. - * For **example**, if the microSD card is */dev/sdc*: -``` +Create EXT3 partition on the SD-card using fdisk and set the MBR. + +* For **example**, if the microSD card is */dev/sdc*: + +```bash sudo fdisk /dev/sdc Welcome to fdisk (util-linux 2.27.1). @@ -175,17 +208,19 @@ sudo fdisk /dev/sdc Calling ioctl() to re-read partition table. Syncing disks. ``` -* Initialize the ext3 partition using “mke2fs”: - * for **example** if the microSD card is associated with *sdc*: -``` +Initialize the ext3 partition using “mke2fs”: + +* for **example** if the microSD card is associated with *sdc*: + +```bash sudo mke2fs -t ext3 /dev/sdc1 mke2fs 1.42.13 (17-May-2015) Creating filesystem with 3911168 4k blocks and 979200 inodes Filesystem UUID: 690804b9-6c7d-4bbb-b1c1-e9357efabc52 Superblock backups stored on blocks: - 32768, 98304, 163840, 229376, 294912, 819200, 884736, 1605632, 2654208 + 32768, 98304, 163840, 229376, 294912, 819200, 884736, 1605632, 2654208 Allocating group tables: done Writing inode tables: done @@ -194,12 +229,14 @@ sudo mke2fs -t ext3 /dev/sdc1 ``` ### Copying the built image to the SD-card + Insert the SD-card into your build host: + * Your desktop system may probably offer a choice to mount the SD-card automatically in some directory. * In the next sample code, we'll suppose that the SD-card mount directory is stored in the variable $SDCARD. * For example **example** the microSD card is associated with device *sdc*: -``` +```bash export SDCARD=/tmp/agl mkdir -p $SDCARD sudo mount /dev/sdc1 $SDCARD @@ -207,72 +244,85 @@ sudo mount /dev/sdc1 $SDCARD Go to your build directory: -``` +```bash cd $AGL_TOP/build/tmp/deploy/images/porter ``` Make sure the filesystem is empty: -``` +```bash sudo rm -rf ${SDCARD:-bad_dir}/* ``` + *** IMPORTANT *** Verify that **tar** version is 1.28 or newer: -``` +```bash tar --version tar (GNU tar) 1.28 [snip] ``` + If your distribution is up to date on this dependency, you can use the host tool directly. Let's define a variable for the following steps: -``` + +```bash TAR=$(which tar) ``` + Otherwise, a native up-to-date version of tar is also generated while building AGL distribution: -``` + +```bash TAR=$AGL_TOP/build/tmp/sysroots/x86_64-linux/usr/bin/tar-native/tar $TAR --version tar (GNU tar) 1.28 [snip] ``` + Copy Automotive Grade Linux (AGL) files onto the mircoSD card by extracting the root file system archive: -``` +```bash sudo $TAR --extract --xz --numeric-owner --preserve-permissions --preserve-order --totals \ --xattrs-include='*' --directory=$SDCARD --file=agl-demo-platform-porter.tar.xz ``` Copy Kernel Image and Device Tree Blob file into the **boot** directory: -``` +```bash sudo cp uImage+dtb /tmp/agl/boot/ ``` Ensure the changes have been written to the disk: -``` +```bash sync ``` + Unmount the micrSD card: -``` +```bash sudo umount $SDCARD ``` + ### Booting the board + Turn the board off using the power switch. Insert the microSD-card into the appropriate slot. Verify that you have plugged in, at least, the following: + * External monitor on HDMI port * Input device (keyboard, mouse, touchscreen...) on USB port. + Turn the board on using the power switch. After a few seconds, you'll see the AGL splash screen on the display and you'll be able to log in on the console terminal (login is 'root', no password): -``` +```bash Automotive Grade Linux 2.0.0 porter ttySC6 porter login: ``` + ### To access the shell (serial) + Install a serial client on your computer. This can be “screen”, “picocom”, “minicom”. The lighter of the 3 is “picocom” (it has less dependencies). @@ -280,7 +330,8 @@ Plug a USB cable from your computer to the serial CP2102 USB port of the porter With “dmesg” you can check the device created for the serial link. To get it, you must switch the board on. For example: -``` + +```bash dmesg | tail [609575.767056] usb 2-1.6.4: new full-speed USB device number 21 using ehci-pci [609575.854083] usb 2-1.6.4: New USB device found, idVendor=10c4, idProduct=ea60 @@ -297,23 +348,30 @@ dmesg | tail [609576.068184] usb 2-1.6.4: reset full-speed USB device number 21 using ehci-pci [609576.154125] usb 2-1.6.4: cp210x converter now attached to ttyUSB0 ``` + The link is attached to the device /dev/ttyUSB0. It is time to launch your serial client. Example: -``` + +```bash picocom -b 38400 /dev/ttyUSB0 ``` + or -``` + +```bash minicom -b 38400 -D /dev/ttyUSB0 ``` + or -``` + +```bash screen /dev/ttyUSB0 38400 ``` Power on the Porter board to see a shell on the console -``` + +```bash KOELSCH SPI_LOADER(DDR3L_1333) V0.16a 2014.10.03 DEVICE S25FL512 @@ -342,26 +400,26 @@ Follow the steps below to configure boot from microSD card and to set screen res * Type a character to abort the boot and enter the U-boot menu. * Type **print** to check the environment: -``` +```bash print ``` * Verify that the ethaddr environment variable is set to the same MAC address value shown on the label on top of the RJ45 Ethernet connector. * If not please set it using the following command: -``` +```bash setenv ethaddr <MAC address> ``` For example: -``` +```bash setenv ethaddr 2e:09:0a:00:75:b5 ``` * Set the follow environment variables: -``` +```bash 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 ro rootfstype=ext4 rootwait' @@ -369,17 +427,20 @@ 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' ``` + **WARNINGS:** + * If no display shows up when booting, e.g. for a non-full HD screen, replace **1920x1080** value in the **bootargs_video** variable with lower screen resolution such as **1024x768**. Unfortunately for the moment there are no universally supported setting. * Depending on your board (Porter rev B or rev C, Koelsch etc.), the SD card slots may differ. + Try setting **bootmmc** to **0:1** or **2:1** depending on the slot and card format. For Renesas Porter Rev 1.0 use screen resolution **1024x768** and set **bootmmc** to **2:1**. * Save the environment variables: -``` +```bash saveenv Saving Environment to SPI Flash... SF: Detected S25FL512S with page size 256 KiB, total 64 MiB @@ -388,12 +449,14 @@ saveenv * Reboot: -``` +```bash reset ``` ### Writing a “hello world” application + Yocto project provides a good reference on its complete solution for developers: + * ADT: The Application Development Toolkit is the complete solution; * the cross-toolchain is a simple build environment. @@ -403,61 +466,79 @@ Check the following document for more information [Link][iot.bzh SDK Kickstart o Here, for a quick demo we will build the cross-toolchain and write a sample application. First, let's create the build toolchain: -``` + +```bash cd $AGL_TOP source poky/oe-init-build-env bitbake meta-ide-support ``` The small following “hello world” example: -``` + +```bash cat hello.c #include <stdio.h> int main() { printf(“Hello world\n”); return 0; } ``` … can now be compiled and executed this way: -``` + +```bash . $AGL_TOP/build/tmp/environment-setup-* $CC -o hello hello.c scp hello root@porterboard:/ ssh root@porterboard /hello ``` + where 'porterboard' is replaced by the IP address or the hostname of your Porter board. ### Running CES 2016 Demos + The CES demos are located in /opt/AGL/CES2016 (on the microSD-Card). To run the demo, execute the following commands on the target (from a weston terminal or from the serial console) -``` + +```bash cd /opt/AGL/CES2016 export LD_PRELOAD=/usr/lib/libEGL.so ``` + For the main demo, run: -``` + +```bash /usr/bin/qt5/qmlscene -–fullscreen -I imports Main.qml ``` + To start the demo using IVI Shell, run the appropriate scripts located in /opt/AGL/CES2016: -``` + +```bash ./switch_to_ivi-shell.sh ./start_CES2016_ivi-shell.sh ``` + This will restart Weston with IVI Shell enabled and launch the demo. With the above commands, the demo application has still some decorations. They can be dropped by adding '--fullscreen' in the script. Use the following command once to modify the script. -``` + +```bash sed -i 's/Main.qml/--fullscreen Main.qml/' start_CES2016_ivi-shell.sh ``` + Then restart the demo: -``` + +```bash killall qmlscene ./start_CES2016_ivi-shell.sh ``` -#### IMPORTANT: +#### IMPORTANT + Please note that the current image uses Evaluation drivers: + * as a consequence, the graphics and multimedia acceleration provided by these drivers will stop after 3 hours. When this happens, simply reboot the board and restart the demo. + For more information, you can check the embedded README: -``` + +```bash cat /opt/AGL/CES2016/README.md Open source QML UI @@ -484,12 +565,19 @@ Option b: start QML + CarNavigation:/home/navi. For the time being, CarNavigatio ``` ### More Documentation + More documents, provide by [Iot.bzh][Iot.bzh link], are available to guide developers with AGL and Renesas boards: + * [AGL-Devkit-Image-and-SDK-for-porter.pdf][iot.bzh AGL-Devkit-Image-and-SDK-for-porter] + Detailed guide on how to build AGL for Renesas boards and using AGL SDK inside a ready-to-use Docker container. + * [AGL-Devkit-Build-your-1st-AGL-Application.pdf][Iot.bzh AGL-Devkit-Build-your-1st-AGL-Application] + Generic guide on how to build various application types (HTML5, native, Qt, QML, …) for AGL. + * [AGL-Devkit-HowTo_bake_a_service.pdf][Iot.bzh AGL_Phase2-Devkit-HowTo_bake_a_service] + Generic guide on how to add a new service in the BSP. [R-car Porter]: http://elinux.org/R-Car/Boards/Porter diff --git a/getting-started/machines/qemu.md b/getting-started/machines/qemu.md index a9f6f5c..398eda5 100644 --- a/getting-started/machines/qemu.md +++ b/getting-started/machines/qemu.md @@ -2,7 +2,7 @@ To build the QEMU version of the AGL demo platform use machine **qemux86-64** and feature **agl-demo**: -``` +```bash source meta-agl/scripts/aglsetup.sh -m qemux86-64 agl-demo agl-netboot agl-appfw-smack bitbake agl-demo-platform ``` diff --git a/getting-started/machines/raspberrypi.md b/getting-started/machines/raspberrypi.md index 19a41ce..2300c4c 100644 --- a/getting-started/machines/raspberrypi.md +++ b/getting-started/machines/raspberrypi.md @@ -4,7 +4,7 @@ To build AGL demo platform for Raspberry Pi 3 use machine **raspberrypi3** and feature **agl-demo**: -``` +```bash source meta-agl/scripts/aglsetup.sh -m raspberrypi3 agl-demo agl-netboot agl-appfw-smack bitbake agl-demo-platform ``` @@ -13,7 +13,7 @@ bitbake agl-demo-platform To build AGL demo platform for Raspberry Pi 2 use machine **raspberrypi2** and feature **agl-demo**: -``` +```bash source meta-agl/scripts/aglsetup.sh -m raspberrypi2 agl-demo agl-netboot agl-appfw-smack bitbake agl-demo-platform ``` @@ -30,11 +30,10 @@ Follow the steps below to copy the image to microSD card and to boot it on Raspb *Note: the sdimage files can also be named rpi-sdimg-ota in case you have the **"agl-sota"** feature enabled* -``` +```bash sudo umount [sdcard device] sudo dd if=[output image] of=[sdcard device] bs=4M sync ``` * Plug your microSD card into Raspberry Pi 2 or 3 and boot the board - diff --git a/getting-started/setup-sdk-environment.md b/getting-started/setup-sdk-environment.md index 1435b50..3479a21 100644 --- a/getting-started/setup-sdk-environment.md +++ b/getting-started/setup-sdk-environment.md @@ -1,4 +1,5 @@ # AGL SDK Quick Setup + This tutorial explains how to quickly setup an environment suitable to building and packaging AGL Applications using the SDK and a Docker container. The current tutorial has been tested on Linux, but may work with a few adjustments for Windows or MacOS. @@ -15,6 +16,7 @@ which belong to uid=1664(devel) gid=1664(devel). (Note: password is *devel*) The script 'create_container' presented below instantiates a new container and shares some volumes with the host: + * /xdt (the build directory inside the container) is stored in ~/ssd/xdt_$ID (specific to instance ID) * /home/devel/mirror is stored in ~/ssd/localmirror_$ID (specific to instance ID) * /home/devel/share => points to ~/devel/docker/share (shared by all containers) @@ -27,12 +29,15 @@ mkdir ~/ssd ~/devel chmod a+w ~/ssd ~/devel ``` -**Note**: - * To gain access from your host on files created within the container, your +**Note**: + +* To gain access from your host on files created within the container, your host account requires to be added to group id 1664. ## Step 3: install the "Generic AGL Worker" Docker Image + ### Get docker image + #### Pre-built image A pre-built image is available on automotivelinux download public site and can be used directly. @@ -47,24 +52,28 @@ docker images; jenkins latest 55720d63e328 5 weeks ago 711.9 MB hello-world latest c54a2cc56cbb 5 months ago 1.848 kB ``` + #### Rebuilt image + The Docker image for AGL Worker can be rebuilt using the scripts published here [docker-worker-generator](https://git.automotivelinux.org/AGL/docker-worker-generator/). ### Start image + Then, use the 'create_container' script to start a new, fresh container based on the AGL Worker image: -**Note**: - * The password for the id 'devel' inside the docker image is 'devel'. + +**Note**: + +* The password for the id 'devel' inside the docker image is 'devel'. ```bash git clone https://git.automotivelinux.org/AGL/docker-worker-generator; cd docker-worker-generator; ./contrib/create_container 0; docker ps; - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 4fb7c550ad75 docker.automotivelinux.org/agl/worker:3.0 "/usr/bin/wait_for_ne" 33 hours ago Up 33 hours 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 agl-worker-odin-0-sdx + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 4fb7c550ad75 docker.automotivelinux.org/agl/worker:3.0 "/usr/bin/wait_for_ne" 33 hours ago Up 33 hours 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 agl-worker-odin-0-sdx ``` - ## Step 4: install the AGL SDK for your target Here, we assume that we just built an image 'agl-demo-platform-crosssdk' using the Yocto build procedure documented in the [Getting Started](../) section of the documentation. diff --git a/getting-started/source-code.md b/getting-started/source-code.md index 9b60b82..0c2c387 100644 --- a/getting-started/source-code.md +++ b/getting-started/source-code.md @@ -1,5 +1,3 @@ - - # Introduction: Building target AGL image with Yocto project The standard Yocto process is made of the following steps: @@ -9,55 +7,57 @@ The standard Yocto process is made of the following steps: * Downloading the proprietary drivers and installing them in the build environment (if needed). * Build the image. * Boot using SD-CARD. - * Create an SD-CARD. - * Configure to boot on SD-CARD. - * Copy the image to the SD-CARD. - * Boot the board on it. + * Create an SD-CARD. + * Configure to boot on SD-CARD. + * Copy the image to the SD-CARD. + * Boot the board on it. For convenience, the resulting development images are made available [Here][AGL snapshots master latest] If you want to bypass the build phase and quick boot the board, you can download the image tarball and the kernel then follow the installation procedure. ## Setting up your operating system + The very first step is to ensure that your system can run the build system of the Yocto Project. **Important**: it only runs on Linux - * if your system is Windows© or iOS© you should use a virtualization solution (Virtualbox, VMWare ...) to run a Linux VM on your system. +* if your system is Windows© or iOS© you should use a virtualization solution (Virtualbox, VMWare ...) to run a Linux VM on your system. For AGL 2.1, Yocto Project 2.1, known as krogoth, has been selected for the BSP and build system. Reference data for configuring your system can be found in the Yocto documentation [Here][yocto ref Manual] - - Here after an extract of this documentation for most common Linux distributions: * The build system should be able to run on any modern distributions that has the following versions for: - * Python - * Git 1.7.8 or greater - * tar 1.24 or greater - * GCC, … + * Python + * Git 1.7.8 or greater + * tar 1.24 or greater + * GCC, … -#### Note: -* Python 2.7.3 or greater excluding Python 3.x, which is not supported. +**Note**: +* Python 2.7.3 or greater excluding Python 3.x, which is not supported. ### Ubuntu and Debian + The essential and graphical support packages you need for a supported Ubuntu or Debian distribution are shown in the following command: -``` +```bash sudo apt-get install gawk wget git-core diffstat unzip texinfo gcc-multilib \ build-essential chrpath socat libsdl1.2-dev xterm cpio curl ``` -#### Note: +**Note**: + * Also note that for this tutorial, the utility 'curl' has been added to the list of packages to install. ### Fedora + The essential and graphical packages you need for a supported Fedora distribution are shown in the following command: -``` +```bash sudo yum install gawk make wget tar bzip2 gzip python unzip perl patch \ diffutils diffstat git cpp gcc gcc-c++ glibc-devel texinfo chrpath \ ccache perl-Data-Dumper perl-Text-ParseWords perl-Thread-Queue socat \ @@ -65,85 +65,96 @@ sudo yum install gawk make wget tar bzip2 gzip python unzip perl patch \ ``` ### OpenSUSE + The essential and graphical packages you need for a supported OpenSUSE distribution are shown in the following command: -``` +```bash sudo zypper install python gcc gcc-c++ git chrpath make wget python-xml \ diffstat texinfo python-curses patch socat libSDL-devel xterm curl ``` ### CentOS + The essential and graphical packages you need for a supported CentOS distribution are shown in the following command: -``` +```bash sudo yum install gawk make wget tar bzip2 gzip python unzip perl patch \ diffutils diffstat git cpp gcc gcc-c++ glibc-devel texinfo chrpath \ socat SDL-devel xterm curl ``` # Download AGL Source Code + The AGL source code and Yocto layers are maintained on the AGL Gerrit server. For information on how to create accounts for gerrit see [Getting Started with AGL][Getting Started with AGL]. ## Setting up the build environment + In the following, your top level directory is noted as “AGL_TOP”. For example, we will set AGL_TOP to point to a directory “$HOME/workspace_agl”: -``` +```bash export AGL_TOP=$HOME/workspace_agl mkdir -p $AGL_TOP ``` ## Prepare Repo Tool + AGL Uses the 'repo' tool for managing repositories. You need to setup layers of AGL. You can use the commands below to prepare Repo: -``` +```bash mkdir -p ~/bin export PATH=~/bin:$PATH curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo chmod a+x ~/bin/repo ``` -#### Note: +**Note**: + * More information about the tool 'repo' [Here][repo info] ## Download source + You can choose your source release ### Download Latest Stable Release + To download all layers for the for the latest stable release, Chinook 3.0.1: -``` +```bash cd $AGL_TOP repo init -b chinook -m chinook_3.0.1.xml -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo repo sync ``` ### Download Latest on Chinook Branch + To download all layers on the current release branch which may be in the midst of testing or changes prior to the next stable release: -``` +```bash cd $AGL_TOP repo init -b chinook -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo repo sync ``` ### Download Master Branch + To download all code from master: -``` +```bash cd $AGL_TOP repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo repo sync ``` ## Set up Build Environment Info + AGL has created a set up script for defining the target build and desired optional features. To get a complete list of the options available run. -``` +```bash cd $AGL_TOP source meta-agl/scripts/aglsetup.sh -h ``` @@ -155,18 +166,18 @@ Once you run aglsetup.sh with your desired parameters, you can build any target Here is the list of features for AGL 2.1 that can be specified in the aglsetup.sh command line: * in **meta-agl** - * **agl-archiver**: - * **agl-devel**: activate development options (empty root password, debugger, strace, valgrind …) - * **agl-isafw**: - * **agl-netboot**: enable network boot support through TFTP and NBD (see meta-netboot layer) + * **agl-archiver**: + * **agl-devel**: activate development options (empty root password, debugger, strace, valgrind …) + * **agl-isafw**: + * **agl-netboot**: enable network boot support through TFTP and NBD (see meta-netboot layer) * in **meta-agl-devel** - * **agl-oem-extra-libs**: - * **agl-renesas-kernel**: + * **agl-oem-extra-libs**: + * **agl-renesas-kernel**: * in **meta-agl-extra** - * **agl-appfw-smack**: enables IoT.bzh Application Framework + SMACK + Cynara - * **agl-demo**: enable layer meta-agl-demo and meta-qt5 - required to build * agl-demo-platform - * **agl-localdev**: add a local layer named “meta-localdev” in meta directory and a local.dev.inc conf file if present - * **agl-sota**: enable SOTA components and dependencies (meta-sota, meta-filesystems, meta-ruby, meta-rust are added) + * **agl-appfw-smack**: enables IoT.bzh Application Framework + SMACK + Cynara + * **agl-demo**: enable layer meta-agl-demo and meta-qt5 - required to build * agl-demo-platform + * **agl-localdev**: add a local layer named “meta-localdev” in meta directory and a local.dev.inc conf file if present + * **agl-sota**: enable SOTA components and dependencies (meta-sota, meta-filesystems, meta-ruby, meta-rust are added) For newer features or to get more details on a given feature, take a look at the configuration files stored for each feature and/or each machine in meta-agl/templates and meta-agl-extra/templates. diff --git a/getting-started/troubleshooting.md b/getting-started/troubleshooting.md index 6b2d930..274456d 100644 --- a/getting-started/troubleshooting.md +++ b/getting-started/troubleshooting.md @@ -8,14 +8,15 @@ When using tar to create the SDcard, it is a common error to not copy the extend Verify that **tar** version is 1.28 or newer: -``` +```bash tar --version tar (GNU tar) 1.28 [snip] ``` If it is not the case, a native up-to-date version of tar is also generated while building AGL distribution: -``` + +```bash tmp/sysroots/x86_64-linux/usr/bin/tar-native/tar --version tar (GNU tar) 1.28 [snip] @@ -23,16 +24,17 @@ tar (GNU tar) 1.28 To copy Automotive Grade Linux (AGL) files AND EXTENDED ATRIBUTES onto the SDcard using tar the command is: -``` +```bash tar --extract --xz --numeric-owner --preserve-permissions --preserve-order --totals \ --xattrs-include='*' --directory=DESTINATION_DIRECTORY --file=agl-demo-platform.....tar.xz ``` ## meta-rust + Due to a known bug in the upstream of meta-rust the Yocto/OE recipe for rust-cross may fail while building RVI SOTA Client or another application written in the Rust programming language. Until the complete resolution of the issue the workaround is to disable all use of the CXX11 ABI by applying the following lines to **conf/local.conf**: -``` +```bash LD_CXXFLAGS_append = " -D_GLIBCXX_USE_CXX11_ABI=0" TARGET_CXXFLAGS_append = " -D_GLIBCXX_USE_CXX11_ABI=0" CXXFLAGS_append = " -D_GLIBCXX_USE_CXX11_ABI=0" @@ -40,15 +42,20 @@ CXXFLAGS_append = " -D_GLIBCXX_USE_CXX11_ABI=0" BUILD_CXXFLAGS_remove_pn-gcc-runtime = "-D_GLIBCXX_USE_CXX11_ABI=0" TARGET_CXXFLAGS_remove_pn-gcc-runtime = "-D_GLIBCXX_USE_CXX11_ABI=0" CXXFLAGS_remove_pn-gcc-runtime = "-D_GLIBCXX_USE_CXX11_ABI=0" ``` + ## Screen orientation for Splash and in Weston + Depending of your scren mounting the default orientation of the UI an/or splash screen might be incorrect. -To change the orientation of the splash screen patch -``` +To change the orientation of the splash screen patch + +```bash File: /etc/systemd/system/sysinit.target.wants/psplash-start.service Line: ExecStart=/usr/bin/psplash -n -a 90 ``` + To change the orientation of the UI in Weston patch -``` + +```bash File: /etc/xdg/weston/weston.ini Line: transform=90 ``` @@ -63,7 +70,7 @@ To disable IVI-Shell and revert to the "plain old" weston desktop, you can follo * Modify */etc/xdg/weston/weston.ini* and comment the line mentioning IVI-shell. For example on Porter board: -``` +```bash [core] backend=drm-backend.so #shell=ivi-shell.so @@ -72,7 +79,7 @@ To disable IVI-Shell and revert to the "plain old" weston desktop, you can follo * modify */usr/lib/systemd/user/afm-user-daemon.service* and comment the line specifying QT Wayland backend: -``` +```bash ... #Environment=QT_WAYLAND_SHELL_INTEGRATION=ivi-shell ... @@ -80,12 +87,11 @@ To disable IVI-Shell and revert to the "plain old" weston desktop, you can follo * disable Homescreen services: -``` +```bash # systemctl disable HomeScreenAppFrameworkBinderAGL.service # systemctl disable HomeScreen.service # systemctl disable InputEventManager.service # systemctl disable WindowManager.service ``` -* Reboot your target and you should then be able to start apps on the standard weston screen using afm-util - +* Reboot your target and you should then be able to start apps on the standard weston screen using afm-util
\ No newline at end of file diff --git a/platform/working-on-the-chinook-branch.md b/platform/working-on-the-chinook-branch.md index 1f8eef8..c211650 100644 --- a/platform/working-on-the-chinook-branch.md +++ b/platform/working-on-the-chinook-branch.md @@ -1,16 +1,20 @@ # Working on the chinook branch + ## Intro + This is a quick howto for working on the 'Charming Chinook' branch. Working on the branch is easy as we maintain all changes through gerrit.automotivelinux.org. If you are unfamiliar with gerrit, please read these fine how-to pages were put together from the -Mediawiki community here: https://www.mediawiki.org/wiki/Gerrit/Tutorial . This covers the basics very well. Of course we'll work with gerrit.automotivelinux.org instead so apply likewise. +Mediawiki community here: <https://www.mediawiki.org/wiki/Gerrit/Tutorial> . This covers the basics very well. Of course we'll work with gerrit.automotivelinux.org instead so apply likewise. ## Installation of tools + Install `git` with your distributions package manager. A very useful tool is "git-review" (cmdline is then `git review`). Install it from your distro or with `sudo pip install git-review`. ## Prerequisites + It is important to setup git and gerrit properly (see the Tutorial page mentioned above): * prereq #1) make sure git is properly setup with name/email @@ -20,38 +24,44 @@ It is important to setup git and gerrit properly (see the Tutorial page mentione Follow these steps to submit a change to the 'Charming Chinook' branch: -1) cloning the (tip of the) branch - ``` +1. cloning the (tip of the) branch + + ```bash repo init -b chinook -m default.xml -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo repo sync ``` -2) Change the recipe in question (one change at a time - small is better) - ``` +1. Change the recipe in question (one change at a time - small is better) + + ```bash vi recipe-foo/bar/baz.bb ``` -3) Do a a few builds and tests (try 2 architectures if possible) - ``` +1. Do a a few builds and tests (try 2 architectures if possible) + + ```bash source meta-agl/scripts/aglsetup.sh .... agl-all-features bitbake agl-demo-platform ``` -4) once satisfied do commit your change as usual in git +1. once satisfied do commit your change as usual in git Make sure to do a proper commit message: - http://chris.beams.io/posts/git-commit/ - ``` + <http://chris.beams.io/posts/git-commit/> + + ```bash git commit -s <enter proper commit message> ``` -5) All repos have .gitreview files already, so now it is just - ``` +1. All repos have .gitreview files already, so now it is just + + ```bash git review ``` -6) (optional, but highly recommended!) Reset to gerrit/chinook - ``` +1. (optional, but highly recommended!) Reset to gerrit/chinook + + ```bash git checkout chinook` git reset --hard gerrit/chinook ``` @@ -59,45 +69,54 @@ Follow these steps to submit a change to the 'Charming Chinook' branch: It helps during the review process as gerrit would otherwise enforce the whole series of patches to be reviewed/merged together (2nd depends on 1st patch). -7) Rinse (=6) and repeat (=2-5) +1. Rinse (=6) and repeat (=2-5) ## Using git review to review/test-build a specific change in gerrit + 'git review' is also useful if you want to review a change. Example for meta-agl: -``` + +```bash repo init -b chinook -m default.xml -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo repo sync cd meta-agl/ git review -d 8105 ``` + This will pull-down change 8105. Now we can build with it applied: -``` + +```bash cd .. source ... bitbake ... -```` +``` ## Using gerrit to amend a changeset while in review + The same workflow applies if you want to _amend_ a changeset while it is in review (not merged, yet): -``` + +```bash cd meta-agl/ git review -d 8105 ``` + This will pull-down change 8105. You can now edit a file: -``` + +```bash vi recipes-foo/bar/baz.bb git commit -s --amend ``` Don't forget a test build -``` + +```bash cd .. source meta-agl/scripts/aglsetup.sh ..... agl-all-features bitbake ... # e.g. agl-demo-platform ``` Finally call git review to upload the change -``` -git review -``` +```bash +git review +```
\ No newline at end of file diff --git a/platform/working-on-the-master-branch.md b/platform/working-on-the-master-branch.md index 0f91eaf..16dae32 100644 --- a/platform/working-on-the-master-branch.md +++ b/platform/working-on-the-master-branch.md @@ -1,16 +1,20 @@ # Working on the master branch + ## Intro + This is a quick howto for working on the 'master' branch. Working on the branch is easy as we maintain all changes through gerrit.automotivelinux.org. If you are unfamiliar with gerrit, please read these fine how-to pages were put together from the -Mediawiki community here: https://www.mediawiki.org/wiki/Gerrit/Tutorial . This covers the basics very well. Of course we'll work with gerrit.automotivelinux.org instead so apply likewise. +Mediawiki community here: <https://www.mediawiki.org/wiki/Gerrit/Tutorial> . This covers the basics very well. Of course we'll work with gerrit.automotivelinux.org instead so apply likewise. ## Installation of tools + Install `git` with your distributions package manager. A very useful tool is "git-review" (cmdline is then `git review`). Install it from your distro or with `sudo pip install git-review`. ## Prerequisites + It is important to setup git and gerrit properly (see the Tutorial page mentioned above): * prereq #1) make sure git is properly setup with name/email @@ -20,38 +24,44 @@ It is important to setup git and gerrit properly (see the Tutorial page mentione Follow these steps to submit a change to the 'master' branch: -1) cloning the (tip of the) branch - ``` +1. cloning the (tip of the) branch + + ```bash repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo repo sync ``` -2) Change the recipe in question (one change at a time - small is better) - ``` +1. Change the recipe in question (one change at a time - small is better) + + ```bash vi meta-xyz/recipe-foo/bar/baz.bb ``` -3) Do a a few builds and tests (try 2 architectures if possible) - ``` +1. Do a a few builds and tests (try 2 architectures if possible) + + ```bash source meta-agl/scripts/aglsetup.sh .... agl-all-features bitbake agl-demo-platform ``` -4) once satisfied do commit your change as usual in git +1. once satisfied do commit your change as usual in git Make sure to do a proper commit message: - http://chris.beams.io/posts/git-commit/ - ``` + <http://chris.beams.io/posts/git-commit/> + + ```bash git commit -s <enter proper commit message> ``` -5) All repos have .gitreview files already, so now it is just - ``` +1. All repos have .gitreview files already, so now it is just + + ```bash git review ``` -6) (optional, but highly recommended!) Reset to gerrit/master - ``` +1. (optional, but highly recommended!) Reset to gerrit/master + + ```bash git checkout master git reset --hard gerrit/master ``` @@ -59,45 +69,54 @@ Follow these steps to submit a change to the 'master' branch: It helps during the review process as gerrit would otherwise enforce the whole series of patches to be reviewed/merged together (2nd depends on 1st patch). -7) Rinse (=6) and repeat (=2-5) +1. Rinse (=6) and repeat (=2-5) ## Using git review to review/test-build a specific change in gerrit + 'git review' is also useful if you want to review a change. Example for meta-agl: -``` + +```bash repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo repo sync cd meta-agl/ git review -d 8233 ``` + This will pull-down change 8233. Now we can build with it applied: -``` + +```bash cd .. source ... bitbake ... -```` +``` ## Using gerrit to amend a changeset while in review + The same workflow applies if you want to _amend_ a changeset while it is in review (not merged, yet): -``` + +```bash cd meta-agl/ git review -d 8233 ``` + This will pull-down change 8233. You can now edit a file: -``` + +```bash vi meta-xyz/recipes-foo/bar/baz.bb git commit -s --amend ``` Don't forget a test build -``` + +```bash cd .. source meta-agl/scripts/aglsetup.sh ..... agl-all-features bitbake ... # e.g. agl-demo-platform ``` Finally call git review to upload the change -``` -git review -``` +```bash +git review +```
\ No newline at end of file diff --git a/sec-blueprint/01-overview.md b/sec-blueprint/01-overview.md index ae3c23c..7b26ba1 100644 --- a/sec-blueprint/01-overview.md +++ b/sec-blueprint/01-overview.md @@ -11,9 +11,11 @@ layout: techdoc **Table of Content** 1. TOC + {:toc} ## Introduction + ### Abstract This document describes how it is possible to create reasonably secured connected cars using already available Open Source components. @@ -32,7 +34,7 @@ Proven solutions derived from the IT world are for most of them, inapplicable. For many people the Cyber Security risk for the Automotive industry is still at best not understood and unfortunately more often, simply ignored. If the Fiat-Chrysler cyber car jacking has forced the industry to open their eyes, it is just a beginning. -- 24 Jul 2015 Hacking a radio in a car: +- 24 Jul 2015 Hacking a radio in a car: *"… the computer systems built into Fiat Chrysler cars: the flaw can be exploited by an attacker to wirelessly take control of the engine, brakes and entertainment system ..." @@ -40,7 +42,7 @@ If the Fiat-Chrysler cyber car jacking has forced the industry to open their eye recalled 1.4 million of the manufacturer's cars after a dangerous software flaw was revealed just days ago..."* <http://www.theregister.co.uk/2015/07/24/chrysler_recall_for_wireless_hacking_hole/> -- One day (likely not that far) we could see car blocked by +- One day (likely not that far) we could see car blocked by ramsomware, or cyber terrorism using cars as weapon if nothing is done. @@ -55,7 +57,8 @@ that tracking a mobile source will be more complex. <http://www.theregister.co.uk/2016/10/10/iot\_botnet/> -## Scope +## Scope + Designing Connected cars without enabling a high level of security is not acceptable and will be soon a key market requirement for any respectable automotive company. @@ -68,19 +71,19 @@ Connected Car. The assumptions selected are the following: -- Secure boot with Hardware chain of trust. -- recent LTSI based kernel (4.1.x, 4.9.x, ...) -- kernel and middleware securely updated once in a while - in the future that rate will increase a lot. -- Middleware and Application compiled with up-to-date compiler - protections activated and checked through a static analysis process. -- Rootfs (/) in read-only, /home encrypted., integrity protected by - IMA/EVM -- Customisation reduced to Apps vetted by the manufacturer's store -- 24/7 connection to the outside world (sensor and internet). -- Developer mode not active by default. -- There is no administrator (only a user) for the product which mostly - run non attended. +- Secure boot with Hardware chain of trust. +- recent LTSI based kernel (4.1.x, 4.9.x, ...) +- kernel and middleware securely updated once in a while + in the future that rate will increase a lot. +- Middleware and Application compiled with up-to-date compiler + protections activated and checked through a static analysis process. +- Rootfs (/) in read-only, /home encrypted., integrity protected by + IMA/EVM +- Customisation reduced to Apps vetted by the manufacturer's store +- 24/7 connection to the outside world (sensor and internet). +- Developer mode not active by default. +- There is no administrator (only a user) for the product which mostly + run non attended. We can see that in such configuration, the base OS (kernel&middleware) represents a well guarded entry point for a malicious hacker. @@ -130,12 +133,8 @@ Those types of code are normally called from a very limited entry points in the system and once again the MAC system is your best friend when it comes to restrict activation from valid vector. - ## Glossary DAC Discretionaly Access Control MAC Mandatory Access Control -SoC System on Chip - - - +SoC System on Chip
\ No newline at end of file diff --git a/sec-blueprint/04-adversaries.md b/sec-blueprint/04-adversaries.md index 8740ae5..1dd4758 100644 --- a/sec-blueprint/04-adversaries.md +++ b/sec-blueprint/04-adversaries.md @@ -1,5 +1,7 @@ This section lists some of the adversaries and attackers in Automotive. -## Enthusiast Attackers: + +## Enthusiast Attackers + Enthusiast attackers have physical access to the Engine Control Units (ECUs) at the circuit board level. They can solder ‘mod chips’ onto the board and have access to probing tools. They also have @@ -9,14 +11,16 @@ This section lists some of the adversaries and attackers in Automotive. could be, but is not limited to, adding extra horse power to the car or hacking it just for fun. -## Corrupt Dealers: +## Corrupt Dealers + These are attackers that have access to the same capabilities as enthusiasts, but also have access to the car manufacturer's (OEM) dealer network. They may also have access to standard debugging tools provided by the car manufacturer. Their goal may be to support local car theft gangs or organized criminals. -## Organized Criminal: +## Organized Criminal + Organized Criminals have access to all of the above tools but may also have some level of control over the internal network at many dealerships. They may have hacked and gained temporary @@ -26,7 +30,8 @@ This section lists some of the adversaries and attackers in Automotive. Their goal is to extort money from an OEMs and/or governments by threatening to disable multiple vehicles. -## Malware Developers: +## Malware Developers + Malware Developers have developed malicious software to attach and compromise a large number of vehicle. The malicious software would usually be designed spread from one vehicle to another. @@ -34,11 +39,11 @@ This section lists some of the adversaries and attackers in Automotive. access to them for malicious purposes like denial-of-service (DoS) attacks or stealing private information and data. -## Security Researchers: +## Security Researchers + These attackers are ‘self-publicized’ security consultants trying to make a name for themselves. They have access standard tools for software security analysis. They also have physical access to the vehicle and standard hardware debugging tools (Logic Analyzers, Oscilloscopes, etc). Their goal is to publicize attacks for personal - gains. - + gains.
\ No newline at end of file diff --git a/sec-blueprint/05-security-concepts.md b/sec-blueprint/05-security-concepts.md index 5ddfe5b..48eb572 100644 --- a/sec-blueprint/05-security-concepts.md +++ b/sec-blueprint/05-security-concepts.md @@ -11,9 +11,11 @@ layout: techdoc **Table of Content** 1. TOC + {:toc} ## Security Principles + When connecting a car to the internet, not only we create a mobile entry point to our private life, we also relocate our entry doors anywhere in the world. @@ -33,23 +35,23 @@ short time following connection.. which would be deployed in a high risk zone even when designing cars for out towns and villages**: -- Physical access to the car should not be a white card to hack +- Physical access to the car should not be a white card to hack the system. Most cars sleep in the streets and public car parks where physical accessibility is easy. -- Known defect should be corrected by SW update in real time, without a return to +- Known defect should be corrected by SW update in real time, without a return to home or garage. -- A separation of functionalities in isolated domains should allow the +- A separation of functionalities in isolated domains should allow the car to remain safe and operational by limiting the contamination, would a malicious SW succeed to pass the protections. -- Connectivity between the various domains should be restricted to the +- Connectivity between the various domains should be restricted to the minimal set required for their operation. -- Software loaded in cars and in the cloud should be vetted in +- Software loaded in cars and in the cloud should be vetted in accordance with its capability to access critical resources. The vetting authority must be controllable, enforceable and revocable. -- Inside each domain, sub domains should be created to limit even +- Inside each domain, sub domains should be created to limit even more, the nuisances capabilities of a successful malicious code. -- Software or devices not wetted should never be able to access any +- Software or devices not wetted should never be able to access any critical resources. **The strategy can be summarise as “anything, which is not explicitly @@ -91,6 +93,7 @@ Linux operating system for the connected car market. Non Linux Operating systems which can also be present in a connected car, are not covered by AGL platform security model. ## Strategy + There is no miracle solution. When deciding which security strategy, you will need, first to try to evaluate all the possible attack vectors, @@ -108,18 +111,18 @@ Would your automotive project requires a more protected HW, you will find plenty of literature on that topic. I personally like this relatively old (2004) paper from J Grand as an introduction to the domain. -http://www.grandideastudio.com/wp-content/uploads/secure\_embed\_paper.pdf +<http://www.grandideastudio.com/wp-content/uploads/secure\_embed\_paper.pdf> On the SW side, the most efficient model is to work by layer : -- **be sure that the desired SW is loaded** +- **be sure that the desired SW is loaded** On non connected devices, a trusted boot is considered a valid enough solution, but Connected Cars requirement to enable applications be added after the initial equipment provisioning, requires more than a simple trusted boot. A strategy to control the integrity of the software and its configuration is required. -- **Be able to change (upgrade) the software to correct a newly +- **Be able to change (upgrade) the software to correct a newly discovered risk.** Assuming that the system will never be broken is an utopia. The right strategy is to plan how to recover from the discovering of a @@ -127,7 +130,7 @@ On the SW side, the most efficient model is to work by layer : *This upgrade mechanism must be particularly solid has it has to be capable of being executed on a compromised system without the support of a skilled operator.* -- **Only select trusted Linux drivers.** +- **Only select trusted Linux drivers.** In Linux, drivers are executed with the same privilege level than the Kernel itself. I short a malicious or hacked driver is an @@ -141,8 +144,8 @@ On the SW side, the most efficient model is to work by layer : Solutions to reinforce the Linux Kernel integrity during execution, can be activated but they are an order of magnitude more complex to activate than keeping bespoke logic in user space. - https://www.isoc.org/isoc/conferences/ndss/11/pdf/3\_1.pdf -- **Isolate the core of the system from the middleware.** + <https://www.isoc.org/isoc/conferences/ndss/11/pdf/3\_1.pdf> +- **Isolate the core of the system from the middleware.** By default the protection on Unix type systems (and so Linux) is done by allocating the user a set of access rights. The side effect is that any code running under a given name can access all the @@ -152,7 +155,7 @@ On the SW side, the most efficient model is to work by layer : privilege (root) we foresee the danger of this traditional embedded model. Fortunately Linux provides a Security model called LSM.* ( - https://en.wikipedia.org/wiki/Linux\_Security\_Modules) + <https://en.wikipedia.org/wiki/Linux\_Security\_Modules>) It allows to create an access strategy which is not controlled by the user but rather by the system configuration. Multiple front end are available to control LSM and that will be studied a bit later in @@ -163,7 +166,7 @@ On the SW side, the most efficient model is to work by layer : Other restriction based on the c-groups, the Posix capabilities and the Seccomp can used in addition to LSM to further mitigate the risks. -- **Isolate Applications** +- **Isolate Applications** IoS and Android phones have initiated the Apps model and nowadays launching a product which cannot be extended by Apps (from a closed or open Store) after the creation of the device is a risky @@ -183,30 +186,28 @@ On the SW side, the most efficient model is to work by layer : that such App can claim access, with the enforcement of restriction in accessing the system resources to those explicitly granted, is a far more reliable approach. -- **Private data protection** - *Cars know a lot about us, from where we go, to who we call, who get - in our car (via the phone detection) and hold data that we are not - willing to let go in the Open without our explicit consent.* - This creates three main families of requirements : - - - Requires a safe provisioning of new devices and App in the - system (know who is who and who does what. ) - - Enforce encryption to any traffic going out. - - Enforce encryption on local storage for personal data to - mitigate off line attack risk. - - Enforce isolation of devices own by multiple users that connect - to the car. +- **Private data protection** + *Cars know a lot about us, from where we go, to who we call, who get + in our car (via the phone detection) and hold data that we are not + willing to let go in the Open without our explicit consent.* + This creates three main families of requirements : + - Requires a safe provisioning of new devices and App in the + system (know who is who and who does what. ) + - Enforce encryption to any traffic going out. + - Enforce encryption on local storage for personal data to + mitigate off line attack risk. + - Enforce isolation of devices own by multiple users that connect + to the car. ## Secure Boot + The trusted or secured boot is a facility offered by most Systems on Chip (SoC) which enforces : -- booting the system in a known state - (e.g. all the RAM set to "0", all internal peripherals set - to silent) -- providing a validation that the loaded initial code is signed by a - valid authority - (in short the SW is really coming from a known valid source). +- booting the system in a known state + (e.g. all the RAM set to "0", all internal peripherals set to silent) +- providing a validation that the loaded initial code is signed by a valid authority + (in short the SW is really coming from a known valid source). As the feature is very closed to the HW, almost as many solutions exist than SoC vendors and many of them requires to buy a large volume of SoC @@ -223,7 +224,7 @@ Once the trusted boot activated, you will have a good confidence somewhere)* that the code which will start to run when powering the device, is the expected one. -## Read Only root file system. +## Read Only root file system In most embedded system the core OS is under control of the device manufacturer. @@ -239,7 +240,7 @@ to register some network or locale configurations, an overlay can be created for some directories. Since Linux 4.0, the kernel supports by default OverlayFS which provides that facility and support the extended file attributes required by file base MAC such as SELinux and Smack. -https://github.com/torvalds/linux/commit/e9be9d5e76e34872f0c37d72e25bc27fe9e2c54c +<https://github.com/torvalds/linux/commit/e9be9d5e76e34872f0c37d72e25bc27fe9e2c54c> ## Code Integrity during execution @@ -249,7 +250,7 @@ We can take profit of this favorable position, to limit the capabilities of a ma change our Operating System (OS) after the protected initialisation (trusted boot). This can be done *by activating an integrity enforcement such as IMA/EVM on all the core OS.* -http://sourceforge.net/p/linux-ima/wiki/Home/ +<http://sourceforge.net/p/linux-ima/wiki/Home/> In short IMA allows the kernel to check that a file has not been changed by validating it against a stored/calculate hash (called label) while @@ -257,8 +258,8 @@ EVM checks the file attributes (including the extended ones). Two types of labels are available : -- immutable and signed -- simple +- immutable and signed +- simple The signed labels are reserved for code or data which are static and provide the best level of protection. @@ -290,13 +291,13 @@ Connected Cars are comparable to middle volume consumer managed products software is entirely provided by the device manufacturer. The main side effects are well known : -- low cost and small CPU -- high control of the OS and Middleware loaded on the box -- user, at best, very slow to activate update -- no visibility by the manufacturer of the external environment where - the device is connected. -- No skilled administrator -- No recovery console. +- low cost and small CPU +- high control of the OS and Middleware loaded on the box +- user, at best, very slow to activate update +- no visibility by the manufacturer of the external environment where + the device is connected. +- No skilled administrator +- No recovery console. For those reasons, a solution like Smack has been selected by AGL as the best suited LSM front end. @@ -306,6 +307,7 @@ on keeping good performance on smaller CPUs. <https://wiki.tizen.org/wiki/Category:Security> ## Applications + *Apps are the weak security vector in many modern system.* Car manufacturers need to add bespoke/localised App developers in order to make their product commercially attractive. @@ -321,10 +323,10 @@ required in order to run on very small CPU. **As we cannot fully trust Apps, we have to contain them**. This can be done by : -- Limiting Apps download origin to trusted ones. -- Restrict Apps privileges, resources and APIs access to what is - explicitly authorised -- Isolate Apps runtime +- Limiting Apps download origin to trusted ones. +- Restrict Apps privileges, resources and APIs access to what is + explicitly authorised +- Isolate Apps runtime Restricting Apps origin to trusted source is quite simple. The simple use of a certificate to validate the App signature is a powerful model @@ -352,7 +354,7 @@ Manufacturer, Partner and Community stores). The association between the App and its privileges list must be kept safe and available for enforcement in the system. -The Samsung originated Open Source project Cynera (https://github.com/Samsung/cynara) provides +The Samsung originated Open Source project Cynera (<https://github.com/Samsung/cynara>) provides such service and is optimised for execution on small SoC. Isolating the App when running is the most challenging task, it requires @@ -360,12 +362,12 @@ to let the App access enough of the system to execute its task but no more, to mitigate any malicious activity. One model to address this challenge consist in slicing the access to the system : -- CPU, RAM -- devices -- network -- middleware -- files -- libraries and system calls. +- CPU, RAM +- devices +- network +- middleware +- files +- libraries and system calls. CPU and RAM over use can be restricted with a correct C-Group configuration. @@ -378,7 +380,7 @@ nftables. Middleware in AGL is access via binders which provides not only an isolation via creation of different security context but adds the concept of authentication which limit attack through man-in-the-middle -*https://en.wikipedia.org/wiki/Man-in-the-middle\_attack*. +*<https://en.wikipedia.org/wiki/Man-in-the-middle\_attack>*. The control of Libraries and system API usage is far more complex. MAC advanced usages can help in this domain but Seccomp-BPF can go further. @@ -388,7 +390,7 @@ solution. Seccomp can quickly induce a performance hit and access rules must remain simple. The following page provides interserting reports on performance cost of -that feature. (https://wiki.tizen.org/wiki/Security:Seccomp) for one +that feature. (<https://wiki.tizen.org/wiki/Security:Seccomp>) for one system. ### Name spaces @@ -399,7 +401,7 @@ due to their common use as light virtualisation solution in the cloud. Whichever model of container is referenced, they all use the Linux various name spaces -(http://man7.org/linux/man-pages/man7/namespaces.7.html). +(<http://man7.org/linux/man-pages/man7/namespaces.7.html>). The general idea is to share a common kernel and to let each containers run its own virtual Linux user space and middleware. With the increased CPU performance and the facility provided by novel filesystem architectures @@ -411,21 +413,21 @@ cloud or on small embedded system. From a security point of view, while containers provides an isolation between themselves, it must remain present to the designer that : -- kernel is shared and security weaknesses and zero day defects can be - used to cross domains. -- As each container can provides its own version of the middleware, - upgrading the system is not enough to correct known security issues. - Each container must individually be updated. -- Due to the transparent overlay model sharing files between - containers, predicting the actually used disk space is challenging. -- UX needs to share the same Display and Input what can open back - doors in the system. +- kernel is shared and security weaknesses and zero day defects can be + used to cross domains. +- As each container can provides its own version of the middleware, + upgrading the system is not enough to correct known security issues. + Each container must individually be updated. +- Due to the transparent overlay model sharing files between + containers, predicting the actually used disk space is challenging. +- UX needs to share the same Display and Input what can open back + doors in the system. At least two lines of interest seem to provide a serious value for the Automotive domain : -- Isolating subsystem -- Easing development +- Isolating subsystem +- Easing development The isolation model is very interesting when multiple service providers needs to share the same embedded device. @@ -444,21 +446,22 @@ environment. As further reading on similar topic, you can have a look at the Open Source Vasum project. -https://github.com/Samsung/vasum -https://wiki.tizen.org/wiki/Security:Vasum +<https://github.com/Samsung/vasum> +<https://wiki.tizen.org/wiki/Security:Vasum> ## Process Management + While developers will always have a good reason for delaying the activation of the security layers, to succeed, you will need to keep a few base concepts enforced: -- Security is invasive. It goes everywhere. -- Security cannot be apply as a patch at the end of the project. -- System must be developed with the security 'on' or it will - never work. -- SW must be written secured first time, as late adaptation is - too difficult. +- Security is invasive. It goes everywhere. +- Security cannot be apply as a patch at the end of the project. +- System must be developed with the security 'on' or it will + never work. +- SW must be written secured first time, as late adaptation is + too difficult. - Underestimating the resistance of the developer team is a common -mistake which can lead to massive over costs and delays. + mistake which can lead to massive over costs and delays. - Implication of the right expert and management drive from the beginning is a -requirement that cannot be negotiated. + requirement that cannot be negotiated. diff --git a/sec-blueprint/06-plateform-security.md b/sec-blueprint/06-plateform-security.md index 3940672..41de4f0 100644 --- a/sec-blueprint/06-plateform-security.md +++ b/sec-blueprint/06-plateform-security.md @@ -11,34 +11,41 @@ layout: techdoc **Table of Content** 1. TOC + {:toc} ## Platform Definition + The platform includes a set of HW supporting an AGL Linux distribution and AGL compliant Application and Services. On the HW side this will include : - - A SoC - - RAM, ROM and Storage - - Peripherial + +- A SoC +- RAM, ROM and Storage +- Peripherial The AGL SW platform includes all the SW required after the initial boot loader in order to support AGL compliant applications and services : - - Linux BPS configured for the reference boards - - Set of drivers for the common peripherials available on the reference boards (they may not all be Open Source) - - Application Framework - - Windows/layer management to allow Application to gracefully share the displays - - Sound resource manager to allow Application to gracefully share the displays - - An atomic update system support / as read only and MAC (Smack) - - Set of building and debug tools (based on yocto project) + +- Linux BPS configured for the reference boards +- Set of drivers for the common peripherials available on the reference boards (they may not all be Open Source) +- Application Framework +- Windows/layer management to allow Application to gracefully share the displays +- Sound resource manager to allow Application to gracefully share the displays +- An atomic update system support / as read only and MAC (Smack) +- Set of building and debug tools (based on yocto project) ## Secure boot + The secure boot is tighly linked to the SoC and will vary from SoC to SoC. AGL does not provide the secure boot but AGL platform is designed to be able to operate with a secure boot. ## Certificate and Key Management + The default Key management provided by AGL is SoC independant and use leyrings. This model is less secured than a SoC HW integrated model and we advise AGL adopters to activate HW support from their selected SoC as much as possible. The activation of HW support for Key management if left to the integrator. ## Madatory Access Control configuration + The general Smack schema used by AGL is inspired from Tizen 3 Q2/2015 but tries to enable a better protection of code ran via run time (e.g. JavaScript, Python) and enable Cloud/Device hybrid applications model. @@ -48,8 +55,7 @@ rules and limit the use of MAC for process file access tracking leaving the application capabilities management to other model (Cynara and the Security manager). - -https://wiki.tizen.org/wiki/Security/Overview\#Implementation\_in\_Tizen\_3.0\_2015.Q2 +<https://wiki.tizen.org/wiki/Security/Overview\#Implementation\_in\_Tizen\_3.0\_2015.Q2> ** You will notice that the Smack initial configuration described bellow, even if not obvious to read, represents a manageable complexity which @@ -67,58 +73,57 @@ label. The system is split in 3 domains : -- **Floor**, which includes the base services and associated data and libraries of the OS which are unchanged during the execution of the OS. -Outside of development mode, installation and upgrade software, no one is allowed to write in Floor files and directories. -- **System**; which includes a reduced set of core services of the OS and the data that they maintain. -Those data are expected to change during the execution of the OS. -- **Apps, Services and User**, which includes code providing services to the system and user and their associated data. -Per concept all code running in this domain are under strict control and isolation by the Cynara and Smacks rules. - +- **Floor**, which includes the base services and associated data and libraries of the OS which are unchanged during the execution of the OS. + Outside of development mode, installation and upgrade software, no one is allowed to write in Floor files and directories. +- **System**; which includes a reduced set of core services of the OS and the data that they maintain. + Those data are expected to change during the execution of the OS. +- **Apps, Services and User**, which includes code providing services to the system and user and their associated data. + Per concept all code running in this domain are under strict control and isolation by the Cynara and Smacks rules. -**Floor Domain** +## Floor Domain ------------------------------------------------------------------------------------------------------------------------- |Label| Name | File | Process | Comment | |:-:|:-------|:-------------|:------------------------------------|:-----------------------------------------------------| | | -| - | Floor | r-x for all | Only kernel and<br>internal kernel thread <br>| -- | +| - | Floor | r-x for all | Only kernel and internal kernel thread | -- | | ^ | Hat | --- for all | rx on all domains | only for privileged system Services (today only systemd-journal) useful for backup or virus scan. No file with that label should exist except debug log. | | * | Star | rwx for all | None | used for device files or /tmp Access restriction managed via DAC. Individual files remain protected by their Smack label. | - -**System Domain** +## System Domain ------------------------------------------------------------------------------------------------------------------------- |Label| Name | File | Process | Comment | |:--|:-------|:-------------|:------------------------------------|:-----------------------------------------------------| | | -|System|System|none|Privileged<br>processes|Process should only write on file with transmute attribute.| -|System::run|Run|rwxatl for User and System label|None|files are created with directory label<br>from user and system domain (transmute)<br>Lock is implicit with w.| -|System::shared|Shared|rwxatl for system domain<br>r-x for User label|None|files are created with directory label from system domain (transmute)<br>User domain has lock privilege| -|System::Log|Log|rwa for System label<br>xa for user label|None|Some limitation may impose to add w to enable append.| +|System|System|none|Privileged processes|Process should only write on file with transmute attribute.| +|System::run|Run|rwxatl for User and System label|None|files are created with directory label from user and system domain (transmute) Lock is implicit with w.| +|System::shared|Shared|rwxatl for system domain r-x for User label|None|files are created with directory label from system domain (transmute) User domain has lock privilege| +|System::Log|Log|rwa for System label xa for user label|None|Some limitation may impose to add w to enable append.| |System::Sub|SubSystem|SubSystem Config files|SubSystem only|Isolation of risky SubSystem**| -* Runtime: IoT-OS AppFW always starts a new instance of the runtime for each application (no shared process model is allowed and change the runtime process label to the App Smack label) -* Unconfined mode is reserved for future evolution. +- Runtime: IoT-OS AppFW always starts a new instance of the runtime for each application (no shared process model is allowed and change the runtime process label to the App Smack label) +- Unconfined mode is reserved for future evolution. + +## Apps, services and User Domain -**Apps, services and User Domain** ------------------------------------------------------------------------------------------------------------------------- |Label| Name | File | Process | Comment | |:--|:-------|:-------------|:------------------------------------|:-----------------------------------------------------| | | -|App::$AppID|AppID|rwx (for files created by the App).<br>rx for files installed by AppFW|$App runtime<br>executing $App|One Label per App.<br>A data Dir is created by the AppFW in rwx.<br>Older releases still use User::App::$AppID | -|User::Home|Home|rwx-t from System label<br>r-x-l from App|None|AppFW needs to create Dir in /home/$USER/App-Shared at 1st launch if not present/ with label<br>app-data access="User::App-Shared"<br>without transmute.| -|App-Shared|Shared|rwxat from System and User domains label of $User|None|Shared space between all App running for a given user.<br>Older releases may still use User::App-Shared| - +|App::$AppID|AppID|rwx (for files created by the App). rx for files installed by AppFW|$App runtime executing $App|One Label per App. A data Dir is created by the AppFW in rwx. Older releases still use User::App::$AppID | +|User::Home|Home|rwx-t from System label r-x-l from App|None|AppFW needs to create Dir in /home/$USER/App-Shared at 1st launch if not present/ with label app-data access="User::App-Shared" without transmute.| +|App-Shared|Shared|rwxat from System and User domains label of $User|None|Shared space between all App running for a given user. Older releases may still use User::App-Shared| ## Secured transport for Binder implementation ## Resource Management ## Trust Zone and Trusted Execution + Trusted zone and Trusted execution are services provided by the SoC vendors and services offered can varie even within the same familly of SoC depending of their configuration. AGL platform does not provide any Trusted Zone or Tusted Execution direct support as these are specific to each indivual SoC but on the other side the AGL platform is architectured to ease the use of HW helpers. In particular AGL advise whenever possible to take profit of HW helpers available to store critical data in the secure zone and to execute critical validatin code (in particular signature check) in trusted execution mode. @@ -126,13 +131,14 @@ In particular AGL advise whenever possible to take profit of HW helpers availabl ## Critical Resource Protection ## AGL Platform Software Update + AGL platform provides by default a software update module which is capable to respect the AHL platform update requirements: - - support Smack as MAC - - support read only / file system - - support integrity enforcement such as IMA and EVM. - - + +- support Smack as MAC +- support read only / file system +- support integrity enforcement such as IMA and EVM. + Any update software respecting these requirement can be used. AGL advise strongly to only use solutions that enable a strong verification of the validity and integrity of the download update or upgrade what ever is the selected solution. -## cloud service infrastructure - +## cloud service infrastructure
\ No newline at end of file diff --git a/sec-blueprint/07-application-security.md b/sec-blueprint/07-application-security.md index 09eb3e4..2c757b0 100644 --- a/sec-blueprint/07-application-security.md +++ b/sec-blueprint/07-application-security.md @@ -14,6 +14,7 @@ layout: techdoc {:toc} ## Application Definition + The term of Application (Apps) has a very wide coverage in AGL. To make it short, anything which is not in the core OS, is an App. @@ -21,12 +22,14 @@ Apps can be included in the base image or added after the fact, they can offer a In AGL, most of the middleware will be treated as Apps. ## Apps must be installed + Undependently of the fact that Apps are delivered with the base image or later installed on a running image, Apps are installed under the control of the Application Framework (AppFW). A special off-line mode of the AppFW, allows to install Apps at image creation.\* -**\* Note :** In early release, default Apps are installed on the image at first boot. +**Note :** In early release, default Apps are installed on the image at first boot. ## App containement + Apps are running in isolation of the system and other Apps. In order to acheive an efficient containement multiple strategies are used : @@ -41,7 +44,6 @@ In order to acheive an efficient containement multiple strategies are used : * End2end App author tracking and validation * Apps Privileges * Autiticated Apps to Apps/Services transport - ## Which protection are enforced on an App @@ -49,6 +51,7 @@ In order to acheive an efficient containement multiple strategies are used : The AGL App development process enforces of the level of autorisation given to an App developper and tracks that autorisation level end2end. Depending of the implementation, the tracking may be : + * static, simply enforced at the registration of the App on the repository or dynamic. * dynamic, track and verified at installation by the AppFW. @@ -58,14 +61,18 @@ It is the first section the chain of trust for providing valid information to th ### Platform security configuration The AppFW derives from the Meta data received with the App at delivery, which privileges will be granted to this App : + * Max CPU, RAM, IO, ... * Firewall configuration * Name spaces ... + It will create the directories required for the App following the Smack rules described in the "Platform Security" blueprint as well as the associated systemd config files to be used by the launcher. As the platform securities services are static for a given release of the OS, the mapping remains simple. -**Important** -* An App cannot change the CoreOS. +**Important**: + +* An App cannot change the CoreOS. + It s not allowed for an App to modify or add an element to the CoreOS. Like with containers App are required to embed all the code required for their operation. Within this limitation Apps (which can be a only a service) can still offer services to other App by the mean of AGL binders which use the autenticated AGL transport. @@ -73,6 +80,7 @@ Within this limitation Apps (which can be a only a service) can still offer serv ### AGL Platform protections By default AGL provides three specific protection services : + * Privilege management and enforment via cynara * Autenticated transport (via AGL binders, websocket and Oauth2) * App origin validation @@ -91,6 +99,7 @@ We just need to be sure that means to deactivate those protections are removed f AGL Platform protections are mostly enforced by dedicated middleware which are protected by the platform securities. Some more risky zones are identified : + * the creation of binding where an App could create a look a like binding that does not respect any protection. * services which provide a wide range of service and need to restict the user request following his profile. @@ -100,26 +109,23 @@ The second requires a duplication of some API in order to be able to keep the fi The side effect of this complexity will impose to create an introspection mode where there is the possibility to verify all the API offered by an App and which privileges are required to activate them. ### Privilege grouping + In order keep the concept of White listing manageable, a privilege hiercharchy is used. A small example shoudl clarify that concept. - - System:Com:SMS:notify - - System:Com:SMS:list - - System:Com:SMS:display - - System:Com:SMS:send - - System:Com:SMS:transfer - - System:Com:SMS:* (the * requires to be explicit on global capability request) - - - System:Com:Phone:notify - - System:Com:Phone:list - - System:Com:Phone:display - - System:Com:Phone:send - - System:Com:Phone:transfer - - System:Com:Phone:* - - - System:Com:* (includes SMS:* & Phone:*) - - - - System:Com:*:notify (includes SMS:notify & Phone:notify) +* System:Com:SMS:notify +* System:Com:SMS:list +* System:Com:SMS:display +* System:Com:SMS:send +* System:Com:SMS:transfer +* System:Com:SMS: (*the* requires to be explicit on global capability request) +* System:Com:Phone:notify +* System:Com:Phone:list +* System:Com:Phone:display +* System:Com:Phone:send +* System:Com:Phone:transfer +* System:Com:Phone:* +* System:Com:* (includes SMS:* & Phone:*) +* System:Com:*:notify (includes SMS:notify & Phone:notify) That last concept might be too complex to implement and real usefulness should be validated. diff --git a/sec-blueprint/08-Hardening.md b/sec-blueprint/08-Hardening.md index 12be18f..76f9e54 100644 --- a/sec-blueprint/08-Hardening.md +++ b/sec-blueprint/08-Hardening.md @@ -11,29 +11,26 @@ layout: techdoc **Table of Content** 1. TOC + {:toc} -Overview -======== +# Overview -Scope ------ +## Scope The information contained in this document is applicable to systems based on Automotive Grade Linux. -Limitations ------------ +## Limitations -- This document is based on knowledge and research gained from looking - at security desktop and server versions of Linux as well as Android - exploits and hardening. +* This document is based on knowledge and research gained from looking + at security desktop and server versions of Linux as well as Android + exploits and hardening. -- Some kernel configuration options can have an impact on performance. - This will be noted where applicable. +* Some kernel configuration options can have an impact on performance. + This will be noted where applicable. -Document Structure ------------------- +## Document Structure This document has been divided into three sections; REQUIREMENTS, RECOMMENDATIONS, and VALIDATION. The REQUIREMENTS section details @@ -45,8 +42,7 @@ The third section, VALIDATION, provides reference scripts and test procedures th can be used to verify adherence with the REQUIREMENTS detailed in the first section of this guide. -Hardening ---------- +## Hardening The term *Hardening* refers to the tools, techniques and processes required in order to reduce the attack surface on an embedded system, @@ -70,30 +66,29 @@ and configuration of the root filesystem. release of user space applications, in order to reduce the number of attack surfaces used by potential attackers. -Secure Boot Software Flow Steps -------------------------------- +## Secure Boot Software Flow Steps -1. After power on, the processor will perform the verification - of the Stage 1 boot image, the stage 2 boot image and the Secure - loader image. +1. After power on, the processor will perform the verification + of the Stage 1 boot image, the stage 2 boot image and the Secure + loader image. - a. If any of the images fail the verification process the device - will not boot. + a. If any of the images fail the verification process the device + will not boot. -2. Upon successful verification of all of the boot and loader images, +1. Upon successful verification of all of the boot and loader images, the secure process will initiate the Stage 1 boot process. -3. The Stage 1 boot process will perform processor initialization, and - then initiate the Stage 2 boot process. +1. The Stage 1 boot process will perform processor initialization, and + then initiate the Stage 2 boot process. -4. The Stage 2 boot process will initiate the Secure Loader, which will - process any customer specific customizations (e.g. front panel - of ECU, USB based image updates, etc). +1. The Stage 2 boot process will initiate the Secure Loader, which will + process any customer specific customizations (e.g. front panel + of ECU, USB based image updates, etc). -5. The Secure Loader will check to determine if there are any updates - to be processed. If the update settings indicate that an upgrade - should occur then the Secure Loader will will determine the correct - action based on the nature of the upgrades: +1. The Secure Loader will check to determine if there are any updates + to be processed. If the update settings indicate that an upgrade + should occur then the Secure Loader will will determine the correct + action based on the nature of the upgrades: a. If the Secure Loader determines that an upgrade was performed (or attempted), it will initiate the reboot process. @@ -101,23 +96,22 @@ Secure Boot Software Flow Steps b. If no upgrades were processed: then the Secure Loader will pass control back to the Stage 2 boot process for further processing -6. The Stage 2 boot process will continue with the boot process, by +1. The Stage 2 boot process will continue with the boot process, by performing a verification of the kernel image prior to the load of that image a. If the kernel image verification fails, the Stage 2 boot loader will not boot -8. The Stage 2 boot loader will load the successfully verified kernel - and boot the linux OS +1. The Stage 2 boot loader will load the successfully verified kernel + and boot the linux OS -9. The booted Linux OS will perform the normal Linux init sequence +1. The booted Linux OS will perform the normal Linux init sequence -10. The Linux init process will start the required applications and - services as described in the init process and present on the rootfs. +1. The Linux init process will start the required applications and + services as described in the init process and present on the rootfs. -Requirements -============ +## Requirements For the purposes of reference and explanation, we are providing guidance on how to configure an embedded device that runs with a linux 3. 10.17 @@ -125,8 +119,7 @@ Requirements These requirements must still be met by manufacturers that opt to build using an alternative version of the Linux kernel. -Hardened Boot -------------- +## Hardened Boot ### Boot image selection @@ -145,7 +138,7 @@ feature is available from U-Boot 2013.07 version. To enable the secure boot feature, enable the following features: -``` +```bash CONFIG_FIT: enables support for Flat Image Tree (FIT) uImage format. CONFIG_FIT_SIGNATURE: enables signature verification of FIT images. CONFIG_RSA: enables RSA algorithm used for FIT image verifitcation. @@ -163,7 +156,7 @@ image. It shall use RSA2048 and SHA256 for authentication. To disable USB support in U-Boot, following configs shall not be defined: -``` +```bash CONFIG_CMD_USB: enables basic USB support and the usb command CONFIG_USB_UHCI: defines the lowlevel part. CONFIG_USB_KEYBOARD: enables the USB Keyboard @@ -176,7 +169,7 @@ CONFIG_USB_HOST_ETHER: enables USB ethernet adapter support Serial console output shall be disabled. To disable console output in U-Boot, set the following macros: -``` +```bash CONFIG_SILENT_CONSOLE CONFIG_SYS_DEVICE_NULLDEV CONFIG_SILENT_CONSOLE_UPDATE_ON_RELOC @@ -186,7 +179,7 @@ and set “***silent”*** environment variable. For the Secure loader, disable the traces by undefining the below macro -``` +```bash INC_DEBUG_PRINT ``` @@ -222,7 +215,7 @@ default environment variable and not in non-volatile memory. Remove configuration options related to non-volatile memory such as: -``` +```bash #define CONFIG_ENV_IS_IN_MMC #define CONFIG_ENV_IS_IN_EEPROM #define CONFIG_ENV_IS_IN_FLASH @@ -239,12 +232,11 @@ Remove configuration options related to non-volatile memory such as: and include the following definition: -``` +```bash #define** CONFIG_ENV_IS_NOWHERE ``` -Kernel Hardening ----------------- +## Kernel Hardening The following sub-sections contain information on various kernel configuration options to enhance the security measures in the kernel @@ -279,7 +271,7 @@ Kernel Hardening applications, the following kernel option should be set in the compile-time kernel configuration: -``` +```bash CONFIG_DEVKMEM=n ``` @@ -439,6 +431,7 @@ Kernel Hardening ```bash CONFIG_SWAP=n +``` ### Disable NFS file system @@ -546,28 +539,23 @@ Kernel Hardening ```bash CONFIG_MODULE_FORCE_LOAD=n ``` + ### System Services #### Console & Remote Access -- The kernel console interfaces shall be disabled. Do not pass any statements - of the following kind (e.g. console=ttyS0 console=tty0) on the kernel - command line. All of the console=<interface> statements should be - stripped and removed from the kernel command line. - -- The telnet server shall be disabled. - -- Do not start telnetd in init scripts. - -- Remove telnetd from the root file system. - -- Root login access via the console shall be disabled. - -- Do not run shell or getty on /dev/ttySx or /dev/console from - init scripts. - -- Root login access through remote access such as SSH shall - be disabled or completely removed +* The kernel console interfaces shall be disabled. Do not pass any statements + of the following kind (e.g. console=ttyS0 console=tty0) on the kernel + command line. All of the console=<interface> statements should be + stripped and removed from the kernel command line. +* The telnet server shall be disabled. +* Do not start telnetd in init scripts. +* Remove telnetd from the root file system. +* Root login access via the console shall be disabled. +* Do not run shell or getty on /dev/ttySx or /dev/console from + init scripts. +* Root login access through remote access such as SSH shall + be disabled or completely removed #### Disable *sudo* for other users @@ -587,46 +575,46 @@ Kernel Hardening #### User Account Management - All user accounts shall have strong, non-default passwords. A strong - password is described to have all of the following attributes: +All user accounts shall have strong, non-default passwords. +A strong password is described to have all of the following attributes: -- At least one upper-case letter +* At least one upper-case letter -- At least one numeric character +* At least one numeric character -- At least one lower-case letter +* At least one lower-case letter -- Password shall be eight or more characters in length +* Password shall be eight or more characters in length -- Shall not use a known, common pattern (e.g. Xxxxxxx\# - or Xxxxxxx\#\#) +* Shall not use a known, common pattern (e.g. Xxxxxxx\# + or Xxxxxxx\#\#) #### Remove known insecure services The following legacy services are inherently insecure and should be avoided: -- rlogind +* rlogind -- rshd +* rshd -- rcmd +* rcmd -- rexecd +* rexecd -- rbootd +* rbootd -- rquotad +* rquotad -- rstatd +* rstatd -- rusersd +* rusersd -- rwalld +* rwalld -- rhosts +* rhosts -- rexd +* rexd These services offer insufficient authentication, no encryption, and are not considered secure. They shall be removed along with their @@ -640,51 +628,51 @@ Kernel Hardening non-exhaustive sample of commonly used utilities that are part of the mtd-utils package: -- flash\_erase +* flash\_erase -- flash\_eraseall +* flash\_eraseall -- flashcp +* flashcp -- flash\_lock +* flash\_lock -- flash\_otp\_dump +* flash\_otp\_dump -- flash\_otp\_info +* flash\_otp\_info -- flash\_unlock +* flash\_unlock -- mkfs.jffs2 +* mkfs.jffs2 -- mkfs.ubifs +* mkfs.ubifs -- nanddump +* nanddump -- nandtest +* nandtest -- nandwrite +* nandwrite -- ubiattach +* ubiattach -- ubicrc32 +* ubicrc32 -- ubidetach +* ubidetach -- ubiformat +* ubiformat -- ubimkvol +* ubimkvol -- ubinfo +* ubinfo -- ubinize +* ubinize -- ubirename +* ubirename -- ubirmvol +* ubirmvol -- ubirsvol +* ubirsvol -- ubiupdatevol +* ubiupdatevol The mtd-utils package as a whole (including all of its executable binaries) shall not be present on the file system. Including these @@ -721,7 +709,6 @@ Kernel Hardening The following flags shall be used for mounting common filesystems: - | Partition | Notes | |------------------------------|---------------------------------------------------------------------------------------------| | /boot | Use nosuid and nodev and consider using noexec. | @@ -734,10 +721,8 @@ Kernel Hardening | | Note: if CONFIG\_DEVTMPFS\_MOUNT is set then the kernel will mount /dev and will not apply | | | the nosuid, noexec options. Either disable CONFIG\_DEVTMPFS\_MOUNT or add a remount with | | | noexec and nosuid options to system startup. | - -Recommendations -=============== +## Recommendations The following sections detail best practices that should be applied in order to secure a device. @@ -746,8 +731,7 @@ requirements, they may be upgraded to requirements status in the future. In addition, specific operators may change some of these recommendations into requirements based on their specific needs and objectives. -Hardened Boot -------------- +### Hardened Boot The boot loader consists of the Primary boot loader residing in OTP memory, sboot, U-Boot and Secure loader residing in external flash (NAND @@ -762,7 +746,7 @@ Kernel/system image before passing control to it. In U-Boot, following commands shall be disabled to avoid memory dumps -``` +```bash md : Memory Display command mm : Memory modify command – auto incrementing address @@ -794,8 +778,7 @@ to be disabled. Similarly sboot should disable flash access support through command line if any. -Hardened System ---------------- +## Hardened System ### Network @@ -805,7 +788,7 @@ Hardened System enabled services should be restricted to only those described in the STB’s functional description. -### Remove or Disable Unnecessary Services, Ports, and Devices. +### Remove or Disable Unnecessary Services, Ports, and Devices Services and utilities that do not have a defined purpose on a system should be removed. If removal is not possible, but the service or @@ -829,8 +812,7 @@ Hardened System Whether or not the filesystems are mounted in userspace(FUSE), restricted mount options should be observed. -Kernel Hardening ----------------- +## Kernel Hardening The following sub-sections contain information on various kernel configuration options that will require updating to a newer kernel @@ -896,6 +878,7 @@ Kernel Hardening This configuration is supported in Linux 3.5 and greater and thus should only be disabled for such versions. + ```bash CROSS_MEMORY_ATTACH=n ``` @@ -1025,35 +1008,43 @@ applications to avoid stack smashing, buffer overflow attacks. ### Stack Smashing Attacks - **-fstack-protector-all** - - Emit extra code to check for buffer overflows, such as stack smashing - attacks +```c +**-fstack-protector-all** +``` + +Emit extra code to check for buffer overflows, such as stack smashing attacks ### Position Independent Executables - **-pie –fpic** - - Produce a position independent executable on targets which supports - it. +```c +**-pie –fpic**: +``` + +Produce a position independent executable on targets which supports it. ### Detect Buffer Overflows - **-D\_FORTIFY\_SOURCE=2** - - Helps detect some buffer overflow errors. +```c +**-D\_FORTIFY\_SOURCE=2**: +``` + +Helps detect some buffer overflow errors. ### Prevent Overwrite Attacks - **–z,relro** - +```c +**–z,relro** +``` + This linking option helps during program load, several ELF memory sections need to be written by the linker, but can be turned read-only before turning over control to the program. This prevents some Global Offset Table GOT overwrite attacks, or in the dtors section of the ELF binary. - - **-z,now** + +```c +**-z,now** +``` During program load, all dynamic symbols are resolved, allowing for the complete GOT to be marked read-only (due to -z relro above). This @@ -1063,14 +1054,15 @@ resolved, but this shouldn't be an issue for daemons. ### Library linking - **–static** +```c +**–static** +``` It is recommended that dynamic linking should not be allowed. This will avoid user from replacing a library with malicious library. All libraries should be linked statically. -Removal or Non-Inclusion of Utilities -------------------------------------- +## Removal or Non-Inclusion of Utilities Table below lists utilities that are typically present in an embedded device, along with the normal path of each utility. The table has @@ -1119,8 +1111,7 @@ utilities are not required by the device then those should be removed. **sed, awk, cut, df, dmesg, echo, fdisk, grep, mkdir, mount (vfat), printf, tail, tee, test (directory), test (file)** -Root Access ------------- +## Root Access The main applications, those that provide the principal functionality of the embedded device, **should not execute** with root identity or any @@ -1143,7 +1134,7 @@ the same resources at the same time. Root access **should not be allowed** for the following utilities: -``` +```bash login su ssh @@ -1158,8 +1149,7 @@ user accounts. Switching to elevated privileges shall be allowed in the development environment via sudo. -Network Hardening ------------------ +## Network Hardening ### Disable IPv4 Forwarding @@ -1234,14 +1224,11 @@ Network Hardening SYN requests with the appropriate SYN+ACK reply, but it does not store the connection in its backlog queue. +## Validation -Validation -========== - -Hardened System ---------------- +### Hardened System -### Image Security Analysis Framework (ISAFW) +#### Image Security Analysis Framework (ISAFW) **meta-security-isafw** is an OE layer that allows enabling the Image Security Analysis Framework (isafw) for your image builds. @@ -1251,12 +1238,12 @@ framework for analysing different security aspects of images during the build process. The isafw project itself can be found at - https://github.com/01org/isafw + <https://github.com/01org/isafw> This layer can be added to your builds to produce an analysis report, including a kernel config analysis. -### Usage +#### Usage In order to enable the isafw during the image build, please add the following line to your build/conf/local.conf file: diff --git a/sec-blueprint/index.md b/sec-blueprint/index.md index 9135a43..e20c2aa 100644 --- a/sec-blueprint/index.md +++ b/sec-blueprint/index.md @@ -8,7 +8,6 @@ layout: techdoc --- - ## [Overview](./01-overview.html) ## [Plateform Security](./02-plateform-security.html) diff --git a/signaling/architecture.md b/signaling/architecture.md index 48d596f..2132c4a 100644 --- a/signaling/architecture.md +++ b/signaling/architecture.md @@ -12,6 +12,7 @@ layout: techdoc **Table of Content** 1. TOC + {:toc} ## Context @@ -38,9 +39,9 @@ Our objectives are solving following 3 key issues: 1. reduce as much as possible the amount of exchanged data to the meaningful subset really used by applications -2. offer a high level API that obfuscates low level and proprietary interface to +1. offer a high level API that obfuscates low level and proprietary interface to improve stability in time of the code -3. hide specificities of low level implementation as well as the chosen +1. hide specificities of low level implementation as well as the chosen deployment distribution model. To reach first objective, events emission frequency should be controlled at the @@ -439,13 +440,10 @@ outside world.  -1. Application requests Virtual Signal exactly like if it was a low level - signal -2. Agent Signal has direct relation to low level signal -3. Agent needs to proxy to an other service inside the same ECU to access the - signal -4. Signal is not present on current ECU. Request has to be proxied to the - outside world +1. Application requests Virtual Signal exactly like if it was a low level signal +1. Agent Signal has direct relation to low level signal +1. Agent needs to proxy to an other service inside the same ECU to access the signal +1. Signal is not present on current ECU. Request has to be proxied to the outside world [AppFw]: http://iot.bzh/download/public/2016/appfw/01_Introduction-to-AppFW-for-AGL-1.0.pdf "Application Framework" [APcore]: http://iot.bzh/download/public/2016/appfw/03_Documentation-AppFW-Core-1.0.pdf "AppFw Core" diff --git a/signaling/high-level-viwi-service.md b/signaling/high-level-viwi-service.md index 6b512b9..bfc27d7 100644 --- a/signaling/high-level-viwi-service.md +++ b/signaling/high-level-viwi-service.md @@ -46,7 +46,7 @@ git clone --recursive https://gerrit.automotivelinux.org/gerrit/apps/low-level-c ```bash export WD=$(pwd) -git clone --recusive https://github.com/iotbzh/high-level-viwi-service.git +git clone --recursive https://github.com/iotbzh/high-level-viwi-service.git ``` ## Build @@ -82,41 +82,41 @@ For instance: ```json { - "name": "/car/demoboard/", - "properties": { - "id": { - "type": "string", - "description": "identifier" - }, - "uri": { - "type": "string", - "description": "object uri" - }, - "name": { - "type": "string", - "description": "name" - }, - "unit": { - "type": "string", - "description": "units" - }, - "speed": { - "type": "double", - "description": "vehicle centerpoint speed as shown by the instrument cluster" - }, - "rpm": { - "type": "double", - "description": "engine rotations per minute" - }, - "level": { - "type": "double", - "description": "level of tankage" - }, - "load": { - "type": "double", - "description": "engine load" - } - } + "name": "/car/demoboard/", + "properties": { + "id": { + "type": "string", + "description": "identifier" + }, + "uri": { + "type": "string", + "description": "object uri" + }, + "name": { + "type": "string", + "description": "name" + }, + "unit": { + "type": "string", + "description": "units" + }, + "speed": { + "type": "double", + "description": "vehicle centerpoint speed as shown by the instrument cluster" + }, + "rpm": { + "type": "double", + "description": "engine rotations per minute" + }, + "level": { + "type": "double", + "description": "level of tankage" + }, + "load": { + "type": "double", + "description": "engine load" + } + } } ``` @@ -138,24 +138,24 @@ For instance: ```json { - "name": "/car/demoboard/", - "values": [{ - "name": "vehicleSpeed", - "unit": "km/h", - "speed": "${diagnostic_messages.vehicle.speed,1000}" - }, { - "name": "engineSpeed", - "unit": "rpm", - "rpm": "${diagnostic_messages.engine.speed,1000}" - }, { - "name": "fuelLevel", - "unit": "litre", - "level": "${diagnostic_messages.fuel.level,1000}" - }, { - "name": "engineLoad", - "unit": "Nm", - "load": "${diagnostic_messages.engine.load,1000}" - }] + "name": "/car/demoboard/", + "values": [{ + "name": "vehicleSpeed", + "unit": "km/h", + "speed": "${diagnostic_messages.vehicle.speed,1000}" + }, { + "name": "engineSpeed", + "unit": "rpm", + "rpm": "${diagnostic_messages.engine.speed,1000}" + }, { + "name": "fuelLevel", + "unit": "litre", + "level": "${diagnostic_messages.fuel.level,1000}" + }, { + "name": "engineLoad", + "unit": "Nm", + "load": "${diagnostic_messages.engine.load,1000}" + }] } ``` @@ -185,7 +185,7 @@ On another terminal, connect to the binding using previously installed _**AFB Websocket CLI**_ tool: ```bash -$ afb-client-demo ws://localhost:1234/api?token=1 +afb-client-demo ws://localhost:1234/api?token=1 ``` You will be on an interactive session where you can communicate directly with @@ -197,7 +197,7 @@ _unsubscribe_, which can take a JSON object as an argument. To use the _**AFB Websocket CLI**_ tool, a command line will be like the following: -``` +```bash <api> <verb> <arguments> ``` @@ -209,7 +209,7 @@ Where: You can therefore use commands such as: -``` +```json high-can subscribe {"name":"/car/doors/","interval":10000} high-can unsubscribe {"name":"/car/doors/","interval":10000} high-can get {"name":"/car/demoboard/"} @@ -218,7 +218,7 @@ high-can get {"name":"/car/demoboard/","fields":["fuelLevel","engineLoad"]} For instance the output of the third command should be: -``` +```json high-can get {"name":"/car/demoboard/"} ON-REPLY 1:high-can/get: {"response":{"\/car\/demoboard\/2159e2-5b638a-39e242-7a2f5":{"id":"2159e2-5b638a-39e242-7a2f5","name":"vehicleSpeed","speed":0.000000,"unit":"km\/h","uri":"\/car\/demoboard\/2159e2-5b638a-39e242-7a2f5"},"\/car\/demoboard\/22ad2c-5a3c2b-50fabb-324c82":{"id":"22ad2c-5a3c2b-50fabb-324c82","level":0.000000,"name":"fuelLevel","unit":"litre","uri":"\/car\/demoboard\/22ad2c-5a3c2b-50fabb-324c82"},"\/car\/demoboard\/3a3ab9-2bd52c-11d30-689acf":{"id":"3a3ab9-2bd52c-11d30-689acf","name":"engineSpeed","rpm":0.000000,"unit":"rpm","uri":"\/car\/demoboard\/3a3ab9-2bd52c-11d30-689acf"},"\/car\/demoboard\/5ae808-8093cb-99716-30a605":{"id":"5ae808-8093cb-99716-30a605","load":0.000000,"name":"engineLoad","unit":"Nm","uri":"\/car\/demoboard\/5ae808-8093cb-99716-30a605"}},"jtype":"afb-reply","request":{"status":"success","uuid":"44ce03f9-a7ca-49e1-a62a-40c74db0caa0"}} ``` @@ -232,5 +232,5 @@ You can find an example of data in high level binding, "samples" directory. For instance, on a third terminal: ```bash -$ canplayer -I candata -```
\ No newline at end of file +canplayer -I candata +``` diff --git a/signaling/low-level-can-service-guide.md b/signaling/low-level-can-service-guide.md index 6b3eb47..821f3e9 100644 --- a/signaling/low-level-can-service-guide.md +++ b/signaling/low-level-can-service-guide.md @@ -18,7 +18,7 @@ CAN binding will be separated in two parts:  -- High level: Binding from which others applications will connect to. +* High level: Binding from which others applications will connect to. It provides valuable access to the CAN bus by aggregate signals or providing new signals from several originals. For example, a signal exposing whether or not a door is open, no matter which one it is. Also, we can imagine an @@ -27,7 +27,7 @@ CAN binding will be separated in two parts: a single event representing that behavior to the application which in turn will send a phone message to. -- Low level: Decode messages that transit and send event through **Application +* Low level: Decode messages that transit and send event through **Application Framework** to the subscribers with human readable message. It provides some basic access to the bus + some basic mathematical, statistical features (last_values, min, max, timestamps, averaging) as well as basic filter to get @@ -40,13 +40,13 @@ OpenXC inspired [AGL low level CAN binding Generator](http://github.com/iotbzh/c # Prerequisites -- An AGL system installed with latest Daring Dab version with latest Application +* An AGL system installed with latest Daring Dab version with latest Application framework version >= 0.6. -- Make sure you built the AGL generator else you will not be able to generate +* Make sure you built the AGL generator else you will not be able to generate custom low-level CAN binding. It will produce a _application-generated.cpp_ file to paste in the source, _CAN-binder/low-can-binding/binding/_, directory. -- Make sure you already set up the AGL SDK using the following +* Make sure you already set up the AGL SDK using the following [SDK Quick Setup Guide](http://docs.iot.bzh/docs/getting_started/en/dev/reference/setup-sdk-environment.html). Alternatively, please refer to official guides available on [AGL Developer Site](http://docs.automotivelinux.org/docs/devguides/en/dev/#guides). @@ -63,7 +63,7 @@ prepare_meta -f iotbzh -o /xdt -l /home/devel/mirror -p /home/devel/share/propri /xdt/build/m3ulcb/agl-init-build-env ``` -- (Optionnal) An [USB CAN adapter](http://shop.8devices.com/usb2can) connected to +* (Optionnal) An [USB CAN adapter](http://shop.8devices.com/usb2can) connected to connector through the [right cable](http://www.mouser.fr/ProductDetail/EasySync/OBD-M-DB9-F-ES/)) if you want to connect to a real car through the OBD2 connector. @@ -73,8 +73,8 @@ if you want to connect to a real car through the OBD2 connector. ### Build requirements -- CMake version 3.3 or later -- G++, Clang++ or any C++11 compliant compiler. +* CMake version 3.3 or later +* G++, Clang++ or any C++11 compliant compiler. ### Compile @@ -102,7 +102,7 @@ to the right the more it will be accurate. Let's take an example, here is an example about standard PID name following this convention: -``` +```bash engine.load engine.coolant.temperature fuel.pressure @@ -136,10 +136,10 @@ engine.torque You can use some basic decoder provided by default by the binding which are: -- ***decoder_t::noopDecoder*** : Default decoder if not specified, return raw +* ***decoder_t::noopDecoder*** : Default decoder if not specified, return raw value from signal's bitfield. -- ***decoder_t::booleanDecoder*** : Coerces a numerical value to a boolean. -- ***decoder_t::stateDecoder***s : Find and return the corresponding string +* ***decoder_t::booleanDecoder*** : Coerces a numerical value to a boolean. +* ***decoder_t::stateDecoder***s : Find and return the corresponding string state for a CAN signal's raw integer value. ### Generating JSON from Vector CANoe Database @@ -152,9 +152,9 @@ be able to use the OpenXC `xml_to_json.py` script to make your JSON for you. First, export the Canoe .dbc file as XML - you can do this with Vector CANdb++. Next, create a JSON file according to the format defined above, but only define: -- CAN messages. -- Name of CAN signals within messages and their generic_name. -- Optionnaly name of diagnostic messages and their name. +* CAN messages. +* Name of CAN signals within messages and their generic_name. +* Optionnaly name of diagnostic messages and their name. To install the OpenXC utilities and runs `xml_to_json.py` script: @@ -212,9 +212,9 @@ binding. ### Build requirements -- Kernel >= 4.8 -- CMake version 3.3 or later -- G++, Clang++ or any C++11 compliant compiler. +* Kernel >= 4.8 +* CMake version 3.3 or later +* G++, Clang++ or any C++11 compliant compiler. ### Compile @@ -254,6 +254,7 @@ On the target, assuming _**wgt**_ file is in the root home directory: afm-util install low-can-service.wgt { "added": "low-can-service@4.0" } ``` + # Configure the AGL system ## Virtual CAN device @@ -359,7 +360,7 @@ in section `CANbus-mapping`. Default binding configuration use a CAN bus named `hs` so you need to map it to the real one, here are some examples: -- Using virtual CAN device as described in the previous chapter: +* Using virtual CAN device as described in the previous chapter: ```ini [CANbus-mapping] @@ -367,7 +368,7 @@ hs="vcan0" ls="vcan1" ``` -- Using real CAN device, this example assume CAN bus traffic will be on can0. +* Using real CAN device, this example assume CAN bus traffic will be on can0. ```ini [CANbus-mapping] @@ -375,7 +376,7 @@ hs="can0" ls="can1" ``` -- On a Rcar Gen3 board there is an embedded CAN device so `can0` already +* On a Rcar Gen3 board there is an embedded CAN device so `can0` already exists. So you might want to use your USB CAN adapter plugged to the OBD2 connector, in this case use `can1`: @@ -388,7 +389,7 @@ hs="can1" > configuration file match those specified in your generated source file with > the `CAN-config-generator`. -# Run it, test it, use it ! +# Run it, test it, use it You can run the binding using **afm-util** tool, here is the classic way to go: @@ -438,7 +439,7 @@ JSON file used to generate cpp file for the binding. To use the _**AFB Websocket CLI**_ tool, a command line will be like the following : -``` +```xml <api> <verb> <arguments> ``` @@ -515,13 +516,13 @@ It is possible to limits received event notifications into minimum and maximum boundaries as well as doing frequency thinning. This is possible using the argument filter with one or more of the filters available : -- frequency: specify in Hertz the frequency which will be used to getting +* frequency: specify in Hertz the frequency which will be used to getting notified of new CAN events for the designated signal. If, during the blocked time, further changed CAN messages are received, the last valid one will be transferred after the lockout with a RX_CHANGED. -- min: Minimum value that the decoded value needs to be above to get pushed +* min: Minimum value that the decoded value needs to be above to get pushed to the subscribed client(s). -- max: Maximum value that the decoded value needs to be below to get pushed to +* max: Maximum value that the decoded value needs to be below to get pushed to the subscribed client(s) Order doesn't matter neither the number of filters chosen, you can use one, two |