From 8be9db6f309e1e1b547e187c5db6ceac15f85a50 Mon Sep 17 00:00:00 2001 From: Vinod Ahuja Date: Mon, 7 Nov 2022 16:18:44 -0600 Subject: Fixing the index numbering Fixing the index numbering for all documentation Bug-AGL: [SPEC-4470] Signed-off-by: Vinod Ahuja Change-Id: I96b482a3ab598f0739c692e301de66c0553ba0e4 Reviewed-on: https://gerrit.automotivelinux.org/gerrit/c/AGL/documentation/+/28118 Reviewed-by: Walt Miner Reviewed-by: Jan-Simon Moeller Tested-by: Jan-Simon Moeller --- .../1_Quickstart/Using_Ready_Made_Images.md | 385 ------- .../RaspberryPi2-ModelB-debug-serial-cable.png | Bin 411744 -> 0 bytes .../1_Quickstart/images/vbox-1.png | Bin 111792 -> 0 bytes .../1_Quickstart/images/vbox-2.png | Bin 95870 -> 0 bytes .../1_Quickstart/images/vbox-3.png | Bin 120188 -> 0 bytes .../1_Quickstart/images/vbox-4.png | Bin 79510 -> 0 bytes .../1_Quickstart/images/vbox-5.png | Bin 68911 -> 0 bytes .../2_Building_AGL_Image/0_Build_Process.md | 33 - .../1_Preparing_Your_Build_Host.md | 67 -- .../2_Downloading_AGL_Software.md | 102 -- .../3_Initializing_Your_Build_Environment.md | 255 ----- .../4_Customizing_Your_Build.md | 151 --- .../5_0_Building_the_AGL_Image.md | 21 - .../5_1_x86_Emulation_and_Hardware.md | 255 ----- .../2_Building_AGL_Image/5_2_Raspberry_Pi_4.md | 204 ---- .../2_Building_AGL_Image/5_3_RCar_Gen_3.md | 894 --------------- .../2_Building_AGL_Image/5_4_Virtio.md | 151 --- .../RaspberryPi2-ModelB-debug-serial-cable.png | Bin 411744 -> 0 bytes .../images/image-developer-workflow.png | Bin 93940 -> 0 bytes .../2_Building_AGL_Image/images/vbox-1.png | Bin 111792 -> 0 bytes .../2_Building_AGL_Image/images/vbox-2.png | Bin 95870 -> 0 bytes .../2_Building_AGL_Image/images/vbox-3.png | Bin 120188 -> 0 bytes .../2_Building_AGL_Image/images/vbox-4.png | Bin 79510 -> 0 bytes .../2_Building_AGL_Image/images/vbox-5.png | Bin 68911 -> 0 bytes ...nt_Cluster_(IC-IVI_with_Container_isolation).md | 124 -- .../2_Flutter_Instrument_Cluster_(qemu-x86).md | 126 -- .../2_IVI_Flutter_apps.md | 78 -- .../images/flutter_instrument_cluster.png | Bin 601550 -> 0 bytes .../images/flutter_instrument_cluster_map.png | Bin 715977 -> 0 bytes .../images/ivi_homescreen.PNG | Bin 930228 -> 0 bytes .../1_Quickstart/1_Using_Ready_Made_Images.md | 385 +++++++ .../RaspberryPi2-ModelB-debug-serial-cable.png | Bin 0 -> 411744 bytes .../1_Quickstart/images/vbox-1.png | Bin 0 -> 111792 bytes .../1_Quickstart/images/vbox-2.png | Bin 0 -> 95870 bytes .../1_Quickstart/images/vbox-3.png | Bin 0 -> 120188 bytes .../1_Quickstart/images/vbox-4.png | Bin 0 -> 79510 bytes .../1_Quickstart/images/vbox-5.png | Bin 0 -> 68911 bytes .../2_Building_AGL_Image/1_Build_Process.md | 33 + .../2_Preparing_Your_Build_Host.md | 67 ++ .../3_Downloading_AGL_Software.md | 102 ++ .../4_Initializing_Your_Build_Environment.md | 255 +++++ .../5_Customizing_Your_Build.md | 151 +++ .../6_Building_the_AGL_Image.md | 21 + .../7_x86_Emulation_and_Hardware.md | 255 +++++ .../2_Building_AGL_Image/8_Raspberry_Pi_4.md | 204 ++++ .../2_Building_AGL_Image/9_RCar_Gen_3.md | 894 +++++++++++++++ .../2_Building_AGL_Image/A_Virtio.md | 151 +++ .../RaspberryPi2-ModelB-debug-serial-cable.png | Bin 0 -> 411744 bytes .../images/image-developer-workflow.png | Bin 0 -> 93940 bytes .../2_Building_AGL_Image/images/vbox-1.png | Bin 0 -> 111792 bytes .../2_Building_AGL_Image/images/vbox-2.png | Bin 0 -> 95870 bytes .../2_Building_AGL_Image/images/vbox-3.png | Bin 0 -> 120188 bytes .../2_Building_AGL_Image/images/vbox-4.png | Bin 0 -> 79510 bytes .../2_Building_AGL_Image/images/vbox-5.png | Bin 0 -> 68911 bytes ...nt_Cluster_(IC-IVI_with_Container_isolation).md | 124 ++ .../2_Flutter_Instrument_Cluster_(qemu-x86).md | 126 ++ .../3_IVI_Flutter_apps.md | 78 ++ .../images/flutter_instrument_cluster.png | Bin 0 -> 601550 bytes .../images/flutter_instrument_cluster_map.png | Bin 0 -> 715977 bytes .../images/ivi_homescreen.PNG | Bin 0 -> 930228 bytes docs/1_Hardware_Support/Overview.md | 48 - .../Supported_Hardware_Images.md | 97 -- .../1_Introduction/0_Overview.md | 53 - .../1_AGL_Requirements_Specifications.md | 8 - .../AGL Requirements Specifications.pdf | Bin 3801991 -> 0 bytes .../1_Introduction/images/architecture.jpg | Bin 687441 -> 0 bytes .../2_Security_Blueprint/0_Overview.md | 250 ---- .../2_Security_Blueprint/1_Hardware.md | 64 -- .../2_Security_Blueprint/2_Secure_Boot.md | 261 ----- .../2_Security_Blueprint/3_Hypervisor.md | 17 - .../2_Security_Blueprint/4_Kernel.md | 941 --------------- .../2_Security_Blueprint/5_Platform.md | 921 --------------- .../2_Security_Blueprint/6_Application.md | 125 -- .../2_Security_Blueprint/7_Connectivity.md | 487 -------- .../2_Security_Blueprint/8_Update_OTA.md | 154 --- .../2_Security_Blueprint/9_Secure_development.md | 58 - .../2_Security_Blueprint/Annexes.md | 578 ---------- .../2_Security_Blueprint/images/App-flow.png | Bin 73545 -> 0 bytes .../images/App_signing_flow.png | Bin 154923 -> 0 bytes .../2_Security_Blueprint/images/WhiteBoxArchi.png | Bin 348110 -> 0 bytes docs/2_Hardware_Support/1_Overview.md | 48 + .../2_Supported_Hardware_Images.md | 97 ++ .../1_Introduction/1_Overview.md | 53 + .../2_AGL_Requirements_Specifications.md | 8 + .../AGL Requirements Specifications.pdf | Bin 0 -> 3801991 bytes .../1_Introduction/images/architecture.jpg | Bin 0 -> 687441 bytes .../2_Security_Blueprint/1_Overview.md | 250 ++++ .../2_Security_Blueprint/2_Hardware.md | 64 ++ .../2_Security_Blueprint/3_Secure_Boot.md | 261 +++++ .../2_Security_Blueprint/4_Hypervisor.md | 17 + .../2_Security_Blueprint/5_Kernel.md | 941 +++++++++++++++ .../2_Security_Blueprint/6_Platform.md | 921 +++++++++++++++ .../2_Security_Blueprint/7_Application.md | 125 ++ .../2_Security_Blueprint/8_Connectivity.md | 487 ++++++++ .../2_Security_Blueprint/9_Update_OTA.md | 154 +++ .../2_Security_Blueprint/A_Secure_development.md | 58 + .../2_Security_Blueprint/B_Annexes.md | 578 ++++++++++ .../2_Security_Blueprint/images/App-flow.png | Bin 0 -> 73545 bytes .../images/App_signing_flow.png | Bin 0 -> 154923 bytes .../2_Security_Blueprint/images/WhiteBoxArchi.png | Bin 0 -> 348110 bytes .../1_Application_Framework/1_Introduction.md | 150 --- .../2_Application_Startup.md | 184 --- docs/3_Developer_Guides/1_Setting_Up_AGL_SDK.md | 70 -- .../3_Developer_Guides/2_Creating_a_New_Service.md | 151 --- .../3_Creating_a_New_Application.md | 135 --- .../4_Creating_a_custom_recipe.md | 49 - docs/3_Developer_Guides/5_General_setup.md | 94 -- docs/3_Developer_Guides/6_AGL_Layers/1_Overview.md | 25 - docs/3_Developer_Guides/6_AGL_Layers/2_meta-agl.md | 124 -- .../6_AGL_Layers/3_meta-agl-demo.md | 159 --- .../6_AGL_Layers/4_meta-agl-devel.md | 143 --- docs/3_Developer_Guides/images/AGL_add_recipe.png | Bin 27037 -> 0 bytes docs/4_APIs_and_Services/FIXME.md | 0 .../1_Application_Framework/1_Introduction.md | 150 +++ .../2_Application_Startup.md | 184 +++ docs/4_Developer_Guides/1_Setting_Up_AGL_SDK.md | 70 ++ docs/4_Developer_Guides/2_AGL_Layers/1_Overview.md | 25 + docs/4_Developer_Guides/2_AGL_Layers/2_meta-agl.md | 124 ++ .../2_AGL_Layers/3_meta-agl-demo.md | 159 +++ .../2_AGL_Layers/4_meta-agl-devel.md | 143 +++ .../4_Developer_Guides/2_Creating_a_New_Service.md | 151 +++ .../3_Creating_a_New_Application.md | 135 +++ .../4_Creating_a_custom_recipe.md | 49 + docs/4_Developer_Guides/5_General_setup.md | 94 ++ docs/4_Developer_Guides/images/AGL_add_recipe.png | Bin 0 -> 27037 bytes docs/5_APIs_and_Services/FIXME.md | 0 docs/5_Component_Documentation/0_AGL_components.md | 27 - docs/5_Component_Documentation/1_agl-compositor.md | 498 -------- .../2_waltham-receiver_waltham-transmitter.md | 96 -- docs/5_Component_Documentation/3_rba.md | 1207 -------------------- .../4_drm-leasemanager.md | 108 -- .../5_application_framework.md | 7 - .../6_pipewire_wireplumber.md | 159 --- .../7_ic-sound-manager.md | 120 -- .../images/agl-compositor/arch_diagram.png | Bin 369197 -> 0 bytes .../images/agl-compositor/drawing_shell.png | Bin 395940 -> 0 bytes .../images/ic-sound-manager/architecture.png | Bin 41946 -> 0 bytes .../ic-sound-manager/pipewire-ic-ipc-calls.png | Bin 50886 -> 0 bytes .../ic-sound-manager/pipewire-ic-ipc-processes.png | Bin 48959 -> 0 bytes .../images/rba/Basic_syntax.png | Bin 29945 -> 0 bytes .../5_Component_Documentation/images/rba/model.png | Bin 87500 -> 0 bytes docs/6_Component_Documentation/1_AGL_components.md | 27 + docs/6_Component_Documentation/2_agl-compositor.md | 498 ++++++++ .../3_waltham-receiver_waltham-transmitter.md | 96 ++ docs/6_Component_Documentation/4_rba.md | 1207 ++++++++++++++++++++ .../5_drm-leasemanager.md | 108 ++ .../6_application_framework.md | 7 + .../7_pipewire_wireplumber.md | 159 +++ .../8_ic-sound-manager.md | 120 ++ .../images/agl-compositor/arch_diagram.png | Bin 0 -> 369197 bytes .../images/agl-compositor/drawing_shell.png | Bin 0 -> 395940 bytes .../images/ic-sound-manager/architecture.png | Bin 0 -> 41946 bytes .../ic-sound-manager/pipewire-ic-ipc-calls.png | Bin 0 -> 50886 bytes .../ic-sound-manager/pipewire-ic-ipc-processes.png | Bin 0 -> 48959 bytes .../images/rba/Basic_syntax.png | Bin 0 -> 29945 bytes .../6_Component_Documentation/images/rba/model.png | Bin 0 -> 87500 bytes .../1_Getting_Linux_Foundation_account.md | 98 -- .../2_Using_Jira_for_current_work_items.md | 30 - docs/6_How_To_Contribute/3_Working_with_Gerrit.md | 153 --- docs/6_How_To_Contribute/4_Submitting_Changes.md | 68 -- docs/6_How_To_Contribute/5_Reviewing_Changes.md | 55 - .../6_Gerrit_Recommended_Practices.md | 263 ----- docs/6_How_To_Contribute/7_General_Guidelines.md | 163 --- docs/6_How_To_Contribute/8_Adding_Documentation.md | 121 -- .../9_Contribution_Checklist.md | 60 - .../A_How_to_setup_your_own_AGL_LAVA_Lab.md | 211 ---- docs/6_How_To_Contribute/images/jira-1.png | Bin 14224 -> 0 bytes docs/6_How_To_Contribute/images/jira-2.png | Bin 74302 -> 0 bytes docs/6_How_To_Contribute/images/jira-3.png | Bin 61399 -> 0 bytes docs/6_How_To_Contribute/images/review.png | Bin 56853 -> 0 bytes .../1_Getting_Linux_Foundation_account.md | 98 ++ .../2_Using_Jira_for_current_work_items.md | 30 + docs/7_How_To_Contribute/3_Working_with_Gerrit.md | 153 +++ docs/7_How_To_Contribute/4_Submitting_Changes.md | 68 ++ docs/7_How_To_Contribute/5_Reviewing_Changes.md | 55 + .../6_Gerrit_Recommended_Practices.md | 263 +++++ docs/7_How_To_Contribute/7_General_Guidelines.md | 163 +++ docs/7_How_To_Contribute/8_Adding_Documentation.md | 121 ++ .../9_Contribution_Checklist.md | 60 + .../A_How_to_setup_your_own_AGL_LAVA_Lab.md | 211 ++++ docs/7_How_To_Contribute/images/jira-1.png | Bin 0 -> 14224 bytes docs/7_How_To_Contribute/images/jira-2.png | Bin 0 -> 74302 bytes docs/7_How_To_Contribute/images/jira-3.png | Bin 0 -> 61399 bytes docs/7_How_To_Contribute/images/review.png | Bin 0 -> 56853 bytes 184 files changed, 11636 insertions(+), 11636 deletions(-) delete mode 100644 docs/0_Getting_Started/1_Quickstart/Using_Ready_Made_Images.md delete mode 100644 docs/0_Getting_Started/1_Quickstart/images/RaspberryPi2-ModelB-debug-serial-cable.png delete mode 100644 docs/0_Getting_Started/1_Quickstart/images/vbox-1.png delete mode 100644 docs/0_Getting_Started/1_Quickstart/images/vbox-2.png delete mode 100644 docs/0_Getting_Started/1_Quickstart/images/vbox-3.png delete mode 100644 docs/0_Getting_Started/1_Quickstart/images/vbox-4.png delete mode 100644 docs/0_Getting_Started/1_Quickstart/images/vbox-5.png delete mode 100644 docs/0_Getting_Started/2_Building_AGL_Image/0_Build_Process.md delete mode 100644 docs/0_Getting_Started/2_Building_AGL_Image/1_Preparing_Your_Build_Host.md delete mode 100644 docs/0_Getting_Started/2_Building_AGL_Image/2_Downloading_AGL_Software.md delete mode 100644 docs/0_Getting_Started/2_Building_AGL_Image/3_Initializing_Your_Build_Environment.md delete mode 100644 docs/0_Getting_Started/2_Building_AGL_Image/4_Customizing_Your_Build.md delete mode 100644 docs/0_Getting_Started/2_Building_AGL_Image/5_0_Building_the_AGL_Image.md delete mode 100644 docs/0_Getting_Started/2_Building_AGL_Image/5_1_x86_Emulation_and_Hardware.md delete mode 100644 docs/0_Getting_Started/2_Building_AGL_Image/5_2_Raspberry_Pi_4.md delete mode 100644 docs/0_Getting_Started/2_Building_AGL_Image/5_3_RCar_Gen_3.md delete mode 100644 docs/0_Getting_Started/2_Building_AGL_Image/5_4_Virtio.md delete mode 100644 docs/0_Getting_Started/2_Building_AGL_Image/images/RaspberryPi2-ModelB-debug-serial-cable.png delete mode 100644 docs/0_Getting_Started/2_Building_AGL_Image/images/image-developer-workflow.png delete mode 100644 docs/0_Getting_Started/2_Building_AGL_Image/images/vbox-1.png delete mode 100644 docs/0_Getting_Started/2_Building_AGL_Image/images/vbox-2.png delete mode 100644 docs/0_Getting_Started/2_Building_AGL_Image/images/vbox-3.png delete mode 100644 docs/0_Getting_Started/2_Building_AGL_Image/images/vbox-4.png delete mode 100644 docs/0_Getting_Started/2_Building_AGL_Image/images/vbox-5.png delete mode 100644 docs/0_Getting_Started/3_Build_and_Boot_guide_Profile/1_Instrument_Cluster_(IC-IVI_with_Container_isolation).md delete mode 100644 docs/0_Getting_Started/3_Build_and_Boot_guide_Profile/2_Flutter_Instrument_Cluster_(qemu-x86).md delete mode 100644 docs/0_Getting_Started/3_Build_and_Boot_guide_Profile/2_IVI_Flutter_apps.md delete mode 100644 docs/0_Getting_Started/3_Build_and_Boot_guide_Profile/images/flutter_instrument_cluster.png delete mode 100644 docs/0_Getting_Started/3_Build_and_Boot_guide_Profile/images/flutter_instrument_cluster_map.png delete mode 100644 docs/0_Getting_Started/3_Build_and_Boot_guide_Profile/images/ivi_homescreen.PNG create mode 100644 docs/1_Getting_Started/1_Quickstart/1_Using_Ready_Made_Images.md create mode 100644 docs/1_Getting_Started/1_Quickstart/images/RaspberryPi2-ModelB-debug-serial-cable.png create mode 100644 docs/1_Getting_Started/1_Quickstart/images/vbox-1.png create mode 100644 docs/1_Getting_Started/1_Quickstart/images/vbox-2.png create mode 100644 docs/1_Getting_Started/1_Quickstart/images/vbox-3.png create mode 100644 docs/1_Getting_Started/1_Quickstart/images/vbox-4.png create mode 100644 docs/1_Getting_Started/1_Quickstart/images/vbox-5.png create mode 100644 docs/1_Getting_Started/2_Building_AGL_Image/1_Build_Process.md create mode 100644 docs/1_Getting_Started/2_Building_AGL_Image/2_Preparing_Your_Build_Host.md create mode 100644 docs/1_Getting_Started/2_Building_AGL_Image/3_Downloading_AGL_Software.md create mode 100644 docs/1_Getting_Started/2_Building_AGL_Image/4_Initializing_Your_Build_Environment.md create mode 100644 docs/1_Getting_Started/2_Building_AGL_Image/5_Customizing_Your_Build.md create mode 100644 docs/1_Getting_Started/2_Building_AGL_Image/6_Building_the_AGL_Image.md create mode 100644 docs/1_Getting_Started/2_Building_AGL_Image/7_x86_Emulation_and_Hardware.md create mode 100644 docs/1_Getting_Started/2_Building_AGL_Image/8_Raspberry_Pi_4.md create mode 100644 docs/1_Getting_Started/2_Building_AGL_Image/9_RCar_Gen_3.md create mode 100644 docs/1_Getting_Started/2_Building_AGL_Image/A_Virtio.md create mode 100644 docs/1_Getting_Started/2_Building_AGL_Image/images/RaspberryPi2-ModelB-debug-serial-cable.png create mode 100644 docs/1_Getting_Started/2_Building_AGL_Image/images/image-developer-workflow.png create mode 100644 docs/1_Getting_Started/2_Building_AGL_Image/images/vbox-1.png create mode 100644 docs/1_Getting_Started/2_Building_AGL_Image/images/vbox-2.png create mode 100644 docs/1_Getting_Started/2_Building_AGL_Image/images/vbox-3.png create mode 100644 docs/1_Getting_Started/2_Building_AGL_Image/images/vbox-4.png create mode 100644 docs/1_Getting_Started/2_Building_AGL_Image/images/vbox-5.png create mode 100644 docs/1_Getting_Started/3_Build_and_Boot_guide_Profile/1_Instrument_Cluster_(IC-IVI_with_Container_isolation).md create mode 100644 docs/1_Getting_Started/3_Build_and_Boot_guide_Profile/2_Flutter_Instrument_Cluster_(qemu-x86).md create mode 100644 docs/1_Getting_Started/3_Build_and_Boot_guide_Profile/3_IVI_Flutter_apps.md create mode 100644 docs/1_Getting_Started/3_Build_and_Boot_guide_Profile/images/flutter_instrument_cluster.png create mode 100644 docs/1_Getting_Started/3_Build_and_Boot_guide_Profile/images/flutter_instrument_cluster_map.png create mode 100644 docs/1_Getting_Started/3_Build_and_Boot_guide_Profile/images/ivi_homescreen.PNG delete mode 100644 docs/1_Hardware_Support/Overview.md delete mode 100644 docs/1_Hardware_Support/Supported_Hardware_Images.md delete mode 100644 docs/2_Architecture_Guides/1_Introduction/0_Overview.md delete mode 100644 docs/2_Architecture_Guides/1_Introduction/1_AGL_Requirements_Specifications.md delete mode 100644 docs/2_Architecture_Guides/1_Introduction/AGL Requirements Specifications.pdf delete mode 100644 docs/2_Architecture_Guides/1_Introduction/images/architecture.jpg delete mode 100644 docs/2_Architecture_Guides/2_Security_Blueprint/0_Overview.md delete mode 100644 docs/2_Architecture_Guides/2_Security_Blueprint/1_Hardware.md delete mode 100644 docs/2_Architecture_Guides/2_Security_Blueprint/2_Secure_Boot.md delete mode 100644 docs/2_Architecture_Guides/2_Security_Blueprint/3_Hypervisor.md delete mode 100644 docs/2_Architecture_Guides/2_Security_Blueprint/4_Kernel.md delete mode 100644 docs/2_Architecture_Guides/2_Security_Blueprint/5_Platform.md delete mode 100644 docs/2_Architecture_Guides/2_Security_Blueprint/6_Application.md delete mode 100644 docs/2_Architecture_Guides/2_Security_Blueprint/7_Connectivity.md delete mode 100644 docs/2_Architecture_Guides/2_Security_Blueprint/8_Update_OTA.md delete mode 100644 docs/2_Architecture_Guides/2_Security_Blueprint/9_Secure_development.md delete mode 100644 docs/2_Architecture_Guides/2_Security_Blueprint/Annexes.md delete mode 100644 docs/2_Architecture_Guides/2_Security_Blueprint/images/App-flow.png delete mode 100644 docs/2_Architecture_Guides/2_Security_Blueprint/images/App_signing_flow.png delete mode 100644 docs/2_Architecture_Guides/2_Security_Blueprint/images/WhiteBoxArchi.png create mode 100644 docs/2_Hardware_Support/1_Overview.md create mode 100644 docs/2_Hardware_Support/2_Supported_Hardware_Images.md create mode 100644 docs/3_Architecture_Guides/1_Introduction/1_Overview.md create mode 100644 docs/3_Architecture_Guides/1_Introduction/2_AGL_Requirements_Specifications.md create mode 100644 docs/3_Architecture_Guides/1_Introduction/AGL Requirements Specifications.pdf create mode 100644 docs/3_Architecture_Guides/1_Introduction/images/architecture.jpg create mode 100644 docs/3_Architecture_Guides/2_Security_Blueprint/1_Overview.md create mode 100644 docs/3_Architecture_Guides/2_Security_Blueprint/2_Hardware.md create mode 100644 docs/3_Architecture_Guides/2_Security_Blueprint/3_Secure_Boot.md create mode 100644 docs/3_Architecture_Guides/2_Security_Blueprint/4_Hypervisor.md create mode 100644 docs/3_Architecture_Guides/2_Security_Blueprint/5_Kernel.md create mode 100644 docs/3_Architecture_Guides/2_Security_Blueprint/6_Platform.md create mode 100644 docs/3_Architecture_Guides/2_Security_Blueprint/7_Application.md create mode 100644 docs/3_Architecture_Guides/2_Security_Blueprint/8_Connectivity.md create mode 100644 docs/3_Architecture_Guides/2_Security_Blueprint/9_Update_OTA.md create mode 100644 docs/3_Architecture_Guides/2_Security_Blueprint/A_Secure_development.md create mode 100644 docs/3_Architecture_Guides/2_Security_Blueprint/B_Annexes.md create mode 100644 docs/3_Architecture_Guides/2_Security_Blueprint/images/App-flow.png create mode 100644 docs/3_Architecture_Guides/2_Security_Blueprint/images/App_signing_flow.png create mode 100644 docs/3_Architecture_Guides/2_Security_Blueprint/images/WhiteBoxArchi.png delete mode 100644 docs/3_Developer_Guides/1_Application_Framework/1_Introduction.md delete mode 100644 docs/3_Developer_Guides/1_Application_Framework/2_Application_Startup.md delete mode 100644 docs/3_Developer_Guides/1_Setting_Up_AGL_SDK.md delete mode 100644 docs/3_Developer_Guides/2_Creating_a_New_Service.md delete mode 100644 docs/3_Developer_Guides/3_Creating_a_New_Application.md delete mode 100644 docs/3_Developer_Guides/4_Creating_a_custom_recipe.md delete mode 100644 docs/3_Developer_Guides/5_General_setup.md delete mode 100644 docs/3_Developer_Guides/6_AGL_Layers/1_Overview.md delete mode 100644 docs/3_Developer_Guides/6_AGL_Layers/2_meta-agl.md delete mode 100644 docs/3_Developer_Guides/6_AGL_Layers/3_meta-agl-demo.md delete mode 100644 docs/3_Developer_Guides/6_AGL_Layers/4_meta-agl-devel.md delete mode 100644 docs/3_Developer_Guides/images/AGL_add_recipe.png delete mode 100644 docs/4_APIs_and_Services/FIXME.md create mode 100644 docs/4_Developer_Guides/1_Application_Framework/1_Introduction.md create mode 100644 docs/4_Developer_Guides/1_Application_Framework/2_Application_Startup.md create mode 100644 docs/4_Developer_Guides/1_Setting_Up_AGL_SDK.md create mode 100644 docs/4_Developer_Guides/2_AGL_Layers/1_Overview.md create mode 100644 docs/4_Developer_Guides/2_AGL_Layers/2_meta-agl.md create mode 100644 docs/4_Developer_Guides/2_AGL_Layers/3_meta-agl-demo.md create mode 100644 docs/4_Developer_Guides/2_AGL_Layers/4_meta-agl-devel.md create mode 100644 docs/4_Developer_Guides/2_Creating_a_New_Service.md create mode 100644 docs/4_Developer_Guides/3_Creating_a_New_Application.md create mode 100644 docs/4_Developer_Guides/4_Creating_a_custom_recipe.md create mode 100644 docs/4_Developer_Guides/5_General_setup.md create mode 100644 docs/4_Developer_Guides/images/AGL_add_recipe.png create mode 100644 docs/5_APIs_and_Services/FIXME.md delete mode 100644 docs/5_Component_Documentation/0_AGL_components.md delete mode 100644 docs/5_Component_Documentation/1_agl-compositor.md delete mode 100644 docs/5_Component_Documentation/2_waltham-receiver_waltham-transmitter.md delete mode 100644 docs/5_Component_Documentation/3_rba.md delete mode 100644 docs/5_Component_Documentation/4_drm-leasemanager.md delete mode 100644 docs/5_Component_Documentation/5_application_framework.md delete mode 100644 docs/5_Component_Documentation/6_pipewire_wireplumber.md delete mode 100644 docs/5_Component_Documentation/7_ic-sound-manager.md delete mode 100644 docs/5_Component_Documentation/images/agl-compositor/arch_diagram.png delete mode 100644 docs/5_Component_Documentation/images/agl-compositor/drawing_shell.png delete mode 100644 docs/5_Component_Documentation/images/ic-sound-manager/architecture.png delete mode 100644 docs/5_Component_Documentation/images/ic-sound-manager/pipewire-ic-ipc-calls.png delete mode 100644 docs/5_Component_Documentation/images/ic-sound-manager/pipewire-ic-ipc-processes.png delete mode 100644 docs/5_Component_Documentation/images/rba/Basic_syntax.png delete mode 100644 docs/5_Component_Documentation/images/rba/model.png create mode 100644 docs/6_Component_Documentation/1_AGL_components.md create mode 100644 docs/6_Component_Documentation/2_agl-compositor.md create mode 100644 docs/6_Component_Documentation/3_waltham-receiver_waltham-transmitter.md create mode 100644 docs/6_Component_Documentation/4_rba.md create mode 100644 docs/6_Component_Documentation/5_drm-leasemanager.md create mode 100644 docs/6_Component_Documentation/6_application_framework.md create mode 100644 docs/6_Component_Documentation/7_pipewire_wireplumber.md create mode 100644 docs/6_Component_Documentation/8_ic-sound-manager.md create mode 100644 docs/6_Component_Documentation/images/agl-compositor/arch_diagram.png create mode 100644 docs/6_Component_Documentation/images/agl-compositor/drawing_shell.png create mode 100644 docs/6_Component_Documentation/images/ic-sound-manager/architecture.png create mode 100644 docs/6_Component_Documentation/images/ic-sound-manager/pipewire-ic-ipc-calls.png create mode 100644 docs/6_Component_Documentation/images/ic-sound-manager/pipewire-ic-ipc-processes.png create mode 100644 docs/6_Component_Documentation/images/rba/Basic_syntax.png create mode 100644 docs/6_Component_Documentation/images/rba/model.png delete mode 100644 docs/6_How_To_Contribute/1_Getting_Linux_Foundation_account.md delete mode 100644 docs/6_How_To_Contribute/2_Using_Jira_for_current_work_items.md delete mode 100644 docs/6_How_To_Contribute/3_Working_with_Gerrit.md delete mode 100644 docs/6_How_To_Contribute/4_Submitting_Changes.md delete mode 100644 docs/6_How_To_Contribute/5_Reviewing_Changes.md delete mode 100644 docs/6_How_To_Contribute/6_Gerrit_Recommended_Practices.md delete mode 100644 docs/6_How_To_Contribute/7_General_Guidelines.md delete mode 100644 docs/6_How_To_Contribute/8_Adding_Documentation.md delete mode 100644 docs/6_How_To_Contribute/9_Contribution_Checklist.md delete mode 100644 docs/6_How_To_Contribute/A_How_to_setup_your_own_AGL_LAVA_Lab.md delete mode 100644 docs/6_How_To_Contribute/images/jira-1.png delete mode 100644 docs/6_How_To_Contribute/images/jira-2.png delete mode 100644 docs/6_How_To_Contribute/images/jira-3.png delete mode 100644 docs/6_How_To_Contribute/images/review.png create mode 100644 docs/7_How_To_Contribute/1_Getting_Linux_Foundation_account.md create mode 100644 docs/7_How_To_Contribute/2_Using_Jira_for_current_work_items.md create mode 100644 docs/7_How_To_Contribute/3_Working_with_Gerrit.md create mode 100644 docs/7_How_To_Contribute/4_Submitting_Changes.md create mode 100644 docs/7_How_To_Contribute/5_Reviewing_Changes.md create mode 100644 docs/7_How_To_Contribute/6_Gerrit_Recommended_Practices.md create mode 100644 docs/7_How_To_Contribute/7_General_Guidelines.md create mode 100644 docs/7_How_To_Contribute/8_Adding_Documentation.md create mode 100644 docs/7_How_To_Contribute/9_Contribution_Checklist.md create mode 100644 docs/7_How_To_Contribute/A_How_to_setup_your_own_AGL_LAVA_Lab.md create mode 100644 docs/7_How_To_Contribute/images/jira-1.png create mode 100644 docs/7_How_To_Contribute/images/jira-2.png create mode 100644 docs/7_How_To_Contribute/images/jira-3.png create mode 100644 docs/7_How_To_Contribute/images/review.png (limited to 'docs') diff --git a/docs/0_Getting_Started/1_Quickstart/Using_Ready_Made_Images.md b/docs/0_Getting_Started/1_Quickstart/Using_Ready_Made_Images.md deleted file mode 100644 index eaae38e..0000000 --- a/docs/0_Getting_Started/1_Quickstart/Using_Ready_Made_Images.md +++ /dev/null @@ -1,385 +0,0 @@ ---- -title: Using Ready Made Images ---- - -AGL provides a number of pre-built ready-made images of various versions. - -## x86 (Emulation and Hardware) - -### 1. QEMU (Emulation) - -1. Download the [compressed prebuilt image](https://download.automotivelinux.org/AGL/snapshots/master/latest/qemux86-64/deploy/images/qemux86-64/agl-demo-platform-crosssdk-qemux86-64.ext4.xz). - -2. Download the [compressed kernel image](https://download.automotivelinux.org/AGL/snapshots/master/latest/qemux86-64/deploy/images/qemux86-64/bzImage). - -3. Install [QEMU](https://www.qemu.org/download/) : - - ```sh - $ apt-get install qemu - ``` - -4. Install [vinagre](https://wiki.gnome.org/Apps/Vinagre) : - - ```sh - $ sudo apt install vinagre - ``` - -5. Create boot directory and copy compressed images (prebuilt & kernel) into them : - - ```sh - $ mkdir ~/agl-demo/ - $ cp ~/Downloads/agl-demo-platform-crosssdk-qemux86-64.ext4.xz ~/agl-demo/ - $ cp ~/Downloads/bzImage ~/agl-demo/ - $ cd ~/agl-demo - $ sync - ``` - -6. Extract prebuilt compressed image : - - ```sh - $ xz -v -d agl-demo-platform-crosssdk-qemux86-64.ext4.xz - ``` - -7. Launch QEMU with vinagre (for scaling), remove `- snapshot \` if you want to save changes to the image files : - - ```sh - $ ( sleep 5 && vinagre --vnc-scale localhost ) > /tmp/vinagre.log 2>&1 & - $ qemu-system-x86_64 -device virtio-net-pci,netdev=net0,mac=52:54:00:12:35:02 -netdev user,id=net0,hostfwd=tcp::2222-:22 \ - -drive file=agl-demo-platform-crosssdk-qemux86-64.ext4,if=virtio,format=raw -show-cursor -usb -usbdevice tablet -device virtio-rng-pci \ - -snapshot -vga virtio \ - -vnc :0 -soundhw hda -machine q35 -cpu kvm64 -cpu qemu64,+ssse3,+sse4.1,+sse4.2,+popcnt -enable-kvm \ - -m 2048 -serial mon:vc -serial mon:stdio -serial null -kernel bzImage \ - -append 'root=/dev/vda rw console=tty0 mem=2048M ip=dhcp oprofile.timer=1 console=ttyS0,115200n8 verbose fstab=no' - ``` - - - Login into AGL : - - ```sh - Automotive Grade Linux 11.0.0+snapshot qemux86-64 ttyS1 - - qemux86-64 login: root - ``` - - - - Shutdown QEMU : `$ poweroff`, otherwise QEMU will run in the background. - - To use vnc-viewer instead of vinagre : - ```sh - $ ( sleep 5 && vncviewer ) & - qemu-system-x86_64 -device virtio-net-pci,netdev=net0,mac=52:54:00:12:35:02 -netdev user,id=net0,hostfwd=tcp::2222-:22 \ - -drive file=agl-demo-platform-crosssdk-qemux86-64.ext4,if=virtio,format=raw -show-cursor -usb -usbdevice tablet -device virtio-rng-pci \ - -snapshot -vga virtio \ - -vnc :0 -soundhw hda -machine q35 -cpu kvm64 -cpu qemu64,+ssse3,+sse4.1,+sse4.2,+popcnt -enable-kvm \ - -m 2048 -serial mon:vc -serial mon:stdio -serial null -kernel bzImage \ - -append 'root=/dev/vda rw console=tty0 mem=2048M ip=dhcp oprofile.timer=1 console=ttyS0,115200n8 verbose fstab=no' - ``` - -### 2. Virtual Box (Emulation) - -**NOTE :** Please note [https://www.virtualbox.org/ticket/19873](https://www.virtualbox.org/ticket/19873) as this affects the VMs resolution. -The AGL demo images do require 1920x1080. The instructions below have been adapted. - - 1. Download the [compressed vbox disk image](https://download.automotivelinux.org/AGL/snapshots/master/latest/qemux86-64/deploy/images/qemux86-64/agl-demo-platform-crosssdk-qemux86-64.wic.vmdk.xz). - - 2. Install and set up [Virtual Box](https://www.virtualbox.org/wiki/Linux_Downloads). - - 3. Extract the vmdk file : `$ xz -v -d agl-demo-platform-crosssdk-qemux86-64.wic.vmdk.xz` - - 4. Configure virtual box for AGL : - - Click on `New` or `Add`. - - Enter Name as `agl-demo`. - - Type as `Linux`. - - Version as `Other Linux (64-bit)`, click on `Next`. - ![vbox-step-1](images/vbox-1.png) - - Select Memory size. Recommended is `2048 MB`, click on `Next`. - ![vbox-step-2](images/vbox-2.png) - - Click on `Use an existing virtual hard disk file`, and select the extracted `agl-demo-platform-crosssdk-qemux86-64.wic.vmdk` file, click on `Create`. - ![vbox-step-3](images/vbox-3.png) - - Go to `Settings`, and into `System`. Select `Chipset : IHC9`. Check on `Enable EFI (special OSes only)` and click on `OK`. - ![vbox-step-4](images/vbox-4.png) - - Go to `Storage`, and change the attribute to `Type : AHCI` and click on `OK`. - ![vbox-step-5](images/vbox-5.png) - - Next go to `Display` and change the attribute to 'VMSVGA' for the graphics driver. Change the graphics memory to be at least 64MB. - - **Important:**: Open a new terminal window and execute this command: - ```sh - VBoxManage setextradata agl-demo VBoxInternal2/EfiGraphicsResolution 1920x1080 - ``` - - Return to the UI and click on `Start`. - - For troubleshooting, you can refer [here](https://lists.automotivelinux.org/g/agl-dev-community/message/8474). - -### 3. x86 physical system - - **NOTE :** UEFI enabled system is required. - - 1. Download the [compressed prebuilt image](https://download.automotivelinux.org/AGL/snapshots/master/latest/qemux86-64/deploy/images/qemux86-64/agl-demo-platform-crosssdk-qemux86-64.wic.xz). - - 2. Extract the image into USB drive : - - ```sh - $ lsblk - $ sudo umount - $ xzcat agl-demo-platform-crosssdk-qemux86-64.wic.xz | sudo dd of= bs=4M - $ sync - ``` - - - 3. Boot from USB drive on the x86 system. - -## ARM 32 bit (Emulation and Hardware) - -### 1. QEMU (Emulation) - -1. Download the [compressed prebuilt image](https://download.automotivelinux.org/AGL/snapshots/master/latest/qemuarm/deploy/images/qemuarm/agl-demo-platform-crosssdk-qemuarm.ext4.xz). - -2. Download the [compressed kernel image](https://download.automotivelinux.org/AGL/snapshots/master/latest/qemuarm/deploy/images/qemuarm/zImage). - -3. Install [QEMU](https://www.qemu.org/download/) : - - ```sh - $ apt-get install qemu - ``` - -4. Install [vinagre](https://wiki.gnome.org/Apps/Vinagre) : - - ```sh - $ sudo apt install vinagre - ``` - -5. Create boot directory and copy compressed images (prebuilt & kernel) into them : - - ```sh - $ mkdir ~/agl-demo/ - $ cp ~/Downloads/agl-demo-platform-crosssdk-qemuarm.ext4.xz ~/agl-demo/ - $ cp ~/Downloads/zImage ~/agl-demo/ - $ cd ~/agl-demo - $ sync - ``` - -6. Extract prebuilt compressed image : - - ```sh - $ xz -v -d agl-demo-platform-crosssdk-qemuarm.ext4.xz - ``` - -7. Launch QEMU with vinagre (for scaling), remove `- snapshot` if you want to save changes to the image files : - - ```sh - $ ( sleep 5 && vinagre --vnc-scale localhost ) > /tmp/vinagre.log 2>&1 & - qemu-system-arm -cpu cortex-a15 -machine virt-2.11 -nographic \ - -net nic,model=virtio,macaddr=52:54:00:12:34:58 \ - -net user -m 2048 -monitor none -soundhw hda -device usb-ehci \ - -device virtio-rng-pci -device VGA,vgamem_mb=64,edid=on -vnc :0 \ - -device qemu-xhci -device usb-tablet -device usb-kbd \ - -kernel zImage -append "console=ttyAMA0,115200 root=/dev/vda verbose systemd.log_color=false" \ - -drive format=raw,file=agl-demo-platform-crosssdk-qemuarm.ext4 \ - -snapshot - ``` - - - Login into AGL : - - ```sh - Automotive Grade Linux 11.0.0+snapshot qemux86-64 ttyS1 - - qemux86-64 login: root - ``` - - - - Shutdown QEMU : `$ poweroff`, otherwise QEMU will run in the background. - - To use vnc-viewer instead of vinagre : - ```sh - $ ( sleep 5 && vncviewer ) & - qemu-system-arm -cpu cortex-a15 -machine virt-2.11 -nographic \ - -net nic,model=virtio,macaddr=52:54:00:12:34:58 \ - -net user -m 2048 -monitor none -soundhw hda -device usb-ehci \ - -device virtio-rng-pci -device VGA,vgamem_mb=64,edid=on -vnc :0 \ - -device qemu-xhci -device usb-tablet -device usb-kbd \ - -kernel zImage -append "console=ttyAMA0,115200 root=/dev/vda verbose systemd.log_color=false" \ - -drive format=raw,file=agl-demo-platform-crosssdk-qemuarm.ext4 \ - -snapshot - ``` - -### 2. BeagleBone Enhanced (BBE) - - 1. Download the [compressed prebuilt image](https://download.automotivelinux.org/AGL/snapshots/master/latest/bbe/deploy/images/bbe/agl-demo-platform-crosssdk-bbe.wic.xz). - - 2. Extract the image into the SD card of BeagleBone Enhanced : - - ```sh - $ lsblk - $ sudo umount - $ xzcat agl-demo-platform-crosssdk-bbe.wic.xz | sudo dd of= bs=4M - $ sync - ``` - - **IMPORTANT NOTE:** Before re-writing any device on your Build Host, you need to - be sure you are actually writing to the removable MicroSD card and not some other - device. - Each computer is different and removable devices can change from time to time. - Consequently, you should repeat the previous operation with the MicroSD card to - confirm the device name every time you write to the card. - - To summarize this example so far, we have the following: - The first SATA drive is `/dev/sda` and `/dev/sdc` corresponds to the MicroSD card, and is also marked as a removable device.You can see this in the output of the `lsblk` command where "1" appears in the "RM" column for that device. - -## AARCH64 - ARM 64bit - -### 1. QEMU (Emulation) - -1. Download the [compressed prebuilt image](https://download.automotivelinux.org/AGL/snapshots/master/latest/qemuarm64/deploy/images/qemuarm64/agl-demo-platform-crosssdk-qemuarm64.ext4.xz). - -2. Download the [compressed kernel image](https://download.automotivelinux.org/AGL/snapshots/master/latest/qemuarm64/deploy/images/qemuarm64/Image). - -3. Install [QEMU](https://www.qemu.org/download/) : - - ```sh - $ apt-get install qemu - ``` - -4. Install [vinagre](https://wiki.gnome.org/Apps/Vinagre) : - - ```sh - $ sudo apt install vinagre - ``` - -5. Create boot directory and copy compressed images (prebuilt & kernel) into them : - - ```sh - $ mkdir ~/agl-demo/ - $ cp ~/Downloads/agl-demo-platform-crosssdk-qemuarm64.ext4.xz ~/agl-demo/ - $ cp ~/Downloads/zImage ~/agl-demo/ - $ cd ~/agl-demo - $ sync - ``` - -6. Extract prebuilt compressed image : - - ```sh - $ xz -v -d agl-demo-platform-crosssdk-qemuarm64.ext4.xz - ``` - -7. Launch QEMU with vinagre (for scaling), remove `- snapshot \` if you want to save changes to the image files : - - ```sh - $ ( sleep 5 && vinagre --vnc-scale localhost ) > /tmp/vinagre.log 2>&1 & - qemu-system-aarch64 -cpu cortex-a57 -machine virt -nographic \ - -net nic,model=virtio,macaddr=52:54:00:12:34:58 \ - -net user -m 2048 -monitor none -smp 2 -soundhw hda -device usb-ehci \ - -device virtio-rng-pci -device VGA,vgamem_mb=64,edid=on \ - -device qemu-xhci -device usb-tablet -device usb-kbd -vnc :0 \ - -kernel Image -append "console=ttyAMA0,115200 root=/dev/vda verbose systemd.log_color=false " \ - -drive format=raw,file=agl-demo-platform-crosssdk-qemuarm64.ext4 \ - -snapshot - ``` - - - Login into AGL : - - ```sh - Automotive Grade Linux 11.0.0+snapshot qemux86-64 ttyS1 - - qemux86-64 login: root - ``` - - - - Shutdown QEMU : `$ poweroff`, otherwise QEMU will run in the background. - - To use vnc-viewer instead of vinagre : - ```sh - $ ( sleep 5 && vncviewer ) & - qemu-system-aarch64 -cpu cortex-a57 -machine virt -nographic \ - -net nic,model=virtio,macaddr=52:54:00:12:34:58 \ - -net user -m 2048 -monitor none -smp 2 -soundhw hda -device usb-ehci \ - -device virtio-rng-pci -device VGA,vgamem_mb=64,edid=on \ - -device qemu-xhci -device usb-tablet -device usb-kbd -vnc :0 \ - -kernel Image -append "console=ttyAMA0,115200 root=/dev/vda verbose systemd.log_color=false " \ - -drive format=raw,file=agl-demo-platform-crosssdk-qemuarm64.ext4 \ - -snapshot - ``` - -### 2. Raspberry Pi 4 - - 1. Download the [compressed prebuilt image](https://download.automotivelinux.org/AGL/snapshots/master/latest/raspberrypi4/deploy/images/raspberrypi4-64/agl-demo-platform-crosssdk-raspberrypi4-64.wic.xz). - - 2. Extract the image into the SD card of Raspberry Pi 4 : - - ```sh - $ lsblk - $ sudo umount - $ xzcat agl-demo-platform-crosssdk-raspberrypi4-64.wic.xz | sudo dd of= bs=4M - $ sync - ``` - - **IMPORTANT NOTE:** Before re-writing any device on your Build Host, you need to - be sure you are actually writing to the removable MicroSD card and not some other - device. - Each computer is different and removable devices can change from time to time. - Consequently, you should repeat the previous operation with the MicroSD card to - confirm the device name every time you write to the card. - - To summarize this example so far, we have the following: - The first SATA drive is `/dev/sda` and `/dev/sdc` corresponds to the MicroSD card, and is also marked as a removable device.You can see this in the output of the `lsblk` command where "1" appears in the "RM" column for that device. - - 3. SSH into Raspberry Pi : - - Connect Raspberry Pi to network : `Homescreen > Settings`, IP address mentioned here. - - `ssh root@` - - - 4. Serial Debugging : - - When things go wrong, you can take steps to debug your Raspberry Pi. - For debugging, you need a 3.3 Volt USB Serial cable to fascilitate - communication between your Raspberry Pi board and your build host. - - You can reference the following diagram for information on the following steps: - - ![](images/RaspberryPi2-ModelB-debug-serial-cable.png) - - 1. Connect the TTL cable to the Universal Asynchronous Receiver-Transmitter - (UART) connection on your Raspberry Pi board. - Do not connect the USB side of the cable to your build host at this time. - - **CAUTION:** No warranty is provided using the following procedure. - Pay particular attention to the collors of your cable as they could - vary depending on the vendor. - - 2. Connect the cable's BLUE wire to pin 6 (i.e. Ground) of the UART. - - 3. Connect the able's GREEN RX line to pin 8 (i.e. the TXD line) of - the UART. - - 4. Connect the cable's RED TX line to pin 10 (i.e. the RXD line) of - the UART. - - 5. Plug the USB connector of the cable into your build host's USB port. - - 6. Use your favorite tool for serial communication between your build host - and your Raspberry Pi. - For example, if your build host is a native Linux machine (e.g. Ubuntu) - you could use `screen` as follows from a terminal on the build host: - - ```sh - $ sudo screen /dev/ttyUSB0 115200 - ``` - -### 3. R-Car H3SK (H3ULCB board) - -**NOTE :** The prebuilt image does support **non-accelerated** graphics mode (software rendering). For **accelerated** graphics support, a local build with the neccesary graphics driver is required. - - - 1. Update the [firmware](https://elinux.org/R-Car/Boards/H3SK#Flashing_firmware) using files from [here](https://download.automotivelinux.org/AGL/snapshots/master/latest/h3ulcb-nogfx/deploy/images/h3ulcb/). - - 2. Download the [compressed prebuilt image](https://download.automotivelinux.org/AGL/snapshots/master/latest/h3ulcb-nogfx/deploy/images/h3ulcb/agl-demo-platform-crosssdk-h3ulcb.wic.xz). - - 3. Extract the image into the boot device : - - ```sh - $ lsblk - $ sudo umount - $ xzcat agl-demo-platform-crosssdk-h3ulcb.wic.xz | sudo dd of= bs=4M - $ sync - ``` - - 3. [Serial](https://elinux.org/R-Car/Boards/H3SK) into the board for debugging. - For example, if your build host is a native Linux machine (e.g. Ubuntu) - you could use `screen` as follows from a terminal on the build host: - - ```sh - $ sudo screen /dev/ttyUSB0 115200 - ``` diff --git a/docs/0_Getting_Started/1_Quickstart/images/RaspberryPi2-ModelB-debug-serial-cable.png b/docs/0_Getting_Started/1_Quickstart/images/RaspberryPi2-ModelB-debug-serial-cable.png deleted file mode 100644 index f4374d0..0000000 Binary files a/docs/0_Getting_Started/1_Quickstart/images/RaspberryPi2-ModelB-debug-serial-cable.png and /dev/null differ diff --git a/docs/0_Getting_Started/1_Quickstart/images/vbox-1.png b/docs/0_Getting_Started/1_Quickstart/images/vbox-1.png deleted file mode 100644 index a43c111..0000000 Binary files a/docs/0_Getting_Started/1_Quickstart/images/vbox-1.png and /dev/null differ diff --git a/docs/0_Getting_Started/1_Quickstart/images/vbox-2.png b/docs/0_Getting_Started/1_Quickstart/images/vbox-2.png deleted file mode 100644 index d4e1dd0..0000000 Binary files a/docs/0_Getting_Started/1_Quickstart/images/vbox-2.png and /dev/null differ diff --git a/docs/0_Getting_Started/1_Quickstart/images/vbox-3.png b/docs/0_Getting_Started/1_Quickstart/images/vbox-3.png deleted file mode 100644 index f6389f1..0000000 Binary files a/docs/0_Getting_Started/1_Quickstart/images/vbox-3.png and /dev/null differ diff --git a/docs/0_Getting_Started/1_Quickstart/images/vbox-4.png b/docs/0_Getting_Started/1_Quickstart/images/vbox-4.png deleted file mode 100644 index 09f7f0b..0000000 Binary files a/docs/0_Getting_Started/1_Quickstart/images/vbox-4.png and /dev/null differ diff --git a/docs/0_Getting_Started/1_Quickstart/images/vbox-5.png b/docs/0_Getting_Started/1_Quickstart/images/vbox-5.png deleted file mode 100644 index 0c3f51b..0000000 Binary files a/docs/0_Getting_Started/1_Quickstart/images/vbox-5.png and /dev/null differ diff --git a/docs/0_Getting_Started/2_Building_AGL_Image/0_Build_Process.md b/docs/0_Getting_Started/2_Building_AGL_Image/0_Build_Process.md deleted file mode 100644 index f1a48c7..0000000 --- a/docs/0_Getting_Started/2_Building_AGL_Image/0_Build_Process.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Build Process Overview ---- - -The AGL image development workflow consists of setting up -the system (i.e. the build host) that builds the image and finishes with -using the -[Yocto Project](https://yoctoproject.org) to create an image -targeted towards specific hardware. - -The following figure and list overview the AGL image development -process. -You can learn about the steps in the process by reading through the -remaining sections. - -**NOTE:** This procedure uses information from many other procedures -in the AGL Documentation set. -Links are provided when a set of steps is required that is documented -elsewhere. - -![](images/image-developer-workflow.png) - -1. Prepare your build host to be able to use the tools needed to build your image. - -2. Download the AGL software into a local Git repository on your build host. - -3. Run the build environment script to initialize variables and paths needed for the build. - -4. Make sure your build configuration is defined exactly how you want it for your build. - -5. Use - [BitBake](https://docs.yoctoproject.org/bitbake.html) - to build your image. diff --git a/docs/0_Getting_Started/2_Building_AGL_Image/1_Preparing_Your_Build_Host.md b/docs/0_Getting_Started/2_Building_AGL_Image/1_Preparing_Your_Build_Host.md deleted file mode 100644 index fdca659..0000000 --- a/docs/0_Getting_Started/2_Building_AGL_Image/1_Preparing_Your_Build_Host.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: Preparing Your Build Host ---- - -Preparing your build host so that it can build an AGL image means -making sure your system is set up to use the -[Yocto Project](https://yoctoproject.org) OpenEmbedded build system, -which is based on -[BitBake](https://docs.yoctoproject.org/bitbake.html). - -This section presents minimal information so you can prepare the build host -to use the "Dunfell" version of the Yocto Project (i.e. version 3.1.2). -If you want more details on how the Yocto Project works, you can reference -the Yocto Project documentation -[here](https://www.yoctoproject.org/docs/). - -**NOTE:** This entire section presumes you want to build an image. -You can skip the entire build process if you want to use a ready-made -development image. -The [supported images](https://download.automotivelinux.org/AGL/snapshots/master/latest/) exist for several boards as -well as for the Quick EMUlator (QEMU). -See the -"[Quickstart](../1_Quickstart/Using_Ready_Made_Images.md)" -section for more information on the ready-made images. - -1. **Use a Supported Linux Distribution:** To use the AGL software, it is - recommended that your build host is a native Linux machine that runs a - Yocto Project supported distribution as described by the - "[Supported Linux Distributions](https://docs.yoctoproject.org/ref-manual/system-requirements.html#supported-linux-distributions)" - section in the Yocto Project Reference Manual. - Basically, you should be running a recent version of Ubuntu, Fedora, openSUSE, - CentOS, or Debian. - -2. **Be Sure Your Build Host Has Enough Free Disk Space:** - Your build host should have at least 100 Gbytes. - -3. **Be Sure Tools are Recent:** You need to have recent versions for the following tools: - - - Git 1.8.3.1 or greater - - Tar 1.27 or greater - - Python 3.4.0 or greater - - If your distribution does not meet these minimal requirements, see the - "[Required Git, tar, and Python Versions](https://docs.yoctoproject.org/ref-manual/system-requirements.html#required-git-tar-python-and-gcc-versions)" - section in the Yocto Project Reference Manual for steps that you can - take to be sure you have these tools. - -4. **Install Essential, Graphical, and Eclipse Plug-in Build Host Packages:** - Your build host needs certain host packages. - Depending on the Linux distribution you are using, the list of - host packages differ. - See - "[The Build Host Packages](https://docs.yoctoproject.org/ref-manual/system-requirements.html#required-packages-for-the-build-host)" - section of the Yocto Project Quick Start for information on the packages you need. - - **NOTE:** If you are using the CentOS distribution, you need to - separately install the epel-release package and run the `makecache` command as - described in - "[The Build Host Packages](https://docs.yoctoproject.org/ref-manual/system-requirements.html#required-packages-for-the-build-host)" - section of the Yocto Project Quick Start. - - Aside from the packages listed in the previous section, you need the following: - - * **Ubuntu and Debian:** curl - * **Fedora:** curl - * **OpenSUSE:** glibc-locale curl - * **CentOS:** curl diff --git a/docs/0_Getting_Started/2_Building_AGL_Image/2_Downloading_AGL_Software.md b/docs/0_Getting_Started/2_Building_AGL_Image/2_Downloading_AGL_Software.md deleted file mode 100644 index 02d9108..0000000 --- a/docs/0_Getting_Started/2_Building_AGL_Image/2_Downloading_AGL_Software.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: Downloading AGL Software ---- - -Once you have determined the build host can build an AGL image, -you need to download the AGL source files. -The AGL source files, which includes the Yocto Project layers, are -maintained on the AGL Gerrit server. -For information on how to create accounts for Gerrit, see the -[Getting Started with AGL](https://wiki.automotivelinux.org/start/getting-started) -wiki page. - -**NOTE:** Further information about Download and Build AGL Source Code available at [AGL wiki](https://wiki.automotivelinux.org/agl-distro/source-code). - -The remainder of this section provides steps on how to download the AGL source files: - -1. **Define Your Top-Level Directory:** - You can define an environment variable as your top-level AGL workspace folder. - Following is an example that defines the `$HOME/workspace_agl` folder using - an environment variable named "AGL_TOP": - - ```sh - $ export AGL_TOP=$HOME/AGL - $ echo 'export AGL_TOP=$HOME/AGL' >> $HOME/.bashrc - $ mkdir -p $AGL_TOP - ``` - -2. **Download the `repo` Tool and Set Permissions:** - AGL Uses the `repo` tool for managing repositories. - Use the following commands to download the tool and then set its - permissions to allow for execution: - - ```sh - $ mkdir -p $HOME/bin - $ export PATH=$HOME/bin:$PATH - $ echo 'export PATH=$HOME/bin:$PATH' >> $HOME/.bashrc - $ curl https://storage.googleapis.com/git-repo-downloads/repo > $HOME/bin/repo - $ chmod a+x $HOME/bin/repo - ``` - - **NOTE:** See the - "[Repo Command Reference](https://source.android.com/setup/develop/repo)" - for more information on the `repo` tool. - -3. **Download the AGL Source Files:** - Depending on your development goals, you can either download the - latest stable AGL release branch, or the "cutting-edge" (i.e. "master" - branch) files. - - * **Stable Release:** - Using the latest stable release gives you a solid snapshot of the - latest know release. - The release is static, tested, and known to work. - To download the [latest stable release branch](https://wiki.automotivelinux.org/agl-distro/release-notes#latest_stable_release), use - the following commands: - - **Note:** In this below command please change the branch name to the [latest stable release branch](https://wiki.automotivelinux.org/agl-distro/release-notes#latest_stable_release). For example, for Nifty Needlefish branch use the last name i.e. "needlefish" as branch. - - - ```sh - $ cd $AGL_TOP - $ mkdir <> - $ cd <> - $ repo init -b <> -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo - $ repo sync - ``` - - * **Cutting-Edge Files:** - Using the "cutting-edge" AGL files gives you a snapshot of the - "master" branch. - The resulting local repository you download is dynamic and changes frequently depending on community contributions. - The advantage of using "cutting-edge" AGL files is that you have the - absolute latest features, which are often under development, for AGL. - - To download the "cutting-edge" AGL files, use the following commands: - - ```sh - $ cd $AGL_TOP - $ mkdir master - $ cd master - $ repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo - $ repo sync - ``` - - Once you `sync` the repository, you have the AGL files in the form of - "layers" (e.g. `meta-*` folders). - You also have the `poky` repository in your AGL workspace. - - Listing out the resulting directory structure appears as follows: - - ```sh - $ tree -L 1 - . - ├── bsp - ├── external - ├── meta-agl - ├── meta-agl-cluster-demo - ├── meta-agl-demo - ├── meta-agl-devel - ├── meta-agl-extra - └── meta-agl-telematics-demo - ``` diff --git a/docs/0_Getting_Started/2_Building_AGL_Image/3_Initializing_Your_Build_Environment.md b/docs/0_Getting_Started/2_Building_AGL_Image/3_Initializing_Your_Build_Environment.md deleted file mode 100644 index efe7001..0000000 --- a/docs/0_Getting_Started/2_Building_AGL_Image/3_Initializing_Your_Build_Environment.md +++ /dev/null @@ -1,255 +0,0 @@ ---- -title: Initializing Your Build Environment ---- - -Part of the downloaded AGL software is a setup script that you must -run to initialize the build environment. - -## `aglsetup.sh` Script - -You can find this script here: - -```sh -$AGL_TOP/master/meta-agl/scripts/aglsetup.sh -``` - -The script accepts many options that allow you to define build parameters such -as the target hardware (i.e. the machine), build directory, and so forth. -Use the following commands to see the available options and script syntax: - -```sh -$ cd $AGL_TOP/master -$ source meta-agl/scripts/aglsetup.sh -h -``` - -## AGL Machines (board support) - -Your target platform will be selected with the `-m` flag. -The MACHINE can be selected from the templates in `meta-agl/templates/machine/*`. -Note: This is also the place where you can add new boards. - -Following is a list of the available machines (level of support varies!): - -```sh -Available machines: - [meta-agl] - bbe # BeagleBoneEnhanced - beaglebone # BeagleBone - cubox-i # multiple i.MX6 boards - dragonboard-410c # Qualcomm Dragonboard 410c - dragonboard-820c # Qualcomm Dragonboard 820c - ebisu # Renesas RCar Ebisu - h3-salvator-x # Renesas RCar Salvator/H3 - h3ulcb # Renesas RCar H3 - h3ulcb-kf # Renesas RCar H3 w Kingfisher Board - h3ulcb-nogfx # Renesas RCar H3 w/o gfx blobs - hsdk # ARC HS - imx6qdlsabreauto # i.MX6 sabreauto - imx8mqevk # i.MX8 w etnaviv - imx8mqevk-viv # i.MX8 w vivante - intel-corei7-64 # x86-64 (Intel flavour) - j7-evm # TI Jacinto 7 EVM - m3-salvator-x # Renesas RCar Salvator/M3 - m3ulcb # Renesas RCar M3 - m3ulcb-kf # Renesas RCar M3 w Kingfisher Board - m3ulcb-nogfx # Renesas RCAR M3 w/o gfx blobs - nitrogen6x # i.MX6 nitrogen board - qemuarm # Qemu ARM - qemuarm64 # Qemu AArch 64 (ARM 64bit) - * qemux86-64 # Qemu x86-64 - raspberrypi4 # Raspberry Pi 4 - virtio-aarch64 # Virtio Guest - -``` - -## AGL Features - -Before running the `aglsetup.sh`, you should understand what AGL features you -want to include as part of your image. -The script's help output lists available features and shows you the layers in -which they reside. - -Following is a list of the available features: - -```sh -Available features: - - [meta-agl] # CORE layer - agl-all-features :( agl-demo agl-pipewire agl-app-framework agl-netboot ) - # For the usual demo image - agl-app-framework # Application Framework - agl-archiver # Source Archiver - agl-buildstats # Build Statistics - agl-devel :( agl-package-management ) # Developer Env (root login) - agl-fossdriver # Fossology integration - agl-gplv2 # GPLv2-only packages - agl-localdev # inclusion of local development folder - agl-netboot # network boot (e.g. CI) - agl-package-management # include package management (e.g. rpm) - agl-pipewire # include pipewire - agl-ptest # enable ptest pckages - agl-refhw-h3 # enable reference hardware - agl-virt # EG-Virt features - agl-virt-guest-xen # EG-Virt features - agl-virt-xen :( agl-virt ) # EG-Virt features - agl-weston-remoting :( agl-demo agl-pipewire agl-app-framework ) - agl-weston-waltham-remoting :( agl-demo agl-pipewire agl-app-framework ) - - [meta-agl-demo] # DEMO layer - agl-cluster-demo-support :( agl-weston-remoting agl-demo agl-pipewire agl-app-framework ) - # sample IVI demo - agl-demo :( agl-pipewire agl-app-framework ) # default IVI demo - agl-demo-preload # Add Tokens and sample files - - [meta-agl-devel] # Development layer - agl-basesystem # Toyota basesystem - agl-drm-lease # DRM lease support - agl-egvirt # EG-Virt feature - agl-flutter # Flutter support - agl-jailhouse # GSoC: jailhouse enablement - agl-lxc :( agl-drm-lease agl-pipewire ) # IC-EG container support - agl-ros2 # GSoC: ros2 enablement - -Specialized features (e.g. CI): - agl-ci # Tweaks for CI - agl-ci-change-features :( agl-demo agl-pipewire agl-app-framework agl-devel agl-package-management agl-netboot agl-pipewire agl-buildstats agl-ptest ) - agl-ci-change-features-nogfx :( agl-demo agl-pipewire agl-app-framework agl-devel agl-package-management agl-netboot agl-pipewire agl-buildstats agl-ptest ) - agl-ci-snapshot-features :( agl-demo agl-pipewire agl-app-framework agl-devel agl-package-management agl-netboot agl-archiver agl-pipewire agl-buildstats agl-ptest ) - agl-ci-snapshot-features-nogfx :( agl-demo agl-pipewire agl-app-framework agl-devel agl-package-management agl-netboot agl-archiver agl-pipewire agl-buildstats agl-ptest ) - -``` - -To find out exactly what a feature provides, check out the respective layer and its README. - -An AGL feature is a configuration that accounts for specific settings -and dependencies needed for a particular build. -For example, specifying the "agl-demo" feature makes sure that the -`aglsetup.sh` script creates configuration files needed to build the -image for the AGL demo. - -Following are brief descriptions of the AGL features you can specify on the -`aglsetup.sh` command line: - -* **agl-all-features**: A set of AGL default features. - Do not think of this set of features as all the AGL features. - -* **agl-app-framework**: Application Framework - -* **agl-archiver**: Enables the archiver class for releases. - -* **agl-ci**: Flags used for Continuous Integration (CI). - Using this feature changes the value of the - [`IMAGE_FSTYPES`](https://yoctoproject.org/docs/3.1.4/ref-manual/ref-manual.html#var-IMAGE_FSTYPES) - variable. - -* **agl-ci-change-features**: Enables features for CI builds for Gerrit changes. - -* **agl-ci-change-features-nogfx**: Enables features for CI builds for Gerrit changes - for targets that use binary graphics drivers (i.e. builds without graphics). - -* **agl-ci-snapshot-features**: Enables features for CI daily snapshot builds. - -* **agl-ci-snapshot-features-nogfx**: Enables features for CI daily snapshot builds for - targets that use binary graphics drivers (i.e. builds without graphics). - -* **agl-devel**: Activates development options such as an empty root password, - debuggers, strace, valgrind, and so forth. - -* **agl-netboot**: Enables network boot support through Trivial File Transfer Protocol (TFTP) and Network Block Device (NBD) protocol. - Netboot is needed for CI and useful for development to avoid writing - sdcards. Needs additional setup. - -* **agl-ptest**: Enables - [Ptest](https://yoctoproject.org/docs/3.1.4/dev-manual/dev-manual.html#testing-packages-with-ptest) - as part of the build. - -* **agl-demo**: Enables the layers meta-agl-demo and meta-qt5. - You need agl-demo if you are going to build the agl-demo-platform. - -* **agl-pipewire**: Enables AGLs pipewire support. - -* **agl-localdev**: Adds a local layer named "meta-localdev" in the - meta directory and a local.dev.inc configuration file when that file - is present. - - This feature provides a shortcut for using the layer meta-localdev - in the top-level folder for easy modifications to your own recipes. - -## Example - -Following is an example that initializes the build environment, selects "beaglebone" -for the machine, and chooses the "agl-demo" feature, which also includes the -"agl-appfw-smack", "agl-devel", and "agl-hmi-framework" features: - -```sh -$ source meta-agl/scripts/aglsetup.sh -m qemux86-64 -b qemux86-64 agl-demo agl-devel -aglsetup.sh: Starting -Generating configuration files: - Build dir: /home/scottrif/workspace_agl/build - Machine: qemux86-64 - Features: agl-appfw-smack agl-demo agl-devel - Running /home/scottrif/workspace_agl/poky/oe-init-build-env - Templates dir: /home/scottrif/workspace_agl/meta-agl/templates/base - Config: /home/scottrif/workspace_agl/build/conf/bblayers.conf - Config: /home/scottrif/workspace_agl/build/conf/local.conf - Setup script: /home/scottrif/workspace_agl/build/conf/setup.sh - Executing setup script ... --- beginning of setup script - fragment /home/scottrif/workspace_agl/meta-agl/templates/base/01_setup_EULAfunc.sh - fragment /home/scottrif/workspace_agl/meta-agl/templates/base/99_setup_EULAconf.sh - end of setup script -OK -Generating setup file: /home/scottrif/workspace_agl/build/agl-init-build-env ... OK -aglsetup.sh: Done - Shell environment set up for builds. -You can now run 'bitbake target' -Common targets are: - - meta-agl: (core system) - agl-image-minimal - agl-image-minimal-qa - - agl-image-ivi - agl-image-ivi-qa - agl-image-ivi-crosssdk - - agl-image-weston - - - meta-agl-demo: (demo with UI) - agl-demo-platform (* default demo target) - agl-demo-platform-qa - agl-demo-platform-crosssdk - agl-demo-platform-html5 -``` - -Running the script creates the Build Directory if it does not already exist. -The default Build Directory is `$AGL_TOP//build`, and the nomenclature to be used throughout this doc is going to be `$AGL_TOP//` -For this example, the Build Directory is `$AGL_TOP/master/qemux86-64`. - -The script's output also indicates the machine and AGL features selected for the build. - -The script creates two primary configuration files used for the build: `local.conf` and `bblayers.conf`. -Both these configuration files are located in the Build Directory in the `conf` folder. -If you were to examine these files, you would find standard Yocto Project -configurations along with AGL configuration fragments, which are driven by the -machine (i.e. beaglebone) and the AGL features specified as part of the -script's command line. - -The end result is configuration files specific for your build in the AGL development environment. - -Finally, part of the `aglsetup.sh` script makes sure that any End User License Agreements (EULA) -are considered. -You can see that processing in the script's output as well. - -**NOTE:** Use of the `local.conf` and `bblayers.conf` configuration files is fundamental -in the Yocto Project build environment. -Consequently, it is fundamental in the AGL build environment. -You can find lots of information on configuring builds in the Yocto Project -documentation set. -Here are some references if you want to dig into configuration further: - -* [Customizing Images Using local.conf](https://yoctoproject.org/docs/3.1.4/dev-manual/dev-manual.html#usingpoky-extend-customimage-localconf) -* [Local](https://yoctoproject.org/docs/3.1.4/ref-manual/ref-manual.html#ref-varlocality-config-local) -* [build/conf/local.conf](https://yoctoproject.org/docs/3.1.4/ref-manual/ref-manual.html#structure-build-conf-local.conf) -* [build/conf/bblayers.conf](https://yoctoproject.org/docs/3.1.4/ref-manual/ref-manual.html#structure-build-conf-bblayers.conf) -* [BBLAYERS](https://yoctoproject.org/docs/3.1.4/ref-manual/ref-manual.html#var-BBLAYERS) -* [User Configuration](https://yoctoproject.org/docs/3.1.4/ref-manual/ref-manual.html#user-configuration) -* [Enabling Your Layer](https://yoctoproject.org/docs/3.1.4/dev-manual/dev-manual.html#enabling-your-layer) diff --git a/docs/0_Getting_Started/2_Building_AGL_Image/4_Customizing_Your_Build.md b/docs/0_Getting_Started/2_Building_AGL_Image/4_Customizing_Your_Build.md deleted file mode 100644 index 1c30ddd..0000000 --- a/docs/0_Getting_Started/2_Building_AGL_Image/4_Customizing_Your_Build.md +++ /dev/null @@ -1,151 +0,0 @@ ---- -title: Customizing Your Build ---- - -Because the build process is based on BitBake and the Yocto Project, -build customizations are driven through configuration files used during -the build. - -Lots of configuration files exist that define a build. -However, the primary one that acts as a global configuration mechanism is the -`local.conf` file, which is found in the Build Directory in a folder named "conf". - -Before you start your build process, you should open up the `local.conf` file -and look through it to be sure the general configurations are correct. -The file is well commented so you should be able to understand what the -various variables accomplish. - -To view and customize the `local.conf` file, use any text editor: - -```sh -$ vim $AGL_TOP///conf/local.conf -``` - -As mentioned in the "[Initializing Your Build Environment](./3_Initializing_Your_Build_Environment.md)" section, -the `local.conf` file gets augmented with AGL configuration fragments based on -how you execute the `aglsetup.sh` script. -You can see those fragments at the end the configuration file. - -Even though your build should work fine after running the `aglsetup.sh` script, -you might consider editing your `local.conf` file to use one or more of the -following configurations. - -## Capturing Build History - -You can enable build history to help maintain the quality of your build output. -You can use it to highlight unexpected and possibly unwanted changes in the build output. -Basically, with build history enabled, you get a record of information about the contents -of each package and image. -That information is committed to a local Git repository where you can examine it. - -To enable build history, make sure the following two lines are in your -`local.conf` file: - -```sh -INHERIT += "buildhistory" -BUILDHISTORY_COMMIT = "1" -``` - -See the -"[Maintaining Build Output Quality](https://www.yoctoproject.org/docs/3.1.4/ref-manual/ref-manual.html#maintaining-build-output-quality)" -section in the Yocto Project Reference Manual for a complete discussion on -build history. - -## Deleting Temporary Workspace - -During a build, the build system uses a lot of disk space to store temporary files. -You can ease the burden on your system and speed up the build by configuring the build -to remove temporary workspace. - -You need to inherit the `rm_work` class by using this statement in the `local.conf` file: - -```sh -INHERIT += "rm_work" -``` - -You can read about the class in the -"[rm_work.bbclass](https://www.yoctoproject.org/docs/3.1.4/ref-manual/ref-manual.html#ref-classes-rm-work)" -section of the Yocto Project Reference Manual for more information. - -## Pointing at Shared State Cache Locations - -The build system creates everything from scratch unless BitBake can determine that parts do not need to be rebuilt. Fundamentally, building from scratch is attractive as it means all parts are built fresh and there is no possibility of stale data causing problems. -When developers hit problems, they typically default back to building from scratch so they know the state -of things from the start. - -The build process uses Shared State Cache (sstate) to speed up subsequent builds. -This cache retains artifacts that can be re-used once it is determined that they -would not be different as compared to a re-built module. - -For the AGL build, you can specify the location for sstate files by including the -following in the `local.conf` file: - -```sh -SSTATE_DIR = "${AGL_TOP}/sstate-cache" -``` - -Also, in the `local.conf` file, you can specify additional directories in which the build -system can look for shared state information. -Use the following form in your file to list out the directories you want the build -process to look at for sstate information: - -```sh -SSTATE_MIRRORS ?= "\ - file://.* http://someserver.tld/share/sstate/PATH;downloadfilename=PATH \n \ - file://.* file:///some/local/dir/sstate/PATH" -``` - -If you want to know more about the Yocto Project sstate mechanism, see the -"[Shared State Cache](https://www.yoctoproject.org/docs/3.1.4/ref-manual/ref-manual.html#shared-state-cache)" -section in the Yocto Project Reference Manual. - -## Preserving the Download Directory - -During the initial build, the system downloads many different source code tarballs -from various upstream projects. -Downloading these files can take a while, particularly if your network -connection is slow. -The process downloads files into a -"[download directory](https://www.yoctoproject.org/docs/3.1.4/ref-manual/ref-manual.html#var-DL_DIR)". -The `DL_DIR` variable defines the download directory. -For subsequent builds, you can preserve this directory to speed up the download -part of a build. - -The default download directory is in a folder named "downloads". -For the AGL build you can set the download directory by adding the following to your -`local.conf` file: - -```sh -DL_DIR = "${AGL_TOP}/downloads" -``` - -## Using a Shared State (sstate) Mirror - -The underlying Yocto Project build system uses Shared State Mirrors to cache -artifacts from previous builds. -You can significantly speed up builds and guard against fetcher failures by -using mirrors. -To use mirrors, add this line to your `local.conf` file in the Build directory: - -```sh -SSTATE_MIRRORS_append = " file://.* https://download.automotivelinux.org/sstate-mirror/master/${DEFAULTTUNE}/PATH \n " -``` - -You can learn more about shared state and how it is used in the -"[Shared State Cache](https://yoctoproject.org/docs/3.1.4/ref-manual/ref-manual.html#shared-state-cache)" -section of the Yocto Project Reference Manual. - -## Common Settings using Symbolic Link with site.conf - -```sh -$ echo "# reuse download directories" >> $AGL_TOP/site.conf -$ echo "DL_DIR = \"$HOME/downloads/\"" >> $AGL_TOP/site.conf -$ echo "SSTATE_DIR = \"$AGL_TOP/sstate-cache/\"" >> $AGL_TOP/site.conf -$ cd $AGL_TOP/master/qemux86-64/ -$ ln -sf $AGL_TOP/site.conf conf/ - -In General; -$ cd $AGL_TOP/// -$ ln -sf $AGL_TOP/site.conf conf/ -``` - diff --git a/docs/0_Getting_Started/2_Building_AGL_Image/5_0_Building_the_AGL_Image.md b/docs/0_Getting_Started/2_Building_AGL_Image/5_0_Building_the_AGL_Image.md deleted file mode 100644 index 1573b56..0000000 --- a/docs/0_Getting_Started/2_Building_AGL_Image/5_0_Building_the_AGL_Image.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Building the AGL Image ---- - -Building the AGL image involves running BitBake with a specified target. -Depending on whether you are building the image for the first time or if this -is a subsequent build, the time needed for the build could be significant. - -It is critical that you specify the correct options and configurations for the -build before executing the `bitbake` command. -The previous sections in the "Image Development Workflow" have treated this setup -in a generic fashion. AGL has both `Qt` based and `HTML5` based IVI demos, where in the build process is almost the same except few changes in the build enviroment. - -This section, provides links to topics with instructions needed to create images for -three types of supported platforms and for emulation/virtualization using Quick -EMUlator (QEMU) or VirtualBox: - -* [x86 (Emulation and Hardware)](./5_1_x86_Emulation_and_Hardware.md) -* [Raspberry Pi 4](./5_2_Raspberry_Pi_4.md) -* [R Car Gen 3](./5_3_RCar_Gen_3.md) -* [virtio](./5_4_Virtio.md) diff --git a/docs/0_Getting_Started/2_Building_AGL_Image/5_1_x86_Emulation_and_Hardware.md b/docs/0_Getting_Started/2_Building_AGL_Image/5_1_x86_Emulation_and_Hardware.md deleted file mode 100644 index 871179f..0000000 --- a/docs/0_Getting_Started/2_Building_AGL_Image/5_1_x86_Emulation_and_Hardware.md +++ /dev/null @@ -1,255 +0,0 @@ ---- -title: Building for x86 (Emulation and Hardware) ---- - -Building an image for emulation allows you to simulate your -image without actual target hardware. - -This section describes the steps you need to take to build the -AGL demo image for emulation using either Quick EMUlator (QEMU) or -VirtualBox, and later the same image can be used to boot any hardware. - -## 1. Making Sure Your Build Environment is Correct - -The -"[Initializing Your Build Environment](./3_Initializing_Your_Build_Environment.md)" -section presented generic information for setting up your build environment -using the `aglsetup.sh` script. -If you are building the AGL demo image for emulation, you need to specify some -specific options when you run the script: - -**Sample Qt based IVI demo :** - -```sh -$ source meta-agl/scripts/aglsetup.sh -f -m qemux86-64 -b qemux86-64 agl-demo agl-devel -$ echo "# reuse download directories" >> $AGL_TOP/site.conf -$ echo "DL_DIR = \"$HOME/downloads/\"" >> $AGL_TOP/site.conf -$ echo "SSTATE_DIR = \"$AGL_TOP/sstate-cache/\"" >> $AGL_TOP/site.conf -$ ln -sf $AGL_TOP/site.conf conf/ -``` - -**Sample HTML5 based IVI demo :** - -```sh -$ source meta-agl/scripts/aglsetup.sh -f -m qemux86-64 -b qemux86-64 agl-demo agl-devel agl-profile-graphical-html5 -$ echo "# reuse download directories" >> $AGL_TOP/site.conf -$ echo "DL_DIR = \"$HOME/downloads/\"" >> $AGL_TOP/site.conf -$ echo "SSTATE_DIR = \"$AGL_TOP/sstate-cache/\"" >> $AGL_TOP/site.conf -$ ln -sf $AGL_TOP/site.conf conf/ -``` - -**IVI-EG Flutter based demo :** - -```sh -$ source meta-agl/scripts/aglsetup.sh -f -m qemux86-64 -b qemux86-64 agl-flutter agl-devel -$ echo "# reuse download directories" >> $AGL_TOP/site.conf -$ echo "DL_DIR = \"$HOME/downloads/\"" >> $AGL_TOP/site.conf -$ echo "SSTATE_DIR = \"$AGL_TOP/sstate-cache/\"" >> $AGL_TOP/site.conf -$ ln -sf $AGL_TOP/site.conf conf/ -``` - -**IC-EG container image :** -```sh -### TBD -``` - -**Virt-EG demo image :** -```sh -### TBD -``` - -The "-m" option specifies the "qemux86-64" machine. -The list of AGL features used with script are appropriate for development of -the AGL demo image suited for either QEMU or VirtualBox. - -## 2. Using BitBake - -Start the build using the `bitbake` command. - -**NOTE:** An initial build can take many hours depending on your -CPU and and Internet connection speeds. -The build also takes approximately 100G-bytes of free disk space. - -**Sample Qt based IVI demo :** -The target is `agl-demo-platform`. - -```sh -$ time bitbake agl-demo-platform -``` - -By default, the build process puts the resulting image in the Build Directory and further exporting that as `$IMAGE_NAME`: - -```sh -/tmp/deploy/images/qemux86-64/agl-demo-platform-qemux86-64.vmdk.xz - -$ export IMAGE_NAME=agl-demo-platform-qemux86-64.vmdk.xz -``` - -**Sample HTML5 based IVI demo :** -The target is `agl-demo-platform-html5`. - -```sh -$ time bitbake agl-demo-platform-html5 -``` - -By default, the build process puts the resulting image in the Build Directory and further exporting that as `$IMAGE_NAME`: - -```sh -/tmp/deploy/images/qemux86-64/agl-demo-platform-html5-qemux86-64.vmdk.xz - -$ export IMAGE_NAME=agl-demo-platform-html5-qemux86-64.vmdk.xz -``` - -**IVI-EG Flutter based demo :** -The target is `agl-image-flutter`. - -```sh -$ time bitbake agl-image-flutter -``` - -**IC-EG container image :** -```sh -# TBD -``` - -**Virt-EG demo image :** -```sh -# TBD -``` - -## 3. Deploying the AGL Demo Image - -Deploying the image consists of decompressing the image and then -booting it using either QEMU, VirtualBox or physical system. -The examples below are usually for the 'agl-demo-platform' target. -Please adapt accordingly to your target image. - -**3.1 QEMU** - -Depending on your Linux distribution, use these commands to install QEMU: - -If you built your image with bitbake, you can now just use the ``runqemu`` wrapper, after sourcing `agl-init-build-env` inside the build-dir : - -For this example : - -```sh -$ source $AGL_TOP/master/qemux86-64/agl-init-build-env -``` - -In general : - -```sh -$ source $AGL_TOP/// -``` - -And further use `runqemu` to boot the image : - -```sh -$ runqemu tmp/deploy/images/qemux86-64/agl-demo-platform-qemux86-64.qemuboot.conf kvm serialstdio slirp publicvnc audio -``` - -If you need to run it outside of the bitbake environment or need special settings for -hardware pass-through using `qemu` : - - -**NOTE:** if you have created an AGL crosssdk, it will contain a -QEMU binary for the build host. -This SDK QEMU binary does not support graphics. -Consequently, you cannot use it to boot the AGL image and -need to call your host's qemu binary instead. - -**NOTE:** the VM images need UEFI in the emulator to boot. Thus you need -to install the necessary files with below commands (ovmf). - -If your build host is running -[Arch Linux](https://www.archlinux.org/), use the following commands: - -```sh -sudo pacman -S qemu ovmf -export OVMF_PATH=/usr/share/ovmf/x64/OVMF_CODE.fd -``` - -If your build host is running Debian or Ubuntu, use the following commands: - -```sh -sudo apt-get install qemu-system-x86 ovmf -export OVMF_PATH=/usr/share/ovmf/OVMF.fd -``` - -If you build host is running Fedora, use the following commands: - -```sh -sudo yum install qemu qemu-kvm edk2-ovmf -export OVMF_PATH=/usr/share/edk2/ovmf/OVMF_CODE.fd -``` - -**Note:** - -Once QEMU is installed, boot the image with KVM support: - -```sh -qemu-system-x86_64 -enable-kvm -m 2048 \ - -bios ${OVMF_PATH} \ - -hda ${IMAGE_NAME} \ - -cpu kvm64 -cpu qemu64,+ssse3,+sse4.1,+sse4.2,+popcnt \ - -vga virtio -show-cursor \ - -device virtio-rng-pci \ - -serial mon:stdio -serial null \ - -soundhw hda \ - -net nic \ - -net user,hostfwd=tcp::2222-:22 -``` - -**NOTE:** KVM may not be supported within a virtualized environment such as -VirtualBox. This is indicated by the qemu command above giving the error -message `Could not access KVM kernel module: No such file or directory` or -the kernel log output contains the error message `kvm: no hardware support`. -The image can be booted in such an environment by removing `-enable-kvm` from -the qemu command line, however this will result in lower perfromance within -the AGL demo. - -**3.2 VirtualBox** - -Once VirtualBox is installed, follow these steps to boot the image: - - 1. Install and set up [Virtual Box](https://www.virtualbox.org/wiki/Linux_Downloads). - - 2. Extract the vmdk file : - - ```sh - cd tmp/deploy/images/qemux86-64 - xz -d ${IMAGE_NAME} - ``` - - 3. Configure virtual box for AGL : - - Click on `New` or `Add`. - - Enter Name as `agl-demo`. - - Type as `Linux`. - - Version as `Other Linux (64-bit)`, click on `Next`. - ![vbox-step-1](images/vbox-1.png) - - Select Memory size. Recommended is `2048 MB`, click on `Next`. - ![vbox-step-2](images/vbox-2.png) - - Click on `Use an existing virtual hard disk file`, and select the extracted `agl-demo-platform-qemux86-64.vmdk.xz` or `` file, click on `Create`. - ![vbox-step-3](images/vbox-3.png) - - Go to `Settings`, and into `System`. Select `Chipset : IHC9`. Check on `Enable EFI (special OSes only)` and click on `OK`. - ![vbox-step-4](images/vbox-4.png) - - Go to `Storage`, and change the attribute to `Type : AHCI` and click on `OK`. - ![vbox-step-5](images/vbox-5.png) - - Click on `Start`. - - For troubleshooting, you can refer [here](https://lists.automotivelinux.org/g/agl-dev-community/message/8474). - -**3.3 x86 physical system** - - **NOTE :** UEFI enabled system is required. - - 1. Extract the image into USB drive : - - ```sh - $ cd tmp/deploy/images/qemux86-64 - $ lsblk - $ sudo umount - $ xzcat agl-demo-platform-qemux86-64.wic.xz | sudo dd of= bs=4M - $ sync - ``` - - 2. Boot from USB drive on the x86 system. \ No newline at end of file diff --git a/docs/0_Getting_Started/2_Building_AGL_Image/5_2_Raspberry_Pi_4.md b/docs/0_Getting_Started/2_Building_AGL_Image/5_2_Raspberry_Pi_4.md deleted file mode 100644 index e08a51e..0000000 --- a/docs/0_Getting_Started/2_Building_AGL_Image/5_2_Raspberry_Pi_4.md +++ /dev/null @@ -1,204 +0,0 @@ ---- -title: Building for Raspberry Pi 4 ---- - -The -[Raspberry Pi](https://www.raspberrypi.org/help/what-%20is-a-raspberry-pi/) is a small computer that is ideal for learning computing and computer languages. -The AGL Project supports building images for the -[Raspberry Pi 4](https://www.raspberrypi.org/products/raspberry-pi-4-model-b/) board. -These board comes in a variety of models. -See the -[Raspberry Pi Product Page](https://www.raspberrypi.org/products/) for more information. - -This section describes the steps you need to take to build the -AGL demo image for the Raspberry Pi 4 board. - -## 1. Making Sure Your Build Environment is Correct - -The -"[Initializing Your Build Environment](./3_Initializing_Your_Build_Environment.md)" -section presented generic information for setting up your build environment -using the `aglsetup.sh` script. -If you are building the AGL demo image for a Raspberry Pi 4 board, you need to specify some -specific options when you run the script : - -**Qt based IVI demo :** - - ```sh - $ source meta-agl/scripts/aglsetup.sh -f -m raspberrypi4 -b raspberrypi4 agl-demo agl-devel - $ echo "# reuse download directories" >> $AGL_TOP/site.conf - $ echo "DL_DIR = \"$HOME/downloads/\"" >> $AGL_TOP/site.conf - $ echo "SSTATE_DIR = \"$AGL_TOP/sstate-cache/\"" >> $AGL_TOP/site.conf - $ ln -sf $AGL_TOP/site.conf conf/ - ``` - -**HTML5 based IVI demo :** - - ```sh - $ source meta-agl/scripts/aglsetup.sh -f -m raspberrypi4 -b raspberrypi4 agl-demo agl-devel agl-profile-graphical-html5 - $ echo "# reuse download directories" >> $AGL_TOP/site.conf - $ echo "DL_DIR = \"$HOME/downloads/\"" >> $AGL_TOP/site.conf - $ echo "SSTATE_DIR = \"$AGL_TOP/sstate-cache/\"" >> $AGL_TOP/site.conf - $ ln -sf $AGL_TOP/site.conf conf/ - ``` - -In each case, the "-m" option specifies the machine and the list of AGL features used with script are appropriate for development of -the AGL demo image suited for Raspberry Pi 4. - -## 2. Configuring the Build to Include Packages Under a Commercial License - -Before launching the build, it is good to be sure your build -configuration is set up correctly (`/build/conf/local.conf` file). -The "[Customizing Your Build](./4_Customizing_Your_Build.md)" -section highlights some common configurations that are useful when -building any AGL image. - -For the Raspberry Pi platforms, you need to take an additional -configuration step if you want to include any packages under a -commercial license. - -For example, suppose you want to include an implementation of the -[OpenMAX](https://www.khronos.org/openmax/) Intagration Library -(`libomxil`) under a commercial license as part of your AGL image. -If so, you must include the following two lines in your -`/build/conf/local.conf` file: - -```sh -# For libomxil -LICENSE_FLAGS_WHITELIST = "commercial" -IMAGE_INSTALL_append = "libomxil" -``` - -## 3. Using BitBake - -This section shows the `bitbake` command used to build the AGL image. - -Start the build using the `bitbake` command. - -**NOTE:** An initial build can take many hours depending on your -CPU and and Internet connection speeds. -The build also takes approximately 100G-bytes of free disk space. - -**Qt Based IVI demo :** -The target is `agl-demo-platform`. - -```sh -$ time bitbake agl-demo-platform -``` - -By default, the build process puts the resulting image in the Build Directory and further exporting that as `$IMAGE_NAME`. -Here is example for the Raspberry Pi 4 board for Qt Based demo: - -```sh -/tmp/deploy/images/raspberrypi4/agl-demo-platform-raspberrypi4.wic.xz - -$ export IMAGE_NAME=agl-demo-platform-raspberrypi4.wic.xz -``` - -**HTML5 Based IVI demo :** -The target is `agl-demo-platform-html5`. - -```sh -$ time bitbake agl-demo-platform-html5 -``` - -By default, the build process puts the resulting image in the Build Directory and further exporting that as `$IMAGE_NAME`. -Here is example for the Raspberry Pi 4 board for HTML5 Based demo: - -```sh -/tmp/deploy/images/raspberrypi4/agl-demo-platform-html5-raspberrypi4-64.wic.xz - -$ export IMAGE_NAME=agl-demo-platform-html5-raspberrypi4-64.wic.xz -``` - -## 4. Deploying the AGL Demo Image - -Deploying the AGL demo image consists of copying the image on a MicroSD card, -plugging the card into the Raspberry Pi board, and then booting the board. - -Follow these steps to copy the image to a MicroSD card and boot -the image on the Raspberry Pi 4 board: - - 1. Plug your MicroSD card into your Build Host (i.e. the system that has your build output). - - 2. Extract the image into the SD card of Raspberry Pi 4 : - - **NOTE:** For Raspberry Pi 4, the image is at `/tmp/deploy/images/raspberrypi4/${IMAGE_NAME}`. - - Be sure you are root, provide the actual device name for *sdcard_device_name*, and the actual image name for *image_name*. - - ```sh - $ lsblk - $ sudo umount - $ xzcat ${IMAGE_NAME} | sudo dd of= bs=4M - $ sync - ``` - - **IMPORTANT NOTE:** Before re-writing any device on your Build Host, you need to - be sure you are actually writing to the removable MicroSD card and not some other - device. - Each computer is different and removable devices can change from time to time. - Consequently, you should repeat the previous operation with the MicroSD card to - confirm the device name every time you write to the card. - - To summarize this example so far, we have the following: - The first SATA drive is `/dev/sda` and `/dev/sdc` corresponds to the MicroSD card, and is also marked as a removable device.You can see this in the output of the `lsblk` command where "1" appears in the "RM" column for that device. - - 3. SSH into Raspberry Pi : - - Connect Raspberry Pi to network : `Homescreen > Settings`, IP address mentioned here. - - SSH : - - ```sh - $ ssh root@ - ``` - - 4. Serial Debugging : - - When things go wrong, you can take steps to debug your Raspberry Pi. - For debugging, you need a 3.3 Volt USB Serial cable to fascilitate - communication between your Raspberry Pi board and your build host. - - You can reference the following diagram for information on the following steps: - - ![](images/RaspberryPi2-ModelB-debug-serial-cable.png) - - 1. Connect the TTL cable to the Universal Asynchronous Receiver-Transmitter - (UART) connection on your Raspberry Pi board. - Do not connect the USB side of the cable to your build host at this time. - - **CAUTION:** No warranty is provided using the following procedure. - Pay particular attention to the collors of your cable as they could - vary depending on the vendor. - - 2. Connect the cable's BLUE wire to pin 6 (i.e. Ground) of the UART. - - 3. Connect the able's GREEN RX line to pin 8 (i.e. the TXD line) of - the UART. - - 4. Connect the cable's RED TX line to pin 10 (i.e. the RXD line) of - the UART. - - 5. Plug the USB connector of the cable into your build host's USB port. - - 6. Use your favorite tool for serial communication between your build host - and your Raspberry Pi. - For example, if your build host is a native Linux machine (e.g. Ubuntu) - you could use `screen` as follows from a terminal on the build host: - - ```sh - $ sudo screen /dev/ttyUSB0 115200 - ``` - -5. SOTA - - Follow the step below to build AGL for Raspberry Pi with enabled software over - the air (SOTA) updates: - - 1. Include **agl-sota** feature. - - 2. In **bblayers.conf** replace meta-updater-qemux86-64 with - **meta-updater-raspberrypi**. - - 3. In **local.conf** set `SOTA_PACKED_CREDENTIALS` and `OSTREE_BRANCHNAME`. - - More details are available [here](https://docs.ota.here.com/getstarted/dev/raspberry-pi.html). \ No newline at end of file diff --git a/docs/0_Getting_Started/2_Building_AGL_Image/5_3_RCar_Gen_3.md b/docs/0_Getting_Started/2_Building_AGL_Image/5_3_RCar_Gen_3.md deleted file mode 100644 index 33fc50a..0000000 --- a/docs/0_Getting_Started/2_Building_AGL_Image/5_3_RCar_Gen_3.md +++ /dev/null @@ -1,894 +0,0 @@ ---- -title: Building for Supported Renesas Boards ---- - -AGL supports building for several automotive -[Renesas](https://www.renesas.com/us/en/solutions/automotive.html) board kits. -Renesas is the number one supplier of vehicle control microcontrollers and -System on a Chip (SoC) products for the automotive industry. - -This section provides the build and deploy steps you need to create an -image for the following Renesas platforms: - -* [Renesas R-Car Starter Kit Pro Board](https://www.elinux.org/R-Car/Boards/M3SK) -* [Renesas R-Car Starter Kit Premier Board](https://www.elinux.org/R-Car/Boards/H3SK) -* [Renesas Salvator-X Board](https://www.elinux.org/R-Car/Boards/Salvator-X) -* [Renesas Kingfisher Infotainment Board](https://elinux.org/R-Car/Boards/Kingfisher) - -**NOTE:** You can find similar information for the Pro and Premier board kits on the -[R-Car/Boards/Yocto-Gen3](https://elinux.org/R-Car/Boards/Yocto-Gen3) page on [elinux.org](https://elinux.org). -The information on this page describes setup and build procedures for both of these -Renesas development kits. - -Additionally, the AGL Reference Hardware platform is based on the same Renesas -H3 processor used on the Renesas R-Car Starter Kit Premier and Salvator-X boards, -so support for it leverages the Starter Kit Premier (also known as "h3ulcb") -build. -For more information on the AGL reference hardware platform, please refer to its -[manual](https://wiki.automotivelinux.org/_media/eg-rhsa/rh_manual_ver.1.0.pdf), -or the Reference Hardware System Architecture Expert Group -[wiki page](https://wiki.automotivelinux.org/eg-rhsa). - -## 1. Prepare your build - -### 1.1 Downloading Proprietary Drivers - -Before setting up the build environment, you need to download proprietary drivers from the -[R-Car H3/M3 Software library and Technical document](https://www.renesas.com/us/en/application/automotive/r-car-h3-m3-documents-software) -site. - -Follow these steps to download the drivers you need: - -1. **Determine the Files You Need:** - - Run the ``setup_mm_packages.sh`` script as follows to - display the list of ZIP files containing the drivers you need. - Following is an example: - - ```sh - grep -rn ZIP_.= $AGL_TOP/meta-agl/meta-agl-bsp/meta-rcar-gen3/scripts/setup_mm_packages.sh - ``` - - The script's output identifies the files you need to download from the page. - -2. **Get Your Board Support Package (BSP) Version:** - - Be sure to have the correct BSP version of the R-Car Starter Kit - based on the version of the AGL software you are using. - Find the appropriate download links on the - [R-Car H3/M3 Software library and Technical document](https://www.renesas.com/us/en/application/automotive/r-car-h3-m3-documents-software) - site. - The file pairs are grouped according to the Yocto Project version you are - using with the AGL software. - - Use the following table to map the Renesas version to your AGL software: - - | AGL Version | Renesas version | - |:-:|:-:| - | AGL master | 5.9.0 | - -3. **Download the Files:** - - Start the download process by clicking the download link. - If you do not have an account with Renesas, you will be asked to register a free account. - You must register and follow the "Click Through" licensing process - in order to download these proprietary files. - - If needed, follow the instructions to create the free account by providing the required - account information. - Once the account is registered and you are logged in, you can download the files. - - **NOTE:** You might have to re-access the - [original page](https://www.renesas.com/us/en/application/automotive/r-car-h3-m3-documents-software) - that contains the download links you need after creating the account and logging in. - -4. **Create an Environment Variable to Point to Your Download Area:** - - Create and export an environment variable named `XDG_DOWNLOAD_DIR` that points to - your download directory. - Here is an example: - - ```sh - export XDG_DOWNLOAD_DIR=$HOME/Downloads - ``` - -5. **Be Sure the Files Have Rights:** - - Be sure you have the necessary rights for the files you downloaded. - You can use the following command: - - ```sh - chmod a+rw $XDG_DOWNLOAD_DIR/*.zip - ``` - -6. **Check to be Sure the Files are Downloaded and Have the Correct Rights:** - - Do a quick listing of the files to ensure they are in the download directory and - they have the correct access rights. - Here is an example: - - ```sh - $ ls -l $XDG_DOWNLOAD_DIR/*.zip - -rw-rw-r-- 1 scottrif scottrif 4662080 Nov 19 14:48 /home/scottrif/Downloads/R-Car_Gen3_Series_Evaluation_Software_Package_for_Linux-weston8-20200923.zip - -rw-rw-r-- 1 scottrif scottrif 3137626 Nov 19 14:49 /home/scottrif/Downloads/R-Car_Gen3_Series_Evaluation_Software_Package_of_Linux_Drivers-weston8-20200923.zip - ``` - -### 1.2. Getting More Software - -1. **Get the `bmaptool`:** - - Download this tool from the - [bmap-tools](https://build.opensuse.org/package/show/isv:LinuxAutomotive:AGL_Master/bmap-tools) - repository. - The site has pre-built packages (DEB or RPM) for the supported host - operating systems. - -### 1.3. Getting Your Hardware Together - -Gather together this list of hardware items, which is not exhaustive. -Having these items ahead of time saves you from having to try and -collect hardware during development: - -* Supported Starter Kit Gen3 board with its 5V power supply. -* Micro USB-A cable for serial console. - This cable is optional if you are using Ethernet and an SSH connection. -* USB 2.0 Hub. The hub is optional but makes it easy to connect multiple USB devices. -* Ethernet cable. The cable is optional if you are using a serial console. -* HDMI type D (Micro connector) cable and an associated display. -* 4 Gbyte minimum MicroSD Card. It is recommended that you use a class 10 type. -* USB touch screen device such as the GeChic 1502i/1503i. A touch screen device is optional. - -**NOTE:** The Salvator-X Board has NDA restrictions. -Consequently, less documentation is available for this board both here and across the -Internet. - -### 1.4. Making Sure Your Build Environment is Correct - -The -"[Initializing Your Build Environment](./3_Initializing_Your_Build_Environment.md)" -section presented generic information for setting up your build environment -using the `aglsetup.sh` script. -If you are building an image for a supported Renesas board, -you need to take steps to make sure your build host is set up correctly. - -1. **Define Your Board:** - - Depending on your Renesas board, define and export a `MACHINE` variable as follows: - - | Board | `MACHINE` Setting | - |:-:|:-:| - | Starter Kit Pro/M3 | `MACHINE`=m3ulcb | - | Starter Kit Pro/M3 + kingfisher support | `MACHINE`=m3ulcb-kf | - | Starter Kit Pro/M3 without graphic driver (using pixman) | `MACHINE`=m3ulcb-nogfx | - | Starter Kit Premier/H3 | `MACHINE`=h3ulcb | - | Starter Kit Premier/H3 + kingfisher support | `MACHINE`=h3ulcb-kf | - | Starter Kit Premier/H3 without graphic driver (using pixman) | `MACHINE`=h3ulcb-nogfx | - | Salvator-X | `MACHINE`=h3-salvator-x | - | AGL Reference Hardware | `MACHINE`=h3ulcb | - | AGL Reference Hardware without graphic driver (using pixman) | `MACHINE`=h3ulcb-nogfx | - - For example, the following command defines and exports the `MACHINE` variable - for the Starter Kit Premier/H3 Board: - - ```sh - export MACHINE=h3ulcb - ``` - -### 1.5. **Run the `aglsetup.sh` Script:** - -Use the following commands to run the AGL Setup script: - -```sh -cd $AGL_TOP -source meta-agl/scripts/aglsetup.sh -m $MACHINE -b build agl-devel agl-demo -``` - -**NOTE:** -To avoid useless download and rebuild, it's important to set the variable DL_DIR and SSTATE_DIR in your configuration. - -```sh -echo "# reuse download directories" >> $AGL_TOP/site.conf -echo "DL_DIR = \"$HOME/downloads/\"" >> $AGL_TOP/site.conf -echo "SSTATE_DIR = \"$AGL_TOP/sstate-cache/\"" >> $AGL_TOP/site.conf -ln -sf $AGL_TOP/site.conf conf/ -``` - -**Reference Hardware :** - -If building for the AGL Reference Hardware (with `MACHINE` set to "h3ulcb" or -"h3ulcb-nogfx"), add `agl-refhw-h3`, for example: - -```sh -cd $AGL_TOP -source meta-agl/scripts/aglsetup.sh -m $MACHINE -b build agl-devel agl-demo agl-refhw-h3 -``` - -**HTML5 based IVI demo :** - -For HTML5 based IVI demo the feature "agl-profile-graphical-html5" is needed. - -```sh -$ source meta-agl/scripts/aglsetup.sh -f -m $MACHINE -b $MACHINE agl-demo agl-devel agl-profile-graphical-html5 -``` - -**Instrument Cluster with Container isolation demo :** - -```sh -$ source meta-agl/scripts/aglsetup.sh -f -m $MACHINE -b $MACHINE agl-lxc -``` - -**NOTE:** -You can check if your logs match what is expected in the [troubleshooting section](#4-troubleshooting). - -Running the `aglsetup.sh` script automatically places you in the -working directory (i.e. `$AGL_TOP/build`). -You can change this default behavior by adding the "-f" option to the -script's command line. - -In the previous command, the "-m" option sets your machine to the previously -defined `MACHINE` variable. -The "-b" option defines your Build Directory, which is the -default `$AGL_TOP/build`. -Finally, the AGL features are provided to support building the AGL Demo image -for the Renesas board. - -You can learn more about the AGL Features in the -"[Initializing Your Build Environment](./3_Initializing_Your_Build_Environment.md)" -section. - -## 2. Using BitBake - -This section shows the `bitbake` command used to build the AGL image. -Before running BitBake to start your build, it is good to be reminded that AGL -does provide pre-built images for developers that work with supported hardware. -You can find these pre-built images on the -[AGL Download web site](https://download.automotivelinux.org/AGL/release). - -Start the build using the `bitbake` command. - -**NOTE:** An initial build can take many hours depending on your -CPU and and Internet connection speeds. -The build also takes approximately 100G-bytes of free disk space. - -**Qt based IVI demo :** -For this example, the target is "agl-demo-platform": - -```sh -bitbake agl-demo-platform -``` - -**HTML5 based IVI demo :** -The target is `agl-demo-platform-html5`. - -```sh -$ time bitbake agl-demo-platform-html5 -``` - -**Instrument Cluster with Container isolation demo :** -The target is `lxc-host-image-demo`. - -```sh -$ time bitbake lxc-host-image-demo -``` - -The build process puts the resulting image in the Build Directory: - -```sh -/tmp/deploy/images/$MACHINE -``` - -## 3. Deploying the AGL Demo Image - -To boot your image on the Renesas board, you need to do three things: - -1. [Update all firmware on the board.](#4-troubleshooting) -2. Prepare the MicroSD card to you can boot from it. -3. Boot the board. - -**NOTE:** For subsequent builds, you only have to re-write the MicroSD -card with a new image. - -### 3.1. Booting the Image Using a MicroSD Card - -1. Preparing the MicroSD Card - - Plug the MicroSD card into your Build Host. - After plugging in the device, use the `dmesg` command as follows to - discover the device name: - - ```sh - $ dmesg | tail -4 - [ 1971.462160] sd 6:0:0:0: [sdc] Mode Sense: 03 00 00 00 - [ 1971.462277] sd 6:0:0:0: [sdc] No Caching mode page found - [ 1971.462278] sd 6:0:0:0: [sdc] Assuming drive cache: write through - [ 1971.463870] sdc: sdc1 sdc2 - ``` - - In the previous example, the MicroSD card is attached to the device `/dev/sdc`. - You can also use the `lsblk` command to show all your devices. - Here is an example that shows the MicroSD card as `/dev/sdc`: - - ```sh - $ lsblk - NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT - sda 8:0 0 167,7G 0 disk - ├─sda1 8:1 0 512M 0 part /boot/efi - ├─sda2 8:2 0 159,3G 0 part / - └─sda3 8:3 0 7,9G 0 part [SWAP] - sdb 8:16 0 931,5G 0 disk - └─sdb1 8:17 0 931,5G 0 part /media/storage - sdc 8:32 1 14,9G 0 disk - ├─sdc1 8:33 1 40M 0 part - └─sdc2 8:34 1 788M 0 part - ``` - - **IMPORTANT NOTE:** Before re-writing any device on your Build Host, you need to - be sure you are actually writing to the removable MicroSD card and not some other - device. - Each computer is different and removable devices can change from time to time. - Consequently, you should repeat the previous operation with the MicroSD card to - confirm the device name every time you write to the card. - - To summarize this example so far, we have the following: - - * The first SATA drive is `/dev/sda`. - - * `/dev/sdc` corresponds to the MicroSD card, and is also marked as a removable device. - You can see this in the output of the `lsblk` command where "1" appears in the "RM" column - for that device. - - Now that you have identified the device you are going to be writing the image on, - you can use the `bmaptool` to copy the image to the MicroSD card. - - Your desktop system might offer a choice to mount the MicroSD automatically - in some directory. - For this example, assume that the MicroSD card mount directory is stored in the - `$SDCARD` variable. - - Following are example commands that write the image to the MicroSD card: - - ```sh - cd $AGL_TOP/build/tmp/deploy/images/$MACHINE - bmaptool copy ./agl-demo-platform-$MACHINE.wic.xz - ``` - - Alternatively, you can leave the image in an uncompressed state and write it - to the MicroSD card: - - ```sh - sudo umount - xzcat ./agl-demo-platform-$MACHINE.wic.xz | sudo dd of= bs=4M - sync - ``` - -2. Booting the Board - - Follow these steps to boot the board: - - 1. Use the board's power switch to turn off the board. - - 2. Insert the MicroSD card into the board. - - 3. Verify that you have plugged in the following: - - * An external monitor into the board's HDMI port - - * An input device (e.g. keyboard, mouse, touchscreen, and so forth) into the board's USB ports. - - 4. Use the board's power switch to turn on the board. - - After a few seconds, you will see the AGL splash screen on the display and you - will be able to log in at the console's terminal or using the graphic screen. - -### 3.2. Setting Up the Serial Console - -Setting up the Serial Console involves the following: - -* Installing a serial client on your build host -* Connecting your build host to your Renesas board's serial port -* Powering on the board to get a shell at the console -* Configuring U-Boot parameters -* Logging into the console -* Determining the board's IP address - -1. Installing a Serial Client on Your Build Host - - You need to install a serial client on your build host. - Some examples are: - - * [GNU Screen](https://en.wikipedia.org/wiki/GNU_Screen) - * [picocom](https://linux.die.net/man/8/picocom) - * [Minicom](https://en.wikipedia.org/wiki/Minicom) - - Of these three, "picocom" has the least dependencies and is therefore - considered the "lightest" solution. - -2. Connecting Your Build Host to Your Renesas Board's Serial Port - - You need to physically connect your build host to the Renesas board using - a USB cable from the host to the serial CP2102 USP port (i.e. Micro USB-A port) - on the Renesas board. - - Once you connect the board, determine the device created for the serial link. - Use the ``dmesg`` command on your build host. - Here is an example: - - ```sh - dmesg | tail 9 - [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 - [2097783.385862] usb 2-1.5.3: New USB device strings: Mfr=1, Product=2, SerialNumber=3 - [2097783.385864] usb 2-1.5.3: Product: FT232R USB UART - [2097783.385866] usb 2-1.5.3: Manufacturer: FTDI - [2097783.385867] usb 2-1.5.3: SerialNumber: AK04WWCE - [2097783.388288] ftdi_sio 2-1.5.3:1.0: FTDI USB Serial Device converter detected - [2097783.388330] usb 2-1.5.3: Detected FT232RL - [2097783.388658] usb 2-1.5.3: FTDI USB Serial Device converter now attached to ttyUSB0 - ``` - - The device created is usually "/dev/ttyUSB0". - However, the number might vary depending on other USB serial ports connected to the host. - - To use the link, you need to launch the client. - Here are three commands, which vary based on the serial client, that show - how to launch the client: - - ```sh - picocom -b 115200 /dev/ttyUSB0 - ``` - - or - - ```sh - minicom -b 115200 -D /dev/ttyUSB0 - ``` - - or - - ```sh - screen /dev/ttyUSB0 115200 - ``` - -3. Powering on the Board to Get a Shell at the Console - - Both the Pro and Premier kits (e.g. - [m3ulcb](https://elinux.org/R-Car/Boards/M3SK) and - [h3ulcb](https://elinux.org/R-Car/Boards/H3SK#Hardware)) have nine - switches (SW1 through SW9). - To power on the board, "short-press" SW8, which is the power switch. - - Following, is console output for the power on process for each kit: - - **h3ulcb**: - - ```text - 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 - NOTICE: BL2: DDR1600(rev.0.15) - NOTICE: BL2: DRAM Split is 4ch - NOTICE: BL2: QoS is Gfx Oriented(rev.0.30) - NOTICE: BL2: AVS setting succeeded. DVFS_SetVID=0x52 - NOTICE: BL2: Lossy Decomp areas - NOTICE: Entry 0: DCMPAREACRAx:0x80000540 DCMPAREACRBx:0x570 - NOTICE: Entry 1: DCMPAREACRAx:0x40000000 DCMPAREACRBx:0x0 - NOTICE: Entry 2: DCMPAREACRAx:0x20000000 DCMPAREACRBx:0x0 - NOTICE: BL2: v1.1(release):41099f4 - NOTICE: BL2: Built : 19:20:52, Jun 9 2016 - NOTICE: BL2: Normal boot - NOTICE: BL2: dst=0xe63150c8 src=0x8180000 len=36(0x24) - NOTICE: BL2: dst=0x43f00000 src=0x8180400 len=3072(0xc00) - NOTICE: BL2: dst=0x44000000 src=0x81c0000 len=65536(0x10000) - NOTICE: BL2: dst=0x44100000 src=0x8200000 len=524288(0x80000) - NOTICE: BL2: dst=0x49000000 src=0x8640000 len=1048576(0x100000) - - - U-Boot 2015.04 (Jun 09 2016 - 19:21:52) - - CPU: Renesas Electronics R8A7795 rev 1.1 - Board: H3ULCB - I2C: ready - DRAM: 3.9 GiB - MMC: sh-sdhi: 0, sh-sdhi: 1 - In: serial - Out: serial - Err: serial - Net: Board Net Initialization Failed - No ethernet found. - Hit any key to stop autoboot: 0 - => - ``` - -### 3.3. Setting-up U-boot - -Configuring U-Boot Parameters - -Follow these steps to configure the board to use the MicroSD card as the -boot device and also to set the screen resolution: - -1. As the board is powering up, press any key to stop the autoboot process. -You need to press a key quickly as you have just a few seconds in which to -press a key. - -2. Once the autoboot process is interrupted, use the board's serial console to -enter `printenv` to check if you have correct parameters for booting your board: - - Here is an example using the **h3ulcb** board: - - ```sh - => 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/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 - ``` - -3. To boot your board using the MicroSD card, be sure your environment is set up -as follows: - - ```sh - setenv bootargs console=ttySC0,115200 ignore_loglevel vmalloc=384M video=HDMI-A-1:1920x1080-32@60 root=/dev/mmcblk1p1 rw rootfstype=ext4 rootwait rootdelay=2 - setenv bootcmd run load_ker\; run load_dtb\; booti 0x48080000 - 0x48000000 - setenv load_ker ext4load mmc 0:1 0x48080000 /boot/Image - ``` - -4. Loading dtb : - - **NOTE** : Refer [here](https://elinux.org/R-Car/Boards/Yocto-Gen3-CommonFAQ/Which_dtb_file_is_required_to_boot_linux_on_the_R-Car_Starter_Kit_board_%3F) for more information. - - Make sure your ``load_dtb`` is set as follows : - - | Renesas Boards | DTB Name | - |:-:|:-:| - | **H3SK v2.0(DDR 4GB)** | r8a7795-h3ulcb.dtb | - | **H3SK v2.0(DDR 8GB)/v3.0(DDR 8GB)** | r8a7795-h3ulcb-4x2g.dtb | - | **M3SK v1.0** | r8a7796-m3ulcb.dtb | - | **M3SK v3.0** | r8a7796-m3ulcb-2x4g.dtb | - | **H3SK with a Kingfisher board** | r8a7795-h3ulcb-kf.dtb | - | **M3SK with a Kingfisher board** | r8a7796-m3ulcb-kf.dtb | - | **AGL Reference Hardware board** | r8a7795-agl-refhw.dtb | - - ```sh - setenv load_dtb ext4load mmc 0:1 0x48000000 /boot/r8a7795-h3ulcb-kf.dtb - ``` - -5. Save the boot environment: - - ```sh - saveenv - ``` - -6. Boot the board: - - ```sh - run bootcmd - ``` - -## 4. Troubleshooting - -### 4.1. Checking Your Configuration - -Aside from environment variables and parameters you establish through -running the `aglsetup.sh` script, you can ensure your build's configuration -is just how you want it by examining the `local.conf` configuration file. - -You can find this configuration file in the Build Directory (e.g. -`$TOP_DIR/build/conf/local.conf`). - -In general, the defaults along with the configuration fragments the -`aglsetup.sh` script applies in the `local.conf` file are good enough. -However, you can customize aspects by editing the `local.conf` file. -See the -"[Customizing Your Build](4_Customizing_Your_Build.md)" -section for common configurations you might want to consider. - -**NOTE:** For detailed explanations of the configurations you can make -in the ``local.conf`` file, consult the -[Yocto Project Documentation](https://www.yoctoproject.org/docs/). - -A quick way to see if you have the `$MACHINE` variable set correctly -is to use the following command: - -```sh -grep -w -e "^MACHINE =" $AGL_TOP/build/conf/local.conf -``` - -Depending on the Renesas board you are using, you should see output -as follows: - -```sh -MACHINE = "h3ulcb" -``` - -or - -```sh -MACHINE = "m3ulcb" -``` - -or - -```sh -MACHINE = "h3-salvator-x" -``` - -If you ran the `aglsetup.sh` script as described in the -"[Making Sure Your Build Environment is Correct](./5_3_RCar_Gen_3.md#4-making-sure-your-build-environment-is-correct)" -section earlier, the "agl-devel", "agl-demo", "agl-netboot", "agl-appfw-smack", and -"agl-localdev" AGL features will be in effect. -These features provide the following: - -* 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 such as USB and bluetooth -* Support for the AGL demo platform -* Network boot support through TFTP and NBD protocols -* [IoT.bzh](https://iot.bzh/en/) Application Framework plus -[SMACK](https://en.wikipedia.org/wiki/Smack_(software)) and -[Cynara](https://wiki.tizen.org/Security:Cynara) -* Support for local development including `localdev.inc` when present - -### 4.2. Check the Script's Log: - -Running the `aglsetup.sh` script creates the `setup.log` file, which is in -the `build/conf` folder. -You can examine this log to see the results of the script. -For example, suppose the graphics drivers were missing or could not be extracted -when you ran the script. -In case of missing graphics drivers, you could notice an error message -similar to the following: - -```text -[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 -The graphics and multimedia acceleration packages for -the R-Car Gen3 board can be downloaded from: -https://www.renesas.com/en-us/solutions/automotive/rcar-demoboard-2.html - -These 2 files from there should be store in your'/home/devel/Downloads' directory. - R-Car_Gen3_Series_Evaluation_Software_Package_for_Linux-weston8-20200923.zip - R-Car_Gen3_Series_Evaluation_Software_Package_of_Linux_Drivers-weston8-20200923.zip -/home/working/workspace_agl_master/build_gen3 ---- fragment /home/working/workspace_agl_master/meta-agl/templates/base/99_setup_EULAconf.sh ---- end of setup script -OK -Generating setup file: /home/working/workspace_agl_master/build_gen3/agl-init-build-env ... OK ------------- aglsetup.sh: Done -[snip] -``` - -If you encounter this issue, or any other unwanted behavior, you can fix the error -mentioned, remove the `$AGL_TOP/build` directory, and then re-launch the -`aglsetup.sh` again. - -Here is another example that indicates the driver files could not be extracted from the downloads directory: - -```text -~/workspace_agl/build/conf $ cat setup.log ---- beginning of setup script ---- fragment /home/working/workspace_agl/meta-agl/templates/base/01_setup_EULAfunc.sh ---- fragment /home/working/workspace_agl/meta-agl/templates/machine/h3ulcb/50_setup.sh -~/workspace_agl ~/workspace_agl/build -ERROR: FILES "+/home/working/Downloads/R-Car_Gen3_Series_Evaluation_Software_Package_for_Linux-weston8-20200923.zip+" NOT EXTRACTING CORRECTLY -ERROR: FILES "+/home/working/Downloads/R-car_Gen3_Series_Evaluation_Software_Package_of_Linux_Drivers-weston8-20200923.zip+" NOT EXTRACTING CORRECTLY -The graphics and multimedia acceleration packages for -the R-Car Gen3 board BSP can be downloaded from: - - -These 2 files from there should be stored in your -'/home/working/Downloads' directory. - R-Car_Gen3_Series_Evaluation_Software_Package_for_Linux-weston8-20200923.zip - R-Car_Gen3_Series_Evaluation_Software_Package_of_Linux_Drivers-weston8-20200923.zip -ERROR: Script /home/working/workspace_agl/build/conf/setup.sh failed -[snip] -``` - -### 4.3. Updating the Board's Firmware - -Follow these steps to update the firmware: - -1. **Update the Sample Loader and MiniMonitor:** - - You only need to make these updates one time per device. - - Follow the procedure found on the - eLinux.org wiki to update to at least version 3.02, - which is mandatory to run the AGL image - ([R-car loader update](https://elinux.org/R-Car/Boards/Kingfisher#How_to_update_of_Sample_Loader_and_MiniMonitor)). - -2. **Update the Firmware Stack:** - - You only need to update the firmware stack if you are - using the Eel or later (5.0) version of AGL software. - - M3 and H3 Renesas board are AArch64 platforms. - As such, they have a firmware stack that is divided across: **ARM Trusted Firmware**, **OP-Tee** and **U-Boot**. - - If you are using the Eel (5.0) version or later of the AGL software, you must update - the firmware using the **[h3ulcb] [R-car h3ulcb firmware update](http://elinux.org/R-Car/Boards/H3SK#Flashing_firmware)** - or **[m3ulcb] [R-car m3ulcb firmware update](https://elinux.org/R-Car/Boards/M3SK#Flashing_firmware)** links from the - [Embedded Linux Wiki](https://www.elinux.org/Main_Page) (i.e. `elinux.org`). - - The table in the wiki lists the files you need to flash the firmware. - You can find these files in the following directory: - - ```sh - $AGL_TOP/build/tmp/deploy/images/$MACHINE - ``` - - **NOTE:** The Salvator-X firmware update process is not documented on eLinux. - **NOTE:** The AGL Reference Hardware board generally should not require a - firmware update to be usable, and has a slightly different update procedure. - If you do need to update the firmware, the procedure is documented - [here](https://git.automotivelinux.org/AGL/meta-agl-refhw/tree/meta-agl-refhw-gen3/docs/ReferenceHW_Rcar_gen3.md). - -### 4.4. Logging Into the Console - -Once the board boots, you should see the -[Wayland display](https://en.wikipedia.org/wiki/Wayland_(display_server_protocol)) -on the external monitor. -A login prompt should appear as follows depending on your board: - -**h3ulcb** or **AGL Reference Hardware**: - -```text -Automotive Grade Linux ${AGL_VERSION} h3ulcb ttySC0 - -h3ulcb login: root -``` - -At the prompt, login by using `root` as the login. -The password is "empty" so you should not be prompted for the password. - -### 4.5. Determining the Board's IP Address - -If your board is connected to a local network using Ethernet and -if a DHCP server is able to distribute IP addresses, -you can determine the board's IP address and log in using `ssh`. - -Here is an example for the **h3ulcb** board: - -```sh -h3ulcb login: root -Last login: Tue Dec 6 09:55:15 UTC 2016 on tty2 -root@h3ulcb:~# ip -4 a -1: lo: mtu 65536 qdisc noqueue state UNKNOWN group default - inet 127.0.0.1/8 scope host lo - valid_lft forever preferred_lft forever -3: eth0: mtu 1500 qdisc pfifo_fast state UP group default qlen 1000 - inet 10.0.0.27/24 brd 10.0.0.255 scope global eth0 - valid_lft forever preferred_lft forever -root@h3ulcb:~# -``` - -In the previous example, IP address is 10.0.0.27. -Once you know the address, you can use `ssh` to login. -Following is an example that shows logging into SSH and then -displaying the contents of the `/etc/os-release` file: - -```sh -$ ssh root@10.0.0.27 -Last login: Tue Dec 6 10:01:11 2016 from 10.0.0.13 -root@h3ulcb:~# cat /etc/os-release -ID="poky-agl" -NAME="Automotive Grade Linux" -VERSION="11.0.0+snapshot-20210128 (koi)" -VERSION_ID="11.0.0-snapshot-20210128" -PRETTY_NAME="Automotive Grade Linux 11.0.0+snapshot-20210128 (koi)" -``` - -## 5. Supplementary Information - -### 5.1. R-Car Generation 3 Information - -Refer to the [R-Car](https://elinux.org/R-Car) page on the -[elinux.org](https://elinux.org) website for more information. - -### 5.2. Proprietary libraries for meta-rcar-gen3 - -The meta-rcar-gen3 layer of meta-renesas supports Graphic GLES(GSX) -libraries, proprietary multimedia libraries, and ICCOM software. - -### 5.3. Build with Renesas multimedia libraries - -Multimedia portions depend on GLES portions. - -* A. Configuration for Multimedia features - - * Please copy proprietary libraries to the directory of recipes. - - * Please set local.conf the following. - - **Enable multimedia features. This provides package group of plug-ins of the GStreamer, multimedia libraries and kernel drivers.** - - ```sh - MACHINE_FEATURES:append = " multimedia" - ``` - -* B. Configuration for optional codecs and middleware - - * Please copy proprietary libraries to the directory of recipes. - - * Add features to `DISTRO_FEATURES:append` to local.conf - - **Additional configuration in OMX module**: - - ```text - " h263dec_lib" - for OMX Media Component H263 Decoder Library - " h264dec_lib" - for OMX Media Component H264 Decoder Library - " h264enc_lib" - for OMX Media Component H.264 Encoder Library - " h265dec_lib" - for OMX Media Component H265 Decoder Library - " mpeg2dec_lib" - for OMX Media Component MPEG2 Decoder Library - " mpeg4dec_lib" - for OMX Media Component MPEG4 Decoder Library - " vc1dec_lib" - for OMX Media Component VC-1 Decoder Library - " divxdec_lib" - for OMX Media Component DivX Decoder Library - " rvdec_lib" - for OMX Media Component RealVideo Decoder Library - " alacdec_lib" - for OMX Media Component ALAC Decoder Library - " flacdec_lib" - for OMX Media Component FLAC Decoder Library - " aaclcdec_lib" - for OMX Media Component AAC-LC Decoder Library - " aaclcdec_mdw" - for AAC-LC 2ch Decoder Middleware for Linux - " aacpv2dec_lib" - for OMX Media Component aacPlus V2 Decoder Library - " aacpv2dec_mdw" - for aacPlus V2 Decoder Middleware for Linux - " mp3dec_lib" - for OMX Media Component MP3 Decoder Library - " mp3dec_mdw" - for MP3 Decoder Middleware for Linux - " wmadec_lib" - for OMX Media Component WMA Standard Decoder Library - " wmadec_mdw" - for WMA Standard Decoder Middleware for Linux - " dddec_lib" - for OMX Media Component Dolby(R) Digital Decoder Library - " dddec_mdw" - for Dolby(R) Digital Decoder Middleware for Linux - " aaclcenc_lib" - for OMX Media Component AAC-LC Encoder Library - " vp8dec_lib" - for OMX Media Component VP8 Decoder Library for Linux - " vp8enc_lib" - for OMX Media Component VP8 Encoder Library for Linux - " vp9dec_lib" - for OMX Media Component VP9 Decoder Library for Linux - " aaclcenc_mdw" - for AAC-LC Encoder Middleware for Linux - " cmsbcm" - for CMS Basic Color Management Middleware for Linux - " cmsblc" - for CMS CMM3 Backlight Control Middleware for Linux - " cmsdgc" - for CMS VSP2 Dynamic Gamma Correction Middleware for Linux - " dtv" - for ISDB-T DTV Software Package for Linux - " dvd" - for DVD Core-Middleware for Linux - " adsp" - for ADSP driver, ADSP interface and ADSP framework for Linux - " avb" - for AVB Software Package for Linux - ``` - - Example: - - ```sh - DISTRO_FEATURES:append = " h264dec_lib h265dec_lib mpeg2dec_lib aaclcdec_lib aaclcdec_mdw" - ``` - -* C. Configuration for test packages - - Must ensure that Multimedia features have been enabled. - (Please refer to III/A to enable Multimedia.) - - * Please add feature to `DISTRO_FEATURES:append` to local.conf. - - **Configuration for multimedia test package** - - ```sh - DISTRO_FEATURES:append = " mm-test" - ``` - -### 5.4. Enable Linux ICCOM driver and Linux ICCOM library - -For Linux ICCOM driver and Linux ICCOM library - -* Please copy proprietary libraries to the directory of recipes. - -* Please set the following in local.conf: - - ```sh - DISTRO_FEATURES:append = "iccom" - ``` diff --git a/docs/0_Getting_Started/2_Building_AGL_Image/5_4_Virtio.md b/docs/0_Getting_Started/2_Building_AGL_Image/5_4_Virtio.md deleted file mode 100644 index 3a55fb2..0000000 --- a/docs/0_Getting_Started/2_Building_AGL_Image/5_4_Virtio.md +++ /dev/null @@ -1,151 +0,0 @@ ---- -title: Building for virtio ---- - -Virtio is a standartized interface for implementing virtual I/O devices: - -* Russell, Rusty. "virtio: towards a de-facto standard for virtual I/O devices." ACM SIGOPS Operating Systems Review 42.5 (2008): 95-103. - -This section describes the steps you need to take to build the AGL demo image -for virtio "platform". Later, the same image can be run on various emulators or -hypervisors that provide virtio devices, for example, QEMU aarch64 emulation on -PC, QEMU/KVM aarch64 virtualization on AGL Reference Hardware, etc. - -Below, AGL minimal image and Qt based IVI demo are used as example, but -similiarly one can run HTML5 based demos, cluster demo, or other AGL images. - -## 1. Making Sure Your Build Environment is Correct - -The -"[Initializing Your Build Environment](./3_Initializing_Your_Build_Environment.md)" -section presented generic information for setting up your build environment -using the `aglsetup.sh` script. -If you are building the AGL demo image for virtio platform, you need to specify -some specific options when you run the script: - -```sh -$ source meta-agl/scripts/aglsetup.sh -m virtio-aarch64 -b build-virtio-aarch64 agl-demo -``` - -The "-m" option specifies the "virtio-aarch64" machine. - -The "-b" option sets custom build directory instead of default "build". - -The "-f" option might be added to override previously available configuration. -By default, if there were already configuration files in build directory, they -will not be overriden, as result, aglsetup.sh might not have desired effect. - -## 2. Using BitBake - -This section shows the `bitbake` command used to build the AGL image. - -Start the build using the `bitbake` command. - -**AGL minimal image :** -The target is `agl-image-minimal`. - -```sh -$ bitbake agl-image-minimal -``` - -**Qt Based IVI demo :** -The target is `agl-demo-platform`. - -```sh -$ bitbake agl-demo-platform -``` - -## 3. Deploying the AGL Demo Image - -This subsection describes AGL virtio-aarch64 image deployment under virtio -platform provided by QEMU aarch64 emulator on PC, or QEMU/KVM hypervisor on AGL -Reference Hardware board. - -**3.1 QEMU on PC** - -If shell from which AGL was built is closed, or new shell is opened, then it is -needed to re-initialize build environment: - -```sh -$ source $AGL_TOP/build-virtio-aarch64/agl-init-build-env -``` - -And further use `runqemu` to boot the image : - -```sh -$ runqemu -``` - -**3.2 QEMU/KVM on AGL Reference Hardware** - -Follow these steps to run virtual AGL on bare-metal AGL (AGL-in-AGL) on AGL Reference Hardware board: - - 1. Partition eMMC or SD-Card to have two partitions, at least 1 GiB each. - Actually, can be less but just rounded up to have a nice number. - - 2. Flash AGL minimal image root file system to the second partition on SD-Card - or eMMC. - - 3. Build AGL minimal image for AGL Reference Hardware. - - ```sh - source meta-agl/scripts/aglsetup.sh -m h3ulcb -b build-h3ulcb agl-refhw-h3 - ``` - - In `build-h3ulcb/conf/local.conf` add - - ``` - AGL_DEFAULT_IMAGE_FSTYPES = "ext4" - IMAGE_INSTALL_append = "qemu" - ``` - - CAUTION: Calling aglsetup.sh with "-f" flag will remove above modification - in "local.conf", so they will be needed to be re-applied. - - Build image: - - ```sh - bitbake agl-image-minimal - ``` - - Add virtio kernel to the AGL Reference Hardware Linux rootfs: - - ```sh - cp build-virtio-aarch64/tmp/deploy/images/virtio-aarch64/Image build-h3ulcb/tmp/work/h3ulcb-agl-linux/agl-image-minimal/1.0-r0/rootfs/linux2 - bitbake agl-image-minimal -c image_ext4 -f - bitbake agl-image-minimal -c image_complete - ``` - - Flash root file system to the first partition on SD-Card or eMMC. - - 4. Boot AGL Reference Hardware board using Linux located on the first partition of SD-Card or eMMC. - - 5. Run QEMU from Linux 1 command line - - ```sh - qemu-system-aarch64 \ - -machine virt \ - -cpu cortex-a57 \ - -m 2048 \ - -serial mon:stdio \ - -global virtio-mmio.force-legacy=false \ - -drive id=disk0,file=/dev/mmcblk0p2,if=none,format=raw \ - -device virtio-blk-device,drive=disk0 \ - -object rng-random,filename=/dev/urandom,id=rng0 \ - -device virtio-rng-device,rng=rng0 \ - -nographic \ - -kernel /linux2 - -append 'root=/dev/vda rw mem=2048M' - ``` - - NOTE: mmcblk0p2 above is used for when root file system is flashed on eMMC. - In case of SD-Card, mmcblk1p2 has to be used. - - 6. It is possible to exit from QEMU using monitor commands. Enter "Ctrl+a h" for help. - -Know issue: to enable hardware virtualization using KVM, option `-enable-kvm` -could be added to QEMU command line, but it fails with: - -``` -qemu-system-aarch64: kvm_init_vcpu failed: Invalid argument -``` diff --git a/docs/0_Getting_Started/2_Building_AGL_Image/images/RaspberryPi2-ModelB-debug-serial-cable.png b/docs/0_Getting_Started/2_Building_AGL_Image/images/RaspberryPi2-ModelB-debug-serial-cable.png deleted file mode 100644 index f4374d0..0000000 Binary files a/docs/0_Getting_Started/2_Building_AGL_Image/images/RaspberryPi2-ModelB-debug-serial-cable.png and /dev/null differ diff --git a/docs/0_Getting_Started/2_Building_AGL_Image/images/image-developer-workflow.png b/docs/0_Getting_Started/2_Building_AGL_Image/images/image-developer-workflow.png deleted file mode 100644 index a185dc6..0000000 Binary files a/docs/0_Getting_Started/2_Building_AGL_Image/images/image-developer-workflow.png and /dev/null differ diff --git a/docs/0_Getting_Started/2_Building_AGL_Image/images/vbox-1.png b/docs/0_Getting_Started/2_Building_AGL_Image/images/vbox-1.png deleted file mode 100644 index a43c111..0000000 Binary files a/docs/0_Getting_Started/2_Building_AGL_Image/images/vbox-1.png and /dev/null differ diff --git a/docs/0_Getting_Started/2_Building_AGL_Image/images/vbox-2.png b/docs/0_Getting_Started/2_Building_AGL_Image/images/vbox-2.png deleted file mode 100644 index d4e1dd0..0000000 Binary files a/docs/0_Getting_Started/2_Building_AGL_Image/images/vbox-2.png and /dev/null differ diff --git a/docs/0_Getting_Started/2_Building_AGL_Image/images/vbox-3.png b/docs/0_Getting_Started/2_Building_AGL_Image/images/vbox-3.png deleted file mode 100644 index f6389f1..0000000 Binary files a/docs/0_Getting_Started/2_Building_AGL_Image/images/vbox-3.png and /dev/null differ diff --git a/docs/0_Getting_Started/2_Building_AGL_Image/images/vbox-4.png b/docs/0_Getting_Started/2_Building_AGL_Image/images/vbox-4.png deleted file mode 100644 index 09f7f0b..0000000 Binary files a/docs/0_Getting_Started/2_Building_AGL_Image/images/vbox-4.png and /dev/null differ diff --git a/docs/0_Getting_Started/2_Building_AGL_Image/images/vbox-5.png b/docs/0_Getting_Started/2_Building_AGL_Image/images/vbox-5.png deleted file mode 100644 index 0c3f51b..0000000 Binary files a/docs/0_Getting_Started/2_Building_AGL_Image/images/vbox-5.png and /dev/null differ diff --git a/docs/0_Getting_Started/3_Build_and_Boot_guide_Profile/1_Instrument_Cluster_(IC-IVI_with_Container_isolation).md b/docs/0_Getting_Started/3_Build_and_Boot_guide_Profile/1_Instrument_Cluster_(IC-IVI_with_Container_isolation).md deleted file mode 100644 index d493f87..0000000 --- a/docs/0_Getting_Started/3_Build_and_Boot_guide_Profile/1_Instrument_Cluster_(IC-IVI_with_Container_isolation).md +++ /dev/null @@ -1,124 +0,0 @@ -# Build and Boot AGL Instrument Cluster demo image (IC-IVI with Container isolation) -## Required Equipments -**1) Tested board:** **[Starter Kit Pro/M3](https://elinux.org/R-Car/Boards/M3SK) + [kingfisher support](https://elinux.org/R-Car/Boards/Kingfisher)** - -**2) MicroUSB** - -**3) MicroSD card** -## 0. Host PC environemnt -**Build PC** -Ubuntu OS (Tested version 18.04.6 LTS) - -## 1. Define Your Top-Level Directory - -```bash -export AGL_TOP=$HOME/AGL -mkdir -p $AGL_TOP -``` - -## 2. Download the repo Tool and Set Permissions - -```bash -mkdir -p $HOME/bin -export PATH=$HOME/bin:$PATH -curl https://storage.googleapis.com/git-repo-downloads/repo > $HOME/bin/repo -chmod a+x $HOME/bin/repo -``` - -## 3. Download the AGL Source Files -- **AGL Version:** Magic Marlin -```bash -cd $AGL_TOP -mkdir marlin -export AGL_TOP=$HOME/AGL/marlin -cd $AGL_TOP -git config --global user.email "you@example.com" -git config --global user.name "Your Name" -repo init -b marlin -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo -repo sync -``` -- Optional: Specify the manifest file(marlin_13.0.0.xml) using -m option - -```bash -repo init -b marlin -m marlin_13.0.0.xml -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo -``` -- Optional: Specify the master branch -```bash -repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo -``` - -## 4. Downloading Proprietary Drivers -Downloading Proprietary Drivers from [Renesas-automotive-products](https://www.renesas.com/us/en/products/automotive-products/automotive-system-chips-socs/r-car-h3-m3-documents-software) -- To check the files to download -```bash -grep -rn ZIP_.= $AGL_TOP/meta-agl/meta-agl-bsp/meta-rcar-gen3/scripts/setup_mm_packages.sh -export XDG_DOWNLOAD_DIR=$HOME/Downloads -``` -- Download and copy Proprietary Drivers files (Run commands at downloaded files directory) -```bash -cp R-Car_Gen3_Series_Evaluation_Software_Package_* $XDG_DOWNLOAD_DIR/ -chmod a+rw $XDG_DOWNLOAD_DIR/*.zip -``` -## 5. Define Your Board -- Supporting Starter Kit Pro/M3 + kingfisher Board (For other supported boards, check [Define Your Board](https://docs.automotivelinux.org/en/master/#0_Getting_Started/2_Building_AGL_Image/5_3_RCar_Gen_3/)) -```bash -export MACHINE=m3ulcb-kf -``` -## 6. Run the aglsetup.sh Script -```bash -cd $AGL_TOP -source meta-agl/scripts/aglsetup.sh -f -m $MACHINE -b $MACHINE agl-lxc -``` - -## 7. Using BitBake -```bash -bitbake lxc-host-image-demo -``` -- The build process puts the resulting image in the Build Directory -($AGL_TOP/m3ulcb-kf/tmp/deploy/images/m3ulcb) -## 8.Boot the Board (Deploying the AGL Demo Image) -- To boot your image on the Renesas board, you need to do three things: - -a) Update all [firmware](https://docs.automotivelinux.org/en/marlin/#0_Getting_Started/2_Building_AGL_Image/5_3_RCar_Gen_3/#4-troubleshooting) on R-Car M3 Starter Kit board (Flashing firmware). - -b) Prepare the MicroSD card and Flash image to the MicroSD card using [Etcher](https://www.balena.io/etcher/) - (**image file name:** lxc-host-image-demo-m3ulcb-kf.wic.xz), then insert MicroSD card in the R-Car M3SK. -c) Boot the board. - -1) Use a MicroUSB cable to connect the PC to R-Car Starter Kit Pro (M3ULCB) board CN12 "CPLD/DEBUG" -- Serial settings are 115200 8N1. -- Run any standard terminal emulator program (e.g. minicom). -[Replace **"Device"** with USB tty device name, for example **`/dev/ttyUSB0`**] -```bash -sudo minicom -b 115200 -D "DEVICE" -``` - -- Power on the board -- Quickly hit any key to get into the U-boot command prompt; you should see the following: - ```bash -Hit any key to stop autoboot: 0 => -``` -- Booting image command (for details check [How to boot](https://elinux.org/R-Car/AGL#Instrument_Cluster_with_Container_isolation_demo_image)) - ```bash -ext4load 0x48080000 Image -ext4load 0x48000000 /boot/r8a77961-ulcb-kf.dtb -booti 0x48080000 - 0x48000000 -``` - -# Run SoC board Screen -A) Connect HDMI panel to M3SK(CN4) for **IVI Container** -![IVI](https://elinux.org/images/9/91/Marlin-lxc-Ivi.JPG) - -B) Connect HDMI panel to Kingfisher(CN49)for **Cluster Container** -![IC](https://elinux.org/images/7/76/Marlin-lxc-Cluster.JPG) - - -# Reference webpages - 1. [eLinux](https://elinux.org/R-Car/AGL) - 1. [Kingfisher Board](https://elinux.org/R-Car/Boards/Kingfisher) - 1. [R-Car M3SK](https://elinux.org/R-Car/Boards/M3SK#Flashing_firmware) - 1. [agl reference machines](https://docs.automotivelinux.org/en/master/#1_hardware_support/overview/) - 1. [AGL Tech Day Presenation](https://static.sched.com/hosted_files/agltechday2022/3b/agl-techday-202204.pdf) - 1. [Build AGL Image](https://docs.automotivelinux.org/en/master/#0_Getting_Started/2_Building_AGL_Image/0_Build_Process/) - 1. [Building for Supported Renesas Boards](https://docs.automotivelinux.org/en/master/#0_Getting_Started/2_Building_AGL_Image/5_3_RCar_Gen_3/) - diff --git a/docs/0_Getting_Started/3_Build_and_Boot_guide_Profile/2_Flutter_Instrument_Cluster_(qemu-x86).md b/docs/0_Getting_Started/3_Build_and_Boot_guide_Profile/2_Flutter_Instrument_Cluster_(qemu-x86).md deleted file mode 100644 index 47bb4c0..0000000 --- a/docs/0_Getting_Started/3_Build_and_Boot_guide_Profile/2_Flutter_Instrument_Cluster_(qemu-x86).md +++ /dev/null @@ -1,126 +0,0 @@ -# Build and Boot AGL Flutter Instrument Cluster demo image made for GSoC - -## 0. Prepare Your Build Host - -- Install the required tools to build an AGL Image. For detailed explanation, check [Preparing Your Build host](https://docs.automotivelinux.org/en/needlefish/#0_Getting_Started/2_Building_AGL_Image/1_Preparing_Your_Build_Host/) - -## 1. Define Your Top-Level Directory - -```bash -$ export AGL_TOP=$HOME/AGL -$ echo 'export AGL_TOP=$HOME/AGL' >> $HOME/.bashrc -$ mkdir -p $AGL_TOP -``` - -## 2. Download the repo Tool and Set Permissions - -```bash -$ mkdir -p $HOME/bin -$ export PATH=$HOME/bin:$PATH -$ echo 'export PATH=$HOME/bin:$PATH' >> $HOME/.bashrc -$ curl https://storage.googleapis.com/git-repo-downloads/repo > $HOME/bin/repo -$ chmod a+x $HOME/bin/repo -``` - -## 3. Download the AGL Source Files -To download the latest **master** branch AGL files, use the following commands: -```bash -$ cd $AGL_TOP -$ mkdir master -$ cd master -$ repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo -$ repo sync -``` - -## 4. Initialize the build environment using aglsetup.sh Script -To initialize the build environment, we must use the setup script. -This script is available here: -```bash -$ $AGL_TOP/master/meta-agl/scripts/aglsetup.sh -``` -Run the script: - -```bash -$ cd $AGL_TOP -$ source master/meta-agl/scripts/aglsetup.sh -b build-flutter-cluster -m qemux86-64 agl-demo agl-devel -``` - -- Here `-b` is used to specify the build directory and `-m` is used to specify the target platform. - -- Running this script, will create a build directory if it does not exist. Default build directory: `$AGL_TOP/master/build-flutter-cluster` -- Default target paltform: `qemux86-64` - -** NOTE: Set the API key in local.conf ** - -- By default navigation will not work, you need to set your openrouteservie API key to the variable `OPENROUTE_API_KEY` in your local.conf -- It is present at `$AGL_TOP/master/build-flutter-cluster/conf/local.conf` - -- Example: Just add `OPENROUTE_API_KEY = "your_openrouteservice_api_key"` to the end of local.conf - - -## 5. Using BitBake - -```bash -$ cd $AGL_TOP/master/build-flutter-cluster -$ source agl-init-build-env -$ bitbake agl-cluster-demo-platform-flutter -``` - -## 6. Deploying the AGL Demo Image -Boot the image using QEMU - -```bash -$ cd $AGL_TOP/master/build-flutter-cluster -$ source agl-init-build-env -$ runqemu kvm serialstdio slirp publicvnc -``` - -## 6. Run the Graphics -To get graphics of the app, you need VNC client like VNC Viewer or Vinagre - -- Open the VNC client -- Enter the server address as `localhost:0` - -That's it, you should get something like this: -![Screenshot](images/flutter_instrument_cluster.png) - -## 7. To start navigation widget -To get the navigation, you need to use `kuksa_viss_client` or `kuksa_vss_init.py` script. - -#### **Using inbuilt `kuksa_vss_init.py` script** - - After running the build, you should get this: - -```bash -Automotive Grade Linux 13.93.0 qemux86-64 ttyS0 - -qemux86-64 login: - -``` - -Login as root - -```bash -qemux86-64 login: root -``` -Now run the script - -```bash -root@qemux86-64:~# /usr/sbin/kuksa_vss_init.py -``` - -#### **Using `kuksa_viss_client`** - -Know more about kuksa_viss_client, [Follow this](https://github.com/eclipse/kuksa.val/tree/master/kuksa_viss_client) - -- Run the kuksa_viss_client -- Authorize using token - -Then - -```bash -Test Client> setValue Vehicle.Cabin.SteeringWheel.Switches.Info true -``` -![Screenshot](images/flutter_instrument_cluster_map.png) - - diff --git a/docs/0_Getting_Started/3_Build_and_Boot_guide_Profile/2_IVI_Flutter_apps.md b/docs/0_Getting_Started/3_Build_and_Boot_guide_Profile/2_IVI_Flutter_apps.md deleted file mode 100644 index 6475365..0000000 --- a/docs/0_Getting_Started/3_Build_and_Boot_guide_Profile/2_IVI_Flutter_apps.md +++ /dev/null @@ -1,78 +0,0 @@ -# Build and Boot AGL Flutter IVI dashboard demo applications made for GSoC - -## 0. Prepare Your Build Host - -- Install the required tools to build an AGL Image. For detailed explanation, check [Preparing Your Build host](https://docs.automotivelinux.org/en/needlefish/#0_Getting_Started/2_Building_AGL_Image/1_Preparing_Your_Build_Host/) - -## 1. Define Your Top-Level Directory - -```bash -$ export AGL_TOP=$HOME/AGL -$ echo 'export AGL_TOP=$HOME/AGL' >> $HOME/.bashrc -$ mkdir -p $AGL_TOP -``` - -## 2. Download the repo Tool and Set Permissions - -```bash -$ mkdir -p $HOME/bin -$ export PATH=$HOME/bin:$PATH -$ echo 'export PATH=$HOME/bin:$PATH' >> $HOME/.bashrc -$ curl https://storage.googleapis.com/git-repo-downloads/repo > $HOME/bin/repo -$ chmod a+x $HOME/bin/repo -``` - -## 3. Download the AGL Source Files -To download the latest **master** branch AGL files, use the following commands: -```bash -$ cd $AGL_TOP -$ mkdir master -$ cd master -$ repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo -$ repo sync -``` - -## 4. Initialize the build environment using aglsetup.sh Script -To initialize the build environment, we must use the setup script. -This script is available here: -```bash -$ $AGL_TOP/master/meta-agl/scripts/aglsetup.sh -``` -Run the script: - -```bash -$ cd $AGL_TOP -$ source master/meta-agl/scripts/aglsetup.sh -b build-flutter-dashboard -m qemux86-64 agl-demo agl-devel -``` - -- Here `-b` is used to specify the build directory and `-m` is used to specify the target platform. - -- Running this script, will create a build directory if it does not exist. Default build directory: `$AGL_TOP/master/build-flutter-dashboard` -- Default target paltform: `qemux86-64` - -## 5. Using BitBake - -```bash -$ cd $AGL_TOP/build-flutter-dashboard -$ source agl-init-build-env -$ bitbake agl-ivi-demo-platform-flutter -``` - -## 6. Deploying the AGL Demo Image -Boot the image using QEMU - -```bash -$ cd $AGL_TOP/build-flutter-dashboard -$ source agl-init-build-env -$ runqemu kvm serialstdio slirp publicvnc -``` - -## 6. Run the Graphics -To get graphics of the app, you need VNC client like VNC Viewer or Vinagre - -- Open the VNC client -- Enter the server address as `localhost:0` - -That's it, you should get something like this: -![Screenshot](images/ivi_homescreen.PNG) - diff --git a/docs/0_Getting_Started/3_Build_and_Boot_guide_Profile/images/flutter_instrument_cluster.png b/docs/0_Getting_Started/3_Build_and_Boot_guide_Profile/images/flutter_instrument_cluster.png deleted file mode 100644 index 23cf19d..0000000 Binary files a/docs/0_Getting_Started/3_Build_and_Boot_guide_Profile/images/flutter_instrument_cluster.png and /dev/null differ diff --git a/docs/0_Getting_Started/3_Build_and_Boot_guide_Profile/images/flutter_instrument_cluster_map.png b/docs/0_Getting_Started/3_Build_and_Boot_guide_Profile/images/flutter_instrument_cluster_map.png deleted file mode 100644 index 8d3a1b2..0000000 Binary files a/docs/0_Getting_Started/3_Build_and_Boot_guide_Profile/images/flutter_instrument_cluster_map.png and /dev/null differ diff --git a/docs/0_Getting_Started/3_Build_and_Boot_guide_Profile/images/ivi_homescreen.PNG b/docs/0_Getting_Started/3_Build_and_Boot_guide_Profile/images/ivi_homescreen.PNG deleted file mode 100644 index 8fa63e0..0000000 Binary files a/docs/0_Getting_Started/3_Build_and_Boot_guide_Profile/images/ivi_homescreen.PNG and /dev/null differ diff --git a/docs/1_Getting_Started/1_Quickstart/1_Using_Ready_Made_Images.md b/docs/1_Getting_Started/1_Quickstart/1_Using_Ready_Made_Images.md new file mode 100644 index 0000000..eaae38e --- /dev/null +++ b/docs/1_Getting_Started/1_Quickstart/1_Using_Ready_Made_Images.md @@ -0,0 +1,385 @@ +--- +title: Using Ready Made Images +--- + +AGL provides a number of pre-built ready-made images of various versions. + +## x86 (Emulation and Hardware) + +### 1. QEMU (Emulation) + +1. Download the [compressed prebuilt image](https://download.automotivelinux.org/AGL/snapshots/master/latest/qemux86-64/deploy/images/qemux86-64/agl-demo-platform-crosssdk-qemux86-64.ext4.xz). + +2. Download the [compressed kernel image](https://download.automotivelinux.org/AGL/snapshots/master/latest/qemux86-64/deploy/images/qemux86-64/bzImage). + +3. Install [QEMU](https://www.qemu.org/download/) : + + ```sh + $ apt-get install qemu + ``` + +4. Install [vinagre](https://wiki.gnome.org/Apps/Vinagre) : + + ```sh + $ sudo apt install vinagre + ``` + +5. Create boot directory and copy compressed images (prebuilt & kernel) into them : + + ```sh + $ mkdir ~/agl-demo/ + $ cp ~/Downloads/agl-demo-platform-crosssdk-qemux86-64.ext4.xz ~/agl-demo/ + $ cp ~/Downloads/bzImage ~/agl-demo/ + $ cd ~/agl-demo + $ sync + ``` + +6. Extract prebuilt compressed image : + + ```sh + $ xz -v -d agl-demo-platform-crosssdk-qemux86-64.ext4.xz + ``` + +7. Launch QEMU with vinagre (for scaling), remove `- snapshot \` if you want to save changes to the image files : + + ```sh + $ ( sleep 5 && vinagre --vnc-scale localhost ) > /tmp/vinagre.log 2>&1 & + $ qemu-system-x86_64 -device virtio-net-pci,netdev=net0,mac=52:54:00:12:35:02 -netdev user,id=net0,hostfwd=tcp::2222-:22 \ + -drive file=agl-demo-platform-crosssdk-qemux86-64.ext4,if=virtio,format=raw -show-cursor -usb -usbdevice tablet -device virtio-rng-pci \ + -snapshot -vga virtio \ + -vnc :0 -soundhw hda -machine q35 -cpu kvm64 -cpu qemu64,+ssse3,+sse4.1,+sse4.2,+popcnt -enable-kvm \ + -m 2048 -serial mon:vc -serial mon:stdio -serial null -kernel bzImage \ + -append 'root=/dev/vda rw console=tty0 mem=2048M ip=dhcp oprofile.timer=1 console=ttyS0,115200n8 verbose fstab=no' + ``` + + - Login into AGL : + + ```sh + Automotive Grade Linux 11.0.0+snapshot qemux86-64 ttyS1 + + qemux86-64 login: root + ``` + + + - Shutdown QEMU : `$ poweroff`, otherwise QEMU will run in the background. + - To use vnc-viewer instead of vinagre : + ```sh + $ ( sleep 5 && vncviewer ) & + qemu-system-x86_64 -device virtio-net-pci,netdev=net0,mac=52:54:00:12:35:02 -netdev user,id=net0,hostfwd=tcp::2222-:22 \ + -drive file=agl-demo-platform-crosssdk-qemux86-64.ext4,if=virtio,format=raw -show-cursor -usb -usbdevice tablet -device virtio-rng-pci \ + -snapshot -vga virtio \ + -vnc :0 -soundhw hda -machine q35 -cpu kvm64 -cpu qemu64,+ssse3,+sse4.1,+sse4.2,+popcnt -enable-kvm \ + -m 2048 -serial mon:vc -serial mon:stdio -serial null -kernel bzImage \ + -append 'root=/dev/vda rw console=tty0 mem=2048M ip=dhcp oprofile.timer=1 console=ttyS0,115200n8 verbose fstab=no' + ``` + +### 2. Virtual Box (Emulation) + +**NOTE :** Please note [https://www.virtualbox.org/ticket/19873](https://www.virtualbox.org/ticket/19873) as this affects the VMs resolution. +The AGL demo images do require 1920x1080. The instructions below have been adapted. + + 1. Download the [compressed vbox disk image](https://download.automotivelinux.org/AGL/snapshots/master/latest/qemux86-64/deploy/images/qemux86-64/agl-demo-platform-crosssdk-qemux86-64.wic.vmdk.xz). + + 2. Install and set up [Virtual Box](https://www.virtualbox.org/wiki/Linux_Downloads). + + 3. Extract the vmdk file : `$ xz -v -d agl-demo-platform-crosssdk-qemux86-64.wic.vmdk.xz` + + 4. Configure virtual box for AGL : + - Click on `New` or `Add`. + - Enter Name as `agl-demo`. + - Type as `Linux`. + - Version as `Other Linux (64-bit)`, click on `Next`. + ![vbox-step-1](images/vbox-1.png) + - Select Memory size. Recommended is `2048 MB`, click on `Next`. + ![vbox-step-2](images/vbox-2.png) + - Click on `Use an existing virtual hard disk file`, and select the extracted `agl-demo-platform-crosssdk-qemux86-64.wic.vmdk` file, click on `Create`. + ![vbox-step-3](images/vbox-3.png) + - Go to `Settings`, and into `System`. Select `Chipset : IHC9`. Check on `Enable EFI (special OSes only)` and click on `OK`. + ![vbox-step-4](images/vbox-4.png) + - Go to `Storage`, and change the attribute to `Type : AHCI` and click on `OK`. + ![vbox-step-5](images/vbox-5.png) + - Next go to `Display` and change the attribute to 'VMSVGA' for the graphics driver. Change the graphics memory to be at least 64MB. + - **Important:**: Open a new terminal window and execute this command: + ```sh + VBoxManage setextradata agl-demo VBoxInternal2/EfiGraphicsResolution 1920x1080 + ``` + - Return to the UI and click on `Start`. + - For troubleshooting, you can refer [here](https://lists.automotivelinux.org/g/agl-dev-community/message/8474). + +### 3. x86 physical system + + **NOTE :** UEFI enabled system is required. + + 1. Download the [compressed prebuilt image](https://download.automotivelinux.org/AGL/snapshots/master/latest/qemux86-64/deploy/images/qemux86-64/agl-demo-platform-crosssdk-qemux86-64.wic.xz). + + 2. Extract the image into USB drive : + + ```sh + $ lsblk + $ sudo umount + $ xzcat agl-demo-platform-crosssdk-qemux86-64.wic.xz | sudo dd of= bs=4M + $ sync + ``` + + + 3. Boot from USB drive on the x86 system. + +## ARM 32 bit (Emulation and Hardware) + +### 1. QEMU (Emulation) + +1. Download the [compressed prebuilt image](https://download.automotivelinux.org/AGL/snapshots/master/latest/qemuarm/deploy/images/qemuarm/agl-demo-platform-crosssdk-qemuarm.ext4.xz). + +2. Download the [compressed kernel image](https://download.automotivelinux.org/AGL/snapshots/master/latest/qemuarm/deploy/images/qemuarm/zImage). + +3. Install [QEMU](https://www.qemu.org/download/) : + + ```sh + $ apt-get install qemu + ``` + +4. Install [vinagre](https://wiki.gnome.org/Apps/Vinagre) : + + ```sh + $ sudo apt install vinagre + ``` + +5. Create boot directory and copy compressed images (prebuilt & kernel) into them : + + ```sh + $ mkdir ~/agl-demo/ + $ cp ~/Downloads/agl-demo-platform-crosssdk-qemuarm.ext4.xz ~/agl-demo/ + $ cp ~/Downloads/zImage ~/agl-demo/ + $ cd ~/agl-demo + $ sync + ``` + +6. Extract prebuilt compressed image : + + ```sh + $ xz -v -d agl-demo-platform-crosssdk-qemuarm.ext4.xz + ``` + +7. Launch QEMU with vinagre (for scaling), remove `- snapshot` if you want to save changes to the image files : + + ```sh + $ ( sleep 5 && vinagre --vnc-scale localhost ) > /tmp/vinagre.log 2>&1 & + qemu-system-arm -cpu cortex-a15 -machine virt-2.11 -nographic \ + -net nic,model=virtio,macaddr=52:54:00:12:34:58 \ + -net user -m 2048 -monitor none -soundhw hda -device usb-ehci \ + -device virtio-rng-pci -device VGA,vgamem_mb=64,edid=on -vnc :0 \ + -device qemu-xhci -device usb-tablet -device usb-kbd \ + -kernel zImage -append "console=ttyAMA0,115200 root=/dev/vda verbose systemd.log_color=false" \ + -drive format=raw,file=agl-demo-platform-crosssdk-qemuarm.ext4 \ + -snapshot + ``` + + - Login into AGL : + + ```sh + Automotive Grade Linux 11.0.0+snapshot qemux86-64 ttyS1 + + qemux86-64 login: root + ``` + + + - Shutdown QEMU : `$ poweroff`, otherwise QEMU will run in the background. + - To use vnc-viewer instead of vinagre : + ```sh + $ ( sleep 5 && vncviewer ) & + qemu-system-arm -cpu cortex-a15 -machine virt-2.11 -nographic \ + -net nic,model=virtio,macaddr=52:54:00:12:34:58 \ + -net user -m 2048 -monitor none -soundhw hda -device usb-ehci \ + -device virtio-rng-pci -device VGA,vgamem_mb=64,edid=on -vnc :0 \ + -device qemu-xhci -device usb-tablet -device usb-kbd \ + -kernel zImage -append "console=ttyAMA0,115200 root=/dev/vda verbose systemd.log_color=false" \ + -drive format=raw,file=agl-demo-platform-crosssdk-qemuarm.ext4 \ + -snapshot + ``` + +### 2. BeagleBone Enhanced (BBE) + + 1. Download the [compressed prebuilt image](https://download.automotivelinux.org/AGL/snapshots/master/latest/bbe/deploy/images/bbe/agl-demo-platform-crosssdk-bbe.wic.xz). + + 2. Extract the image into the SD card of BeagleBone Enhanced : + + ```sh + $ lsblk + $ sudo umount + $ xzcat agl-demo-platform-crosssdk-bbe.wic.xz | sudo dd of= bs=4M + $ sync + ``` + + **IMPORTANT NOTE:** Before re-writing any device on your Build Host, you need to + be sure you are actually writing to the removable MicroSD card and not some other + device. + Each computer is different and removable devices can change from time to time. + Consequently, you should repeat the previous operation with the MicroSD card to + confirm the device name every time you write to the card. + + To summarize this example so far, we have the following: + The first SATA drive is `/dev/sda` and `/dev/sdc` corresponds to the MicroSD card, and is also marked as a removable device.You can see this in the output of the `lsblk` command where "1" appears in the "RM" column for that device. + +## AARCH64 - ARM 64bit + +### 1. QEMU (Emulation) + +1. Download the [compressed prebuilt image](https://download.automotivelinux.org/AGL/snapshots/master/latest/qemuarm64/deploy/images/qemuarm64/agl-demo-platform-crosssdk-qemuarm64.ext4.xz). + +2. Download the [compressed kernel image](https://download.automotivelinux.org/AGL/snapshots/master/latest/qemuarm64/deploy/images/qemuarm64/Image). + +3. Install [QEMU](https://www.qemu.org/download/) : + + ```sh + $ apt-get install qemu + ``` + +4. Install [vinagre](https://wiki.gnome.org/Apps/Vinagre) : + + ```sh + $ sudo apt install vinagre + ``` + +5. Create boot directory and copy compressed images (prebuilt & kernel) into them : + + ```sh + $ mkdir ~/agl-demo/ + $ cp ~/Downloads/agl-demo-platform-crosssdk-qemuarm64.ext4.xz ~/agl-demo/ + $ cp ~/Downloads/zImage ~/agl-demo/ + $ cd ~/agl-demo + $ sync + ``` + +6. Extract prebuilt compressed image : + + ```sh + $ xz -v -d agl-demo-platform-crosssdk-qemuarm64.ext4.xz + ``` + +7. Launch QEMU with vinagre (for scaling), remove `- snapshot \` if you want to save changes to the image files : + + ```sh + $ ( sleep 5 && vinagre --vnc-scale localhost ) > /tmp/vinagre.log 2>&1 & + qemu-system-aarch64 -cpu cortex-a57 -machine virt -nographic \ + -net nic,model=virtio,macaddr=52:54:00:12:34:58 \ + -net user -m 2048 -monitor none -smp 2 -soundhw hda -device usb-ehci \ + -device virtio-rng-pci -device VGA,vgamem_mb=64,edid=on \ + -device qemu-xhci -device usb-tablet -device usb-kbd -vnc :0 \ + -kernel Image -append "console=ttyAMA0,115200 root=/dev/vda verbose systemd.log_color=false " \ + -drive format=raw,file=agl-demo-platform-crosssdk-qemuarm64.ext4 \ + -snapshot + ``` + + - Login into AGL : + + ```sh + Automotive Grade Linux 11.0.0+snapshot qemux86-64 ttyS1 + + qemux86-64 login: root + ``` + + + - Shutdown QEMU : `$ poweroff`, otherwise QEMU will run in the background. + - To use vnc-viewer instead of vinagre : + ```sh + $ ( sleep 5 && vncviewer ) & + qemu-system-aarch64 -cpu cortex-a57 -machine virt -nographic \ + -net nic,model=virtio,macaddr=52:54:00:12:34:58 \ + -net user -m 2048 -monitor none -smp 2 -soundhw hda -device usb-ehci \ + -device virtio-rng-pci -device VGA,vgamem_mb=64,edid=on \ + -device qemu-xhci -device usb-tablet -device usb-kbd -vnc :0 \ + -kernel Image -append "console=ttyAMA0,115200 root=/dev/vda verbose systemd.log_color=false " \ + -drive format=raw,file=agl-demo-platform-crosssdk-qemuarm64.ext4 \ + -snapshot + ``` + +### 2. Raspberry Pi 4 + + 1. Download the [compressed prebuilt image](https://download.automotivelinux.org/AGL/snapshots/master/latest/raspberrypi4/deploy/images/raspberrypi4-64/agl-demo-platform-crosssdk-raspberrypi4-64.wic.xz). + + 2. Extract the image into the SD card of Raspberry Pi 4 : + + ```sh + $ lsblk + $ sudo umount + $ xzcat agl-demo-platform-crosssdk-raspberrypi4-64.wic.xz | sudo dd of= bs=4M + $ sync + ``` + + **IMPORTANT NOTE:** Before re-writing any device on your Build Host, you need to + be sure you are actually writing to the removable MicroSD card and not some other + device. + Each computer is different and removable devices can change from time to time. + Consequently, you should repeat the previous operation with the MicroSD card to + confirm the device name every time you write to the card. + + To summarize this example so far, we have the following: + The first SATA drive is `/dev/sda` and `/dev/sdc` corresponds to the MicroSD card, and is also marked as a removable device.You can see this in the output of the `lsblk` command where "1" appears in the "RM" column for that device. + + 3. SSH into Raspberry Pi : + - Connect Raspberry Pi to network : `Homescreen > Settings`, IP address mentioned here. + - `ssh root@` + + + 4. Serial Debugging : + + When things go wrong, you can take steps to debug your Raspberry Pi. + For debugging, you need a 3.3 Volt USB Serial cable to fascilitate + communication between your Raspberry Pi board and your build host. + + You can reference the following diagram for information on the following steps: + + ![](images/RaspberryPi2-ModelB-debug-serial-cable.png) + + 1. Connect the TTL cable to the Universal Asynchronous Receiver-Transmitter + (UART) connection on your Raspberry Pi board. + Do not connect the USB side of the cable to your build host at this time. + + **CAUTION:** No warranty is provided using the following procedure. + Pay particular attention to the collors of your cable as they could + vary depending on the vendor. + + 2. Connect the cable's BLUE wire to pin 6 (i.e. Ground) of the UART. + + 3. Connect the able's GREEN RX line to pin 8 (i.e. the TXD line) of + the UART. + + 4. Connect the cable's RED TX line to pin 10 (i.e. the RXD line) of + the UART. + + 5. Plug the USB connector of the cable into your build host's USB port. + + 6. Use your favorite tool for serial communication between your build host + and your Raspberry Pi. + For example, if your build host is a native Linux machine (e.g. Ubuntu) + you could use `screen` as follows from a terminal on the build host: + + ```sh + $ sudo screen /dev/ttyUSB0 115200 + ``` + +### 3. R-Car H3SK (H3ULCB board) + +**NOTE :** The prebuilt image does support **non-accelerated** graphics mode (software rendering). For **accelerated** graphics support, a local build with the neccesary graphics driver is required. + + + 1. Update the [firmware](https://elinux.org/R-Car/Boards/H3SK#Flashing_firmware) using files from [here](https://download.automotivelinux.org/AGL/snapshots/master/latest/h3ulcb-nogfx/deploy/images/h3ulcb/). + + 2. Download the [compressed prebuilt image](https://download.automotivelinux.org/AGL/snapshots/master/latest/h3ulcb-nogfx/deploy/images/h3ulcb/agl-demo-platform-crosssdk-h3ulcb.wic.xz). + + 3. Extract the image into the boot device : + + ```sh + $ lsblk + $ sudo umount + $ xzcat agl-demo-platform-crosssdk-h3ulcb.wic.xz | sudo dd of= bs=4M + $ sync + ``` + + 3. [Serial](https://elinux.org/R-Car/Boards/H3SK) into the board for debugging. + For example, if your build host is a native Linux machine (e.g. Ubuntu) + you could use `screen` as follows from a terminal on the build host: + + ```sh + $ sudo screen /dev/ttyUSB0 115200 + ``` diff --git a/docs/1_Getting_Started/1_Quickstart/images/RaspberryPi2-ModelB-debug-serial-cable.png b/docs/1_Getting_Started/1_Quickstart/images/RaspberryPi2-ModelB-debug-serial-cable.png new file mode 100644 index 0000000..f4374d0 Binary files /dev/null and b/docs/1_Getting_Started/1_Quickstart/images/RaspberryPi2-ModelB-debug-serial-cable.png differ diff --git a/docs/1_Getting_Started/1_Quickstart/images/vbox-1.png b/docs/1_Getting_Started/1_Quickstart/images/vbox-1.png new file mode 100644 index 0000000..a43c111 Binary files /dev/null and b/docs/1_Getting_Started/1_Quickstart/images/vbox-1.png differ diff --git a/docs/1_Getting_Started/1_Quickstart/images/vbox-2.png b/docs/1_Getting_Started/1_Quickstart/images/vbox-2.png new file mode 100644 index 0000000..d4e1dd0 Binary files /dev/null and b/docs/1_Getting_Started/1_Quickstart/images/vbox-2.png differ diff --git a/docs/1_Getting_Started/1_Quickstart/images/vbox-3.png b/docs/1_Getting_Started/1_Quickstart/images/vbox-3.png new file mode 100644 index 0000000..f6389f1 Binary files /dev/null and b/docs/1_Getting_Started/1_Quickstart/images/vbox-3.png differ diff --git a/docs/1_Getting_Started/1_Quickstart/images/vbox-4.png b/docs/1_Getting_Started/1_Quickstart/images/vbox-4.png new file mode 100644 index 0000000..09f7f0b Binary files /dev/null and b/docs/1_Getting_Started/1_Quickstart/images/vbox-4.png differ diff --git a/docs/1_Getting_Started/1_Quickstart/images/vbox-5.png b/docs/1_Getting_Started/1_Quickstart/images/vbox-5.png new file mode 100644 index 0000000..0c3f51b Binary files /dev/null and b/docs/1_Getting_Started/1_Quickstart/images/vbox-5.png differ diff --git a/docs/1_Getting_Started/2_Building_AGL_Image/1_Build_Process.md b/docs/1_Getting_Started/2_Building_AGL_Image/1_Build_Process.md new file mode 100644 index 0000000..f1a48c7 --- /dev/null +++ b/docs/1_Getting_Started/2_Building_AGL_Image/1_Build_Process.md @@ -0,0 +1,33 @@ +--- +title: Build Process Overview +--- + +The AGL image development workflow consists of setting up +the system (i.e. the build host) that builds the image and finishes with +using the +[Yocto Project](https://yoctoproject.org) to create an image +targeted towards specific hardware. + +The following figure and list overview the AGL image development +process. +You can learn about the steps in the process by reading through the +remaining sections. + +**NOTE:** This procedure uses information from many other procedures +in the AGL Documentation set. +Links are provided when a set of steps is required that is documented +elsewhere. + +![](images/image-developer-workflow.png) + +1. Prepare your build host to be able to use the tools needed to build your image. + +2. Download the AGL software into a local Git repository on your build host. + +3. Run the build environment script to initialize variables and paths needed for the build. + +4. Make sure your build configuration is defined exactly how you want it for your build. + +5. Use + [BitBake](https://docs.yoctoproject.org/bitbake.html) + to build your image. diff --git a/docs/1_Getting_Started/2_Building_AGL_Image/2_Preparing_Your_Build_Host.md b/docs/1_Getting_Started/2_Building_AGL_Image/2_Preparing_Your_Build_Host.md new file mode 100644 index 0000000..fdca659 --- /dev/null +++ b/docs/1_Getting_Started/2_Building_AGL_Image/2_Preparing_Your_Build_Host.md @@ -0,0 +1,67 @@ +--- +title: Preparing Your Build Host +--- + +Preparing your build host so that it can build an AGL image means +making sure your system is set up to use the +[Yocto Project](https://yoctoproject.org) OpenEmbedded build system, +which is based on +[BitBake](https://docs.yoctoproject.org/bitbake.html). + +This section presents minimal information so you can prepare the build host +to use the "Dunfell" version of the Yocto Project (i.e. version 3.1.2). +If you want more details on how the Yocto Project works, you can reference +the Yocto Project documentation +[here](https://www.yoctoproject.org/docs/). + +**NOTE:** This entire section presumes you want to build an image. +You can skip the entire build process if you want to use a ready-made +development image. +The [supported images](https://download.automotivelinux.org/AGL/snapshots/master/latest/) exist for several boards as +well as for the Quick EMUlator (QEMU). +See the +"[Quickstart](../1_Quickstart/Using_Ready_Made_Images.md)" +section for more information on the ready-made images. + +1. **Use a Supported Linux Distribution:** To use the AGL software, it is + recommended that your build host is a native Linux machine that runs a + Yocto Project supported distribution as described by the + "[Supported Linux Distributions](https://docs.yoctoproject.org/ref-manual/system-requirements.html#supported-linux-distributions)" + section in the Yocto Project Reference Manual. + Basically, you should be running a recent version of Ubuntu, Fedora, openSUSE, + CentOS, or Debian. + +2. **Be Sure Your Build Host Has Enough Free Disk Space:** + Your build host should have at least 100 Gbytes. + +3. **Be Sure Tools are Recent:** You need to have recent versions for the following tools: + + - Git 1.8.3.1 or greater + - Tar 1.27 or greater + - Python 3.4.0 or greater + + If your distribution does not meet these minimal requirements, see the + "[Required Git, tar, and Python Versions](https://docs.yoctoproject.org/ref-manual/system-requirements.html#required-git-tar-python-and-gcc-versions)" + section in the Yocto Project Reference Manual for steps that you can + take to be sure you have these tools. + +4. **Install Essential, Graphical, and Eclipse Plug-in Build Host Packages:** + Your build host needs certain host packages. + Depending on the Linux distribution you are using, the list of + host packages differ. + See + "[The Build Host Packages](https://docs.yoctoproject.org/ref-manual/system-requirements.html#required-packages-for-the-build-host)" + section of the Yocto Project Quick Start for information on the packages you need. + + **NOTE:** If you are using the CentOS distribution, you need to + separately install the epel-release package and run the `makecache` command as + described in + "[The Build Host Packages](https://docs.yoctoproject.org/ref-manual/system-requirements.html#required-packages-for-the-build-host)" + section of the Yocto Project Quick Start. + + Aside from the packages listed in the previous section, you need the following: + + * **Ubuntu and Debian:** curl + * **Fedora:** curl + * **OpenSUSE:** glibc-locale curl + * **CentOS:** curl diff --git a/docs/1_Getting_Started/2_Building_AGL_Image/3_Downloading_AGL_Software.md b/docs/1_Getting_Started/2_Building_AGL_Image/3_Downloading_AGL_Software.md new file mode 100644 index 0000000..02d9108 --- /dev/null +++ b/docs/1_Getting_Started/2_Building_AGL_Image/3_Downloading_AGL_Software.md @@ -0,0 +1,102 @@ +--- +title: Downloading AGL Software +--- + +Once you have determined the build host can build an AGL image, +you need to download the AGL source files. +The AGL source files, which includes the Yocto Project layers, are +maintained on the AGL Gerrit server. +For information on how to create accounts for Gerrit, see the +[Getting Started with AGL](https://wiki.automotivelinux.org/start/getting-started) +wiki page. + +**NOTE:** Further information about Download and Build AGL Source Code available at [AGL wiki](https://wiki.automotivelinux.org/agl-distro/source-code). + +The remainder of this section provides steps on how to download the AGL source files: + +1. **Define Your Top-Level Directory:** + You can define an environment variable as your top-level AGL workspace folder. + Following is an example that defines the `$HOME/workspace_agl` folder using + an environment variable named "AGL_TOP": + + ```sh + $ export AGL_TOP=$HOME/AGL + $ echo 'export AGL_TOP=$HOME/AGL' >> $HOME/.bashrc + $ mkdir -p $AGL_TOP + ``` + +2. **Download the `repo` Tool and Set Permissions:** + AGL Uses the `repo` tool for managing repositories. + Use the following commands to download the tool and then set its + permissions to allow for execution: + + ```sh + $ mkdir -p $HOME/bin + $ export PATH=$HOME/bin:$PATH + $ echo 'export PATH=$HOME/bin:$PATH' >> $HOME/.bashrc + $ curl https://storage.googleapis.com/git-repo-downloads/repo > $HOME/bin/repo + $ chmod a+x $HOME/bin/repo + ``` + + **NOTE:** See the + "[Repo Command Reference](https://source.android.com/setup/develop/repo)" + for more information on the `repo` tool. + +3. **Download the AGL Source Files:** + Depending on your development goals, you can either download the + latest stable AGL release branch, or the "cutting-edge" (i.e. "master" + branch) files. + + * **Stable Release:** + Using the latest stable release gives you a solid snapshot of the + latest know release. + The release is static, tested, and known to work. + To download the [latest stable release branch](https://wiki.automotivelinux.org/agl-distro/release-notes#latest_stable_release), use + the following commands: + + **Note:** In this below command please change the branch name to the [latest stable release branch](https://wiki.automotivelinux.org/agl-distro/release-notes#latest_stable_release). For example, for Nifty Needlefish branch use the last name i.e. "needlefish" as branch. + + + ```sh + $ cd $AGL_TOP + $ mkdir <> + $ cd <> + $ repo init -b <> -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo + $ repo sync + ``` + + * **Cutting-Edge Files:** + Using the "cutting-edge" AGL files gives you a snapshot of the + "master" branch. + The resulting local repository you download is dynamic and changes frequently depending on community contributions. + The advantage of using "cutting-edge" AGL files is that you have the + absolute latest features, which are often under development, for AGL. + + To download the "cutting-edge" AGL files, use the following commands: + + ```sh + $ cd $AGL_TOP + $ mkdir master + $ cd master + $ repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo + $ repo sync + ``` + + Once you `sync` the repository, you have the AGL files in the form of + "layers" (e.g. `meta-*` folders). + You also have the `poky` repository in your AGL workspace. + + Listing out the resulting directory structure appears as follows: + + ```sh + $ tree -L 1 + . + ├── bsp + ├── external + ├── meta-agl + ├── meta-agl-cluster-demo + ├── meta-agl-demo + ├── meta-agl-devel + ├── meta-agl-extra + └── meta-agl-telematics-demo + ``` diff --git a/docs/1_Getting_Started/2_Building_AGL_Image/4_Initializing_Your_Build_Environment.md b/docs/1_Getting_Started/2_Building_AGL_Image/4_Initializing_Your_Build_Environment.md new file mode 100644 index 0000000..efe7001 --- /dev/null +++ b/docs/1_Getting_Started/2_Building_AGL_Image/4_Initializing_Your_Build_Environment.md @@ -0,0 +1,255 @@ +--- +title: Initializing Your Build Environment +--- + +Part of the downloaded AGL software is a setup script that you must +run to initialize the build environment. + +## `aglsetup.sh` Script + +You can find this script here: + +```sh +$AGL_TOP/master/meta-agl/scripts/aglsetup.sh +``` + +The script accepts many options that allow you to define build parameters such +as the target hardware (i.e. the machine), build directory, and so forth. +Use the following commands to see the available options and script syntax: + +```sh +$ cd $AGL_TOP/master +$ source meta-agl/scripts/aglsetup.sh -h +``` + +## AGL Machines (board support) + +Your target platform will be selected with the `-m` flag. +The MACHINE can be selected from the templates in `meta-agl/templates/machine/*`. +Note: This is also the place where you can add new boards. + +Following is a list of the available machines (level of support varies!): + +```sh +Available machines: + [meta-agl] + bbe # BeagleBoneEnhanced + beaglebone # BeagleBone + cubox-i # multiple i.MX6 boards + dragonboard-410c # Qualcomm Dragonboard 410c + dragonboard-820c # Qualcomm Dragonboard 820c + ebisu # Renesas RCar Ebisu + h3-salvator-x # Renesas RCar Salvator/H3 + h3ulcb # Renesas RCar H3 + h3ulcb-kf # Renesas RCar H3 w Kingfisher Board + h3ulcb-nogfx # Renesas RCar H3 w/o gfx blobs + hsdk # ARC HS + imx6qdlsabreauto # i.MX6 sabreauto + imx8mqevk # i.MX8 w etnaviv + imx8mqevk-viv # i.MX8 w vivante + intel-corei7-64 # x86-64 (Intel flavour) + j7-evm # TI Jacinto 7 EVM + m3-salvator-x # Renesas RCar Salvator/M3 + m3ulcb # Renesas RCar M3 + m3ulcb-kf # Renesas RCar M3 w Kingfisher Board + m3ulcb-nogfx # Renesas RCAR M3 w/o gfx blobs + nitrogen6x # i.MX6 nitrogen board + qemuarm # Qemu ARM + qemuarm64 # Qemu AArch 64 (ARM 64bit) + * qemux86-64 # Qemu x86-64 + raspberrypi4 # Raspberry Pi 4 + virtio-aarch64 # Virtio Guest + +``` + +## AGL Features + +Before running the `aglsetup.sh`, you should understand what AGL features you +want to include as part of your image. +The script's help output lists available features and shows you the layers in +which they reside. + +Following is a list of the available features: + +```sh +Available features: + + [meta-agl] # CORE layer + agl-all-features :( agl-demo agl-pipewire agl-app-framework agl-netboot ) + # For the usual demo image + agl-app-framework # Application Framework + agl-archiver # Source Archiver + agl-buildstats # Build Statistics + agl-devel :( agl-package-management ) # Developer Env (root login) + agl-fossdriver # Fossology integration + agl-gplv2 # GPLv2-only packages + agl-localdev # inclusion of local development folder + agl-netboot # network boot (e.g. CI) + agl-package-management # include package management (e.g. rpm) + agl-pipewire # include pipewire + agl-ptest # enable ptest pckages + agl-refhw-h3 # enable reference hardware + agl-virt # EG-Virt features + agl-virt-guest-xen # EG-Virt features + agl-virt-xen :( agl-virt ) # EG-Virt features + agl-weston-remoting :( agl-demo agl-pipewire agl-app-framework ) + agl-weston-waltham-remoting :( agl-demo agl-pipewire agl-app-framework ) + + [meta-agl-demo] # DEMO layer + agl-cluster-demo-support :( agl-weston-remoting agl-demo agl-pipewire agl-app-framework ) + # sample IVI demo + agl-demo :( agl-pipewire agl-app-framework ) # default IVI demo + agl-demo-preload # Add Tokens and sample files + + [meta-agl-devel] # Development layer + agl-basesystem # Toyota basesystem + agl-drm-lease # DRM lease support + agl-egvirt # EG-Virt feature + agl-flutter # Flutter support + agl-jailhouse # GSoC: jailhouse enablement + agl-lxc :( agl-drm-lease agl-pipewire ) # IC-EG container support + agl-ros2 # GSoC: ros2 enablement + +Specialized features (e.g. CI): + agl-ci # Tweaks for CI + agl-ci-change-features :( agl-demo agl-pipewire agl-app-framework agl-devel agl-package-management agl-netboot agl-pipewire agl-buildstats agl-ptest ) + agl-ci-change-features-nogfx :( agl-demo agl-pipewire agl-app-framework agl-devel agl-package-management agl-netboot agl-pipewire agl-buildstats agl-ptest ) + agl-ci-snapshot-features :( agl-demo agl-pipewire agl-app-framework agl-devel agl-package-management agl-netboot agl-archiver agl-pipewire agl-buildstats agl-ptest ) + agl-ci-snapshot-features-nogfx :( agl-demo agl-pipewire agl-app-framework agl-devel agl-package-management agl-netboot agl-archiver agl-pipewire agl-buildstats agl-ptest ) + +``` + +To find out exactly what a feature provides, check out the respective layer and its README. + +An AGL feature is a configuration that accounts for specific settings +and dependencies needed for a particular build. +For example, specifying the "agl-demo" feature makes sure that the +`aglsetup.sh` script creates configuration files needed to build the +image for the AGL demo. + +Following are brief descriptions of the AGL features you can specify on the +`aglsetup.sh` command line: + +* **agl-all-features**: A set of AGL default features. + Do not think of this set of features as all the AGL features. + +* **agl-app-framework**: Application Framework + +* **agl-archiver**: Enables the archiver class for releases. + +* **agl-ci**: Flags used for Continuous Integration (CI). + Using this feature changes the value of the + [`IMAGE_FSTYPES`](https://yoctoproject.org/docs/3.1.4/ref-manual/ref-manual.html#var-IMAGE_FSTYPES) + variable. + +* **agl-ci-change-features**: Enables features for CI builds for Gerrit changes. + +* **agl-ci-change-features-nogfx**: Enables features for CI builds for Gerrit changes + for targets that use binary graphics drivers (i.e. builds without graphics). + +* **agl-ci-snapshot-features**: Enables features for CI daily snapshot builds. + +* **agl-ci-snapshot-features-nogfx**: Enables features for CI daily snapshot builds for + targets that use binary graphics drivers (i.e. builds without graphics). + +* **agl-devel**: Activates development options such as an empty root password, + debuggers, strace, valgrind, and so forth. + +* **agl-netboot**: Enables network boot support through Trivial File Transfer Protocol (TFTP) and Network Block Device (NBD) protocol. + Netboot is needed for CI and useful for development to avoid writing + sdcards. Needs additional setup. + +* **agl-ptest**: Enables + [Ptest](https://yoctoproject.org/docs/3.1.4/dev-manual/dev-manual.html#testing-packages-with-ptest) + as part of the build. + +* **agl-demo**: Enables the layers meta-agl-demo and meta-qt5. + You need agl-demo if you are going to build the agl-demo-platform. + +* **agl-pipewire**: Enables AGLs pipewire support. + +* **agl-localdev**: Adds a local layer named "meta-localdev" in the + meta directory and a local.dev.inc configuration file when that file + is present. + + This feature provides a shortcut for using the layer meta-localdev + in the top-level folder for easy modifications to your own recipes. + +## Example + +Following is an example that initializes the build environment, selects "beaglebone" +for the machine, and chooses the "agl-demo" feature, which also includes the +"agl-appfw-smack", "agl-devel", and "agl-hmi-framework" features: + +```sh +$ source meta-agl/scripts/aglsetup.sh -m qemux86-64 -b qemux86-64 agl-demo agl-devel +aglsetup.sh: Starting +Generating configuration files: + Build dir: /home/scottrif/workspace_agl/build + Machine: qemux86-64 + Features: agl-appfw-smack agl-demo agl-devel + Running /home/scottrif/workspace_agl/poky/oe-init-build-env + Templates dir: /home/scottrif/workspace_agl/meta-agl/templates/base + Config: /home/scottrif/workspace_agl/build/conf/bblayers.conf + Config: /home/scottrif/workspace_agl/build/conf/local.conf + Setup script: /home/scottrif/workspace_agl/build/conf/setup.sh + Executing setup script ... --- beginning of setup script + fragment /home/scottrif/workspace_agl/meta-agl/templates/base/01_setup_EULAfunc.sh + fragment /home/scottrif/workspace_agl/meta-agl/templates/base/99_setup_EULAconf.sh + end of setup script +OK +Generating setup file: /home/scottrif/workspace_agl/build/agl-init-build-env ... OK +aglsetup.sh: Done + Shell environment set up for builds. +You can now run 'bitbake target' +Common targets are: + - meta-agl: (core system) + agl-image-minimal + agl-image-minimal-qa + + agl-image-ivi + agl-image-ivi-qa + agl-image-ivi-crosssdk + + agl-image-weston + + - meta-agl-demo: (demo with UI) + agl-demo-platform (* default demo target) + agl-demo-platform-qa + agl-demo-platform-crosssdk + agl-demo-platform-html5 +``` + +Running the script creates the Build Directory if it does not already exist. +The default Build Directory is `$AGL_TOP//build`, and the nomenclature to be used throughout this doc is going to be `$AGL_TOP//` +For this example, the Build Directory is `$AGL_TOP/master/qemux86-64`. + +The script's output also indicates the machine and AGL features selected for the build. + +The script creates two primary configuration files used for the build: `local.conf` and `bblayers.conf`. +Both these configuration files are located in the Build Directory in the `conf` folder. +If you were to examine these files, you would find standard Yocto Project +configurations along with AGL configuration fragments, which are driven by the +machine (i.e. beaglebone) and the AGL features specified as part of the +script's command line. + +The end result is configuration files specific for your build in the AGL development environment. + +Finally, part of the `aglsetup.sh` script makes sure that any End User License Agreements (EULA) +are considered. +You can see that processing in the script's output as well. + +**NOTE:** Use of the `local.conf` and `bblayers.conf` configuration files is fundamental +in the Yocto Project build environment. +Consequently, it is fundamental in the AGL build environment. +You can find lots of information on configuring builds in the Yocto Project +documentation set. +Here are some references if you want to dig into configuration further: + +* [Customizing Images Using local.conf](https://yoctoproject.org/docs/3.1.4/dev-manual/dev-manual.html#usingpoky-extend-customimage-localconf) +* [Local](https://yoctoproject.org/docs/3.1.4/ref-manual/ref-manual.html#ref-varlocality-config-local) +* [build/conf/local.conf](https://yoctoproject.org/docs/3.1.4/ref-manual/ref-manual.html#structure-build-conf-local.conf) +* [build/conf/bblayers.conf](https://yoctoproject.org/docs/3.1.4/ref-manual/ref-manual.html#structure-build-conf-bblayers.conf) +* [BBLAYERS](https://yoctoproject.org/docs/3.1.4/ref-manual/ref-manual.html#var-BBLAYERS) +* [User Configuration](https://yoctoproject.org/docs/3.1.4/ref-manual/ref-manual.html#user-configuration) +* [Enabling Your Layer](https://yoctoproject.org/docs/3.1.4/dev-manual/dev-manual.html#enabling-your-layer) diff --git a/docs/1_Getting_Started/2_Building_AGL_Image/5_Customizing_Your_Build.md b/docs/1_Getting_Started/2_Building_AGL_Image/5_Customizing_Your_Build.md new file mode 100644 index 0000000..1c30ddd --- /dev/null +++ b/docs/1_Getting_Started/2_Building_AGL_Image/5_Customizing_Your_Build.md @@ -0,0 +1,151 @@ +--- +title: Customizing Your Build +--- + +Because the build process is based on BitBake and the Yocto Project, +build customizations are driven through configuration files used during +the build. + +Lots of configuration files exist that define a build. +However, the primary one that acts as a global configuration mechanism is the +`local.conf` file, which is found in the Build Directory in a folder named "conf". + +Before you start your build process, you should open up the `local.conf` file +and look through it to be sure the general configurations are correct. +The file is well commented so you should be able to understand what the +various variables accomplish. + +To view and customize the `local.conf` file, use any text editor: + +```sh +$ vim $AGL_TOP///conf/local.conf +``` + +As mentioned in the "[Initializing Your Build Environment](./3_Initializing_Your_Build_Environment.md)" section, +the `local.conf` file gets augmented with AGL configuration fragments based on +how you execute the `aglsetup.sh` script. +You can see those fragments at the end the configuration file. + +Even though your build should work fine after running the `aglsetup.sh` script, +you might consider editing your `local.conf` file to use one or more of the +following configurations. + +## Capturing Build History + +You can enable build history to help maintain the quality of your build output. +You can use it to highlight unexpected and possibly unwanted changes in the build output. +Basically, with build history enabled, you get a record of information about the contents +of each package and image. +That information is committed to a local Git repository where you can examine it. + +To enable build history, make sure the following two lines are in your +`local.conf` file: + +```sh +INHERIT += "buildhistory" +BUILDHISTORY_COMMIT = "1" +``` + +See the +"[Maintaining Build Output Quality](https://www.yoctoproject.org/docs/3.1.4/ref-manual/ref-manual.html#maintaining-build-output-quality)" +section in the Yocto Project Reference Manual for a complete discussion on +build history. + +## Deleting Temporary Workspace + +During a build, the build system uses a lot of disk space to store temporary files. +You can ease the burden on your system and speed up the build by configuring the build +to remove temporary workspace. + +You need to inherit the `rm_work` class by using this statement in the `local.conf` file: + +```sh +INHERIT += "rm_work" +``` + +You can read about the class in the +"[rm_work.bbclass](https://www.yoctoproject.org/docs/3.1.4/ref-manual/ref-manual.html#ref-classes-rm-work)" +section of the Yocto Project Reference Manual for more information. + +## Pointing at Shared State Cache Locations + +The build system creates everything from scratch unless BitBake can determine that parts do not need to be rebuilt. Fundamentally, building from scratch is attractive as it means all parts are built fresh and there is no possibility of stale data causing problems. +When developers hit problems, they typically default back to building from scratch so they know the state +of things from the start. + +The build process uses Shared State Cache (sstate) to speed up subsequent builds. +This cache retains artifacts that can be re-used once it is determined that they +would not be different as compared to a re-built module. + +For the AGL build, you can specify the location for sstate files by including the +following in the `local.conf` file: + +```sh +SSTATE_DIR = "${AGL_TOP}/sstate-cache" +``` + +Also, in the `local.conf` file, you can specify additional directories in which the build +system can look for shared state information. +Use the following form in your file to list out the directories you want the build +process to look at for sstate information: + +```sh +SSTATE_MIRRORS ?= "\ + file://.* http://someserver.tld/share/sstate/PATH;downloadfilename=PATH \n \ + file://.* file:///some/local/dir/sstate/PATH" +``` + +If you want to know more about the Yocto Project sstate mechanism, see the +"[Shared State Cache](https://www.yoctoproject.org/docs/3.1.4/ref-manual/ref-manual.html#shared-state-cache)" +section in the Yocto Project Reference Manual. + +## Preserving the Download Directory + +During the initial build, the system downloads many different source code tarballs +from various upstream projects. +Downloading these files can take a while, particularly if your network +connection is slow. +The process downloads files into a +"[download directory](https://www.yoctoproject.org/docs/3.1.4/ref-manual/ref-manual.html#var-DL_DIR)". +The `DL_DIR` variable defines the download directory. +For subsequent builds, you can preserve this directory to speed up the download +part of a build. + +The default download directory is in a folder named "downloads". +For the AGL build you can set the download directory by adding the following to your +`local.conf` file: + +```sh +DL_DIR = "${AGL_TOP}/downloads" +``` + +## Using a Shared State (sstate) Mirror + +The underlying Yocto Project build system uses Shared State Mirrors to cache +artifacts from previous builds. +You can significantly speed up builds and guard against fetcher failures by +using mirrors. +To use mirrors, add this line to your `local.conf` file in the Build directory: + +```sh +SSTATE_MIRRORS_append = " file://.* https://download.automotivelinux.org/sstate-mirror/master/${DEFAULTTUNE}/PATH \n " +``` + +You can learn more about shared state and how it is used in the +"[Shared State Cache](https://yoctoproject.org/docs/3.1.4/ref-manual/ref-manual.html#shared-state-cache)" +section of the Yocto Project Reference Manual. + +## Common Settings using Symbolic Link with site.conf + +```sh +$ echo "# reuse download directories" >> $AGL_TOP/site.conf +$ echo "DL_DIR = \"$HOME/downloads/\"" >> $AGL_TOP/site.conf +$ echo "SSTATE_DIR = \"$AGL_TOP/sstate-cache/\"" >> $AGL_TOP/site.conf +$ cd $AGL_TOP/master/qemux86-64/ +$ ln -sf $AGL_TOP/site.conf conf/ + +In General; +$ cd $AGL_TOP/// +$ ln -sf $AGL_TOP/site.conf conf/ +``` + diff --git a/docs/1_Getting_Started/2_Building_AGL_Image/6_Building_the_AGL_Image.md b/docs/1_Getting_Started/2_Building_AGL_Image/6_Building_the_AGL_Image.md new file mode 100644 index 0000000..1573b56 --- /dev/null +++ b/docs/1_Getting_Started/2_Building_AGL_Image/6_Building_the_AGL_Image.md @@ -0,0 +1,21 @@ +--- +title: Building the AGL Image +--- + +Building the AGL image involves running BitBake with a specified target. +Depending on whether you are building the image for the first time or if this +is a subsequent build, the time needed for the build could be significant. + +It is critical that you specify the correct options and configurations for the +build before executing the `bitbake` command. +The previous sections in the "Image Development Workflow" have treated this setup +in a generic fashion. AGL has both `Qt` based and `HTML5` based IVI demos, where in the build process is almost the same except few changes in the build enviroment. + +This section, provides links to topics with instructions needed to create images for +three types of supported platforms and for emulation/virtualization using Quick +EMUlator (QEMU) or VirtualBox: + +* [x86 (Emulation and Hardware)](./5_1_x86_Emulation_and_Hardware.md) +* [Raspberry Pi 4](./5_2_Raspberry_Pi_4.md) +* [R Car Gen 3](./5_3_RCar_Gen_3.md) +* [virtio](./5_4_Virtio.md) diff --git a/docs/1_Getting_Started/2_Building_AGL_Image/7_x86_Emulation_and_Hardware.md b/docs/1_Getting_Started/2_Building_AGL_Image/7_x86_Emulation_and_Hardware.md new file mode 100644 index 0000000..871179f --- /dev/null +++ b/docs/1_Getting_Started/2_Building_AGL_Image/7_x86_Emulation_and_Hardware.md @@ -0,0 +1,255 @@ +--- +title: Building for x86 (Emulation and Hardware) +--- + +Building an image for emulation allows you to simulate your +image without actual target hardware. + +This section describes the steps you need to take to build the +AGL demo image for emulation using either Quick EMUlator (QEMU) or +VirtualBox, and later the same image can be used to boot any hardware. + +## 1. Making Sure Your Build Environment is Correct + +The +"[Initializing Your Build Environment](./3_Initializing_Your_Build_Environment.md)" +section presented generic information for setting up your build environment +using the `aglsetup.sh` script. +If you are building the AGL demo image for emulation, you need to specify some +specific options when you run the script: + +**Sample Qt based IVI demo :** + +```sh +$ source meta-agl/scripts/aglsetup.sh -f -m qemux86-64 -b qemux86-64 agl-demo agl-devel +$ echo "# reuse download directories" >> $AGL_TOP/site.conf +$ echo "DL_DIR = \"$HOME/downloads/\"" >> $AGL_TOP/site.conf +$ echo "SSTATE_DIR = \"$AGL_TOP/sstate-cache/\"" >> $AGL_TOP/site.conf +$ ln -sf $AGL_TOP/site.conf conf/ +``` + +**Sample HTML5 based IVI demo :** + +```sh +$ source meta-agl/scripts/aglsetup.sh -f -m qemux86-64 -b qemux86-64 agl-demo agl-devel agl-profile-graphical-html5 +$ echo "# reuse download directories" >> $AGL_TOP/site.conf +$ echo "DL_DIR = \"$HOME/downloads/\"" >> $AGL_TOP/site.conf +$ echo "SSTATE_DIR = \"$AGL_TOP/sstate-cache/\"" >> $AGL_TOP/site.conf +$ ln -sf $AGL_TOP/site.conf conf/ +``` + +**IVI-EG Flutter based demo :** + +```sh +$ source meta-agl/scripts/aglsetup.sh -f -m qemux86-64 -b qemux86-64 agl-flutter agl-devel +$ echo "# reuse download directories" >> $AGL_TOP/site.conf +$ echo "DL_DIR = \"$HOME/downloads/\"" >> $AGL_TOP/site.conf +$ echo "SSTATE_DIR = \"$AGL_TOP/sstate-cache/\"" >> $AGL_TOP/site.conf +$ ln -sf $AGL_TOP/site.conf conf/ +``` + +**IC-EG container image :** +```sh +### TBD +``` + +**Virt-EG demo image :** +```sh +### TBD +``` + +The "-m" option specifies the "qemux86-64" machine. +The list of AGL features used with script are appropriate for development of +the AGL demo image suited for either QEMU or VirtualBox. + +## 2. Using BitBake + +Start the build using the `bitbake` command. + +**NOTE:** An initial build can take many hours depending on your +CPU and and Internet connection speeds. +The build also takes approximately 100G-bytes of free disk space. + +**Sample Qt based IVI demo :** +The target is `agl-demo-platform`. + +```sh +$ time bitbake agl-demo-platform +``` + +By default, the build process puts the resulting image in the Build Directory and further exporting that as `$IMAGE_NAME`: + +```sh +/tmp/deploy/images/qemux86-64/agl-demo-platform-qemux86-64.vmdk.xz + +$ export IMAGE_NAME=agl-demo-platform-qemux86-64.vmdk.xz +``` + +**Sample HTML5 based IVI demo :** +The target is `agl-demo-platform-html5`. + +```sh +$ time bitbake agl-demo-platform-html5 +``` + +By default, the build process puts the resulting image in the Build Directory and further exporting that as `$IMAGE_NAME`: + +```sh +/tmp/deploy/images/qemux86-64/agl-demo-platform-html5-qemux86-64.vmdk.xz + +$ export IMAGE_NAME=agl-demo-platform-html5-qemux86-64.vmdk.xz +``` + +**IVI-EG Flutter based demo :** +The target is `agl-image-flutter`. + +```sh +$ time bitbake agl-image-flutter +``` + +**IC-EG container image :** +```sh +# TBD +``` + +**Virt-EG demo image :** +```sh +# TBD +``` + +## 3. Deploying the AGL Demo Image + +Deploying the image consists of decompressing the image and then +booting it using either QEMU, VirtualBox or physical system. +The examples below are usually for the 'agl-demo-platform' target. +Please adapt accordingly to your target image. + +**3.1 QEMU** + +Depending on your Linux distribution, use these commands to install QEMU: + +If you built your image with bitbake, you can now just use the ``runqemu`` wrapper, after sourcing `agl-init-build-env` inside the build-dir : + +For this example : + +```sh +$ source $AGL_TOP/master/qemux86-64/agl-init-build-env +``` + +In general : + +```sh +$ source $AGL_TOP/// +``` + +And further use `runqemu` to boot the image : + +```sh +$ runqemu tmp/deploy/images/qemux86-64/agl-demo-platform-qemux86-64.qemuboot.conf kvm serialstdio slirp publicvnc audio +``` + +If you need to run it outside of the bitbake environment or need special settings for +hardware pass-through using `qemu` : + + +**NOTE:** if you have created an AGL crosssdk, it will contain a +QEMU binary for the build host. +This SDK QEMU binary does not support graphics. +Consequently, you cannot use it to boot the AGL image and +need to call your host's qemu binary instead. + +**NOTE:** the VM images need UEFI in the emulator to boot. Thus you need +to install the necessary files with below commands (ovmf). + +If your build host is running +[Arch Linux](https://www.archlinux.org/), use the following commands: + +```sh +sudo pacman -S qemu ovmf +export OVMF_PATH=/usr/share/ovmf/x64/OVMF_CODE.fd +``` + +If your build host is running Debian or Ubuntu, use the following commands: + +```sh +sudo apt-get install qemu-system-x86 ovmf +export OVMF_PATH=/usr/share/ovmf/OVMF.fd +``` + +If you build host is running Fedora, use the following commands: + +```sh +sudo yum install qemu qemu-kvm edk2-ovmf +export OVMF_PATH=/usr/share/edk2/ovmf/OVMF_CODE.fd +``` + +**Note:** + +Once QEMU is installed, boot the image with KVM support: + +```sh +qemu-system-x86_64 -enable-kvm -m 2048 \ + -bios ${OVMF_PATH} \ + -hda ${IMAGE_NAME} \ + -cpu kvm64 -cpu qemu64,+ssse3,+sse4.1,+sse4.2,+popcnt \ + -vga virtio -show-cursor \ + -device virtio-rng-pci \ + -serial mon:stdio -serial null \ + -soundhw hda \ + -net nic \ + -net user,hostfwd=tcp::2222-:22 +``` + +**NOTE:** KVM may not be supported within a virtualized environment such as +VirtualBox. This is indicated by the qemu command above giving the error +message `Could not access KVM kernel module: No such file or directory` or +the kernel log output contains the error message `kvm: no hardware support`. +The image can be booted in such an environment by removing `-enable-kvm` from +the qemu command line, however this will result in lower perfromance within +the AGL demo. + +**3.2 VirtualBox** + +Once VirtualBox is installed, follow these steps to boot the image: + + 1. Install and set up [Virtual Box](https://www.virtualbox.org/wiki/Linux_Downloads). + + 2. Extract the vmdk file : + + ```sh + cd tmp/deploy/images/qemux86-64 + xz -d ${IMAGE_NAME} + ``` + + 3. Configure virtual box for AGL : + - Click on `New` or `Add`. + - Enter Name as `agl-demo`. + - Type as `Linux`. + - Version as `Other Linux (64-bit)`, click on `Next`. + ![vbox-step-1](images/vbox-1.png) + - Select Memory size. Recommended is `2048 MB`, click on `Next`. + ![vbox-step-2](images/vbox-2.png) + - Click on `Use an existing virtual hard disk file`, and select the extracted `agl-demo-platform-qemux86-64.vmdk.xz` or `` file, click on `Create`. + ![vbox-step-3](images/vbox-3.png) + - Go to `Settings`, and into `System`. Select `Chipset : IHC9`. Check on `Enable EFI (special OSes only)` and click on `OK`. + ![vbox-step-4](images/vbox-4.png) + - Go to `Storage`, and change the attribute to `Type : AHCI` and click on `OK`. + ![vbox-step-5](images/vbox-5.png) + - Click on `Start`. + - For troubleshooting, you can refer [here](https://lists.automotivelinux.org/g/agl-dev-community/message/8474). + +**3.3 x86 physical system** + + **NOTE :** UEFI enabled system is required. + + 1. Extract the image into USB drive : + + ```sh + $ cd tmp/deploy/images/qemux86-64 + $ lsblk + $ sudo umount + $ xzcat agl-demo-platform-qemux86-64.wic.xz | sudo dd of= bs=4M + $ sync + ``` + + 2. Boot from USB drive on the x86 system. \ No newline at end of file diff --git a/docs/1_Getting_Started/2_Building_AGL_Image/8_Raspberry_Pi_4.md b/docs/1_Getting_Started/2_Building_AGL_Image/8_Raspberry_Pi_4.md new file mode 100644 index 0000000..e08a51e --- /dev/null +++ b/docs/1_Getting_Started/2_Building_AGL_Image/8_Raspberry_Pi_4.md @@ -0,0 +1,204 @@ +--- +title: Building for Raspberry Pi 4 +--- + +The +[Raspberry Pi](https://www.raspberrypi.org/help/what-%20is-a-raspberry-pi/) is a small computer that is ideal for learning computing and computer languages. +The AGL Project supports building images for the +[Raspberry Pi 4](https://www.raspberrypi.org/products/raspberry-pi-4-model-b/) board. +These board comes in a variety of models. +See the +[Raspberry Pi Product Page](https://www.raspberrypi.org/products/) for more information. + +This section describes the steps you need to take to build the +AGL demo image for the Raspberry Pi 4 board. + +## 1. Making Sure Your Build Environment is Correct + +The +"[Initializing Your Build Environment](./3_Initializing_Your_Build_Environment.md)" +section presented generic information for setting up your build environment +using the `aglsetup.sh` script. +If you are building the AGL demo image for a Raspberry Pi 4 board, you need to specify some +specific options when you run the script : + +**Qt based IVI demo :** + + ```sh + $ source meta-agl/scripts/aglsetup.sh -f -m raspberrypi4 -b raspberrypi4 agl-demo agl-devel + $ echo "# reuse download directories" >> $AGL_TOP/site.conf + $ echo "DL_DIR = \"$HOME/downloads/\"" >> $AGL_TOP/site.conf + $ echo "SSTATE_DIR = \"$AGL_TOP/sstate-cache/\"" >> $AGL_TOP/site.conf + $ ln -sf $AGL_TOP/site.conf conf/ + ``` + +**HTML5 based IVI demo :** + + ```sh + $ source meta-agl/scripts/aglsetup.sh -f -m raspberrypi4 -b raspberrypi4 agl-demo agl-devel agl-profile-graphical-html5 + $ echo "# reuse download directories" >> $AGL_TOP/site.conf + $ echo "DL_DIR = \"$HOME/downloads/\"" >> $AGL_TOP/site.conf + $ echo "SSTATE_DIR = \"$AGL_TOP/sstate-cache/\"" >> $AGL_TOP/site.conf + $ ln -sf $AGL_TOP/site.conf conf/ + ``` + +In each case, the "-m" option specifies the machine and the list of AGL features used with script are appropriate for development of +the AGL demo image suited for Raspberry Pi 4. + +## 2. Configuring the Build to Include Packages Under a Commercial License + +Before launching the build, it is good to be sure your build +configuration is set up correctly (`/build/conf/local.conf` file). +The "[Customizing Your Build](./4_Customizing_Your_Build.md)" +section highlights some common configurations that are useful when +building any AGL image. + +For the Raspberry Pi platforms, you need to take an additional +configuration step if you want to include any packages under a +commercial license. + +For example, suppose you want to include an implementation of the +[OpenMAX](https://www.khronos.org/openmax/) Intagration Library +(`libomxil`) under a commercial license as part of your AGL image. +If so, you must include the following two lines in your +`/build/conf/local.conf` file: + +```sh +# For libomxil +LICENSE_FLAGS_WHITELIST = "commercial" +IMAGE_INSTALL_append = "libomxil" +``` + +## 3. Using BitBake + +This section shows the `bitbake` command used to build the AGL image. + +Start the build using the `bitbake` command. + +**NOTE:** An initial build can take many hours depending on your +CPU and and Internet connection speeds. +The build also takes approximately 100G-bytes of free disk space. + +**Qt Based IVI demo :** +The target is `agl-demo-platform`. + +```sh +$ time bitbake agl-demo-platform +``` + +By default, the build process puts the resulting image in the Build Directory and further exporting that as `$IMAGE_NAME`. +Here is example for the Raspberry Pi 4 board for Qt Based demo: + +```sh +/tmp/deploy/images/raspberrypi4/agl-demo-platform-raspberrypi4.wic.xz + +$ export IMAGE_NAME=agl-demo-platform-raspberrypi4.wic.xz +``` + +**HTML5 Based IVI demo :** +The target is `agl-demo-platform-html5`. + +```sh +$ time bitbake agl-demo-platform-html5 +``` + +By default, the build process puts the resulting image in the Build Directory and further exporting that as `$IMAGE_NAME`. +Here is example for the Raspberry Pi 4 board for HTML5 Based demo: + +```sh +/tmp/deploy/images/raspberrypi4/agl-demo-platform-html5-raspberrypi4-64.wic.xz + +$ export IMAGE_NAME=agl-demo-platform-html5-raspberrypi4-64.wic.xz +``` + +## 4. Deploying the AGL Demo Image + +Deploying the AGL demo image consists of copying the image on a MicroSD card, +plugging the card into the Raspberry Pi board, and then booting the board. + +Follow these steps to copy the image to a MicroSD card and boot +the image on the Raspberry Pi 4 board: + + 1. Plug your MicroSD card into your Build Host (i.e. the system that has your build output). + + 2. Extract the image into the SD card of Raspberry Pi 4 : + + **NOTE:** For Raspberry Pi 4, the image is at `/tmp/deploy/images/raspberrypi4/${IMAGE_NAME}`. + + Be sure you are root, provide the actual device name for *sdcard_device_name*, and the actual image name for *image_name*. + + ```sh + $ lsblk + $ sudo umount + $ xzcat ${IMAGE_NAME} | sudo dd of= bs=4M + $ sync + ``` + + **IMPORTANT NOTE:** Before re-writing any device on your Build Host, you need to + be sure you are actually writing to the removable MicroSD card and not some other + device. + Each computer is different and removable devices can change from time to time. + Consequently, you should repeat the previous operation with the MicroSD card to + confirm the device name every time you write to the card. + + To summarize this example so far, we have the following: + The first SATA drive is `/dev/sda` and `/dev/sdc` corresponds to the MicroSD card, and is also marked as a removable device.You can see this in the output of the `lsblk` command where "1" appears in the "RM" column for that device. + + 3. SSH into Raspberry Pi : + - Connect Raspberry Pi to network : `Homescreen > Settings`, IP address mentioned here. + - SSH : + + ```sh + $ ssh root@ + ``` + + 4. Serial Debugging : + + When things go wrong, you can take steps to debug your Raspberry Pi. + For debugging, you need a 3.3 Volt USB Serial cable to fascilitate + communication between your Raspberry Pi board and your build host. + + You can reference the following diagram for information on the following steps: + + ![](images/RaspberryPi2-ModelB-debug-serial-cable.png) + + 1. Connect the TTL cable to the Universal Asynchronous Receiver-Transmitter + (UART) connection on your Raspberry Pi board. + Do not connect the USB side of the cable to your build host at this time. + + **CAUTION:** No warranty is provided using the following procedure. + Pay particular attention to the collors of your cable as they could + vary depending on the vendor. + + 2. Connect the cable's BLUE wire to pin 6 (i.e. Ground) of the UART. + + 3. Connect the able's GREEN RX line to pin 8 (i.e. the TXD line) of + the UART. + + 4. Connect the cable's RED TX line to pin 10 (i.e. the RXD line) of + the UART. + + 5. Plug the USB connector of the cable into your build host's USB port. + + 6. Use your favorite tool for serial communication between your build host + and your Raspberry Pi. + For example, if your build host is a native Linux machine (e.g. Ubuntu) + you could use `screen` as follows from a terminal on the build host: + + ```sh + $ sudo screen /dev/ttyUSB0 115200 + ``` + +5. SOTA + + Follow the step below to build AGL for Raspberry Pi with enabled software over + the air (SOTA) updates: + + 1. Include **agl-sota** feature. + + 2. In **bblayers.conf** replace meta-updater-qemux86-64 with + **meta-updater-raspberrypi**. + + 3. In **local.conf** set `SOTA_PACKED_CREDENTIALS` and `OSTREE_BRANCHNAME`. + + More details are available [here](https://docs.ota.here.com/getstarted/dev/raspberry-pi.html). \ No newline at end of file diff --git a/docs/1_Getting_Started/2_Building_AGL_Image/9_RCar_Gen_3.md b/docs/1_Getting_Started/2_Building_AGL_Image/9_RCar_Gen_3.md new file mode 100644 index 0000000..33fc50a --- /dev/null +++ b/docs/1_Getting_Started/2_Building_AGL_Image/9_RCar_Gen_3.md @@ -0,0 +1,894 @@ +--- +title: Building for Supported Renesas Boards +--- + +AGL supports building for several automotive +[Renesas](https://www.renesas.com/us/en/solutions/automotive.html) board kits. +Renesas is the number one supplier of vehicle control microcontrollers and +System on a Chip (SoC) products for the automotive industry. + +This section provides the build and deploy steps you need to create an +image for the following Renesas platforms: + +* [Renesas R-Car Starter Kit Pro Board](https://www.elinux.org/R-Car/Boards/M3SK) +* [Renesas R-Car Starter Kit Premier Board](https://www.elinux.org/R-Car/Boards/H3SK) +* [Renesas Salvator-X Board](https://www.elinux.org/R-Car/Boards/Salvator-X) +* [Renesas Kingfisher Infotainment Board](https://elinux.org/R-Car/Boards/Kingfisher) + +**NOTE:** You can find similar information for the Pro and Premier board kits on the +[R-Car/Boards/Yocto-Gen3](https://elinux.org/R-Car/Boards/Yocto-Gen3) page on [elinux.org](https://elinux.org). +The information on this page describes setup and build procedures for both of these +Renesas development kits. + +Additionally, the AGL Reference Hardware platform is based on the same Renesas +H3 processor used on the Renesas R-Car Starter Kit Premier and Salvator-X boards, +so support for it leverages the Starter Kit Premier (also known as "h3ulcb") +build. +For more information on the AGL reference hardware platform, please refer to its +[manual](https://wiki.automotivelinux.org/_media/eg-rhsa/rh_manual_ver.1.0.pdf), +or the Reference Hardware System Architecture Expert Group +[wiki page](https://wiki.automotivelinux.org/eg-rhsa). + +## 1. Prepare your build + +### 1.1 Downloading Proprietary Drivers + +Before setting up the build environment, you need to download proprietary drivers from the +[R-Car H3/M3 Software library and Technical document](https://www.renesas.com/us/en/application/automotive/r-car-h3-m3-documents-software) +site. + +Follow these steps to download the drivers you need: + +1. **Determine the Files You Need:** + + Run the ``setup_mm_packages.sh`` script as follows to + display the list of ZIP files containing the drivers you need. + Following is an example: + + ```sh + grep -rn ZIP_.= $AGL_TOP/meta-agl/meta-agl-bsp/meta-rcar-gen3/scripts/setup_mm_packages.sh + ``` + + The script's output identifies the files you need to download from the page. + +2. **Get Your Board Support Package (BSP) Version:** + + Be sure to have the correct BSP version of the R-Car Starter Kit + based on the version of the AGL software you are using. + Find the appropriate download links on the + [R-Car H3/M3 Software library and Technical document](https://www.renesas.com/us/en/application/automotive/r-car-h3-m3-documents-software) + site. + The file pairs are grouped according to the Yocto Project version you are + using with the AGL software. + + Use the following table to map the Renesas version to your AGL software: + + | AGL Version | Renesas version | + |:-:|:-:| + | AGL master | 5.9.0 | + +3. **Download the Files:** + + Start the download process by clicking the download link. + If you do not have an account with Renesas, you will be asked to register a free account. + You must register and follow the "Click Through" licensing process + in order to download these proprietary files. + + If needed, follow the instructions to create the free account by providing the required + account information. + Once the account is registered and you are logged in, you can download the files. + + **NOTE:** You might have to re-access the + [original page](https://www.renesas.com/us/en/application/automotive/r-car-h3-m3-documents-software) + that contains the download links you need after creating the account and logging in. + +4. **Create an Environment Variable to Point to Your Download Area:** + + Create and export an environment variable named `XDG_DOWNLOAD_DIR` that points to + your download directory. + Here is an example: + + ```sh + export XDG_DOWNLOAD_DIR=$HOME/Downloads + ``` + +5. **Be Sure the Files Have Rights:** + + Be sure you have the necessary rights for the files you downloaded. + You can use the following command: + + ```sh + chmod a+rw $XDG_DOWNLOAD_DIR/*.zip + ``` + +6. **Check to be Sure the Files are Downloaded and Have the Correct Rights:** + + Do a quick listing of the files to ensure they are in the download directory and + they have the correct access rights. + Here is an example: + + ```sh + $ ls -l $XDG_DOWNLOAD_DIR/*.zip + -rw-rw-r-- 1 scottrif scottrif 4662080 Nov 19 14:48 /home/scottrif/Downloads/R-Car_Gen3_Series_Evaluation_Software_Package_for_Linux-weston8-20200923.zip + -rw-rw-r-- 1 scottrif scottrif 3137626 Nov 19 14:49 /home/scottrif/Downloads/R-Car_Gen3_Series_Evaluation_Software_Package_of_Linux_Drivers-weston8-20200923.zip + ``` + +### 1.2. Getting More Software + +1. **Get the `bmaptool`:** + + Download this tool from the + [bmap-tools](https://build.opensuse.org/package/show/isv:LinuxAutomotive:AGL_Master/bmap-tools) + repository. + The site has pre-built packages (DEB or RPM) for the supported host + operating systems. + +### 1.3. Getting Your Hardware Together + +Gather together this list of hardware items, which is not exhaustive. +Having these items ahead of time saves you from having to try and +collect hardware during development: + +* Supported Starter Kit Gen3 board with its 5V power supply. +* Micro USB-A cable for serial console. + This cable is optional if you are using Ethernet and an SSH connection. +* USB 2.0 Hub. The hub is optional but makes it easy to connect multiple USB devices. +* Ethernet cable. The cable is optional if you are using a serial console. +* HDMI type D (Micro connector) cable and an associated display. +* 4 Gbyte minimum MicroSD Card. It is recommended that you use a class 10 type. +* USB touch screen device such as the GeChic 1502i/1503i. A touch screen device is optional. + +**NOTE:** The Salvator-X Board has NDA restrictions. +Consequently, less documentation is available for this board both here and across the +Internet. + +### 1.4. Making Sure Your Build Environment is Correct + +The +"[Initializing Your Build Environment](./3_Initializing_Your_Build_Environment.md)" +section presented generic information for setting up your build environment +using the `aglsetup.sh` script. +If you are building an image for a supported Renesas board, +you need to take steps to make sure your build host is set up correctly. + +1. **Define Your Board:** + + Depending on your Renesas board, define and export a `MACHINE` variable as follows: + + | Board | `MACHINE` Setting | + |:-:|:-:| + | Starter Kit Pro/M3 | `MACHINE`=m3ulcb | + | Starter Kit Pro/M3 + kingfisher support | `MACHINE`=m3ulcb-kf | + | Starter Kit Pro/M3 without graphic driver (using pixman) | `MACHINE`=m3ulcb-nogfx | + | Starter Kit Premier/H3 | `MACHINE`=h3ulcb | + | Starter Kit Premier/H3 + kingfisher support | `MACHINE`=h3ulcb-kf | + | Starter Kit Premier/H3 without graphic driver (using pixman) | `MACHINE`=h3ulcb-nogfx | + | Salvator-X | `MACHINE`=h3-salvator-x | + | AGL Reference Hardware | `MACHINE`=h3ulcb | + | AGL Reference Hardware without graphic driver (using pixman) | `MACHINE`=h3ulcb-nogfx | + + For example, the following command defines and exports the `MACHINE` variable + for the Starter Kit Premier/H3 Board: + + ```sh + export MACHINE=h3ulcb + ``` + +### 1.5. **Run the `aglsetup.sh` Script:** + +Use the following commands to run the AGL Setup script: + +```sh +cd $AGL_TOP +source meta-agl/scripts/aglsetup.sh -m $MACHINE -b build agl-devel agl-demo +``` + +**NOTE:** +To avoid useless download and rebuild, it's important to set the variable DL_DIR and SSTATE_DIR in your configuration. + +```sh +echo "# reuse download directories" >> $AGL_TOP/site.conf +echo "DL_DIR = \"$HOME/downloads/\"" >> $AGL_TOP/site.conf +echo "SSTATE_DIR = \"$AGL_TOP/sstate-cache/\"" >> $AGL_TOP/site.conf +ln -sf $AGL_TOP/site.conf conf/ +``` + +**Reference Hardware :** + +If building for the AGL Reference Hardware (with `MACHINE` set to "h3ulcb" or +"h3ulcb-nogfx"), add `agl-refhw-h3`, for example: + +```sh +cd $AGL_TOP +source meta-agl/scripts/aglsetup.sh -m $MACHINE -b build agl-devel agl-demo agl-refhw-h3 +``` + +**HTML5 based IVI demo :** + +For HTML5 based IVI demo the feature "agl-profile-graphical-html5" is needed. + +```sh +$ source meta-agl/scripts/aglsetup.sh -f -m $MACHINE -b $MACHINE agl-demo agl-devel agl-profile-graphical-html5 +``` + +**Instrument Cluster with Container isolation demo :** + +```sh +$ source meta-agl/scripts/aglsetup.sh -f -m $MACHINE -b $MACHINE agl-lxc +``` + +**NOTE:** +You can check if your logs match what is expected in the [troubleshooting section](#4-troubleshooting). + +Running the `aglsetup.sh` script automatically places you in the +working directory (i.e. `$AGL_TOP/build`). +You can change this default behavior by adding the "-f" option to the +script's command line. + +In the previous command, the "-m" option sets your machine to the previously +defined `MACHINE` variable. +The "-b" option defines your Build Directory, which is the +default `$AGL_TOP/build`. +Finally, the AGL features are provided to support building the AGL Demo image +for the Renesas board. + +You can learn more about the AGL Features in the +"[Initializing Your Build Environment](./3_Initializing_Your_Build_Environment.md)" +section. + +## 2. Using BitBake + +This section shows the `bitbake` command used to build the AGL image. +Before running BitBake to start your build, it is good to be reminded that AGL +does provide pre-built images for developers that work with supported hardware. +You can find these pre-built images on the +[AGL Download web site](https://download.automotivelinux.org/AGL/release). + +Start the build using the `bitbake` command. + +**NOTE:** An initial build can take many hours depending on your +CPU and and Internet connection speeds. +The build also takes approximately 100G-bytes of free disk space. + +**Qt based IVI demo :** +For this example, the target is "agl-demo-platform": + +```sh +bitbake agl-demo-platform +``` + +**HTML5 based IVI demo :** +The target is `agl-demo-platform-html5`. + +```sh +$ time bitbake agl-demo-platform-html5 +``` + +**Instrument Cluster with Container isolation demo :** +The target is `lxc-host-image-demo`. + +```sh +$ time bitbake lxc-host-image-demo +``` + +The build process puts the resulting image in the Build Directory: + +```sh +/tmp/deploy/images/$MACHINE +``` + +## 3. Deploying the AGL Demo Image + +To boot your image on the Renesas board, you need to do three things: + +1. [Update all firmware on the board.](#4-troubleshooting) +2. Prepare the MicroSD card to you can boot from it. +3. Boot the board. + +**NOTE:** For subsequent builds, you only have to re-write the MicroSD +card with a new image. + +### 3.1. Booting the Image Using a MicroSD Card + +1. Preparing the MicroSD Card + + Plug the MicroSD card into your Build Host. + After plugging in the device, use the `dmesg` command as follows to + discover the device name: + + ```sh + $ dmesg | tail -4 + [ 1971.462160] sd 6:0:0:0: [sdc] Mode Sense: 03 00 00 00 + [ 1971.462277] sd 6:0:0:0: [sdc] No Caching mode page found + [ 1971.462278] sd 6:0:0:0: [sdc] Assuming drive cache: write through + [ 1971.463870] sdc: sdc1 sdc2 + ``` + + In the previous example, the MicroSD card is attached to the device `/dev/sdc`. + You can also use the `lsblk` command to show all your devices. + Here is an example that shows the MicroSD card as `/dev/sdc`: + + ```sh + $ lsblk + NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT + sda 8:0 0 167,7G 0 disk + ├─sda1 8:1 0 512M 0 part /boot/efi + ├─sda2 8:2 0 159,3G 0 part / + └─sda3 8:3 0 7,9G 0 part [SWAP] + sdb 8:16 0 931,5G 0 disk + └─sdb1 8:17 0 931,5G 0 part /media/storage + sdc 8:32 1 14,9G 0 disk + ├─sdc1 8:33 1 40M 0 part + └─sdc2 8:34 1 788M 0 part + ``` + + **IMPORTANT NOTE:** Before re-writing any device on your Build Host, you need to + be sure you are actually writing to the removable MicroSD card and not some other + device. + Each computer is different and removable devices can change from time to time. + Consequently, you should repeat the previous operation with the MicroSD card to + confirm the device name every time you write to the card. + + To summarize this example so far, we have the following: + + * The first SATA drive is `/dev/sda`. + + * `/dev/sdc` corresponds to the MicroSD card, and is also marked as a removable device. + You can see this in the output of the `lsblk` command where "1" appears in the "RM" column + for that device. + + Now that you have identified the device you are going to be writing the image on, + you can use the `bmaptool` to copy the image to the MicroSD card. + + Your desktop system might offer a choice to mount the MicroSD automatically + in some directory. + For this example, assume that the MicroSD card mount directory is stored in the + `$SDCARD` variable. + + Following are example commands that write the image to the MicroSD card: + + ```sh + cd $AGL_TOP/build/tmp/deploy/images/$MACHINE + bmaptool copy ./agl-demo-platform-$MACHINE.wic.xz + ``` + + Alternatively, you can leave the image in an uncompressed state and write it + to the MicroSD card: + + ```sh + sudo umount + xzcat ./agl-demo-platform-$MACHINE.wic.xz | sudo dd of= bs=4M + sync + ``` + +2. Booting the Board + + Follow these steps to boot the board: + + 1. Use the board's power switch to turn off the board. + + 2. Insert the MicroSD card into the board. + + 3. Verify that you have plugged in the following: + + * An external monitor into the board's HDMI port + + * An input device (e.g. keyboard, mouse, touchscreen, and so forth) into the board's USB ports. + + 4. Use the board's power switch to turn on the board. + + After a few seconds, you will see the AGL splash screen on the display and you + will be able to log in at the console's terminal or using the graphic screen. + +### 3.2. Setting Up the Serial Console + +Setting up the Serial Console involves the following: + +* Installing a serial client on your build host +* Connecting your build host to your Renesas board's serial port +* Powering on the board to get a shell at the console +* Configuring U-Boot parameters +* Logging into the console +* Determining the board's IP address + +1. Installing a Serial Client on Your Build Host + + You need to install a serial client on your build host. + Some examples are: + + * [GNU Screen](https://en.wikipedia.org/wiki/GNU_Screen) + * [picocom](https://linux.die.net/man/8/picocom) + * [Minicom](https://en.wikipedia.org/wiki/Minicom) + + Of these three, "picocom" has the least dependencies and is therefore + considered the "lightest" solution. + +2. Connecting Your Build Host to Your Renesas Board's Serial Port + + You need to physically connect your build host to the Renesas board using + a USB cable from the host to the serial CP2102 USP port (i.e. Micro USB-A port) + on the Renesas board. + + Once you connect the board, determine the device created for the serial link. + Use the ``dmesg`` command on your build host. + Here is an example: + + ```sh + dmesg | tail 9 + [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 + [2097783.385862] usb 2-1.5.3: New USB device strings: Mfr=1, Product=2, SerialNumber=3 + [2097783.385864] usb 2-1.5.3: Product: FT232R USB UART + [2097783.385866] usb 2-1.5.3: Manufacturer: FTDI + [2097783.385867] usb 2-1.5.3: SerialNumber: AK04WWCE + [2097783.388288] ftdi_sio 2-1.5.3:1.0: FTDI USB Serial Device converter detected + [2097783.388330] usb 2-1.5.3: Detected FT232RL + [2097783.388658] usb 2-1.5.3: FTDI USB Serial Device converter now attached to ttyUSB0 + ``` + + The device created is usually "/dev/ttyUSB0". + However, the number might vary depending on other USB serial ports connected to the host. + + To use the link, you need to launch the client. + Here are three commands, which vary based on the serial client, that show + how to launch the client: + + ```sh + picocom -b 115200 /dev/ttyUSB0 + ``` + + or + + ```sh + minicom -b 115200 -D /dev/ttyUSB0 + ``` + + or + + ```sh + screen /dev/ttyUSB0 115200 + ``` + +3. Powering on the Board to Get a Shell at the Console + + Both the Pro and Premier kits (e.g. + [m3ulcb](https://elinux.org/R-Car/Boards/M3SK) and + [h3ulcb](https://elinux.org/R-Car/Boards/H3SK#Hardware)) have nine + switches (SW1 through SW9). + To power on the board, "short-press" SW8, which is the power switch. + + Following, is console output for the power on process for each kit: + + **h3ulcb**: + + ```text + 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 + NOTICE: BL2: DDR1600(rev.0.15) + NOTICE: BL2: DRAM Split is 4ch + NOTICE: BL2: QoS is Gfx Oriented(rev.0.30) + NOTICE: BL2: AVS setting succeeded. DVFS_SetVID=0x52 + NOTICE: BL2: Lossy Decomp areas + NOTICE: Entry 0: DCMPAREACRAx:0x80000540 DCMPAREACRBx:0x570 + NOTICE: Entry 1: DCMPAREACRAx:0x40000000 DCMPAREACRBx:0x0 + NOTICE: Entry 2: DCMPAREACRAx:0x20000000 DCMPAREACRBx:0x0 + NOTICE: BL2: v1.1(release):41099f4 + NOTICE: BL2: Built : 19:20:52, Jun 9 2016 + NOTICE: BL2: Normal boot + NOTICE: BL2: dst=0xe63150c8 src=0x8180000 len=36(0x24) + NOTICE: BL2: dst=0x43f00000 src=0x8180400 len=3072(0xc00) + NOTICE: BL2: dst=0x44000000 src=0x81c0000 len=65536(0x10000) + NOTICE: BL2: dst=0x44100000 src=0x8200000 len=524288(0x80000) + NOTICE: BL2: dst=0x49000000 src=0x8640000 len=1048576(0x100000) + + + U-Boot 2015.04 (Jun 09 2016 - 19:21:52) + + CPU: Renesas Electronics R8A7795 rev 1.1 + Board: H3ULCB + I2C: ready + DRAM: 3.9 GiB + MMC: sh-sdhi: 0, sh-sdhi: 1 + In: serial + Out: serial + Err: serial + Net: Board Net Initialization Failed + No ethernet found. + Hit any key to stop autoboot: 0 + => + ``` + +### 3.3. Setting-up U-boot + +Configuring U-Boot Parameters + +Follow these steps to configure the board to use the MicroSD card as the +boot device and also to set the screen resolution: + +1. As the board is powering up, press any key to stop the autoboot process. +You need to press a key quickly as you have just a few seconds in which to +press a key. + +2. Once the autoboot process is interrupted, use the board's serial console to +enter `printenv` to check if you have correct parameters for booting your board: + + Here is an example using the **h3ulcb** board: + + ```sh + => 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/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 + ``` + +3. To boot your board using the MicroSD card, be sure your environment is set up +as follows: + + ```sh + setenv bootargs console=ttySC0,115200 ignore_loglevel vmalloc=384M video=HDMI-A-1:1920x1080-32@60 root=/dev/mmcblk1p1 rw rootfstype=ext4 rootwait rootdelay=2 + setenv bootcmd run load_ker\; run load_dtb\; booti 0x48080000 - 0x48000000 + setenv load_ker ext4load mmc 0:1 0x48080000 /boot/Image + ``` + +4. Loading dtb : + + **NOTE** : Refer [here](https://elinux.org/R-Car/Boards/Yocto-Gen3-CommonFAQ/Which_dtb_file_is_required_to_boot_linux_on_the_R-Car_Starter_Kit_board_%3F) for more information. + + Make sure your ``load_dtb`` is set as follows : + + | Renesas Boards | DTB Name | + |:-:|:-:| + | **H3SK v2.0(DDR 4GB)** | r8a7795-h3ulcb.dtb | + | **H3SK v2.0(DDR 8GB)/v3.0(DDR 8GB)** | r8a7795-h3ulcb-4x2g.dtb | + | **M3SK v1.0** | r8a7796-m3ulcb.dtb | + | **M3SK v3.0** | r8a7796-m3ulcb-2x4g.dtb | + | **H3SK with a Kingfisher board** | r8a7795-h3ulcb-kf.dtb | + | **M3SK with a Kingfisher board** | r8a7796-m3ulcb-kf.dtb | + | **AGL Reference Hardware board** | r8a7795-agl-refhw.dtb | + + ```sh + setenv load_dtb ext4load mmc 0:1 0x48000000 /boot/r8a7795-h3ulcb-kf.dtb + ``` + +5. Save the boot environment: + + ```sh + saveenv + ``` + +6. Boot the board: + + ```sh + run bootcmd + ``` + +## 4. Troubleshooting + +### 4.1. Checking Your Configuration + +Aside from environment variables and parameters you establish through +running the `aglsetup.sh` script, you can ensure your build's configuration +is just how you want it by examining the `local.conf` configuration file. + +You can find this configuration file in the Build Directory (e.g. +`$TOP_DIR/build/conf/local.conf`). + +In general, the defaults along with the configuration fragments the +`aglsetup.sh` script applies in the `local.conf` file are good enough. +However, you can customize aspects by editing the `local.conf` file. +See the +"[Customizing Your Build](4_Customizing_Your_Build.md)" +section for common configurations you might want to consider. + +**NOTE:** For detailed explanations of the configurations you can make +in the ``local.conf`` file, consult the +[Yocto Project Documentation](https://www.yoctoproject.org/docs/). + +A quick way to see if you have the `$MACHINE` variable set correctly +is to use the following command: + +```sh +grep -w -e "^MACHINE =" $AGL_TOP/build/conf/local.conf +``` + +Depending on the Renesas board you are using, you should see output +as follows: + +```sh +MACHINE = "h3ulcb" +``` + +or + +```sh +MACHINE = "m3ulcb" +``` + +or + +```sh +MACHINE = "h3-salvator-x" +``` + +If you ran the `aglsetup.sh` script as described in the +"[Making Sure Your Build Environment is Correct](./5_3_RCar_Gen_3.md#4-making-sure-your-build-environment-is-correct)" +section earlier, the "agl-devel", "agl-demo", "agl-netboot", "agl-appfw-smack", and +"agl-localdev" AGL features will be in effect. +These features provide the following: + +* 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 such as USB and bluetooth +* Support for the AGL demo platform +* Network boot support through TFTP and NBD protocols +* [IoT.bzh](https://iot.bzh/en/) Application Framework plus +[SMACK](https://en.wikipedia.org/wiki/Smack_(software)) and +[Cynara](https://wiki.tizen.org/Security:Cynara) +* Support for local development including `localdev.inc` when present + +### 4.2. Check the Script's Log: + +Running the `aglsetup.sh` script creates the `setup.log` file, which is in +the `build/conf` folder. +You can examine this log to see the results of the script. +For example, suppose the graphics drivers were missing or could not be extracted +when you ran the script. +In case of missing graphics drivers, you could notice an error message +similar to the following: + +```text +[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 +The graphics and multimedia acceleration packages for +the R-Car Gen3 board can be downloaded from: +https://www.renesas.com/en-us/solutions/automotive/rcar-demoboard-2.html + +These 2 files from there should be store in your'/home/devel/Downloads' directory. + R-Car_Gen3_Series_Evaluation_Software_Package_for_Linux-weston8-20200923.zip + R-Car_Gen3_Series_Evaluation_Software_Package_of_Linux_Drivers-weston8-20200923.zip +/home/working/workspace_agl_master/build_gen3 +--- fragment /home/working/workspace_agl_master/meta-agl/templates/base/99_setup_EULAconf.sh +--- end of setup script +OK +Generating setup file: /home/working/workspace_agl_master/build_gen3/agl-init-build-env ... OK +------------ aglsetup.sh: Done +[snip] +``` + +If you encounter this issue, or any other unwanted behavior, you can fix the error +mentioned, remove the `$AGL_TOP/build` directory, and then re-launch the +`aglsetup.sh` again. + +Here is another example that indicates the driver files could not be extracted from the downloads directory: + +```text +~/workspace_agl/build/conf $ cat setup.log +--- beginning of setup script +--- fragment /home/working/workspace_agl/meta-agl/templates/base/01_setup_EULAfunc.sh +--- fragment /home/working/workspace_agl/meta-agl/templates/machine/h3ulcb/50_setup.sh +~/workspace_agl ~/workspace_agl/build +ERROR: FILES "+/home/working/Downloads/R-Car_Gen3_Series_Evaluation_Software_Package_for_Linux-weston8-20200923.zip+" NOT EXTRACTING CORRECTLY +ERROR: FILES "+/home/working/Downloads/R-car_Gen3_Series_Evaluation_Software_Package_of_Linux_Drivers-weston8-20200923.zip+" NOT EXTRACTING CORRECTLY +The graphics and multimedia acceleration packages for +the R-Car Gen3 board BSP can be downloaded from: + + +These 2 files from there should be stored in your +'/home/working/Downloads' directory. + R-Car_Gen3_Series_Evaluation_Software_Package_for_Linux-weston8-20200923.zip + R-Car_Gen3_Series_Evaluation_Software_Package_of_Linux_Drivers-weston8-20200923.zip +ERROR: Script /home/working/workspace_agl/build/conf/setup.sh failed +[snip] +``` + +### 4.3. Updating the Board's Firmware + +Follow these steps to update the firmware: + +1. **Update the Sample Loader and MiniMonitor:** + + You only need to make these updates one time per device. + + Follow the procedure found on the + eLinux.org wiki to update to at least version 3.02, + which is mandatory to run the AGL image + ([R-car loader update](https://elinux.org/R-Car/Boards/Kingfisher#How_to_update_of_Sample_Loader_and_MiniMonitor)). + +2. **Update the Firmware Stack:** + + You only need to update the firmware stack if you are + using the Eel or later (5.0) version of AGL software. + + M3 and H3 Renesas board are AArch64 platforms. + As such, they have a firmware stack that is divided across: **ARM Trusted Firmware**, **OP-Tee** and **U-Boot**. + + If you are using the Eel (5.0) version or later of the AGL software, you must update + the firmware using the **[h3ulcb] [R-car h3ulcb firmware update](http://elinux.org/R-Car/Boards/H3SK#Flashing_firmware)** + or **[m3ulcb] [R-car m3ulcb firmware update](https://elinux.org/R-Car/Boards/M3SK#Flashing_firmware)** links from the + [Embedded Linux Wiki](https://www.elinux.org/Main_Page) (i.e. `elinux.org`). + + The table in the wiki lists the files you need to flash the firmware. + You can find these files in the following directory: + + ```sh + $AGL_TOP/build/tmp/deploy/images/$MACHINE + ``` + + **NOTE:** The Salvator-X firmware update process is not documented on eLinux. + **NOTE:** The AGL Reference Hardware board generally should not require a + firmware update to be usable, and has a slightly different update procedure. + If you do need to update the firmware, the procedure is documented + [here](https://git.automotivelinux.org/AGL/meta-agl-refhw/tree/meta-agl-refhw-gen3/docs/ReferenceHW_Rcar_gen3.md). + +### 4.4. Logging Into the Console + +Once the board boots, you should see the +[Wayland display](https://en.wikipedia.org/wiki/Wayland_(display_server_protocol)) +on the external monitor. +A login prompt should appear as follows depending on your board: + +**h3ulcb** or **AGL Reference Hardware**: + +```text +Automotive Grade Linux ${AGL_VERSION} h3ulcb ttySC0 + +h3ulcb login: root +``` + +At the prompt, login by using `root` as the login. +The password is "empty" so you should not be prompted for the password. + +### 4.5. Determining the Board's IP Address + +If your board is connected to a local network using Ethernet and +if a DHCP server is able to distribute IP addresses, +you can determine the board's IP address and log in using `ssh`. + +Here is an example for the **h3ulcb** board: + +```sh +h3ulcb login: root +Last login: Tue Dec 6 09:55:15 UTC 2016 on tty2 +root@h3ulcb:~# ip -4 a +1: lo: mtu 65536 qdisc noqueue state UNKNOWN group default + inet 127.0.0.1/8 scope host lo + valid_lft forever preferred_lft forever +3: eth0: mtu 1500 qdisc pfifo_fast state UP group default qlen 1000 + inet 10.0.0.27/24 brd 10.0.0.255 scope global eth0 + valid_lft forever preferred_lft forever +root@h3ulcb:~# +``` + +In the previous example, IP address is 10.0.0.27. +Once you know the address, you can use `ssh` to login. +Following is an example that shows logging into SSH and then +displaying the contents of the `/etc/os-release` file: + +```sh +$ ssh root@10.0.0.27 +Last login: Tue Dec 6 10:01:11 2016 from 10.0.0.13 +root@h3ulcb:~# cat /etc/os-release +ID="poky-agl" +NAME="Automotive Grade Linux" +VERSION="11.0.0+snapshot-20210128 (koi)" +VERSION_ID="11.0.0-snapshot-20210128" +PRETTY_NAME="Automotive Grade Linux 11.0.0+snapshot-20210128 (koi)" +``` + +## 5. Supplementary Information + +### 5.1. R-Car Generation 3 Information + +Refer to the [R-Car](https://elinux.org/R-Car) page on the +[elinux.org](https://elinux.org) website for more information. + +### 5.2. Proprietary libraries for meta-rcar-gen3 + +The meta-rcar-gen3 layer of meta-renesas supports Graphic GLES(GSX) +libraries, proprietary multimedia libraries, and ICCOM software. + +### 5.3. Build with Renesas multimedia libraries + +Multimedia portions depend on GLES portions. + +* A. Configuration for Multimedia features + + * Please copy proprietary libraries to the directory of recipes. + + * Please set local.conf the following. + + **Enable multimedia features. This provides package group of plug-ins of the GStreamer, multimedia libraries and kernel drivers.** + + ```sh + MACHINE_FEATURES:append = " multimedia" + ``` + +* B. Configuration for optional codecs and middleware + + * Please copy proprietary libraries to the directory of recipes. + + * Add features to `DISTRO_FEATURES:append` to local.conf + + **Additional configuration in OMX module**: + + ```text + " h263dec_lib" - for OMX Media Component H263 Decoder Library + " h264dec_lib" - for OMX Media Component H264 Decoder Library + " h264enc_lib" - for OMX Media Component H.264 Encoder Library + " h265dec_lib" - for OMX Media Component H265 Decoder Library + " mpeg2dec_lib" - for OMX Media Component MPEG2 Decoder Library + " mpeg4dec_lib" - for OMX Media Component MPEG4 Decoder Library + " vc1dec_lib" - for OMX Media Component VC-1 Decoder Library + " divxdec_lib" - for OMX Media Component DivX Decoder Library + " rvdec_lib" - for OMX Media Component RealVideo Decoder Library + " alacdec_lib" - for OMX Media Component ALAC Decoder Library + " flacdec_lib" - for OMX Media Component FLAC Decoder Library + " aaclcdec_lib" - for OMX Media Component AAC-LC Decoder Library + " aaclcdec_mdw" - for AAC-LC 2ch Decoder Middleware for Linux + " aacpv2dec_lib" - for OMX Media Component aacPlus V2 Decoder Library + " aacpv2dec_mdw" - for aacPlus V2 Decoder Middleware for Linux + " mp3dec_lib" - for OMX Media Component MP3 Decoder Library + " mp3dec_mdw" - for MP3 Decoder Middleware for Linux + " wmadec_lib" - for OMX Media Component WMA Standard Decoder Library + " wmadec_mdw" - for WMA Standard Decoder Middleware for Linux + " dddec_lib" - for OMX Media Component Dolby(R) Digital Decoder Library + " dddec_mdw" - for Dolby(R) Digital Decoder Middleware for Linux + " aaclcenc_lib" - for OMX Media Component AAC-LC Encoder Library + " vp8dec_lib" - for OMX Media Component VP8 Decoder Library for Linux + " vp8enc_lib" - for OMX Media Component VP8 Encoder Library for Linux + " vp9dec_lib" - for OMX Media Component VP9 Decoder Library for Linux + " aaclcenc_mdw" - for AAC-LC Encoder Middleware for Linux + " cmsbcm" - for CMS Basic Color Management Middleware for Linux + " cmsblc" - for CMS CMM3 Backlight Control Middleware for Linux + " cmsdgc" - for CMS VSP2 Dynamic Gamma Correction Middleware for Linux + " dtv" - for ISDB-T DTV Software Package for Linux + " dvd" - for DVD Core-Middleware for Linux + " adsp" - for ADSP driver, ADSP interface and ADSP framework for Linux + " avb" - for AVB Software Package for Linux + ``` + + Example: + + ```sh + DISTRO_FEATURES:append = " h264dec_lib h265dec_lib mpeg2dec_lib aaclcdec_lib aaclcdec_mdw" + ``` + +* C. Configuration for test packages + + Must ensure that Multimedia features have been enabled. + (Please refer to III/A to enable Multimedia.) + + * Please add feature to `DISTRO_FEATURES:append` to local.conf. + + **Configuration for multimedia test package** + + ```sh + DISTRO_FEATURES:append = " mm-test" + ``` + +### 5.4. Enable Linux ICCOM driver and Linux ICCOM library + +For Linux ICCOM driver and Linux ICCOM library + +* Please copy proprietary libraries to the directory of recipes. + +* Please set the following in local.conf: + + ```sh + DISTRO_FEATURES:append = "iccom" + ``` diff --git a/docs/1_Getting_Started/2_Building_AGL_Image/A_Virtio.md b/docs/1_Getting_Started/2_Building_AGL_Image/A_Virtio.md new file mode 100644 index 0000000..3a55fb2 --- /dev/null +++ b/docs/1_Getting_Started/2_Building_AGL_Image/A_Virtio.md @@ -0,0 +1,151 @@ +--- +title: Building for virtio +--- + +Virtio is a standartized interface for implementing virtual I/O devices: + +* Russell, Rusty. "virtio: towards a de-facto standard for virtual I/O devices." ACM SIGOPS Operating Systems Review 42.5 (2008): 95-103. + +This section describes the steps you need to take to build the AGL demo image +for virtio "platform". Later, the same image can be run on various emulators or +hypervisors that provide virtio devices, for example, QEMU aarch64 emulation on +PC, QEMU/KVM aarch64 virtualization on AGL Reference Hardware, etc. + +Below, AGL minimal image and Qt based IVI demo are used as example, but +similiarly one can run HTML5 based demos, cluster demo, or other AGL images. + +## 1. Making Sure Your Build Environment is Correct + +The +"[Initializing Your Build Environment](./3_Initializing_Your_Build_Environment.md)" +section presented generic information for setting up your build environment +using the `aglsetup.sh` script. +If you are building the AGL demo image for virtio platform, you need to specify +some specific options when you run the script: + +```sh +$ source meta-agl/scripts/aglsetup.sh -m virtio-aarch64 -b build-virtio-aarch64 agl-demo +``` + +The "-m" option specifies the "virtio-aarch64" machine. + +The "-b" option sets custom build directory instead of default "build". + +The "-f" option might be added to override previously available configuration. +By default, if there were already configuration files in build directory, they +will not be overriden, as result, aglsetup.sh might not have desired effect. + +## 2. Using BitBake + +This section shows the `bitbake` command used to build the AGL image. + +Start the build using the `bitbake` command. + +**AGL minimal image :** +The target is `agl-image-minimal`. + +```sh +$ bitbake agl-image-minimal +``` + +**Qt Based IVI demo :** +The target is `agl-demo-platform`. + +```sh +$ bitbake agl-demo-platform +``` + +## 3. Deploying the AGL Demo Image + +This subsection describes AGL virtio-aarch64 image deployment under virtio +platform provided by QEMU aarch64 emulator on PC, or QEMU/KVM hypervisor on AGL +Reference Hardware board. + +**3.1 QEMU on PC** + +If shell from which AGL was built is closed, or new shell is opened, then it is +needed to re-initialize build environment: + +```sh +$ source $AGL_TOP/build-virtio-aarch64/agl-init-build-env +``` + +And further use `runqemu` to boot the image : + +```sh +$ runqemu +``` + +**3.2 QEMU/KVM on AGL Reference Hardware** + +Follow these steps to run virtual AGL on bare-metal AGL (AGL-in-AGL) on AGL Reference Hardware board: + + 1. Partition eMMC or SD-Card to have two partitions, at least 1 GiB each. + Actually, can be less but just rounded up to have a nice number. + + 2. Flash AGL minimal image root file system to the second partition on SD-Card + or eMMC. + + 3. Build AGL minimal image for AGL Reference Hardware. + + ```sh + source meta-agl/scripts/aglsetup.sh -m h3ulcb -b build-h3ulcb agl-refhw-h3 + ``` + + In `build-h3ulcb/conf/local.conf` add + + ``` + AGL_DEFAULT_IMAGE_FSTYPES = "ext4" + IMAGE_INSTALL_append = "qemu" + ``` + + CAUTION: Calling aglsetup.sh with "-f" flag will remove above modification + in "local.conf", so they will be needed to be re-applied. + + Build image: + + ```sh + bitbake agl-image-minimal + ``` + + Add virtio kernel to the AGL Reference Hardware Linux rootfs: + + ```sh + cp build-virtio-aarch64/tmp/deploy/images/virtio-aarch64/Image build-h3ulcb/tmp/work/h3ulcb-agl-linux/agl-image-minimal/1.0-r0/rootfs/linux2 + bitbake agl-image-minimal -c image_ext4 -f + bitbake agl-image-minimal -c image_complete + ``` + + Flash root file system to the first partition on SD-Card or eMMC. + + 4. Boot AGL Reference Hardware board using Linux located on the first partition of SD-Card or eMMC. + + 5. Run QEMU from Linux 1 command line + + ```sh + qemu-system-aarch64 \ + -machine virt \ + -cpu cortex-a57 \ + -m 2048 \ + -serial mon:stdio \ + -global virtio-mmio.force-legacy=false \ + -drive id=disk0,file=/dev/mmcblk0p2,if=none,format=raw \ + -device virtio-blk-device,drive=disk0 \ + -object rng-random,filename=/dev/urandom,id=rng0 \ + -device virtio-rng-device,rng=rng0 \ + -nographic \ + -kernel /linux2 + -append 'root=/dev/vda rw mem=2048M' + ``` + + NOTE: mmcblk0p2 above is used for when root file system is flashed on eMMC. + In case of SD-Card, mmcblk1p2 has to be used. + + 6. It is possible to exit from QEMU using monitor commands. Enter "Ctrl+a h" for help. + +Know issue: to enable hardware virtualization using KVM, option `-enable-kvm` +could be added to QEMU command line, but it fails with: + +``` +qemu-system-aarch64: kvm_init_vcpu failed: Invalid argument +``` diff --git a/docs/1_Getting_Started/2_Building_AGL_Image/images/RaspberryPi2-ModelB-debug-serial-cable.png b/docs/1_Getting_Started/2_Building_AGL_Image/images/RaspberryPi2-ModelB-debug-serial-cable.png new file mode 100644 index 0000000..f4374d0 Binary files /dev/null and b/docs/1_Getting_Started/2_Building_AGL_Image/images/RaspberryPi2-ModelB-debug-serial-cable.png differ diff --git a/docs/1_Getting_Started/2_Building_AGL_Image/images/image-developer-workflow.png b/docs/1_Getting_Started/2_Building_AGL_Image/images/image-developer-workflow.png new file mode 100644 index 0000000..a185dc6 Binary files /dev/null and b/docs/1_Getting_Started/2_Building_AGL_Image/images/image-developer-workflow.png differ diff --git a/docs/1_Getting_Started/2_Building_AGL_Image/images/vbox-1.png b/docs/1_Getting_Started/2_Building_AGL_Image/images/vbox-1.png new file mode 100644 index 0000000..a43c111 Binary files /dev/null and b/docs/1_Getting_Started/2_Building_AGL_Image/images/vbox-1.png differ diff --git a/docs/1_Getting_Started/2_Building_AGL_Image/images/vbox-2.png b/docs/1_Getting_Started/2_Building_AGL_Image/images/vbox-2.png new file mode 100644 index 0000000..d4e1dd0 Binary files /dev/null and b/docs/1_Getting_Started/2_Building_AGL_Image/images/vbox-2.png differ diff --git a/docs/1_Getting_Started/2_Building_AGL_Image/images/vbox-3.png b/docs/1_Getting_Started/2_Building_AGL_Image/images/vbox-3.png new file mode 100644 index 0000000..f6389f1 Binary files /dev/null and b/docs/1_Getting_Started/2_Building_AGL_Image/images/vbox-3.png differ diff --git a/docs/1_Getting_Started/2_Building_AGL_Image/images/vbox-4.png b/docs/1_Getting_Started/2_Building_AGL_Image/images/vbox-4.png new file mode 100644 index 0000000..09f7f0b Binary files /dev/null and b/docs/1_Getting_Started/2_Building_AGL_Image/images/vbox-4.png differ diff --git a/docs/1_Getting_Started/2_Building_AGL_Image/images/vbox-5.png b/docs/1_Getting_Started/2_Building_AGL_Image/images/vbox-5.png new file mode 100644 index 0000000..0c3f51b Binary files /dev/null and b/docs/1_Getting_Started/2_Building_AGL_Image/images/vbox-5.png differ diff --git a/docs/1_Getting_Started/3_Build_and_Boot_guide_Profile/1_Instrument_Cluster_(IC-IVI_with_Container_isolation).md b/docs/1_Getting_Started/3_Build_and_Boot_guide_Profile/1_Instrument_Cluster_(IC-IVI_with_Container_isolation).md new file mode 100644 index 0000000..d493f87 --- /dev/null +++ b/docs/1_Getting_Started/3_Build_and_Boot_guide_Profile/1_Instrument_Cluster_(IC-IVI_with_Container_isolation).md @@ -0,0 +1,124 @@ +# Build and Boot AGL Instrument Cluster demo image (IC-IVI with Container isolation) +## Required Equipments +**1) Tested board:** **[Starter Kit Pro/M3](https://elinux.org/R-Car/Boards/M3SK) + [kingfisher support](https://elinux.org/R-Car/Boards/Kingfisher)** + +**2) MicroUSB** + +**3) MicroSD card** +## 0. Host PC environemnt +**Build PC** +Ubuntu OS (Tested version 18.04.6 LTS) + +## 1. Define Your Top-Level Directory + +```bash +export AGL_TOP=$HOME/AGL +mkdir -p $AGL_TOP +``` + +## 2. Download the repo Tool and Set Permissions + +```bash +mkdir -p $HOME/bin +export PATH=$HOME/bin:$PATH +curl https://storage.googleapis.com/git-repo-downloads/repo > $HOME/bin/repo +chmod a+x $HOME/bin/repo +``` + +## 3. Download the AGL Source Files +- **AGL Version:** Magic Marlin +```bash +cd $AGL_TOP +mkdir marlin +export AGL_TOP=$HOME/AGL/marlin +cd $AGL_TOP +git config --global user.email "you@example.com" +git config --global user.name "Your Name" +repo init -b marlin -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo +repo sync +``` +- Optional: Specify the manifest file(marlin_13.0.0.xml) using -m option + +```bash +repo init -b marlin -m marlin_13.0.0.xml -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo +``` +- Optional: Specify the master branch +```bash +repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo +``` + +## 4. Downloading Proprietary Drivers +Downloading Proprietary Drivers from [Renesas-automotive-products](https://www.renesas.com/us/en/products/automotive-products/automotive-system-chips-socs/r-car-h3-m3-documents-software) +- To check the files to download +```bash +grep -rn ZIP_.= $AGL_TOP/meta-agl/meta-agl-bsp/meta-rcar-gen3/scripts/setup_mm_packages.sh +export XDG_DOWNLOAD_DIR=$HOME/Downloads +``` +- Download and copy Proprietary Drivers files (Run commands at downloaded files directory) +```bash +cp R-Car_Gen3_Series_Evaluation_Software_Package_* $XDG_DOWNLOAD_DIR/ +chmod a+rw $XDG_DOWNLOAD_DIR/*.zip +``` +## 5. Define Your Board +- Supporting Starter Kit Pro/M3 + kingfisher Board (For other supported boards, check [Define Your Board](https://docs.automotivelinux.org/en/master/#0_Getting_Started/2_Building_AGL_Image/5_3_RCar_Gen_3/)) +```bash +export MACHINE=m3ulcb-kf +``` +## 6. Run the aglsetup.sh Script +```bash +cd $AGL_TOP +source meta-agl/scripts/aglsetup.sh -f -m $MACHINE -b $MACHINE agl-lxc +``` + +## 7. Using BitBake +```bash +bitbake lxc-host-image-demo +``` +- The build process puts the resulting image in the Build Directory +($AGL_TOP/m3ulcb-kf/tmp/deploy/images/m3ulcb) +## 8.Boot the Board (Deploying the AGL Demo Image) +- To boot your image on the Renesas board, you need to do three things: + +a) Update all [firmware](https://docs.automotivelinux.org/en/marlin/#0_Getting_Started/2_Building_AGL_Image/5_3_RCar_Gen_3/#4-troubleshooting) on R-Car M3 Starter Kit board (Flashing firmware). + +b) Prepare the MicroSD card and Flash image to the MicroSD card using [Etcher](https://www.balena.io/etcher/) + (**image file name:** lxc-host-image-demo-m3ulcb-kf.wic.xz), then insert MicroSD card in the R-Car M3SK. +c) Boot the board. + +1) Use a MicroUSB cable to connect the PC to R-Car Starter Kit Pro (M3ULCB) board CN12 "CPLD/DEBUG" +- Serial settings are 115200 8N1. +- Run any standard terminal emulator program (e.g. minicom). +[Replace **"Device"** with USB tty device name, for example **`/dev/ttyUSB0`**] +```bash +sudo minicom -b 115200 -D "DEVICE" +``` + +- Power on the board +- Quickly hit any key to get into the U-boot command prompt; you should see the following: + ```bash +Hit any key to stop autoboot: 0 => +``` +- Booting image command (for details check [How to boot](https://elinux.org/R-Car/AGL#Instrument_Cluster_with_Container_isolation_demo_image)) + ```bash +ext4load 0x48080000 Image +ext4load 0x48000000 /boot/r8a77961-ulcb-kf.dtb +booti 0x48080000 - 0x48000000 +``` + +# Run SoC board Screen +A) Connect HDMI panel to M3SK(CN4) for **IVI Container** +![IVI](https://elinux.org/images/9/91/Marlin-lxc-Ivi.JPG) + +B) Connect HDMI panel to Kingfisher(CN49)for **Cluster Container** +![IC](https://elinux.org/images/7/76/Marlin-lxc-Cluster.JPG) + + +# Reference webpages + 1. [eLinux](https://elinux.org/R-Car/AGL) + 1. [Kingfisher Board](https://elinux.org/R-Car/Boards/Kingfisher) + 1. [R-Car M3SK](https://elinux.org/R-Car/Boards/M3SK#Flashing_firmware) + 1. [agl reference machines](https://docs.automotivelinux.org/en/master/#1_hardware_support/overview/) + 1. [AGL Tech Day Presenation](https://static.sched.com/hosted_files/agltechday2022/3b/agl-techday-202204.pdf) + 1. [Build AGL Image](https://docs.automotivelinux.org/en/master/#0_Getting_Started/2_Building_AGL_Image/0_Build_Process/) + 1. [Building for Supported Renesas Boards](https://docs.automotivelinux.org/en/master/#0_Getting_Started/2_Building_AGL_Image/5_3_RCar_Gen_3/) + diff --git a/docs/1_Getting_Started/3_Build_and_Boot_guide_Profile/2_Flutter_Instrument_Cluster_(qemu-x86).md b/docs/1_Getting_Started/3_Build_and_Boot_guide_Profile/2_Flutter_Instrument_Cluster_(qemu-x86).md new file mode 100644 index 0000000..47bb4c0 --- /dev/null +++ b/docs/1_Getting_Started/3_Build_and_Boot_guide_Profile/2_Flutter_Instrument_Cluster_(qemu-x86).md @@ -0,0 +1,126 @@ +# Build and Boot AGL Flutter Instrument Cluster demo image made for GSoC + +## 0. Prepare Your Build Host + +- Install the required tools to build an AGL Image. For detailed explanation, check [Preparing Your Build host](https://docs.automotivelinux.org/en/needlefish/#0_Getting_Started/2_Building_AGL_Image/1_Preparing_Your_Build_Host/) + +## 1. Define Your Top-Level Directory + +```bash +$ export AGL_TOP=$HOME/AGL +$ echo 'export AGL_TOP=$HOME/AGL' >> $HOME/.bashrc +$ mkdir -p $AGL_TOP +``` + +## 2. Download the repo Tool and Set Permissions + +```bash +$ mkdir -p $HOME/bin +$ export PATH=$HOME/bin:$PATH +$ echo 'export PATH=$HOME/bin:$PATH' >> $HOME/.bashrc +$ curl https://storage.googleapis.com/git-repo-downloads/repo > $HOME/bin/repo +$ chmod a+x $HOME/bin/repo +``` + +## 3. Download the AGL Source Files +To download the latest **master** branch AGL files, use the following commands: +```bash +$ cd $AGL_TOP +$ mkdir master +$ cd master +$ repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo +$ repo sync +``` + +## 4. Initialize the build environment using aglsetup.sh Script +To initialize the build environment, we must use the setup script. +This script is available here: +```bash +$ $AGL_TOP/master/meta-agl/scripts/aglsetup.sh +``` +Run the script: + +```bash +$ cd $AGL_TOP +$ source master/meta-agl/scripts/aglsetup.sh -b build-flutter-cluster -m qemux86-64 agl-demo agl-devel +``` + +- Here `-b` is used to specify the build directory and `-m` is used to specify the target platform. + +- Running this script, will create a build directory if it does not exist. Default build directory: `$AGL_TOP/master/build-flutter-cluster` +- Default target paltform: `qemux86-64` + +** NOTE: Set the API key in local.conf ** + +- By default navigation will not work, you need to set your openrouteservie API key to the variable `OPENROUTE_API_KEY` in your local.conf +- It is present at `$AGL_TOP/master/build-flutter-cluster/conf/local.conf` + +- Example: Just add `OPENROUTE_API_KEY = "your_openrouteservice_api_key"` to the end of local.conf + + +## 5. Using BitBake + +```bash +$ cd $AGL_TOP/master/build-flutter-cluster +$ source agl-init-build-env +$ bitbake agl-cluster-demo-platform-flutter +``` + +## 6. Deploying the AGL Demo Image +Boot the image using QEMU + +```bash +$ cd $AGL_TOP/master/build-flutter-cluster +$ source agl-init-build-env +$ runqemu kvm serialstdio slirp publicvnc +``` + +## 6. Run the Graphics +To get graphics of the app, you need VNC client like VNC Viewer or Vinagre + +- Open the VNC client +- Enter the server address as `localhost:0` + +That's it, you should get something like this: +![Screenshot](images/flutter_instrument_cluster.png) + +## 7. To start navigation widget +To get the navigation, you need to use `kuksa_viss_client` or `kuksa_vss_init.py` script. + +#### **Using inbuilt `kuksa_vss_init.py` script** + + After running the build, you should get this: + +```bash +Automotive Grade Linux 13.93.0 qemux86-64 ttyS0 + +qemux86-64 login: + +``` + +Login as root + +```bash +qemux86-64 login: root +``` +Now run the script + +```bash +root@qemux86-64:~# /usr/sbin/kuksa_vss_init.py +``` + +#### **Using `kuksa_viss_client`** + +Know more about kuksa_viss_client, [Follow this](https://github.com/eclipse/kuksa.val/tree/master/kuksa_viss_client) + +- Run the kuksa_viss_client +- Authorize using token + +Then + +```bash +Test Client> setValue Vehicle.Cabin.SteeringWheel.Switches.Info true +``` +![Screenshot](images/flutter_instrument_cluster_map.png) + + diff --git a/docs/1_Getting_Started/3_Build_and_Boot_guide_Profile/3_IVI_Flutter_apps.md b/docs/1_Getting_Started/3_Build_and_Boot_guide_Profile/3_IVI_Flutter_apps.md new file mode 100644 index 0000000..6475365 --- /dev/null +++ b/docs/1_Getting_Started/3_Build_and_Boot_guide_Profile/3_IVI_Flutter_apps.md @@ -0,0 +1,78 @@ +# Build and Boot AGL Flutter IVI dashboard demo applications made for GSoC + +## 0. Prepare Your Build Host + +- Install the required tools to build an AGL Image. For detailed explanation, check [Preparing Your Build host](https://docs.automotivelinux.org/en/needlefish/#0_Getting_Started/2_Building_AGL_Image/1_Preparing_Your_Build_Host/) + +## 1. Define Your Top-Level Directory + +```bash +$ export AGL_TOP=$HOME/AGL +$ echo 'export AGL_TOP=$HOME/AGL' >> $HOME/.bashrc +$ mkdir -p $AGL_TOP +``` + +## 2. Download the repo Tool and Set Permissions + +```bash +$ mkdir -p $HOME/bin +$ export PATH=$HOME/bin:$PATH +$ echo 'export PATH=$HOME/bin:$PATH' >> $HOME/.bashrc +$ curl https://storage.googleapis.com/git-repo-downloads/repo > $HOME/bin/repo +$ chmod a+x $HOME/bin/repo +``` + +## 3. Download the AGL Source Files +To download the latest **master** branch AGL files, use the following commands: +```bash +$ cd $AGL_TOP +$ mkdir master +$ cd master +$ repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo +$ repo sync +``` + +## 4. Initialize the build environment using aglsetup.sh Script +To initialize the build environment, we must use the setup script. +This script is available here: +```bash +$ $AGL_TOP/master/meta-agl/scripts/aglsetup.sh +``` +Run the script: + +```bash +$ cd $AGL_TOP +$ source master/meta-agl/scripts/aglsetup.sh -b build-flutter-dashboard -m qemux86-64 agl-demo agl-devel +``` + +- Here `-b` is used to specify the build directory and `-m` is used to specify the target platform. + +- Running this script, will create a build directory if it does not exist. Default build directory: `$AGL_TOP/master/build-flutter-dashboard` +- Default target paltform: `qemux86-64` + +## 5. Using BitBake + +```bash +$ cd $AGL_TOP/build-flutter-dashboard +$ source agl-init-build-env +$ bitbake agl-ivi-demo-platform-flutter +``` + +## 6. Deploying the AGL Demo Image +Boot the image using QEMU + +```bash +$ cd $AGL_TOP/build-flutter-dashboard +$ source agl-init-build-env +$ runqemu kvm serialstdio slirp publicvnc +``` + +## 6. Run the Graphics +To get graphics of the app, you need VNC client like VNC Viewer or Vinagre + +- Open the VNC client +- Enter the server address as `localhost:0` + +That's it, you should get something like this: +![Screenshot](images/ivi_homescreen.PNG) + diff --git a/docs/1_Getting_Started/3_Build_and_Boot_guide_Profile/images/flutter_instrument_cluster.png b/docs/1_Getting_Started/3_Build_and_Boot_guide_Profile/images/flutter_instrument_cluster.png new file mode 100644 index 0000000..23cf19d Binary files /dev/null and b/docs/1_Getting_Started/3_Build_and_Boot_guide_Profile/images/flutter_instrument_cluster.png differ diff --git a/docs/1_Getting_Started/3_Build_and_Boot_guide_Profile/images/flutter_instrument_cluster_map.png b/docs/1_Getting_Started/3_Build_and_Boot_guide_Profile/images/flutter_instrument_cluster_map.png new file mode 100644 index 0000000..8d3a1b2 Binary files /dev/null and b/docs/1_Getting_Started/3_Build_and_Boot_guide_Profile/images/flutter_instrument_cluster_map.png differ diff --git a/docs/1_Getting_Started/3_Build_and_Boot_guide_Profile/images/ivi_homescreen.PNG b/docs/1_Getting_Started/3_Build_and_Boot_guide_Profile/images/ivi_homescreen.PNG new file mode 100644 index 0000000..8fa63e0 Binary files /dev/null and b/docs/1_Getting_Started/3_Build_and_Boot_guide_Profile/images/ivi_homescreen.PNG differ diff --git a/docs/1_Hardware_Support/Overview.md b/docs/1_Hardware_Support/Overview.md deleted file mode 100644 index 56dbd13..0000000 --- a/docs/1_Hardware_Support/Overview.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Supported Hardware ---- - -### Supported Hardware - -AGL makes two types of hardware support available: Reference BSPs and Community BSPs. - -1) **Reference Boards** have Board Support Packages (BSPs) that are maintained by their sponsoring companies and are included in our Jenkins CI system. Reference BSPs have snapshot builds that are made available daily and are fully validated with test results made available for every major AGL release. - -2) **Community Boards** have BSPs that are maintained as a best effort by the AGL community based on upstream BSPs. Community Boards include some of the most-used Hobbyist boards such as older automotive boards. - -The following table briefs about the various hardware platforms, supported by AGL : - -### AGL Reference Boards - -| BOARD | MACHINE | ARCHITECTURE | QUICK START GUIDE| LATEST SNAPSHOT | -|:---------------:|:--------------:|:------------:|:----------------:|:--------------------:| -| QEMU | qemu-x86-64 | x86 |[QEMU Quick Start](https://docs.automotivelinux.org/en/master/#0_Getting_Started/1_Quickstart/Using_Ready_Made_Images/#_top)| [qemu-x86-64](https://download.automotivelinux.org/AGL/snapshots/master/latest/qemux86-64/)| -| | qemu-arm | arm32 | | [qemu-arm](https://download.automotivelinux.org/AGL/snapshots/master/latest/qemuarm/)| -| | qemu-arm64 | arm64 | | [qemu-arm64](https://download.automotivelinux.org/AGL/snapshots/master/latest/qemuarm64/)| -| | | | -| RCar Gen 3 | h3ulcb | arm64 |[RCar Gen 3 Quick Start](https://docs.automotivelinux.org/en/master/#0_Getting_Started/1_Quickstart/Using_Ready_Made_Images/#3-r-car-h3sk-h3ulcb-board)| [h3ulcb-nogfx](https://download.automotivelinux.org/AGL/snapshots/master/latest/h3ulcb-nogfx/)| -| | h3-salvator-x | arm64 | -| | h3-kf | arm64 | -| | m3ulcb | arm64 | -| | m3-salvator-x | arm64 | -| | m3-kf | arm64 | -| | agl-refhw | arm64 | -| | | | -| Raspberry Pi | raspberrypi4 | arm64 |[Raspberry Pi Quick Start](https://docs.automotivelinux.org/en/master/#0_Getting_Started/1_Quickstart/Using_Ready_Made_Images/#2-raspberry-pi-4)|[raspberrypi4](https://download.automotivelinux.org/AGL/snapshots/master/latest/raspberrypi4/)| - -**Note:** Latest stable release source tar and binary for all the boards can be found [here](https://wiki.automotivelinux.org/agl-distro/release-notes#latest_stable_release) - -### Community Supported Boards - -| BOARD | MACHINE | ARCHITECTURE | -|:-------------:|:---------------------:|:-------------:| -| BeagleBone | bbe | arm32 | -| | beaglebone | arm32 | -| | | | -| i.MX 6 | cubox-i | arm32 | -| | imx6qdlsabreauto | arm32 | -| | | | -| i.MX 8 | imx8mqevk | arm64 | -| | imx8mqevk-viv | arm64 | -| | | | -| virtio | virtio-aarch64 | arm64 | diff --git a/docs/1_Hardware_Support/Supported_Hardware_Images.md b/docs/1_Hardware_Support/Supported_Hardware_Images.md deleted file mode 100644 index 83f3902..0000000 --- a/docs/1_Hardware_Support/Supported_Hardware_Images.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: Supported Hardware Images ---- - - - -### Supported Hardware Images - -AGL supports a variety of interfaces, each requiring unique setup configuration. - -#### 1. In-Vehicle Infotainment (IVI) - -**Supported boards** : - -AGL Reference Boards [QEMU, RCar Gen 3, Raspberry Pi 4](./Overview.md), & agl-refhw - -Community supported Boards [BBE, i. MX 6, i. MX 8](./Overview.md) - -* Qt Based : - - * Setting up flags at `aglsetup` script : - - ```sh - $ source meta-agl/scripts/aglsetup.sh -f -m $MACHINE -b build-$MACHINE agl-demo - - #To enable Developer Options - $ source meta-agl/scripts/aglsetup.sh -f -m $MACHINE -b build-$MACHINE agl-demo agl-devel - ``` - - * Building target image : - - ```sh - $ time bitbake agl-demo-platform - ``` - -* HTML5 Based : - - * Setting up flags at `aglsetup` script : - - ```sh - $ source meta-agl/scripts/aglsetup.sh -f -m $MACHINE -b build-$MACHINE agl-demo - - # To enable Developer Options - $ source meta-agl/scripts/aglsetup.sh -f -m $MACHINE -b build-$MACHINE agl-demo agl-devel - ``` - - * Building target image : - - ```sh - $ time bitbake agl-demo-platform-html5 - ``` - - -#### 2. Instrument Cluster - -**Supported boards** : - -AGL Reference Boards [QEMU, RCar Gen 3, & Raspberry Pi 4](./Overview.md) - -* Setting up flags at `aglsetup` script : - - ```sh - $ source meta-agl/scripts/aglsetup.sh -f -m $MACHINE -b build-$MACHINE agl-demo - - # To enable Developer Options - $ source meta-agl/scripts/aglsetup.sh -f -m $MACHINE -b build-$MACHINE agl-demo agl-devel - ``` - -* Building target image : - - ```sh - $ time bitbake agl-cluster-demo - ``` - -#### 3. Telematics - -Headless demo platform for low-spec boards. - -**Supported boards** : - -Community supported Boards [BeagleBone](./Overview.md) - - -* Setting up flags at `aglsetup` script : - - ```sh - $ source meta-agl/scripts/aglsetup.sh -f -m $MACHINE -b build-$MACHINE agl-demo - - # To enable Developer Options - $ source meta-agl/scripts/aglsetup.sh -f -m $MACHINE -b build-$MACHINE agl-demo agl-devel - ``` - -* Building target image : - - ```sh - $ time bitbake agl-telematics-demo - ``` diff --git a/docs/2_Architecture_Guides/1_Introduction/0_Overview.md b/docs/2_Architecture_Guides/1_Introduction/0_Overview.md deleted file mode 100644 index 0648aa9..0000000 --- a/docs/2_Architecture_Guides/1_Introduction/0_Overview.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Overview ---- - -The AGL Unified Code Base (UCB) is a Linux distribution built from the ground up -through a joint effort by automakers and suppliers to deliver a modern -in-vehicle infotainment and connected car experience for consumers. Further -helping reduce fragmentation and facilitate innovation in the development -process. The following use cases are in development or planned to be developed : - - - In Vehicle Infotainment (IVI) - - Instrument Cluster (IC) - - Telematics - - and more : - - Heads-up Display (HUD) - - Advanced Driver Assistance Systems (ADAS) - - Autonomous Driving (AD) - -The goal of the UCB platform is to provide 70-80% of the starting -point for a production project. This enables automakers and suppliers to focus -their resources on customizing the other 20-30% to meet their unique product needs. - -The [System Architecture Team](https://wiki.automotivelinux.org/agl-sat) defines the overall architecture of the AGL -software according to the business requirements established by the [Steering Committee](https://www.automotivelinux.org/about/steering-committee/). - -There are multiple parallel efforts in the areas of the following, with most having specialized [Expert Groups -(EG)](https://wiki.automotivelinux.org/#active_expert_groups) : - - - [App Framework and Security](https://wiki.automotivelinux.org/eg-app-fw) - - [Navigation](https://wiki.automotivelinux.org/eg-navi) - - [Speech](https://wiki.automotivelinux.org/eg-speech) - - [UI and Graphics](https://wiki.automotivelinux.org/eg-ui-graphics) - - [Connectivity](https://wiki.automotivelinux.org/eg-connectivity) - - [Continuous Integration and Test](https://wiki.automotivelinux.org/eg-ciat) - - [Instrument Cluster](https://wiki.automotivelinux.org/eg-ic) - - In Vehicle Infotainment (IVI) - - [Reference Hardware System Architecture](https://wiki.automotivelinux.org/eg-rhsa) - - Telematics - - [Requirements Specification](https://wiki.automotivelinux.org/eg-requirements-specification) - - [Vehicle to Cloud](https://wiki.automotivelinux.org/eg-v2c) - - [Virtualization](https://wiki.automotivelinux.org/eg-virt) - -The Automotive Grade Linux Software Architecture diagram is below. The architecture consists -of five layers. The App/HMI layer contains applications with their associated business logic and -HMI. - -![Architecture Diagram](images/architecture.jpg) - -The Application Framework layer provides the APIs for creating both managing and running -applications on an AGL system. The Services layer contains user space services that all -applications can access. The Operating System (OS) layer provides the Linux kernel and device -drivers along with standard OS utilities. For IVI (In Vehicle Infotainment) -system a full fledged demo is [available](../../0_Getting_Started/1_Quickstart/Using_Ready_Made_Images.md). \ No newline at end of file diff --git a/docs/2_Architecture_Guides/1_Introduction/1_AGL_Requirements_Specifications.md b/docs/2_Architecture_Guides/1_Introduction/1_AGL_Requirements_Specifications.md deleted file mode 100644 index b15202a..0000000 --- a/docs/2_Architecture_Guides/1_Introduction/1_AGL_Requirements_Specifications.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: AGL Requirements Specifications ---- - - - - -[**AGL Requirements Specifications PDF**](AGL Requirements Specifications.pdf) diff --git a/docs/2_Architecture_Guides/1_Introduction/AGL Requirements Specifications.pdf b/docs/2_Architecture_Guides/1_Introduction/AGL Requirements Specifications.pdf deleted file mode 100644 index c5be950..0000000 Binary files a/docs/2_Architecture_Guides/1_Introduction/AGL Requirements Specifications.pdf and /dev/null differ diff --git a/docs/2_Architecture_Guides/1_Introduction/images/architecture.jpg b/docs/2_Architecture_Guides/1_Introduction/images/architecture.jpg deleted file mode 100644 index e83cbc4..0000000 Binary files a/docs/2_Architecture_Guides/1_Introduction/images/architecture.jpg and /dev/null differ diff --git a/docs/2_Architecture_Guides/2_Security_Blueprint/0_Overview.md b/docs/2_Architecture_Guides/2_Security_Blueprint/0_Overview.md deleted file mode 100644 index ee5e7f7..0000000 --- a/docs/2_Architecture_Guides/2_Security_Blueprint/0_Overview.md +++ /dev/null @@ -1,250 +0,0 @@ ---- -title: Overview ---- - -Modern cars have become a lot more technologically sophisticated and different -than those of the past. We are seeing a wider range of new features and -functionality, with a lot more complex software. It is fair to say that the cars -being introduced to the market today have much more in common with computing -devices like cell phones, than their predecessors did. Modern car manufacturers -are also integrating support for a broad range of communication technologies for -these “connected” cars. With the advent of such vehicles, Linux has become a -natural choice for the software platform, with Automotive Grade Linux as a -promising example. - -From a security point of view, the remote capabilities of a connected car -results in a much larger attack surface. This opens a whole new world of -security vulnerabilities that need to be considered during the architectural -design. History shows that physical access to a device is sufficient for a -hacker to gain root privileges. This makes the car a hostile environment. - -The Security Blueprint documents the security features that are included as part -of Automotive Grade Linux (AGL) and identifies areas that need to be addressed -from a security perspective as part of AGL. It also gives guidance around -existing technologies and solutions. - -Security domains will allow us to create a set of tests verifying the security -of Automotive Grade Linux. - -This document is firstly based on an existing AGL security-blueprint. - -**For security to be effective, the concepts must be simple. And by default, -anything that is not allowed is forbidden.** - -We will cover topics starting from the lowest level (_Hardware_) up to the -highest levels (_Connectivity_ and _Application_). We will move quickly on -_Hardware_ and _Connectivity_ because this is not supported at our level. -Solutions of connectivity problems concern updates and secured settings while -hardware securing is related to the manufacturers. - -## Adversaries - -Adversaries and attackers within the Automotive space. - -- 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 information on ECUs that have been -previously compromised and have access to softwares and instructions developed -by other members of car modification forums. The goal of the enthusiast hacker -could be, but is not limited to, adding extra horse power to the car or hacking -it just for fun. - -- Corrupt Automotive Dealers - -Corrupt automotive dealers 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 Criminals - -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 control of the Over-The-Air (OTA) servers or the -In-Vehicle Infotainment (IVI) systems. This is very much like the role of -organized criminals in other industries such as paid media today. Their goal is -to extort money from OEMs and/or governments by threatening to disable multiple -vehicles. - -- Malware Developers - -Malware developers have developed malicious software to attack and compromise a -large number of vehicles. The malicious software is usually designed to spread -from one vehicle to another. Usually, the goal is to take control of multiple -machines and then sell access to them for malicious purposes like -denial-of-service (DoS) attacks or theft of private information and data. - -- Security Researchers - -Security researchers are ‘self-publicized’ security consultants trying to make a -name for themselves. They have access to 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 gain or just to gain personal understanding with -a sense of helping make things more secure. - -## Attack Goals - -In today’s connected vehicle, more and more functionality is moving to software -control, meaning that the threat of attack becomes greater and greater. We see -car features like navigation and summoning, car access/engine start, and -motor/ECU upgrades all controlled through software and connections to the cloud. -The risk of attack is high because there are high value targets in play. - -Here, we outline some of the major threats categories along with some sample -attackers, example attacks, and a relative importance. These threat categories -are intended to be general examples. There can be many nuances to threat types. -Additionally, there can be many sub-attacks that eventually lead to these higher -level attack goals. - -| Threat Category | Sample Attacker | Example Attacks | Relative Importance | -|-------------------------------|-----------------------------------------|-------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------| -| Vehicle theft | Individual, organized criminals | Send the car to an unplanned destination, get a key for the car, gain control of the unlock mechanism | Reduced likelihood of future vehicle purchases (Profit Later), bad press (Brand Integrity) | -| Reduced vehicle functionality | Terrorist groups, disgruntled employees | Lock the driver out of the car, cause the car to crash, block access to infotainment system | Inability sell paid-for apps and content (Profit Now), bad press (Brand Integrity), possible loss of life (Physical Injury) | -| Vehicle hacking | Vehicle owner, competitor | Get content without paying, modify DRM licenses, unlock of after-market features, theft of IP | Loss of sales for content and features (Profit Now), lawsuits from content owners (Profit Later), loss of competitive advantage (Profit Later) | -| Sensitive asset theft | Organized criminals, blackmailers | Steal credit card numbers, health information, camera data, steal bandwidth | Bad press (Brand Integrity), lawsuits from vehicle owners (Profit Later) | - -The Automotive Grade Linux (AGL) initiative builds upon open-source software -including Linux and Tizen to offer a flexible application framework. However, -the security provisions of the app framework, Cynara, and the security manager -only go so far in keeping the biggest threats at bay. As experience has shown, -providing a constrained app (like that in the Android Open Source Platform) and -store development flow, signature verification, DAC sandboxing, and MAC (SMACK) -controls over the platform can have a certain amount of success with the -security of the system. However, the openness of the system invites many -researchers, hobbyists and hackers and financially motivated attackers to -compromise the system for their own gains. - -As AGL arrives on modern automobiles, this is inevitably inviting many capable -actors to modify, attack, and compromise these well thought-out systems and -their applications. With concerns like safety and security, the auto industry -cannot afford to go the way of consumer devices like phones and tablets where -security problems are encountered on a frequent basis. It is imperative to use a -layered approach and defense-in-depth to protect the system from inevitable -attack. - -## Assets and Security Categorization - -This section outlines some of the assets that are likely to be found in the -vehicle and their relative sensitivity from an attack point of view. -Additionally, the final column on the right lists some of the recommended -protection types that can be applied to these types of assets (Note that the -empty cells refer to the cells above them). A good protection approach will give -priority to the most sensitive assets, using a defense-in-depth approach to -cover these assets. Less sensitive assets are treated at a lower priority, -typically protected with fewer protection techniques. A more fine-grained -prioritization of the the assets in a concrete vehicle network can be achieved -with detailed threat analysis which considers the topology of the vehicle -network and access-controls that are in-place. e.g. the EVITA framework for -attack trees. - -| Asset Category | Examples | Sensitivity | Recommended Protection Types | -|-------------------|--------------------------------------------------------------------------------|-------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Software | ECU software, infotainment software, OS images | Critical | Key Management, Mutual Asymmetric Authentication, HSM and WhiteBox Encryption, Message Integrity Checks, Hardening/SW Protection, Program Transforms/ Obfuscation, Integrity Verification, Secure OS | -| Car Access | Biometric data, car keys | | | -| Payment Data | Credit cards, User profile critical data | | | -| Recordings | Internal camera recording, internal audio recording, external camera recording | High | Encryption, Message Integrity Checks, Hardening/SW Protection, Program Transforms / Obfuscation | -| User Profile | Usernames and passwords, customization, calendar, contacts | | | -| Location | GPS coordinates, vehicle usage data | | | -| Purchased Content | Video, audio, licenses | | | -| Teleconference | Chat, audio, video | Medium | SW Protection, Program Transforms / Obfuscation, Authenticated encryption for transmission | -| Vehicle data | Vehicle info, sensor data | | | -| Navigation data | Static and dynamic maps | | | -| 3rd party data | Home automation commands, cloud game data | | | - -## Hardening term - -The term Hardening refers to the tools, techniques and processes required in -order to reduce the attack surface on an embedded system, such as an embedded -control unit (**ECU**) or other managed devices. The target for all hardening -activities is to prevent the execution of invalid binaries on the device, and to -prevent copying of security related data from the device. - -## AGL security overview - -AGL roots are based on security concepts. Those concepts are implemented by the -security framework as shown in this picture: - -![AGL architecture](images/WhiteBoxArchi.png) - --------------------------------------------------------------------------------- - -# Acronyms and Abbreviations - -The following table lists the strongest terms utilized within all this document. - -| Acronyms or Abbreviations | Description | -|---------------------------|-------------------------------------| -| _AGL_ | **A**utomotive **G**rade **L**inux | -| _ECU_ | **E**lectronic **C**ontrol **U**nit | - --------------------------------------------------------------------------------- - -# References - -- [security-blueprint](http://docs.automotivelinux.org/docs/architecture/en/dev/reference/security/01-overview.html). - - _http:// - docs.automotivelinux.org/docs/architecture/en/dev/reference/security/01-overview.html_ -- **[2017]** - [kernel - security](https://www.kernel.org/doc/Documentation/security/). - - _https:// www.kernel.org/doc/Documentation/security/_ -- **[2017]** - [Systemd integration and user - management](http://iot.bzh/download/public/2017/AMM-Dresden/AGL-systemd.pdf). - - _http:// iot.bzh/download/public/2017/AMM-Dresden/AGL-systemd.pdf_ -- **[2017]** - [AGL - Application Framework - Documentation](http://iot.bzh/download/public/2017/SDK/AppFw-Documentation-v3.1.pdf). - - _http:// iot.bzh/download/public/2017/SDK/AppFw-Documentation-v3.1.pdf_ -- **[2017]** - [Improving Vehicle - Cybersecurity](https://access.atis.org/apps/group_public/download.php/35648/ATIS-I-0000059.pdf). - - _https:// - access.atis.org/apps/group_public/download.php/35648/ATIS-I-0000059.pdf_ -- **[2016]** - [AGL framework - overview](http://docs.automotivelinux.org/docs/apis_services/en/dev/reference/af-main/0-introduction.html). - - _http:// - docs.automotivelinux.org/docs/apis_services/en/dev/reference/af-main/0-introduction.html_ -- **[2016]** - - [SecureBoot-SecureSoftwareUpdates](http://iot.bzh/download/public/2016/publications/SecureBoot-SecureSoftwareUpdates.pdf). - - _http:// - iot.bzh/download/public/2016/publications/SecureBoot-SecureSoftwareUpdates.pdf_ -- **[2016]** - [Linux Automotive - Security](http://iot.bzh/download/public/2016/security/Linux-Automotive-Security-v10.pdf). - - _http:// - iot.bzh/download/public/2016/security/Linux-Automotive-Security-v10.pdf_ -- **[2016]** - [Automotive Security Best - Practices](https://www.mcafee.com/it/resources/white-papers/wp-automotive-security.pdf). - - _https:// - www.mcafee.com/it/resources/white-papers/wp-automotive-security.pdf_ -- **[2016]** - [Gattacking Bluetooth Smart - Devices](http://gattack.io/whitepaper.pdf). - - _http:// gattack.io/whitepaper.pdf_ -- **[2015]** - [Comprehensive Experimental Analysis of Automotive Attack - Surfaces](http://www.cs.wayne.edu/fengwei/15fa-csc6991/slides/8-CarHackingUsenixSecurity.pdf). - - _http:// - www.cs.wayne.edu/fengwei/15fa-csc6991/slides/8-CarHackingUsenixSecurity.pdf_ -- **[2015]** - [Security in Automotive Bus - Systems](http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.92.728&rep=rep1&type=pdf). - - _http:// - citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.92.728&rep=rep1&type=pdf_ -- **[2014]** - [IOActive Remote Attack - Surface](https://www.ioactive.com/pdfs/IOActive_Remote_Attack_Surfaces.pdf). - - _https:// www.ioactive.com/pdfs/IOActive_Remote_Attack_Surfaces.pdf_ -- **[2011]** - [A practical attack against GPRS/EDGE/UMTS/HSPA mobile data - communications](https://media.blackhat.com/bh-dc-11/Perez-Pico/BlackHat_DC_2011_Perez-Pico_Mobile_Attacks-wp.pdf). - - _https:// - media.blackhat.com/bh-dc-11/Perez-Pico/BlackHat_DC_2011_Perez-Pico_Mobile_Attacks-wp.pdf_ -- **[2011]** - [Comprehensive Experimental Analyses of Automotive Attack - Surfaces](http://www.autosec.org/pubs/cars-usenixsec2011.pdf). - - _http:// www.autosec.org/pubs/cars-usenixsec2011.pdf_ -- **[2010]** - [Relay Attacks on Passive Keyless Entry and Start Systems in - Modern Cars](https://eprint.iacr.org/2010/332.pdf). - - _https:// eprint.iacr.org/2010/332.pdf_ -- **[2010]** - [Wifi attacks wep - wpa](https://matthieu.io/dl/wifi-attacks-wep-wpa.pdf). - - _https:// matthieu.io/dl/wifi-attacks-wep-wpa.pdf_ -- **[2008]** - - [SMACK](http://schaufler-ca.com/yahoo_site_admin/assets/docs/SmackWhitePaper.257153003.pdf). - - _http:// - schaufler-ca.com/yahoo_site_admin/assets/docs/SmackWhitePaper.257153003.pdf_ diff --git a/docs/2_Architecture_Guides/2_Security_Blueprint/1_Hardware.md b/docs/2_Architecture_Guides/2_Security_Blueprint/1_Hardware.md deleted file mode 100644 index 328dd15..0000000 --- a/docs/2_Architecture_Guides/2_Security_Blueprint/1_Hardware.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: Hardware ---- - -The Automotive Grade Linux platform is a Linux distribution with **AGL** -compliant applications and services. The platform includes the following -hardware: - -- SoC (System-on-Chip). -- Memory (RAM, ROM, storage, etc.). -- Peripherals. - -You will find in this first part everything that concerns the hardware security. -The goal is to protect system against all attacks that are trying to gain -additional privileges by recovering and/or changing cryptographic keys in order -to alter the integrity of the boot. We should also prevent hardware -modifications in order to achieve this goal. We will expose below some examples -of possible configurations. - --------------------------------------------------------------------------------- - -## Acronyms and Abbreviations - -The following table lists the terms utilized within this part of the document. - -Acronyms or Abbreviations | Description -------------------------- | -------------------------------------- -_HSM_ | **H**ardware **S**ecurity **M**odule -_NVM_ | **N**on-**V**olatile **M**emory -_SHE_ | **S**ecure **H**ardware **E**xtensions - --------------------------------------------------------------------------------- - -## Integrity - -The board must store hardcoded cryptographic keys in order to verify among -others the _integrity_ of the _bootloader_. Manufacturers can use **HSM** and -**SHE** to enhance the security of their board. - -Domain | Object | Recommendations --------------------- | ---------- | ---------------------------------- -Hardware-Integrity-1 | Bootloader | Must control bootloader integrity. -Hardware-Integrity-2 | Board | Must use a HSM. -Hardware-Integrity-3 | RTC | Must not be alterable. - --------------------------------------------------------------------------------- - -## Certificates - -Domain | Object | Recommendations ----------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- -Hardware-Certificate-1 | System | Shall allow storing dedicated certificates. -Hardware-Certificate-2 | ECU | The ECU must verify the certification authority hierarchy. -Hardware-Certificate-3 | System | Allow the modification of certificates only if the source can be authenticated by a certificate already stored or in the higher levels of the chain of trust. - --------------------------------------------------------------------------------- - -## Memory - -Domain | Object | Recommendations ------------------ | ---------- | ------------------------------------------------------------------------------------ -Hardware-Memory-1 | ECU | The ECU shall never expose the unencrypted key in RAM when using cryptographic keys. -Hardware-Memory-2 | Bootloader | Internal NVM only -Hardware-Module-3 | - | HSM must be used to secure keys. \ No newline at end of file diff --git a/docs/2_Architecture_Guides/2_Security_Blueprint/2_Secure_Boot.md b/docs/2_Architecture_Guides/2_Security_Blueprint/2_Secure_Boot.md deleted file mode 100644 index cdaa84c..0000000 --- a/docs/2_Architecture_Guides/2_Security_Blueprint/2_Secure_Boot.md +++ /dev/null @@ -1,261 +0,0 @@ ---- -title: Secure Boot ---- - -Domain | Improvement ---------------- | ---------------------------------------------------- -Boot-Abstract-1 | More generic and add examples (The chain of trust). - -Secure boot refers to preventing malicious software applications and -“unauthorized” operating systems from loading during the system start-up -process. The goal is to protect users from rootkits and other low-level malware -attacks. Modern bootloaders come with features that can be used to enable secure -boot in the system. - -**Boot Hardening**: Steps/requirements to configure the boot sequence, in order -to restrict the device from executing anything other than the approved software -image. - -In this part, we will see a series of settings that will allow us to improve -security during boot phase. For the purposes of reference and explanation, we -are providing guidance on how to configure an embedded device that runs with a -3.10.17 Linux kernel. If the integrity is not checked or if a critical error -occurs, the system must boot on a very stable backup image. - -**Requirements**: These requirements must be met even if an alternative version -of the Linux kernel is chosen. - -**Recommendations**: Detailed best practices that should be applied in order to -secure a device. Although they are not currently listed as hard 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. - -Domain | Improvement ---------------- | ------------------------------------------- -Boot-Abstract-1 | Review the definition of the "boot loader". - -**Boot loader**: The boot loader consists of the Primary boot loader residing in -**OTP** memory, sboot, U-Boot and Secure loader residing in external flash (NAND -or SPI/NOR flash memory). The CPU on power on or reset executes the primary boot -loader. The **OTP** primary boot loader makes the necessary initial system -configuration and then loads the secondary boot loader sboot from external flash -memory to ram memory. The sboot then loads the U-Boot along with the Secure -loader. U-Boot then verifies the Kernel/system image integrity, then loads the -Kernel/system image before passing control to it. - --------------------------------------------------------------------------------- - -## Acronyms and Abbreviations - -The following table lists the terms utilized within this part of the document. - -Acronyms or Abbreviations | Description -------------------------- | ----------------------------------------------------------------------- -_FUSE_ | **F**ilesystem in **U**ser**S**pac**E** -_OTP_ | **O**ne-**T**ime-**P**rogrammable -_DOCSIS_ | **D**ata **O**ver **C**able **S**ervice **I**nterface **S**pecification - -# Image - -## Image selection - -The boot process shall be uninterruptible and shall irrevocably boot the image -as specified in the boot environment. - -In U-Boot set the "_bootdelay_" environment variable and/or define -`CONFIG_BOOTDELAY` to _-2_. - -Domain | _Variable_ / `Config` name | `Value` ----------------------- | -------------------------- | ------- -Boot-Image-Selection-1 | `CONFIG_BOOTDELAY` | `-2` -Boot-Image-Selection-2 | _bootdelay_ | `-2` - --------------------------------------------------------------------------------- - -## Image authenticity - -It shall not be possible to boot from an unverified image. The secure boot -feature in U-Boot shall be enabled. The secure boot feature is available from -U-Boot 2013.07 version. To enable the secure boot feature, enable the following -features: - -```sh -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 verification. -CONFIG_OF_CONTROL: Enables Flattened Device Tree (FDT) configuration. -CONFIG_OF_SEPARATE: Enables separate build of u-Boot from the device tree. -CONFIG_DEFAULT_DEVICE_TREE: Specifies the default Device Tree used for the run-time configuration of U-Boot. -``` - -Generate the U-Boot image with public keys to validate and load the image. It -shall use RSA2048 and SHA256 for authentication. - -Domain | `Config` name | _State_ -------------------------- | ---------------------------- | -------- -Boot-Image-Authenticity-1 | `CONFIG_FIT` | _Enable_ -Boot-Image-Authenticity-2 | `CONFIG_FIT_SIGNATURE` | _Enable_ -Boot-Image-Authenticity-3 | `CONFIG_RSA` | _Enable_ -Boot-Image-Authenticity-4 | `CONFIG_OF_CONTROL` | _Enable_ -Boot-Image-Authenticity-5 | `CONFIG_OF_SEPARATE` | _Enable_ -Boot-Image-Authenticity-6 | `CONFIG_DEFAULT_DEVICE_TREE` | _Enable_ - -# Communication modes - -## Disable USB, Serial and DOCSIS Support - -To disable USB support in U-Boot, following config's shall not be defined: - -``` -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. -CONFIG_USB_STORAGE: Enables the USB storage devices. -CONFIG_USB_HOST_ETHER: Enables USB Ethernet adapter support. -``` - -In addition, disable unnecessary communication modes like Ethernet, Serial -ports, DOCSIS in U-Boot and sboot that are not necessary. - -Linux Kernel support for USB should be compiled-out if not required. If it is -needed, the Linux Kernel should be configured to only enable the minimum -required USB devices. User-initiated USB-filesystems should be treated with -special care. Whether or not the filesystems are mounted in userspace -(**FUSE**), restricted mount options should be observed. - -Domain | Communication modes | _State_ --------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- -Boot-Communication-1 | `USB` | _Disabled_ and _Compiled-out_ if not required. -Boot-Communication-2 | `USB` | Else, Kernel should be configured to only enable the minimum required USB devices and filesystems should be treated with special care. -Boot-Communication-3 | `Ethernet` | _Disabled_ -Boot-Communication-4 | U-boot and sboot `DOCSIS` | _Disabled_ -Boot-Communication-5 | `Serial ports` | _Disabled_ - -Domain | `Config` name | _State_ ------------------------- | ----------------------- | ------------- -Boot-Communication-USB-1 | `CONFIG_CMD_USB` | _Not defined_ -Boot-Communication-USB-2 | `CONFIG_USB_UHCI` | _Not defined_ -Boot-Communication-USB-3 | `CONFIG_USB_KEYBOARD` | _Not defined_ -Boot-Communication-USB-4 | `CONFIG_USB_STORAGE` | _Not defined_ -Boot-Communication-USB-5 | `CONFIG_USB_HOST_ETHER` | _Not defined_ - --------------------------------------------------------------------------------- - -## Disable all unused Network Interfaces - -Only used network interfaces should be enabled. Where possible, services should -also be limited to those necessary. - -Domain | Communication modes | _State_ --------------------- | -------------------- | --------------------------------------------------------------------------------------------- -Boot-Communication-1 | `Network interfaces` | Preferably _no network interface is allowed_, otherwise, restrict the services to those used. - -## Remove or Disable Unnecessary Services, Ports, and Devices - -Restrict the `services`, `ports` and `devices` to those used. - -Domain | Object | Recommendations --------------------- | --------------------------------- | ------------------------------------------------------------- -Boot-Communication-1 | `Services`, `ports` and `devices` | Restrict the `services`, `ports` and `devices` to those used. - -## Disable flash access - -**Recommendation**: - -In U-Boot following flash memory commands shall be disabled: - -**NAND**: Support for nand flash access available through `do_nand` has to be -disabled. - -Domain | `Command` name | _State_ --------------------------- | -------------- | --------- -Boot-Communication-Flash-1 | `do_nand` | _Disable_ - -Similarly sboot should disable flash access support through command line if any. - -# Consoles - -## Disable serial console - -Serial console output shall be disabled. To disable console output in U-Boot, -set the following macros: - -Domain | `Config` name | `Value` ----------------------- | --------------------------------------- | --------- -Boot-Consoles-Serial-1 | `CONFIG_SILENT_CONSOLE` | `Disable` -Boot-Consoles-Serial-2 | `CONFIG_SYS_DEVICE_NULLDEV` | `Disable` -Boot-Consoles-Serial-3 | `CONFIG_SILENT_CONSOLE_UPDATE_ON_RELOC` | `Disable` - -Domain | Improvement ---------------- | ------------------------------------ -Boot-Consoles-1 | Secure loader: No reference earlier? - -And set "**silent**" environment variable. For the Secure loader, disable the -traces by not defining the below macro: - -Domain | `Environment variable` name | _State_ ----------------------- | --------------------------- | ------------- -Boot-Consoles-Serial-1 | `INC_DEBUG_PRINT` | _Not defined_ - -For sboot proper configuration needs to be done to disable the serial console. - --------------------------------------------------------------------------------- - -## Immutable environment variables - -In U-Boot, ensure Kernel command line, boot commands, boot delay and other -environment variables are immutable. This will prevent side-loading of alternate -images, by restricting the boot selection to only the image in FLASH. - -The environment variables shall be part of the text region in U-Boot as default -environment variable and not in non-volatile memory. - -Remove configuration options related to non-volatile memory, such as: - -Domain | `Config` name | _State_ --------------------------- | ---------------------------- | --------- -Boot-Consoles-Variables-1 | `CONFIG_ENV_IS_IN_MMC` | `#undef` -Boot-Consoles-Variables-2 | `CONFIG_ENV_IS_IN_EEPROM` | `#undef` -Boot-Consoles-Variables-3 | `CONFIG_ENV_IS_IN_FLASH` | `#undef` -Boot-Consoles-Variables-4 | `CONFIG_ENV_IS_IN_DATAFLASH` | `#undef` -Boot-Consoles-Variables-5 | `CONFIG_ENV_IS_IN_FAT` | `#undef` -Boot-Consoles-Variables-6 | `CONFIG_ENV_IS_IN_NAND` | `#undef` -Boot-Consoles-Variables-7 | `CONFIG_ENV_IS_IN_NVRAM` | `#undef` -Boot-Consoles-Variables-8 | `CONFIG_ENV_IS_IN_ONENAND` | `#undef` -Boot-Consoles-Variables-9 | `CONFIG_ENV_IS_IN_SPI_FLASH` | `#undef` -Boot-Consoles-Variables-10 | `CONFIG_ENV_IS_IN_REMOTE` | `#undef` -Boot-Consoles-Variables-11 | `CONFIG_ENV_IS_IN_UBI` | `#undef` -Boot-Consoles-Variables-12 | `CONFIG_ENV_IS_NOWHERE` | `#define` - --------------------------------------------------------------------------------- - -## (Recommendation) Removal of memory dump commands - -In U-Boot, following commands shall be disabled to avoid memory dumps: - -``` -md : Memory Display command. -mm : Memory modify command - auto incrementing address. -nm : Memory modify command - constant address. -mw : Memory write. -cp : Memory copy. -mwc : Memory write cyclic. -mdc : Memory display cyclic. -mtest : Simple ram read/write test. -loopw : Infinite write loop on address range. -``` - -Domain | `Command` name | _State_ ------------------------ | -------------- | ---------- -Boot-Consoles-MemDump-1 | `md` | _Disabled_ -Boot-Consoles-MemDump-2 | `mm` | _Disabled_ -Boot-Consoles-MemDump-3 | `nm` | _Disabled_ -Boot-Consoles-MemDump-4 | `mw` | _Disabled_ -Boot-Consoles-MemDump-5 | `cp` | _Disabled_ -Boot-Consoles-MemDump-6 | `mwc` | _Disabled_ -Boot-Consoles-MemDump-7 | `mdc` | _Disabled_ -Boot-Consoles-MemDump-8 | `mtest` | _Disabled_ -Boot-Consoles-MemDump-9 | `loopw` | _Disabled_ - -Similarly, memory dump support shall be disabled from sboot. \ No newline at end of file diff --git a/docs/2_Architecture_Guides/2_Security_Blueprint/3_Hypervisor.md b/docs/2_Architecture_Guides/2_Security_Blueprint/3_Hypervisor.md deleted file mode 100644 index 61cc227..0000000 --- a/docs/2_Architecture_Guides/2_Security_Blueprint/3_Hypervisor.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Hypervisor ---- - -**Definition** : "A hypervisor or virtual machine monitor (VMM) is computer -software, firmware or hardware that creates and runs virtual machines". - -It must include a signature verification (possibly delegated). - -Domain | Improvement ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- -Hypervisor-Abstract-1 | Complete Hypervisor part ([jailhouse](https://github.com/siemens/jailhouse) / [KVM](https://www.linux-kvm.org/page/Main_Page) / [Xen](https://www.xenproject.org/developers/teams/embedded-and-automotive.html)). - -## Native or Bare-metal hypervisors - -These hypervisors run directly on the host's hardware to control the hardware -and to manage guest operating systems. Those are the ones we're interested in. \ No newline at end of file diff --git a/docs/2_Architecture_Guides/2_Security_Blueprint/4_Kernel.md b/docs/2_Architecture_Guides/2_Security_Blueprint/4_Kernel.md deleted file mode 100644 index 33e24d5..0000000 --- a/docs/2_Architecture_Guides/2_Security_Blueprint/4_Kernel.md +++ /dev/null @@ -1,941 +0,0 @@ ---- -title: Kernel ---- - -**System Hardening:** Best practices associated with the configuration of an -embedded Linux based operating system. This section includes both hardening of -the kernel itself, as well as specific configurations and patches used to -protect against known vulnerabilities within the build and configuration of the -root filesystem. - -At the Kernel level, we must ensure that no console can be launched. It could be -used to change the behavior of the system or to have more information about it. -Another aspect is the protection of the memory used by the Kernel. - -The next sub-sections contain information on various kernel configuration -options to enhance the security in the kernel (3.10.17) and also for -applications compiled to take advantage of these security features. -Additionally, there are also configuration options that protect from known -vulnerable configuration options. Here's a high level summary of various kernel -configurations that shall be required for deployment. - -## Kernel Version - -The choice of kernel version for the AGL system is essential to its security. -Depending on the type of board and eventual production system, different kernel -versions are used. For example, one of the systems under study uses the Linux -kernel version 3.10, while another uses the Linux kernel version 4.4. For the -Linux kernel version 3.10.31, there are 25 known vulnerabilities. These -vulnerabilities would allow an attacker to gain privileges, bypass access -restrictions, allow memory to be corrupted, or cause denial of service. In -contrast, the Linux kernel version of 4.4 has many fewer known vulnerabilities. -For this reason, we would in general recommend the later kernel version as a -basis for the platform. - -Note that, although there are fewer known vulnerabilities in the most recent -kernel versions there may be many unknown vulnerabilities underlying. A rule of -thumb is to update the kernel as much as possible to avoid the problems you do -know, but you should not be complacent in the trust that you place in it. A -defense-in-depth approach would then apply. - -If there are constraints and dependencies in upgrading to a newer kernel version -(e.g. device drivers, board support providers) and you are forced to an older -Linux kernel version, there need to be additional provisions made to reduce the -risk of kernel exploits, which can include memory monitoring, watch-dog -services, and system call hooking. In this case, further defense-in-depth -techniques may be required to mitigate the risk of attacks to known -vulnerabilities, which can also include runtime integrity verification of -components that are vulnerable to tampering. - -## Kernel Build Configuration - -The kernel build configuration is extremely important for determining the level -of access to services and to reduce the breadth of the attack surface. Linux -contains a great and flexible number of capabilities and this is only controlled -through the build configuration. For example, the `CONFIG_MODULES` parameter -allows kernel modules to be loaded at runtime extending the capabilities of the -kernel. This capability needs to be either inhibited or controlled at runtime -through other configuration parameters. For example, `CONFIG_MODULE_SIG_FORCE=y` -ensures that only signed modules are loaded. There is a very large number of -kernel configuration parameters, and these are discussed in detail in this -section. - -# General configuration - -## Mandatory Access Control - -Kernel should controls access with labels and policy. - -Domain | `Config` name | `Value` --------------------- | -------------- | -------------------------------------- -Kernel-General-MAC-1 | CONFIG_IP_NF_SECURITY | m -Kernel-General-MAC-2 | CONFIG_IP6_NF_SECURITY | m -Kernel-General-MAC-3 | CONFIG_EXT2_FS_SECURITY | y -Kernel-General-MAC-4 | CONFIG_EXT3_FS_SECURITY | y -Kernel-General-MAC-5 | CONFIG_EXT4_FS_SECURITY | y -Kernel-General-MAC-6 | CONFIG_SECURITY | y -Kernel-General-MAC-7 | CONFIG_SECURITY_SMACK | y -Kernel-General-MAC-8 | CONFIG_TMPFS_XATTR | y - -Please also refer to the [Mandatory Access Control documentation in -Platform](5_Platform.md). You can also find useful documentation and -links on wikipedia about -[**MAC**](https://en.wikipedia.org/wiki/Mandatory_access_control) and about -[**SMACK**](https://en.wikipedia.org/wiki/Simplified_Mandatory_Access_Control_Kernel). - --------------------------------------------------------------------------------- - -## Disable kexec - -**Kexec** is a system call that enables you to load and boot into another kernel -from the currently running kernel. This feature is not required in a production -environment. - - - -Domain | `Config` name | `Value` ----------------------- | -------------- | ------- -Kernel-General-kexec-1 | `CONFIG_KEXEC` | `n` - - - - - -**kexec** can load arbitrary kernels but signing of new kernel can be enforced -like it is can be enforced for new modules. - --------------------------------------------------------------------------------- - -## Disable kernel IP auto-configuration - -It is preferable to have an IP configuration performed using a user-space tool -as these tend to have more validation. We do not want the network interface -coming up until the system has come up properly. - - - -Domain | `Config` name | `Value` ---------------------------- | --------------- | ------- -Kernel-General-IPAutoConf-1 | `CONFIG_IP_PNP` | `n` - - - --------------------------------------------------------------------------------- - -## Disable Sysctl syscall support - -Enabling this will result in code being included that is hard to maintain and -not well tested. - - - -Domain | `Config` name | `Value` -------------------------------- | ----------------------- | ------- -Kernel-General-SysCtl_SysCall-1 | `CONFIG_SYSCTL_SYSCALL` | `n` - - - --------------------------------------------------------------------------------- - -## Disable Legacy Linux Support - -There are some Kernel Configs which are present only to support legacy binaries. -See also "Consoles" part in order to disabling support for legacy binary -formats. The `uselib` system call, in particular, has no valid use in any -`libc6` or `uclibc` system in recent times. This configuration is supported in -**Linux 3.15 and greater** and thus should only be disabled for such versions. - - - -Domain | `Config` name | `Value` ----------------------------- | --------------- | ------- -Kernel-General-LegacyLinux-1 | `CONFIG_USELIB` | `n` - - - --------------------------------------------------------------------------------- - -## Disable firmware auto-loading user mode helper - -The firmware auto loading helper, which is a utility executed by the kernel on -`hotplug` events requiring firmware, can to be set `setuid`. As a result of -this, the helper utility is an attractive target for attackers with control of -physical ports on the device. Disabling this configuration that is supported in -**Linux 3.9 and greater**. - - - -Domain | `Config` name | `Value` ---------------------------- | ------------------------------ | ------- -Kernel-General-FirmHelper-1 | `CONFIG_FW_LOADER_USER_HELPER` | `n` - - - - - -It doesn't strictly need to be `setuid`, there is an option of shipping firmware -builtin into kernel without initrd/filesystem. - - - --------------------------------------------------------------------------------- - -## Enable Kernel Panic on OOPS - -When fuzzing the kernel or attempting kernel exploits attackers are likely to -trigger kernel OOPSes. Setting the behavior on OOPS to PANIC can impede their -progress. - -This configuration is supported in **Linux 3.5 and greater** and thus should -only be enabled for such versions. - - - -Domain | `Config` name | `Value` ----------------------------- | ---------------------- | ------- -Kernel-General-PanicOnOOPS-1 | `CONFIG_PANIC_ON_OOPS` | `y` - - - --------------------------------------------------------------------------------- - - - -## Disable socket monitoring interface - -These monitors can be used to inspect shared file descriptors on Unix Domain -sockets or traffic on 'localhost' which is otherwise assumed to be confidential. - -The `CONFIG_PACKET_DIAG` configuration is supported in **Linux 3.7 and greater** -and thus should only be disabled for such versions. - -The `CONFIG_UNIX_DIAG` configuration is supported in **Linux 3.3 and greater** -and thus should only be disabled for such versions. - - - -Domain | `Config` name | `Value` --------------------------- | -------------------- | ------- -Kernel-General-SocketMon-1 | `CONFIG_PACKET_DIAG` | `n` -Kernel-General-SocketMon-2 | `CONFIG_UNIX_DIAG` | `n` - - - --------------------------------------------------------------------------------- - -## Disable BPF JIT - -The BPF JIT can be used to create kernel-payloads from firewall table rules. - -This configuration for is supported in **Linux 3.16 and greater** and thus -should only be disabled for such versions. - - - -Domain | `Config` name | `Value` ------------------------- | ---------------- | ------- -Kernel-General-BPF_JIT-1 | `CONFIG_BPF_JIT` | `n` - - - --------------------------------------------------------------------------------- - -## Enable Enforced Module Signing - -The kernel should never allow an unprivileged user the ability to load specific -kernel modules, since that would provide a facility to unexpectedly extend the -available attack surface. - -To protect against even privileged users, systems may need to either disable -module loading entirely, or provide signed modules (e.g. -`CONFIG_MODULE_SIG_FORCE`, or dm-crypt with LoadPin), to keep from having root -load arbitrary kernel code via the module loader interface. - -This configuration is supported in **Linux 3.7 and greater** and thus should -only be enabled for such versions. - - - -Domain | `Config` name | `Value` ------------------------------- | ------------------------- | ------- -Kernel-General-ModuleSigning-1 | `CONFIG_MODULE_SIG_FORCE` | `y` - - - -It is also possible to block the loading of modules after startup with -"kernel.modules_disabled". - - - -Domain | `Variable` name | `Value` ------------------------------- | ------------------------- | ------- -Kernel-General-ModuleSigning-2 | `kernel.modules_disabled` | `1` - - - --------------------------------------------------------------------------------- - - - -## Disable all USB, PCMCIA (and other `hotplug` bus) drivers that aren't needed - -To reduce the attack surface, the driver enumeration, probe, and operation -happen in the kernel. The driver data is parsed by the kernel, so any logic bugs -in these drivers can become kernel exploits. - - - -Domain | Object | _State_ ------------------------- | ------------------- | ---------- -Kernel-General-Drivers-1 | `USB` | _Disabled_ -Kernel-General-Drivers-2 | `PCMCIA` | _Disabled_ -Kernel-General-Drivers-3 | Other `hotplug` bus | _Disabled_ - - - --------------------------------------------------------------------------------- - -## Position Independent Executables - - - -Domain | Improvement --------------------------------- | ----------------------------- -Kernel-General-IndependentExec-1 | Kernel or/and platform part ? - - - - - -Domain | `compiler` and `linker` options | _State_ --------------------------------- | ------------------------------- | -------- -Kernel-General-IndependentExec-1 | `-pie -fpic` | _Enable_ - - - -Produce a position independent executable on targets which supports it. - --------------------------------------------------------------------------------- - -## Prevent Overwrite Attacks - -`-z,relro` 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. - - - -Domain | `compiler` and `linker` options | _State_ ---------------------------------- | ------------------------------- | -------- -Kernel-General-OverwriteAttacks-1 | `-z,relro` | _Enable_ -Kernel-General-OverwriteAttacks-2 | `-z,now` | _Enable_ - - - -During program load, all dynamic symbols are resolved, allowing for the complete -GOT to be marked read-only (due to `-z relro` above). This prevents GOT -overwrite attacks. For very large application, this can incur some performance -loss during initial load while symbols are resolved, but this shouldn't be an -issue for daemons. - --------------------------------------------------------------------------------- - - - -## Library linking - - - -Domain | Improvement -------------------------------- | --------------- -Kernel-General-LibraryLinking-1 | Keep this part? - - - -It is recommended that dynamic linking should generally not be allowed. This -will avoid the user from replacing a library with malicious library. - - - -Domain | Object | Recommendations -------------------------------- | --------------- | -------------------------------- -Kernel-General-LibraryLinking-1 | Dynamic linking | Should generally not be allowed. - -Linking everything statically doesn't change anything wrt security as binaries -will live under same user:group as libraries and setuid executables ignore -`LD_PRELOAD/LD_LIBRARY_PATH`. It also increases RSS footprint and creates -problems with upgrading. - -# Memory - -## Restrict access to kernel memory - -The /dev/kmem file in Linux systems is directly mapped to kernel virtual memory. -This can be disastrous if an attacker gains root access, as the attacker would -have direct access to kernel virtual memory. - -To disable the /dev/kmem file, which is very infrequently used by applications, -the following kernel option should be set in the compile-time kernel -configuration: - -Domain | `Config` name | `Value` ------------------------------- | ---------------- | ------- -Kernel-Memory-RestrictAccess-1 | `CONFIG_DEVKMEM` | `n` - -In case applications in userspace need /dev/kmem support, it should be available -only for authenticated applications. - --------------------------------------------------------------------------------- - -## Disable access to a kernel core dump - -This kernel configuration disables access to a kernel core dump from user space. -If enabled, it gives attackers a useful view into kernel memory. - - - -Domain | `Config` name | `Value` ------------------------- | ------------------- | ------- -Kernel-Memory-CoreDump-1 | `CONFIG_PROC_KCORE` | `n` - - - --------------------------------------------------------------------------------- - -## Disable swap - -If not disabled, attackers can enable swap at runtime, add pressure to the -memory subsystem and then scour the pages written to swap for useful -information. - - - -Domain | `Config` name | `Value` --------------------- | ------------- | ------- -Kernel-Memory-Swap-1 | `CONFIG_SWAP` | `n` - - - - - -- Enabling swap at runtime require `CAP_SYS_ADMIN`. -- Swap block device is usually under root:disk. -- Linux never swaps kernel pages. -- If swap disabling is not possible, swap encryption should be enabled. - - - --------------------------------------------------------------------------------- - - - -## Disable "Load All Symbols" - -There is a /proc/kallsyms file which exposes the kernel memory space address of -many kernel symbols (functions, variables, etc...). This information is useful -to attackers in identifying kernel versions/configurations and in preparing -payloads for the exploits of kernel space. - -Both `KALLSYMS_ALL` and `KALLSYMS` shall be disabled; - - - -Domain | `Config` name | `Value` ------------------------------- | --------------------- | ------- -Kernel-Memory-LoadAllSymbols-1 | `CONFIG_KALLSYMS` | `n` -Kernel-Memory-LoadAllSymbols-2 | `CONFIG_KALLSYMS_ALL` | `n` - - - --------------------------------------------------------------------------------- - -## Stack protection - -To prevent stack-smashing, similar to the stack protector used for ELF programs -in user-space, the kernel can protect its internal stacks as well. - -This configuration is supported in **Linux 3.11 and greater** and thus should -only be enabled for such versions. - -This configuration also requires building the kernel with the **gcc compiler 4.2 -or greater**. - - - -Domain | `Config` name | `Value` ---------------------- | -------------------------- | ------- -Kernel-Memory-Stack-1 | `CONFIG_CC_STACKPROTECTOR` | `y` - - - -Other defenses include things like shadow stacks. - --------------------------------------------------------------------------------- - -## Disable access to /dev/mem - -The /dev/mem file in Linux systems is directly mapped to physical memory. This -can be disastrous if an attacker gains root access, as the attacker would have -direct access to physical memory through this convenient device file. It may not -always be possible to disable such file, as some applications might need such -support. In that case, then this device file should be available only for -authenticated applications. - -This configuration is supported in **Linux 4.0 and greater** and thus should -only be disabled for such versions. - - - -Domain | `Config` name | `Value` ----------------------- | --------------- | ------- -Kernel-Memory-Access-1 | `CONFIG_DEVMEM` | `n` - - - --------------------------------------------------------------------------------- - - - -## Disable cross-memory attach - -Disable the process_vm_*v syscalls which allow one process to peek/poke the -virtual memory of another. - -This configuration is supported in **Linux 3.5 and greater** and thus should -only be disabled for such versions. - - - -Domain | `Config` name | `Value` ------------------------------- | --------------------- | ------- -Kernel-Memory-CrossMemAttach-1 | `CROSS_MEMORY_ATTACH` | `n` - - - --------------------------------------------------------------------------------- - -## Stack Smashing Attacks - - - -Domain | `compiler` and `linker` options | _State_ ------------------------------ | ------------------------------- | -------- -Kernel-Memory-StackSmashing-1 | `-fstack-protector-all` | _Enable_ - - - -Emit extra code to check for buffer overflows, such as stack smashing attacks. - --------------------------------------------------------------------------------- - -## Detect Buffer Overflows - -Domain | `compiler` options and `config` name | `Value` -------------------------------- | ------------------------------------ | ------- -Kernel-Memory-BufferOverflows-1 | `-D_FORTIFY_SOURCE` | `2` -Kernel-Memory-BufferOverflows-2 | `CONFIG_FORTIFY_SOURCE` | `y` - -Helps detect some buffer overflow errors. - -# Serial - -## Disable serial console - -The serial console should be disabled to prevent an attacker from accessing this -powerful interface. - -Domain | `Config` name | `Value` ------------------------- | ---------------------------- | ------- -Kernel-Consoles-Serial-1 | `CONFIG_SERIAL_8250` | `n` -Kernel-Consoles-Serial-2 | `CONFIG_SERIAL_8250_CONSOLE` | `n` -Kernel-Consoles-Serial-3 | `CONFIG_SERIAL_CORE` | `n` -Kernel-Consoles-Serial-4 | `CONFIG_SERIAL_CORE_CONSOLE` | `n` - --------------------------------------------------------------------------------- - -## Bake-in the kernel command-line - -The kernel command-line is used to control many aspects of the booting kernel, -and is prone to tampering as they are passed in RAM with little to no reverse -validation on these parameters. To prevent this type of attack, the kernel shall -be configured to ignore commands line arguments, and use pre-configured (compile -time) options instead. - -Set the kernel command line in the `CONFIG_CMDLINE KConfig` item and then pass -no arguments from the bootloader. - - - -Domain | `Config` name | `Value` ------------------------------ | ------------------------- | ----------------------------------- -Kernel-Consoles-CommandLine-1 | `CONFIG_CMDLINE_BOOL` | `y` -Kernel-Consoles-CommandLine-2 | `CONFIG_CMDLINE` | `"insert kernel command line here"` -Kernel-Consoles-CommandLine-3 | `CONFIG_CMDLINE_OVERRIDE` | `y` - - - -It is recommended that any per-device settings (e.g: MAC addresses, serial -numbers, etc.) be stored and accessed from read-only memory (or files), and that -any such parameters be verified (signature checking) prior to their use. - --------------------------------------------------------------------------------- - -## Disable KGDB - -The Linux kernel supports KGDB over USB and console ports. These mechanisms are -controlled by the `kgdbdbgp` and `kgdboc` kernel command-line parameters. It is -important to ensure that no shipping product contains a kernel with KGDB -compiled-in. - - - -Domain | `Config` name | `Value` ----------------------- | ------------- | ------- -Kernel-Consoles-KDBG-1 | `CONFIG_KGDB` | `n` - - - --------------------------------------------------------------------------------- - -## Disable magic sysrq support - -On a few architectures, you can access a powerful debugger interface from the -keyboard. The same powerful interface can be present on the serial console -(responding to serial break) of Linux on other architectures. Disable to avoid -potentially exposing this powerful backdoor. - - - -Domain | `Config` name | `Value` ------------------------ | -------------------- | ------- -Kernel-Consoles-SysRQ-1 | `CONFIG_MAGIC_SYSRQ` | `n` - - - --------------------------------------------------------------------------------- - -## Disable support for binary formats other than ELF - -This will make possible to plug wrapper-driven binary formats into the kernel. -It enables support for binary formats other than ELF. Providing the ability to -use alternate interpreters would assist an attacker in discovering attack -vectors. - - - -Domain | `Config` name | `Value` ------------------------------- | -------------------- | ------- -Kernel-Consoles-BinaryFormat-1 | `CONFIG_BINFMT_MISC` | `n` - -# Debug - -No debuggers shall be present on the file system. This includes, but is not -limited to, the GNU Debugger client/server (commonly known in their short form -names such as the `gdb` and `gdbserver` executable binaries respectively), the -`LLDB` next generation debugger or the `TCF` (Target Communications Framework) -agnostic framework. Including these binaries as part of the file system will -facilitate an attacker's ability to reverse engineer and debug (either locally -or remotely) any process that is currently executing on the device. - -## Kernel debug symbols - -Debug symbols should always be removed from production kernels as they provide a -lot of information to attackers. - - - -Domain | `Config` name | `Value` ----------------------- | ------------------- | ------- -Kernel-Debug-Symbols-1 | `CONFIG_DEBUG_INFO` | `n` - - - -These kernel debug symbols are enabled by other config items in the kernel. Care -should be taken to disable those also. If `CONFIG_DEBUG_INFO` cannot be -disabled, then enabling `CONFIG_DEBUG_INFO_REDUCED` is second best. - - - -At least `CONFIG_DEBUG_INFO_REDUCED` should be always enabled for developers to -convert addresses in oops messages to line numbers. - - - --------------------------------------------------------------------------------- - -## Disable Kprobes - -Kprobes enables you to dynamically break into any kernel routine and collect -debugging and performance information non-disruptively. You can trap at almost -any kernel code address, specifying a handler routine to be invoked when the -breakpoint is hit. - - - -Domain | `Config` name | `Value` ----------------------- | ---------------- | ------- -Kernel-Debug-Kprobes-1 | `CONFIG_KPROBES` | `n` - - - --------------------------------------------------------------------------------- - -## Disable Tracing - -FTrace enables the kernel to trace every kernel function. Providing kernel trace -functionality would assist an attacker in discovering attack vectors. - - - -Domain | `Config` name | `Value` ----------------------- | --------------- | ------- -Kernel-Debug-Tracing-1 | `CONFIG_FTRACE` | `n` - - - --------------------------------------------------------------------------------- - -## Disable Profiling - -Profiling and OProfile enables profiling the whole system, include the kernel, -kernel modules, libraries, and applications. Providing profiling functionality -would assist an attacker in discovering attack vectors. - - - -Domain | `Config` name | `Value` ------------------------- | ------------------ | ------- -Kernel-Debug-Profiling-1 | `CONFIG_OPROFILE` | `n` -Kernel-Debug-Profiling-2 | `CONFIG_PROFILING` | `n` - - - --------------------------------------------------------------------------------- - -## Disable OOPS print on BUG() - -The output from OOPS print can be helpful in Return Oriented Programming (ROP) -when trying to determine the effectiveness of an exploit. - - - -Domain | `Config` name | `Value` ------------------------- | ------------------------- | ------- -Kernel-Debug-OOPSOnBUG-1 | `CONFIG_DEBUG_BUGVERBOSE` | `n` - - - --------------------------------------------------------------------------------- - -## Disable Kernel Debugging - -There are development-only branches of code in the kernel enabled by the -`DEBUG_KERNEL` conf. This should be disabled to compile-out these branches. - - - -Domain | `Config` name | `Value` ------------------- | --------------------- | ------- -Kernel-Debug-Dev-1 | `CONFIG_DEBUG_KERNEL` | `n` -Kernel-Debug-Dev-2 | `CONFIG_EMBEDDED` | `n` - - - -In some kernel versions, disabling this requires also disabling -`CONFIG_EMBEDDED`, and `CONFIG_EXPERT`. Disabling `CONFIG_EXPERT` makes it -impossible to disable `COREDUMP`, `DEBUG_BUGVERBOSE`, `NAMESPACES`, `KALLSYMS` -and `BUG`. In which case it is better to leave this enabled than enable the -others. - --------------------------------------------------------------------------------- - - - -## Disable the kernel debug filesystem - -The kernel debug filesystem presents a lot of useful information and means of -manipulation of the kernel to an attacker. - - - -Domain | `Config` name | `Value` -------------------------- | ----------------- | ------- -Kernel-Debug-FileSystem-1 | `CONFIG_DEBUG_FS` | `n` - - - --------------------------------------------------------------------------------- - -## Disable BUG() support - -The kernel will display backtrace and register information for BUGs and WARNs in -kernel space, making it easier for attackers to develop exploits. - - - -Domain | `Config` name | `Value` ------------------- | ------------- | ------- -Kernel-Debug-BUG-1 | `CONFIG_BUG` | `n` - - - --------------------------------------------------------------------------------- - -## Disable core dumps - -Core dumps provide a lot of debug information for hackers. So disabling core -dumps are recommended in production builds. - -This configuration is supported in **Linux 3.7 and greater** and thus should -only be disabled for such versions. - - - -Domain | `Config` name | `Value` ------------------------- | ----------------- | ------- -Kernel-Debug-CoreDumps-1 | `CONFIG_COREDUMP` | `n` - - - --------------------------------------------------------------------------------- - - - -## Kernel Address Display Restriction - -When attackers try to develop "run anywhere" exploits for kernel -vulnerabilities, they frequently need to know the location of internal kernel -structures. By treating kernel addresses as sensitive information, those -locations are not visible to regular local users. - -**/proc/sys/kernel/kptr_restrict is set to "1"** to block the reporting of known -kernel address leaks. - - - -Domain | `File` name | `Value` ----------------------------- | -------------------------------- | ------- -Kernel-Debug-AdressDisplay-1 | `/proc/sys/kernel/kptr_restrict` | `1` - - - -Additionally, various files and directories should be readable only by the root -user: `/boot/vmlinuz*`, `/boot/System.map*`, `/sys/kernel/debug/`, -`/proc/slabinfo` - - - -Domain | `File` or `Directorie` name | _State_ ----------------------------- | --------------------------- | ----------------------------- -Kernel-Debug-AdressDisplay-1 | `/boot/vmlinuz*` | _Readable Only for root user_ -Kernel-Debug-AdressDisplay-2 | `/boot/System.map*` | _Readable Only for root user_ -Kernel-Debug-AdressDisplay-3 | `/sys/kernel/debug/` | _Readable Only for root user_ -Kernel-Debug-AdressDisplay-4 | `/proc/slabinfo` | _Readable Only for root user_ - - - --------------------------------------------------------------------------------- - -## DMESG Restrictions - -When attackers try to develop "run anywhere" exploits for vulnerabilities, they -frequently will use `dmesg` output. By treating `dmesg` output as sensitive -information, this output is not available to the attacker. - -**/proc/sys/kernel/dmesg_restrict can be set to "1"** to treat dmesg output as -sensitive. - - - -Domain | `File` name | `Value` --------------------- | --------------------------------- | ------- -Kernel-Debug-DMESG-1 | `/proc/sys/kernel/dmesg_restrict` | `1` - - - -Enable the below compiler and linker options when building user-space -applications to avoid stack smashing, buffer overflow attacks. - --------------------------------------------------------------------------------- - - - -## Disable /proc/config.gz - -It is extremely important to not expose the kernel configuration used on a -production device to a potential attacker. With access to the kernel config, it -could be possible for an attacker to build a custom kernel for the device that -may disable critical security features. - - - -Domain | `Config` name | `Value` ---------------------- | ----------------- | ------- -Kernel-Debug-Config-1 | `CONFIG_IKCONFIG` | `n` - -# File System - -## Disable all file systems not needed - -To reduce the attack surface, file system data is parsed by the kernel, so any -logic bugs in file system drivers can become kernel exploits. - -### Disable NFS file system - -NFS FileSystems are useful during development phases, but this can be a very -helpful way for an attacker to get files when you are in production mode, so we -must disable them. - - - -Domain | `Config` name | `Value` ------------------------- | --------------- | ------- -Kernel-FileSystems-NFS-1 | `CONFIG_NFSD` | `n` -Kernel-FileSystems-NFS-2 | `CONFIG_NFS_FS` | `n` - - - --------------------------------------------------------------------------------- - - - -## Partition Mount Options - -There are several security restrictions that can be set on a filesystem when it -is mounted. Some common security options include, but are not limited to: - -`nosuid` - Do not allow set-user-identifier or set-group-identifier bits to take -effect. - -`nodev` - Do not interpret character or block special devices on the filesystem. - -`noexec` - Do not allow execution of any binaries on the mounted filesystem. - -`ro` - Mount filesystem as read-only. - -The following flags shall be used for mounting common filesystems: - - - -Domain | `Partition` | `Value` --------------------------- | ------------------- | ----------------------------------------------------------------- -Kernel-FileSystems-Mount-1 | `/boot` | `nosuid`, `nodev` and `noexec`. -Kernel-FileSystems-Mount-2 | `/var` & `/tmp` | In `/etc/fstab` or `vfstab`, add `nosuid`, `nodev` and `noexec`. -Kernel-FileSystems-Mount-3 | _Non-root local_ | If type is `ext2` or `ext3` and mount point not '/', add `nodev`. -Kernel-FileSystems-Mount-4 | _Removable storage_ | Add `nosuid`, `nodev` and `noexec`. -Kernel-FileSystems-Mount-5 | _Temporary storage_ | Add `nosuid`, `nodev` and `noexec`. -Kernel-FileSystems-Mount-6 | `/dev/shm` | Add `nosuid`, `nodev` and `noexec`. -Kernel-FileSystems-Mount-7 | `/dev` | Add `nosuid` and `noexec`. - - - -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. - - - -Domain | `Config` name | _State_ or `Value` --------------------------- | ----------------------- | ----------------------------------------------------------------------- -Kernel-FileSystems-Mount-1 | `CONFIG_DEVTMPFS_MOUNT` | _Disabled_ or add remount with `noexec` and `nosuid` to system startup. \ No newline at end of file diff --git a/docs/2_Architecture_Guides/2_Security_Blueprint/5_Platform.md b/docs/2_Architecture_Guides/2_Security_Blueprint/5_Platform.md deleted file mode 100644 index 2112fdc..0000000 --- a/docs/2_Architecture_Guides/2_Security_Blueprint/5_Platform.md +++ /dev/null @@ -1,921 +0,0 @@ ---- -title: Platform ---- - -The Automotive Grade Linux platform is a Linux distribution with **AGL** -compliant applications and services. The platform includes the following -software: - -- Linux **BSP** configured for reference boards. -- Proprietary device drivers for common peripherals on reference boards. -- Application framework. -- Windows/layer management (graphics). -- Sound resource management. -- An atomic software update system (chapter Update). -- Building and debug tools (based on Yocto project). - - - -Domain | Improvement -------------------- | -------------------------------- -Platform-Abstract-1 | Create a graphics and sound part. - - - -This part focuses on the AGL platform including all tools and techniques used to -upgrade the security and downgrade the danger. It must be possible to apply the -two fundamental principles written at the very beginning of the document. First -of all, security management must remain simple. You must also prohibit -everything by default, and then define a set of authorization rules. As cases to -deal with, we must: - -- Implement a **MAC** for processes and files. -- Limit communication between applications (_SystemBus_ and _SystemD_ part). -- Prohibit all tools used during development mode (_Utilities_ and _Services_ - part). -- Manage user capabilities (_Users_ part). -- Manage application permissions and policies (_AGLFw_ part). - - - -The tools and concepts used to meet these needs are only examples. Any other -tool that meets the need can be used. - - - -In AGL, as in many other embedded systems, different security mechanisms settle -in the core layers to ensure isolation and data privacy. While the Mandatory -Access Control layer (**SMACK**) provides global security and isolation, other -mechanisms like **Cynara** are required to check application's permissions at -runtime. Applicative permissions (also called "_privileges_") may vary depending -on the user and the application being run: an application should have access to -a given service only if it is run by the proper user and if the appropriate -permissions are granted. - -## Discretionary Access Control - -**D**iscretionary **A**ccess **C**ontrol (**DAC**) is the traditional Linux -method of separating users and groups from one another. In a shared environment -where multiple users have access to a computer or network, Unix IDs have offered -a way to contain access within privilege areas for individuals, or shared among -the group or system. The Android system took this one step further, assigning -new user IDs for each App. This was never the original intention of Linux UIDs, -but was able to provide Android’s initial security element: the ability to -sandbox applications. - -Although AGL mentions use of **DAC** for security isolation, the weight of the -security responsibility lies in the **M**andatory **A**ccess **C**ontrol -(**MAC**) and **Cynara**. Furthermore, there are system services with unique -UIDs. however,the system does not go to the extreme of Android, where every -application has its own UID. All sandboxing (app isolation) in AGL is handled in -the **MAC** contexts. - -## Mandatory Access Control - -**M**andatory **A**ccess **C**ontrol (**MAC**) is an extension to **DAC**, -whereby extended attributes (xattr) are associated with the filesystem. In the -case of AGL, the smackfs filesystem allows files and directories to be -associated with a SMACK label, providing the ability of further discrimination -on access control. A SMACK label is a simple null terminated character string -with a maximum of 255 bytes. While it doesn’t offer the richness of an SELinux -label, which provides a user, role,type, and level, the simplicity of a single -value makes the overall design far less complex. There is arguably less chance -of the security author making mistakes in the policies set forth. - --------------------------------------------------------------------------------- - - - -## Acronyms and Abbreviations - -The following table lists the terms utilized within this part of the document. - -Acronyms or Abbreviations | Description -------------------------- | -------------------------------------------------------------- -_ACL_ | **A**ccess **C**ontrol **L**ists -_alsa_ | **A**dvanced **L**inux **S**ound **A**rchitecture -_API_ | **A**pplication **P**rogramming **I**nterface -_AppFw_ | **App**lication **F**rame**w**ork -_BSP_ | **B**oard **S**upport **P**ackage -_Cap_ | **Cap**abilities -_DAC_ | **D**iscretionary **A**ccess **C**ontrol -_DDOS_ | **D**istributed **D**enial **O**f **S**ervice -_DOS_ | **D**enial **O**f **S**ervice -_IPC_ | **I**nter-**P**rocess **C**ommunication -_MAC_ | **M**andatory **A**ccess **C**ontrol -_PAM_ | **P**luggable **A**uthentication **M**odules -_SMACK_ | **S**implified **M**andatory **A**ccess **C**ontrol **K**ernel - -# Mandatory Access Control - - - -We decided to put the **MAC** protection on the platform part despite the fact -that it applies to the kernel too, since its use will be mainly at the platform -level (except floor part). - - - -**M**andatory **A**ccess **C**ontrol (**MAC**) is a protection provided by the -Linux kernel that requires a **L**inux **S**ecurity **M**odule (**LSM**). AGL -uses an **LSM** called **S**implified **M**andatory **A**ccess **C**ontrol -**K**ernel (**SMACK**). This protection involves the creation of **SMACK** -labels as part of the extended attributes **SMACK** labels to the file extended -attributes. And a policy is also created to define the behaviour of each label. - -The kernel access controls is based on these labels and this policy. If there is -no rule, no access will be granted and as a consequence, what is not explicitly -authorized is forbidden. - -There are two types of **SMACK** labels: - -- **Execution SMACK** (Attached to the process): Defines how files are - _accessed_ and _created_ by that process. -- **File Access SMACK** (Written to the extended attribute of the file): Defines - _which_ process can access the file. - -By default a process executes with its File Access **SMACK** label unless an -Execution **SMACK** label is defined. - -AGL's **SMACK** scheme is based on the _Tizen 3 Q2/2015_. It divides the System -into the following domains: - -- Floor. -- System. -- Applications, Services and User. - -See [AGL security framework -review](http://iot.bzh/download/public/2017/AMMQ1Tokyo/AGL-security-framework-review.pdf) -and [Smack White -Paper](http://schaufler-ca.com/yahoo_site_admin/assets/docs/SmackWhitePaper.257153003.pdf) -for more information. - --------------------------------------------------------------------------------- - - - -## Floor - -The _floor_ domain includes the base system services and any associated data and -libraries. This data remains unchanged at runtime. Writing to floor files or -directories is allowed only in development mode or during software installation -or upgrade. - -The following table details the _floor_ domain: - -Label | Name | Execution **SMACK** | File Access **SMACK** ------ | ----- | ------------------- | --------------------------------------- -`-` | Floor | `r-x` for all | Only kernel and internal kernel thread. -`^` | Hat | `---` for all | `rx` on all domains. -`*` | Star | `rwx` for all | None - - - -- The Hat label is Only for privileged system services (currently only - systemd-journal). Useful for backup or virus scans. No file with this label - should exist except in the debug log. - -- The Star label is used for device files or `/tmp` Access restriction managed - via **DAC**. Individual files remain protected by their **SMACK** label. - - - -Domain | `Label` name | Recommendations ------------------- | ------------ | ----------------------------------------------------------- -Kernel-MAC-Floor-1 | `^` | Only for privileged system services. -Kernel-MAC-Floor-2 | `*` | Used for device files or `/tmp` Access restriction via DAC. - - - --------------------------------------------------------------------------------- - - - -## System - -The _system_ domain includes a reduced set of core system services of the OS and -any associated data. This data may change at runtime. - -The following table details the _system_ domain: - -Label | Name | Execution **SMACK** | File Access **SMACK** ----------------- | --------- | ----------------------------------------------- | --------------------- -`System` | System | None | Privileged processes -`System::Run` | Run | `rwxatl` for User and System label | None -`System::Shared` | Shared | `rwxatl` for system domain `r-x` for User label | None -`System::Log` | Log | `rwa` for System label `xa` for user label | None -`System::Sub` | SubSystem | Subsystem Config files | SubSystem only - - - -Domain | `Label` name | Recommendations -------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------- -Kernel-MAC-System-1 | `System` | Process should write only to file with transmute attribute. -Kernel-MAC-System-2 | `System::run` | Files are created with the directory label from user and system domain (transmute) Lock is implicit with `w`. -Kernel-MAC-System-3 | `System::Shared` | Files are created with the directory label from system domain (transmute) User domain has locked privilege. -Kernel-MAC-System-4 | `System::Log` | Some limitation may impose to add `w` to enable append. -Kernel-MAC-System-5 | `System::Sub` | Isolation of risky Subsystem. - - - --------------------------------------------------------------------------------- - - - -## Applications, Services and User - -The _application_, _services_ and _user_ domain includes code that provides -services to the system and user, as well as any associated data. All code -running on this domain is under _Cynara_ control. - -The following table details the _application_, _services_ and _user_ domain: - -Label | Name | Execution **SMACK** | File Access **SMACK** -------------------- | ------ | --------------------------------------------------------------------------- | --------------------------- -`User::Pkg::$AppID` | AppID | `rwx` (for files created by the App). `rx` for files installed by **AppFw** | $App runtime executing $App -`User::Home` | Home | `rwx-t` from System label `r-x-l` from App | None -`User::App-Shared` | Shared | `rwxat` from System and User domains label of $User | None - - - -Domain | `Label` name | Recommendations -------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- -Kernel-MAC-System-1 | `User::Pkg::$AppID` | Only one Label is allowed per App. A data directory is created by the AppFw in `rwx` mode. -Kernel-MAC-System-2 | `User::Home` | AppFw needs to create a directory in `/home/$USER/App-Shared` at first launch if not present with label app-data access is `User::App-Shared` without transmute. -Kernel-MAC-System-3 | `User::App-Shared` | Shared space between all App running for a given user. - - - -## Attack Vectors - -There are 4 major components to the system: - -- The LSM kernel module. -- The `smackfs` filesystem. -- Basic utilities for policy management and checking. -- The policy/configuration data. - -As with any mandatory access system, the policy management needs to be carefully -separated from the checking, as the management utilities can become a convenient -point of attack. Dynamic additions to the policy system need to be carefully -verified, as the ability to update the policies is often needed, but introduces -a possible threat. Finally, even if the policy management is well secured, the -policy checking and failure response to that checking is also of vital -importance to the smooth operation of the system. - -While **MAC** is a certainly a step up in security when compared to DAC, there -are still many ways to compromise a SMACK-enabled Linux system. Some of these -ways are as follows: - -- Disabling SMACK at invocation of the kernel (with command-line: - security=none). -- Disabling SMACK in the kernel build and redeploying the kernel. -- Changing a SMACK attribute of a file or directory at install time. -- Tampering with a process with the CAP_MAC_ADMIN privilege. -- Setting/Re-setting the SMACK label of a file. -- Tampering with the default domains (i.e. - /etc/smack/accesses.d/default-access-domains). -- Disabling or tampering with the SMACK filesystem (i.e. /smackfs). -- Adding policies with `smackload` (adding the utility if not present). -- Changing labels with `chsmack` (adding the utility if not present). - -# SystemD - -`afm-system-daemon` is used to: - -- Manage users and user sessions. -- Setup applications and services (_CGroups_, _namespaces_, autostart, - permissions). -- Use of `libsystemd` for its programs (event management, **D-Bus** interface). - - - -Domain | Object | Recommendations ------------------- | -------------- | ------------------------------------ -Platform-SystemD-1 | Security model | Use Namespaces for containerization. -Platform-SystemD-2 | Security model | Use CGroups to organise processes. - - - -See [systemd integration and user -management](http://iot.bzh/download/public/2017/AMM-Dresden/AGL-systemd.pdf) for -more information. - -## Benefits - -- Removal of one privileged process: **afm-user-daemon** -- Access and use of high level features: - - - Socket activation. - - Management of users and integration of **PAM**. - - Dependency resolution to services. - - `Cgroups` and resource control. - - `Namespaces` containerization. - - Autostart of required API. - - Permissions and security settings. - - Network management. - - - -## CGroups - -Control Groups offer a lot of features, with the most useful ones you can -control: Memory usage, how much CPU time is allocated, how much device I/O is -allowed or which devices can be accessed. **SystemD** uses _CGroups_ to organise -processes (each service is a _CGroups_, and all processes started by that -service use that _CGroups_). By default, **SystemD** automatically creates a -hierarchy of slice, scope and service units to provide a unified structure for -the _CGroups_ tree. With the `systemctl` command, you can further modify this -structure by creating custom slices. Currently, in AGL, there are 2 slices -(**user.slice** and **system.slice**). - -## Namespaces - -### User side - -There are several ways of authenticating users (Key Radio Frequency, Phone, -Gesture, ...). Each authentication provides dynamic allocation of **uids** to -authenticated users. **Uids** is used to ensure privacy of users and **SMACK** -for applications privacy. - -First, the user initiates authentication with **PAM** activation. **PAM** -Standard offers highly configurable authentication with modular design like face -recognition, Voice identification or with a password. Then users should access -identity services with services and applications. - -# D-Bus - -D-Bus is a well-known **IPC** (Inter-Process Communication) protocol (and -daemon) that helps applications to talk to each other. The use of D-Bus is great -because it allows to implement discovery and signaling. - -The D-Bus session is by default addressed by environment variable -`DBUS_SESSION_BUS_ADDRESS`. Using **systemd** variable -`DBUS_SESSION_BUS_ADDRESS` is automatically set for user sessions. D-Bus usage -is linked to permissions. - -D-Bus has already had several [security -issues](https://www.cvedetails.com/vulnerability-list/vendor_id-13442/D-bus-Project.html) -(mostly **DoS** issues), to allow applications to keep talking to each other. It -is important to protect against this type of attack to keep the system more -stable. - - - - -Domain | Object | Recommendations ---------------- | -------------- | ------------------------------------ -Platform-DBus-1 | Security model | Use D-Bus as IPC. -Platform-DBus-2 | Security model | Apply D-BUS security patches: [D-Bus CVE](https://www.cvedetails.com/vulnerability-list/vendor_id-13442/D-bus-Project.html) - - - -# System services and daemons - - - -Domain | Improvement -------------------- | ----------- -Platform-Services-1 | SystemD ? -Platform-Services-2 | Secure daemon ? - - - -## Tools - -- **connman**: An internet connection manager designed to be slim and to use as - few resources as possible. It is a fully modular system that can be extended, - through plug-ins, to support all kinds of wired or wireless technologies. -- **bluez** is a Bluetooth stack. Its goal is to program an implementation of - the Bluetooth wireless standards specifications. In addition to the basic - stack, the `bluez-utils` and `bluez-firmware` packages contain low level - utilities such as `dfutool` which can interrogate the Bluetooth adapter - chipset in order to determine whether its firmware can be upgraded. -- **gstreamer** is a pipeline-based multimedia framework. It can be used to - build a system that reads files in one format, processes them, and exports - them in another format. -- **alsa** is a software framework and part of the Linux kernel that provides an - **API** for sound card device drivers. - - - -Domain | `Tool` name | _State_ --------------------- | ----------- | ------- -Platform-Utilities-1 | `connman` | _Used_ as a connection manager. -Platform-Utilities-2 | `bluez` | _Used_ as a Bluetooth manager. -Platform-Utilities-3 | `gstreamer` | _Used_ to manage multimedia file format. -Platform-Utilities-4 | `alsa` | _Used_ to provides an API for sound card device drivers. - - - -# Application framework/model (**AppFw**) - -The AGL application framework consists of several inter-working parts: - -- **SMACK**: The kernel level **LSM** (**L**inux **S**ecurity **M**odule) that - performs extended access control of the system. -- **Cynara**: the native gatekeeper daemon used for policy handling, updating to - the database and policy checking. -- Security Manager: a master service, through which all security events are - intended to take place. -- Several native application framework utilities: `afm-main-binding`, - `afm-user-daemon`, `afm-system-daemon`. - -The application framework manages: - -- The applications and services management: Installing, Uninstalling, Listing, - ... -- The life cycle of applications: Start -> (Pause, Resume) -> Stop. -- Events and signals propagation. -- Privileges granting and checking. -- API for interaction with applications. - - - -- The **security model** refers to the security model used to ensure security - and to the tools that are provided for implementing that model. It's an - implementation detail that should not impact the layers above the application - framework. - -- The **security model** refers to how **DAC** (**D**iscretionary **A**ccess - **C**ontrol), **MAC** (Mandatory Access Control) and `Capabilities` are used - by the system to ensure security and privacy. It also includes features of - reporting using audit features and by managing logs and alerts. - - - -The **AppFw** uses the security model to ensure the security and the privacy of -the applications that it manages. It must be compliant with the underlying -security model. But it should hide it to the applications. - - - -Domain | Object | Recommendations ----------------------- | -------------- | -------------------------------- -Platform-AGLFw-AppFw-1 | Security model | Use the AppFw as Security model. - - - -See [AGL AppFw Privileges -Management](http://docs.automotivelinux.org/docs/devguides/en/dev/reference/iotbzh2016/appfw/03-AGL-AppFW-Privileges-Management.pdf) -and [AGL - Application Framework -Documentation](http://iot.bzh/download/public/2017/SDK/AppFw-Documentation-v3.1.pdf) -for more information. - - - -The Security Manager communicates policy information to **Cynara**, which -retains information in its own database in the format of a text file with -comma-separated values (CSV). There are provisions to retain a copy of the CSV -text file when the file is being updated. - -Runtime checking occurs through **Cynara**. Each application that is added to -the framework has its own instantiation of a SMACK context and D-bus bindings. -The afb_daemon and Binder form a web-service that is communicated to through -http or a websocket from the application-proper. This http or websocket -interface uses a standard unique web token for API communication. - -![Application Framework Flow](images/App-flow.png) - -## Cynara - -There's a need for another mechanism responsible for checking applicative -permissions: Currently in AGL, this task depends on a policy-checker service -(**Cynara**). - -- Stores complex policies in databases. -- "Soft" security (access is checked by the framework). - -Cynara interact with **D-Bus** in order to deliver this information. - -Cynara consists of several parts: - -- Cynara: a daemon for controlling policies and responding to access control - requests. -- Database: a spot to hold policies. -- Libraries: several static and dynamic libraries for communicating with Cynara. - -The daemon communicates to the libraries over Unix domain sockets. The database -storage format is a series of CSV-like files with an index file. - -There are several ways that an attacker can manipulate policies of the Cynara -system: - -- Disable Cynara by killing the process. -- Tamper with the Cynara binary on-disk or in-memory. -- Corrupt the database controlled by Cynara. -- Tamper with the database controlled by Cynara. -- Highjack the communication between Cynara and the database. - -The text-based database is the weakest part of the system and although there are -some consistency mechanisms in place (i.e. the backup guard), these mechanisms -are weak at best and can be countered by an attacker very easily. - - - -Domain | Object | Recommendations ------------------------ | ----------- | ------------------------------------- -Platform-AGLFw-Cynara-1 | Permissions | Use Cynara as policy-checker service. - - - -### Policies - -- Policy rules: - - - Are simple - for pair [application context, privilege] there is straight - answer (single Policy Type): [ALLOW / DENY / ...]. - - No code is executed (no script). - - Can be easily cached and managed. - -- Application context (describes id of the user and the application credentials) - It is build of: - - - UID of the user that runs the application. - - **SMACK** label of application. - -## Holding policies - -Policies are kept in buckets. Buckets are set of policies which have additional -a property of default answer, the default answer is yielded if no policy matches -searched key. Buckets have names which might be used in policies (for -directions). - -## Attack Vectors - -The following attack vectors are not completely independent. While attackers may -have varying levels of access to an AGL system, experience has shown that a -typical attack can start with direct access to a system, find the -vulnerabilities, then proceed to automate the attack such that it can be invoked -from less accessible standpoint (e.g. remotely). Therefore, it is important to -assess all threat levels, and protect the system appropriately understanding -that direct access attacks are the door-way into remote attacks. - -### Remote Attacks - -The local web server interface used for applications is the first point of -attack, as web service APIs are well understood and easily intercepted. The -local web server could potentially be exploited by redirecting web requests -through the local service and exploiting the APIs. While there is the use of a -security token on the web service API, this is weak textual matching at best. -This will not be difficult to spoof. It is well known that [API Keys do not -provide any real security](http://nordicapis.com/why-api-keys-are-not-enough/). - -It is likely that the architectural inclusion of an http / web-service interface -provided the most flexibility for applications to be written natively or in -HTML5. However, this flexibility may trade-off with security concerns. For -example, if a native application were linked directly to the underlying -framework services, there would be fewer concerns over remote attacks coming -through the web-service interface. - -Leaving the interface as designed, mitigations to attacks could include further -securing the interface layer with cryptographic protocols: e.g. encrypted -information passing, key exchange (e.g. Elliptic-Curve Diffie-Hellman). - -### User-level Native Attacks - -- Modifying the CSV data-base -- Modifying the SQLite DB -- Tampering with the user-level binaries -- Tampering with the user daemons -- Spoofing the D-bus Interface -- Adding executables/libraries - -With direct access to the device, there are many security concerns on the native -level. For example, as **Cynara** uses a text file data-base with -comma-separated values (CSV), an attacker could simply modify the data-base to -escalate privileges of an application. Once a single application has all the -privileges possible on the system, exploits can come through in this manner. -Similarly the SQLite database used by the Security Manager is not much different -than a simple text file. There are many tools available to add, remove, modify -entries in an SQLite data-base. - -On the next level, a common point of attack is to modify binaries or daemons for -exploiting functionality. There are many Linux tools available to aid in this -regard, including: [IDA Pro](https://www.hex-rays.com/products/ida/index.shtml), -and [radare2](https://rada.re/r/). With the ability to modify binaries, an -attacker can do any number of activities including: removing calls to security -checks, redirecting control to bypass verification functionality, ignoring -security policy handling, escalating privileges, etc. - -Additionally, another attack vector would be to spoof the D-bus interface. D-bus -is a message passing system built upon Inter-Process Communication (IPC), where -structured messages are passed based upon a protocol. The interface is generic -and well documented. Therefore, modifying or adding binaries/libraries to spoof -this interface is a relatively straight-forward process. Once the interface has -been spoofed, the attacker can issue any number of commands that lead into -control of low-level functionality. - -Protecting a system from native attacks requires a methodical approach. First, -the system should reject processes that are not sanctioned to run. -Signature-level verification at installation time will help in this regard, but -run-time integrity verification is much better. Signatures need to originate -from authorized parties, which is discussed further in a later section on the -Application Store. - -On the next level, executables should not be allowed to do things where they -have not been granted permission. DAC and SMACK policies can help in this -regard. On the other hand, there remain concerns with memory accesses, system -calls, and other process activity that may go undetected. For this reason, a -secure environment which monitors all activity can give indication of all -unauthorized activity on the system. - -Finally, it is very difficult to catch attacks of direct tampering in a system. -These types of attacks require a defense-in-depth approach, where complementary -software protection and hardening techniques are needed. Tamper-resistance and -anti-reverse-engineering technologies include program -transformations/obfuscation, integrity verification, and white-box cryptography. -If applied in a mutually-dependent fashion and considering performance/security -tradeoffs, the approach can provide an effective barrier to direct attacks to -the system. Furthermore, the use of threat monitoring provides a valuable -telemetry/analytics capability and the ability to react and renew a system under -attack. - -### Root-level Native Attacks - -- Tampering the system daemon -- Tampering Cynara -- Tampering the security manager -- Disabling SMACK -- Tampering the kernel - -Once root-level access (i.e. su) has been achieved on the device, there are many -ways to compromise the system. The system daemon, **Cynara**, and the security -manager are vulnerable to tampering attacks. For example, an executable can be -modified in memory to jam a branch, jump to an address, or disregard a check. -This can be as simple as replacing a branch instruction with a NOP, changing a -memory value, or using a debugger (e.g. gdb, IDA) to change an instruction. -Tampering these executables would mean that policies can be ignored and -verification checks can be bypassed. - -Without going so far as to tamper an executable, the **SMACK** system is also -vulnerable to attack. For example, if the kernel is stopped and restarted with -the *security=none* flag, then SMACK is not enabled. Furthermore, `systemd` -starts the loading of **SMACK** rules during start-up. If this start-up process -is interfered with, then **SMACK** will not run. Alternatively, new policies can -be added with `smackload` allowing unforeseen privileges to alternative -applications/executables. - -Another intrusion on the kernel level is to rebuild the kernel (as it is -open-source) and replace it with a copy that has **SMACK** disabled, or even -just the **SMACK** filesystem (`smackfs`) disabled. Without the extended label -attributes, the **SMACK** system is disabled. - -Root-level access to the device has ultimate power, where the entire system can -be compromised. More so, a system with this level access allows an attacker to -craft a simpler *point-attack* which can operate on a level requiring fewer -privileges (e.g. remote access, user-level access). - -## Vulnerable Resources - -### Resource: `afm-user-daemon` - -The `afm-user-daemon` is in charge of handling applications on behalf of a user. -Its main tasks are: - -- Enumerate applications that the end user can run and keep this list available - on demand. -- Start applications on behalf of the end user, set user running environment, - set user security context. -- List current runnable or running applications. -- Stop (aka pause), continue (aka resume), terminate a running instance of a - given application. -- Transfer requests for installation/uninstallation of applications to the - corresponding system daemon afm-system-daemon. - -The `afm-user-daemon` launches applications. It builds a secure environment for -the application before starting it within that environment. Different kinds of -applications can be launched, based on a configuration file that describes how -to launch an application of a given kind within a given launching mode: local or -remote. Launching an application locally means that the application and its -binder are launched together. Launching an application remotely translates in -only launching the application binder. - -The UI by itself has to be activated remotely by a request (i.e. HTML5 -homescreen in a browser). Once launched, running instances of the application -receive a `runid` that identifies them. `afm-user-daemon` manages the list of -applications that it has launched. When owning the right permissions, a client -can get the list of running instances and details about a specific running -instance. It can also terminate, stop or continue a given application. If the -client owns the right permissions, `afm-user-daemon` delegates the task of -installing and uninstalling applications to `afm-system-daemon`. - -`afm-user-daemon` is launched as a `systemd` service attached to a user session. -Normally, the service file is located at -/usr/lib/systemd/user/afm-user-daemon.service. - -Attacker goals: - -- Disable `afm-user-daemon`. -- Tamper with the `afm-user-daemon` configuration. - - /usr/lib/systemd/user/afm-user-daemon.service. - - Application(widget) config.xml file. - - /etc/afm/afm-launch.conf (launcher configuration). - -- Escalate user privileges to gain more access with `afm-user-daemon`. -- Install malicious application (widget). -- Tamper with `afm-user-daemon` on disk or in memory. - -### Resource: `afm-system-daemon` - -The `afm-system-daemon` is in charge of installing applications on the AGL -system. Its main tasks are: - -- Install applications and setup security framework for newly installed - applications. -- Uninstall applications. - -`afm-system-daemon` is launched as a `systemd` service attached to system. -Normally, the service file is located at -/lib/systemd/system/afm-systemdaemon.service. - -Attacker goals: - -- Disable `afm-system-daemon`. -- Tamper with the `afm-system-daemon` configuration. -- Tamper `afm-system-daemon` on disk or in memory. - -### Resource `afb-daemon` - -`afb-binder` is in charge of serving resources and features through an HTTP -interface. `afb-daemon` is in charge of binding one instance of an application -to the AGL framework and AGL system. The application and its companion binder -run in a secured and isolated environment set for them. Applications are -intended to access to AGL system through the binder. `afb-daemon` binders serve -files through HTTP protocol and offers developers the capability to expose -application API methods through HTTP or WebSocket protocol. - -Binder bindings are used to add APIs to `afb-daemon`. The user can write a -binding for `afb-daemon`. The binder `afb-daemon` serves multiple purposes: - -1. It acts as a gateway for the application to access the system. -2. It acts as an HTTP server for serving files to HTML5 applications. -3. It allows HTML5 applications to have native extensions subject to security - enforcement for accessing hardware resources or for speeding up parts of - algorithm. - -Attacker goals: - -- Break from isolation. -- Disable `afb-daemon`. -- Tamper `afb-demon` on disk or in memory. -- Tamper **capabilities** by creating/installing custom bindings for - `afb-daemon`. - -# Utilities - -- **busybox**: Software that provides several stripped-down Unix tools in a - single executable file. Of course, it will be necessary to use a "production" - version of **busybox** in order to avoid all the tools useful only in - development mode. - - - -Domain | `Tool` name | _State_ --------------------- | ----------- | ---------------------------------------------------------------------- -Platform-Utilities-1 | `busybox` | _Used_ to provide a number of tools. Do not compile development tools. - - - -## Functionalities to exclude in production mode - -In production mode, a number of tools must be disabled to prevent an attacker -from finding logs for example. This is useful to limit the visible surface and -thus complicate the fault finding process. The tools used only in development -mode are marked by an '**agl-devel**' feature. When building in production mode, -these tools will not be compiled. - - - -Domain | `Utility` name and normal `path` | _State_ ---------------------- | ---------------------------------------------------- | ---------- -Platform-Utilities-1 | `chgrp` in `/bin/chgrp` | _Disabled_ -Platform-Utilities-2 | `chmod` in `/bin/chmod` | _Disabled_ -Platform-Utilities-3 | `chown` in `/bin/chown` | _Disabled_ -Platform-Utilities-4 | `dmesg` in `/bin/dmesg` | _Disabled_ -Platform-Utilities-5 | `Dnsdomainname` in `/bin/dnsdomainname` | _Disabled_ -Platform-Utilities-6 | `dropbear`, Remove "dropbear" from `/etc/init.d/rcs` | _Disabled_ -Platform-Utilities-7 | `Editors` in (vi) `/bin/vi` | _Disabled_ -Platform-Utilities-8 | `find` in `/bin/find` | _Disabled_ -Platform-Utilities-9 | `gdbserver` in `/bin/gdbserver` | _Disabled_ -Platform-Utilities-10 | `hexdump` in `/bin/hexdump` | _Disabled_ -Platform-Utilities-11 | `hostname` in `/bin/hostname` | _Disabled_ -Platform-Utilities-12 | `install` in `/bin/install` | _Disabled_ -Platform-Utilities-13 | `iostat` in `/bin/iostat` | _Disabled_ -Platform-Utilities-14 | `killall` in `/bin/killall` | _Disabled_ -Platform-Utilities-15 | `klogd` in `/sbin/klogd` | _Disabled_ -Platform-Utilities-16 | `logger` in `/bin/logger` | _Disabled_ -Platform-Utilities-17 | `lsmod` in `/sbin/lsmod` | _Disabled_ -Platform-Utilities-18 | `pmap` in `/bin/pmap` | _Disabled_ -Platform-Utilities-19 | `ps` in `/bin/ps` | _Disabled_ -Platform-Utilities-20 | `ps` in `/bin/ps` | _Disabled_ -Platform-Utilities-21 | `rpm` in `/bin/rpm` | _Disabled_ -Platform-Utilities-22 | `SSH` | _Disabled_ -Platform-Utilities-23 | `stbhotplug` in `/sbin/stbhotplug` | _Disabled_ -Platform-Utilities-24 | `strace` in `/bin/trace` | _Disabled_ -Platform-Utilities-25 | `su` in `/bin/su` | _Disabled_ -Platform-Utilities-26 | `syslogd` in (logger) `/bin/logger` | _Disabled_ -Platform-Utilities-27 | `top` in `/bin/top` | _Disabled_ -Platform-Utilities-28 | `UART` in `/proc/tty/driver/` | _Disabled_ -Platform-Utilities-29 | `which` in `/bin/which` | _Disabled_ -Platform-Utilities-30 | `who` and `whoami` in `/bin/whoami` | _Disabled_ -Platform-Utilities-31 | `awk` (busybox) | _Enabled_ -Platform-Utilities-32 | `cut` (busybox) | _Enabled_ -Platform-Utilities-33 | `df` (busybox) | _Enabled_ -Platform-Utilities-34 | `echo` (busybox) | _Enabled_ -Platform-Utilities-35 | `fdisk` (busybox) | _Enabled_ -Platform-Utilities-36 | `grep` (busybox) | _Enabled_ -Platform-Utilities-37 | `mkdir` (busybox) | _Enabled_ -Platform-Utilities-38 | `mount` (vfat) (busybox) | _Enabled_ -Platform-Utilities-39 | `printf` (busybox) | _Enabled_ -Platform-Utilities-40 | `sed` in `/bin/sed` (busybox) | _Enabled_ -Platform-Utilities-41 | `tail` (busybox) | _Enabled_ -Platform-Utilities-42 | `tee` (busybox) | _Enabled_ -Platform-Utilities-43 | `test` (busybox) | _Enabled_ - - - -The _Enabled_ Unix/Linux utilities above shall be permitted as they are often -used in the start-up scripts and for USB logging. If any of these utilities are -not required by the device then those should be removed. - - - -# Users - -The user policy can group users by function within the car. For example, we can -consider a driver and his passengers. Each user is assigned to a single group to -simplify the management of space security. - -## Root Access - -The main applications, those that provide the principal functionality of the -embedded device, should not execute with root identity or any capability. - -If the main application is allowed to execute at any capability, then the entire -system is at the mercy of the said application's good behaviour. Problems arise -when an application is compromised and able to execute commands which could -consistently and persistently compromise the system by implanting rogue -applications. - -It is suggested that the middleware and the UI should run in a context on a user -with no capability and all persistent resources should be maintained without any -capability. - -One way to ensure this is by implementing a server-client paradigm. Services -provided by the system's drivers can be shared this way. The other advantage of -this approach is that multiple applications can share the same resources at the -same time. - - - -Domain | Object | Recommendations ---------------------- | ---------------- | ----------------------------------------------------- -Platform-Users-root-1 | Main application | Should not execute as root. -Platform-Users-root-2 | UI | Should run in a context on a user with no capability. - - - -Root access should not be allowed for the following utilities: - - - -Domain | `Utility` name | _State_ ---------------------- | -------------- | ------------- -Platform-Users-root-3 | `login` | _Not allowed_ -Platform-Users-root-4 | `su` | _Not allowed_ -Platform-Users-root-5 | `ssh` | _Not allowed_ -Platform-Users-root-6 | `scp` | _Not allowed_ -Platform-Users-root-7 | `sftp` | _Not allowed_ - - - -Root access should not be allowed for the console device. The development -environment should allow users to login with pre-created user accounts. - -Switching to elevated privileges shall be allowed in the development environment -via `sudo`. - --------------------------------------------------------------------------------- - - - -## Capabilities - - - -Domain | Improvement ------------------------------ | ------------------------ -Platform-Users-Capabilities-1 | Kernel or Platform-user? -Platform-Users-Capabilities-2 | Add config note. - - - -The goal is to restrict functionality that will not be useful in **AGL**. They -are integrated into the **LSM**. Each privileged transaction is associated with -a capability. These capabilities are divided into three groups: - -- e: Effective: This means the capability is “activated”. -- p: Permitted: This means the capability can be used/is allowed. -- i: Inherited: The capability is kept by child/subprocesses upon execve() for - example. diff --git a/docs/2_Architecture_Guides/2_Security_Blueprint/6_Application.md b/docs/2_Architecture_Guides/2_Security_Blueprint/6_Application.md deleted file mode 100644 index c08d06e..0000000 --- a/docs/2_Architecture_Guides/2_Security_Blueprint/6_Application.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -title: Application ---- - -**Application Hardening**: Best practices to apply to the build and release of -user space applications, in order to reduce the number of attack surfaces used -by potential attackers. - -The term of Application (App) has a very wide definition in **AGL**. Almost -anything which is not in the core Operating System (OS) is an Application. -Applications can be included in the base software package (image) or can be -added at run-time. - -Application containment is achieved using the following protections: - -- Linux Native protection - - Mandatory Access Control (**MAC**) -- AGL Platform protections - - Origin Tracking and Validation - - Application Privilege Management and Enforcement via Cynara - - Authenticated Transport via D-Bus - -## Application Types - -AGL provides a framework for applications to be written in different forms: - -- Web application: HTML5 + JavaScript -- Qt application: in a QML file -- Native application: in C - -While there is no harm in providing multiple types of applications, from a -security perspective this does increase the attack surface for an intruder. The -application framework (**AppFw**) consists of a number of utilities and daemons -which provide context for the applications. Isolation is provided through -**SMACK** labels. - -## Application Store - -Although the Tizen system has defined a [system of App signing and signing -flow](https://wiki.tizen.org/Security/Tizen_3.X_Overview#Application_Singing_and_Certificates) -to avoid the spread of unauthorized Apps that might contain malware. At this -point, it is unclear how much of this flow AGL will adopt. However, judging from -the experience, it is an essential topic. For example, the Google Play Store -controls the authorization of Apps through signing, and still, there are [many -accounts of Apps containing malware on the -store](http://www.eweek.com/mobile/researchers-find-132-malware-infected-android-apps-on-google-play). - -Tizen defines 5 levels of certificates and signing at each level, including an -author, testing distributor, public level store distributor, partner level store -distributor, and platform level store distributor. AGL may define a different -number of third parties, but at a minimum an author and store distributor should -be defined. - -![App Signing Flow](images/App_signing_flow.png) - -Once the number of signatures has been established, verification of those -signatures needs to be done at a minimum at installation time on the AGL device. -It is important to ensure the robustness/integrity of the public key used for -signature verification. If the public key is modified, then this compromised key -can be used to verify an attacker's private key signature. - -Further to this, installation-time verification is limited. Attacks can happen -to apps in-memory at runtime. Any modifications made after installation will be -missed by installation-time verification. Integrity verification that runs -during execution makes for a more complete security story. - --------------------------------------------------------------------------------- - -## Acronyms and Abbreviations - -The following table lists the terms utilized within this part of the document. - -Acronyms or Abbreviations | Description -------------------------- | ---------------------------------------------------- -_3GPP_ | **3**rd **G**eneration **P**artnership **P**roject -_CASB_ | **C**loud **A**ccess **S**ecurity **B**roker -_DAST_ | **D**ynamic **A**pplication **S**ecurity **T**esting -_DPI_ | **D**eep **P**acket **I**nspection -_IDS_ | **I**ntrusion **D**etection **S**ystems -_IPS_ | **I**ntrusion **P**revention **S**ystems -_IPSec_ | **I**nternet **P**rotocol **Sec**urity -_LSM_ | **L**inux **S**ecurity **M**odule -_MITM_ | **M**an **I**n **T**he **M**iddle -_OSI_ | **O**pen **S**ystems **I**nterconnection -_SATS_ | **S**tatic **A**pplication **S**ecurity **T**esting - -# Local - -Domain | Improvement --------------------------- | ------------------------------ -Application-Installation-1 | Talk about AppFw offline mode. - -## Installation - -Applications can be delivered and installed with the base image using a special -offline-mode provided by the **AppFw**. Apps can also be installed at run time. - -During early release, default Apps are installed on the image at first boot. - -Domain | Object | Recommendations --------------------------- | --------- | ----------------------------------------------------------------------- -Application-Installation-1 | AppFw | Provide offline-mode in order to install app with the base image. -Application-Installation-2 | Integrity | Allow the installation of applications only if their integrity is good. - -# Local - -## Privilege Management - -Application privileges are managed by **Cynara** and the security manager in the -**AppFw**. For more details, please refer to the **AppFw** documentation in -Platform part. - -# App Signature - -Domain | Improvement ------------------------ | ---------------------------------------------------------- -Application-Signature-1 | Add content (see secure build in Secure development part). - - -# Services - -Domain | Improvement ----------------------- | ------------ -Application-Services-1 | Add content (Which services?). -Application-Services-2 | Add Binder. \ No newline at end of file diff --git a/docs/2_Architecture_Guides/2_Security_Blueprint/7_Connectivity.md b/docs/2_Architecture_Guides/2_Security_Blueprint/7_Connectivity.md deleted file mode 100644 index 076c0e0..0000000 --- a/docs/2_Architecture_Guides/2_Security_Blueprint/7_Connectivity.md +++ /dev/null @@ -1,487 +0,0 @@ ---- -title: Connectivity ---- - -This part shows different Connectivity attacks on the car. - -Domain | Improvement ------------------------ | ----------------- -Connectivity-Abstract-1 | Improve abstract. - - - --------------------------------------------------------------------------------- - - - -## Acronyms and Abbreviations - -The following table lists the terms utilized within this part of the document. - -Acronyms or Abbreviations | Description -------------------------- | --------------------------------------------------------------------------------- -_ARP_ | **A**ddress **R**esolution **P**rotocol -_BLE_ | **B**luetooth **L**ow **E**nergy -_CAN_ | **C**ar **A**rea **N**etwork -_CCMP_ | **C**ounter-Mode/**C**BC-**M**ac **P**rotocol -_EDGE_ | **E**nhanced **D**ata **R**ates for **GSM** **E**volution - Evolution of **GPRS** -_GEA_ | **G**PRS **E**ncryption **A**lgorithm -_GPRS_ | **G**eneral **P**acket **R**adio **S**ervice (2,5G, 2G+) -_GSM_ | **G**lobal **S**ystem for **M**obile Communications (2G) -_HSPA_ | **H**igh **S**peed **P**acket **A**ccess (3G+) -_IMEI_ | **I**nternational **M**obile **E**quipment **I**dentity -_LIN_ | **L**ocal **I**nterconnect **N**etwork -_MOST_ | **M**edia **O**riented **S**ystem **T**ransport -_NFC_ | **N**ear **F**ield **C**ommunication -_OBD_ | **O**n-**B**oard **D**iagnostics -_PATS_ | **P**assive **A**nti-**T**heft **S**ystem -_PKE_ | **P**assive **K**eyless **E**ntry -_PSK_ | **P**hase-**S**hift **K**eying -_RDS_ | **R**adio **D**ata **S**ystem -_RFID_ | **R**adio **F**requency **I**dentification -_RKE_ | **R**emote **K**eyless **E**ntry -_SDR_ | **S**oftware **D**efined **R**adio -_SSP_ | **S**ecure **S**imple **P**airing -_TKIP_ | **T**emporal **K**ey **I**ntegrity **P**rotocol -_TPMS_ | **T**ire **P**ressure **M**onitoring **S**ystem -_UMTS_ | **U**niversal **M**obile **T**elecommunications **S**ystem (3G) -_USB_ | **U**niversal **S**erial **B**us -_WEP_ | **W**ired **E**quivalent **P**rivacy -_WPA_ | **W**ifi **P**rotected **A**ccess - -# Bus - -We only speak about the **CAN** bus to take an example, because the different -attacks on bus like _FlewRay_, _ByteFlight_, _Most_ and _Lin_ use retro -engineering and the main argument to improve their security is to encrypt data -packets. We just describe them a bit: - -- **CAN**: Controller Area Network, developed in the early 1980s, is an - event-triggered controller network for serial communication with data rates up - to one MBit/s. **CAN** messages are classified over their respective - identifier. **CAN** controller broadcast their messages to all connected nodes - and all receiving nodes decide independently if they process the message. -- **FlewRay**: Is a deterministic and error-tolerant high-speed bus. With a data - rate up to 10 MBit/s. -- **ByteFlight**: Is used for safety-critical applications in motor vehicles - like air-bags. Byteflight runs at 10Mbps over 2 or 3 wires plastic optical - fibers. -- **Most**: Media Oriented System Transport, is used for transmitting audio, - video, voice, and control data via fiber optic cables. The speed is, for the - synchronous way, up to 24 MBit/s and asynchronous way up to 14 MBit/s. - **MOST** messages include always a clear sender and receiver address. -- **LIN**: Local Interconnect Network, is a single-wire subnet work for - low-cost, serial communication between smart sensors and actuators with - typical data rates up to 20 kBit/s. It is intended to be used from the year - 2001 on everywhere in a car, where the bandwidth and versatility of a **CAN** - network is not required. - -On just about every vehicle, **ECU**s (**E**lectronic **C**ontrol **U**nits) -communicate over a CAN bus, which is a two-wire bus using hardware arbitration -for messages sent on the shared medium. This is essentially a *trusted* network -where all traffic is visible to all controllers and any controller can send any -message. - -A malicious **ECU** on the CAN bus can easily inject messages destined for any -other device, including things like the instrument cluster and the head unit. -There are common ways for hardware to do USB to CAN and open source software to -send and receive messages. For example, there is a driver included in the Linux -kernel that can be used to send/receive CAN signals. A malicious device on the -CAN bus can cause a great number of harmful things to happen to the system, -including: sending bogus information to other devices, sending unintended -commands to ECUs, causing DOS (Denial Of Service) on the CAN bus, etc. - - - -Domain | Tech name | Recommendations ----------------------------------- | --------- | -------------------------------------------------------------------------- -Connectivity-BusAndConnector-Bus-1 | CAN | Implement hardware solution in order to prohibit sending unwanted signals. - - - -See [Security in Automotive Bus -Systems](http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.92.728&rep=rep1&type=pdf) -for more information. - -# Connectors - -For the connectors, we supposed that they were disabled by default. For example, -the **USB** must be disabled to avoid attacks like BadUSB. If not, configure the -Kernel to only enable the minimum require **USB** devices. The connectors used -to diagnose the car like **OBD-II** must be disabled outside garages. - - - -Domain | Tech name | Recommendations ------------------------------------------ | --------- | ---------------------------------------------------------------------- -Connectivity-BusAndConnector-Connectors-1 | USB | Must be disabled. If not, only enable the minimum require USB devices. -Connectivity-BusAndConnector-Connectors-2 | USB | Confidential data exchanged with the ECU over USB must be secure. -Connectivity-BusAndConnector-Connectors-3 | USB | USB Boot on a ECU must be disable. -Connectivity-BusAndConnector-Connectors-4 | OBD-II | Must be disabled outside garages. - - - -# Wireless - -In this part, we talk about possible remote attacks on a car, according to the -different areas of possible attacks. For each communication channels, we -describe attacks and how to prevent them with some recommendations. The main -recommendation is to always follow the latest updates of these remote -communication channels. - - - -Domain | Object | Recommendations ------------------------ | ------ | ------------------------------------------------------------------ -Connectivity-Wireless-1 | Update | Always follow the latest updates of remote communication channels. - - - -We will see the following parts: - -- [Wifi](#wifi) - -- [Bluetooth](#bluetooth) - -- [Cellular](#cellular) - -- [Radio](#radio) - -- [NFC](#nfc) - - - -Domain | Improvement ------------------------ | ------------------------------------------- -Connectivity-Wireless-1 | Add communication channels (RFID, ZigBee?). - - - --------------------------------------------------------------------------------- - -For existing automotive-specific means, we take examples of existing system -attacks from the _IOActive_ document ([A Survey of Remote Automotive Attack -Surfaces](https://www.ioactive.com/pdfs/IOActive_Remote_Attack_Surfaces.pdf)) -and from the ETH document ([Relay Attacks on Passive Keyless Entry and Start -Systems in Modern Cars](https://eprint.iacr.org/2010/332.pdf)). - -- [Telematics](https://www.ioactive.com/pdfs/IOActive_Remote_Attack_Surfaces.pdf#%5B%7B%22num%22%3A40%2C%22gen%22%3A0%7D%2C%7B%22name%22%3A%22XYZ%22%7D%2C60%2C720%2C0%5D) - -- [Passive Anti-Theft System - (PATS)](https://www.ioactive.com/pdfs/IOActive_Remote_Attack_Surfaces.pdf#%5B%7B%22num%22%3A11%2C%22gen%22%3A0%7D%2C%7B%22name%22%3A%22XYZ%22%7D%2C60%2C574%2C0%5D) - -- [Tire Pressure Monitoring System - (TPMS)](https://www.ioactive.com/pdfs/IOActive_Remote_Attack_Surfaces.pdf#%5B%7B%22num%22%3A17%2C%22gen%22%3A0%7D%2C%7B%22name%22%3A%22XYZ%22%7D%2C60%2C720%2C0%5D) - -- [Remote Keyless Entry/Start - (RKE)](https://www.ioactive.com/pdfs/IOActive_Remote_Attack_Surfaces.pdf#%5B%7B%22num%22%3A26%2C%22gen%22%3A0%7D%2C%7B%22name%22%3A%22XYZ%22%7D%2C60%2C720%2C0%5D) - -- [Passive Keyless Entry (PKE)](https://eprint.iacr.org/2010/332.pdf) - --------------------------------------------------------------------------------- - - - -## Wifi - -### Attacks - -We can differentiate existing attacks on wifi in two categories: Those on -**WEP** and those on **WPA**. - -- **WEP** attacks: - - - **FMS**: (**F**luhrer, **M**antin and **S**hamir attack) is a "Stream cipher - attack on the widely used RC4 stream cipher. The attack allows an attacker - to recover the key in an RC4 encrypted stream from a large number of - messages in that stream." - - **KoreK**: "Allows the attacker to reduce the key space". - - **PTW**: (**P**yshkin **T**ews **W**einmann attack). - - **Chopchop**: Found by KoreK, "Weakness of the CRC32 checksum and the lack - of replay protection." - - **Fragmentation** - -- **WPA** attacks: - - - **Beck and Tews**: Exploit weakness in **TKIP**. "Allow the attacker to - decrypt **ARP** packets and to inject traffic into a network, even allowing - him to perform a **DoS** or an **ARP** poisoning". - - [KRACK](https://github.com/kristate/krackinfo): (K)ey (R)einstallation - (A)tta(ck) ([jira AGL - SPEC-1017](https://jira.automotivelinux.org/browse/SPEC-1017)). - -### Recommendations - -- Do not use **WEP**, **PSK** and **TKIP**. - -- Use **WPA2** with **CCMP**. - -- Should protect data sniffing. - - - -Domain | Tech name or object | Recommendations ----------------------------- | ------------------- | ------------------------------------------------------------------------- -Connectivity-Wireless-Wifi-1 | WEP, PSK, TKIP | Disabled -Connectivity-Wireless-Wifi-2 | WPA2 and AES-CCMP | Used -Connectivity-Wireless-Wifi-3 | WPA2 | Should protect data sniffing. -Connectivity-Wireless-Wifi-4 | PSK | Changing regularly the password. -Connectivity-Wireless-Wifi-5 | Device | Upgraded easily in software or firmware to have the last security update. - - - -See [Wifi attacks WEP WPA](https://matthieu.io/dl/wifi-attacks-wep-wpa.pdf) and -[Breaking wep and wpa (Beck and -Tews)](https://dl.aircrack-ng.org/breakingwepandwpa.pdf) for more information. - --------------------------------------------------------------------------------- - - - -## Bluetooth - -### Attacks - -- **Bluesnarfing** attacks involve an attacker covertly gaining access to your - Bluetooth-enabled device for the purpose of retrieving information, including - addresses, calendar information or even the device's **I**nternational - **M**obile **E**quipment **I**dentity. With the **IMEI**, an attacker could - route your incoming calls to his cell phone. -- **Bluebugging** is a form of Bluetooth attack often caused by a lack of - awareness. Similar to bluesnarfing, bluebugging accesses and uses all phone - features but is limited by the transmitting power of class 2 Bluetooth radios, - normally capping its range at 10-15 meters. -- **Bluejacking** is the sending of unsolicited messages. -- **BLE**: **B**luetooth **L**ow **E**nergy - [attacks](https://www.usenix.org/system/files/conference/woot13/woot13-ryan.pdf). -- **DoS**: Drain a device's battery or temporarily paralyze the phone. - -### Recommendations - -- Not allowing Bluetooth pairing attempts without the driver's first manually - placing the vehicle in pairing mode. -- Monitoring. -- Use **BLE** with caution. -- For v2.1 and later devices using **S**ecure **S**imple **P**airing (**SSP**), - avoid using the "Just Works" association model. The device must verify that an - authenticated link key was generated during pairing. - - - -Domain | Tech name | Recommendations ---------------------------------- | ------------- | ------------------------------------------------------------ -Connectivity-Wireless-Bluetooth-1 | BLE | Use with caution. -Connectivity-Wireless-Bluetooth-2 | Bluetooth | Monitoring -Connectivity-Wireless-Bluetooth-3 | SSP | Avoid using the "Just Works" association model. -Connectivity-Wireless-Bluetooth-4 | Visibility | Configured by default as undiscoverable. Except when needed. -Connectivity-Wireless-Bluetooth-5 | Anti-scanning | Used, inter alia, to slow down brute force attacks. - - - -See [Low energy and the automotive -transformation](http://www.ti.com/lit/wp/sway008/sway008.pdf), [Gattacking -Bluetooth Smart Devices](http://gattack.io/whitepaper.pdf), [Comprehensive -Experimental Analyses of Automotive Attack -Surfaces](http://www.autosec.org/pubs/cars-usenixsec2011.pdf) and [With Low -Energy comes Low -Security](https://www.usenix.org/system/files/conference/woot13/woot13-ryan.pdf) -for more information. - --------------------------------------------------------------------------------- - - - -## Cellular - -### Attacks - -- **IMSI-Catcher**: Is a telephone eavesdropping device used for intercepting - mobile phone traffic and tracking location data of mobile phone users. - Essentially a "fake" mobile tower acting between the target mobile phone and - the service provider's real towers, it is considered a man-in-the-middle - (**MITM**) attack. - -- Lack of mutual authentication (**GPRS**/**EDGE**) and encryption with - **GEA0**. - -- **Fall back** from **UMTS**/**HSPA** to **GPRS**/**EDGE** (Jamming against - **UMTS**/**HSPA**). - -- 4G **DoS** attack. - -### Recommendations - -- Check antenna legitimacy. - - - -Domain | Tech name | Recommendations --------------------------------- | --------- | -------------------------- -Connectivity-Wireless-Cellular-1 | GPRS/EDGE | Avoid -Connectivity-Wireless-Cellular-2 | UMTS/HSPA | Protected against Jamming. - - - -See [A practical attack against GPRS/EDGE/UMTS/HSPA mobile data -communications](https://media.blackhat.com/bh-dc-11/Perez-Pico/BlackHat_DC_2011_Perez-Pico_Mobile_Attacks-wp.pdf) -for more information. - --------------------------------------------------------------------------------- - -## Radio - -### Attacks - -- Interception of data with low cost material (**SDR** with hijacked DVB-T/DAB - for example). - -### Recommendations - -- Use the **R**adio **D**ata **S**ystem (**RDS**) only to send signals for audio - output and meta concerning radio. - - - -Domain | Tech name | Recommendations ------------------------------ | --------- | -------------------------------------------- -Connectivity-Wireless-Radio-1 | RDS | Only audio output and meta concerning radio. - - - --------------------------------------------------------------------------------- - - - -## NFC - -### Attacks - -- **MITM**: Relay and replay attack. - -### Recommendations - -- Should implements protection against relay and replay attacks (Tokens, - etc...). -- Disable unneeded and unapproved services and profiles. -- NFC should be use encrypted link (secure channel). A standard key agreement - protocol like Diffie-Hellmann based on RSA or Elliptic Curves could be applied - to establish a shared secret between two devices. -- Automotive NFC device should be certified by NFC forum entity: The NFC Forum - Certification Mark shows that products meet global interoperability standards. -- NFC Modified Miller coding is preferred over NFC Manchester coding. - - - -Domain | Tech name | Recommendations ---------------------------- | --------- | ------------------------------------------------------ -Connectivity-Wireless-NFC-1 | NFC | Protected against relay and replay attacks. -Connectivity-Wireless-NFC-2 | Device | Disable unneeded and unapproved services and profiles. - - - -# Cloud - -## Download - -- **authentication**: Authentication is the security process that validates the - claimed identity of a device, entity or person, relying on one or more - characteristics bound to that device, entity or person. - -- **Authorization**: Parses the network to allow access to some or all network - functionality by providing rules and allowing access or denying access based - on a subscriber's profile and services purchased. - - - -Domain | Object | Recommendations ----------------------------- | -------------- | -------------------------------------- -Application-Cloud-Download-1 | authentication | Must implement authentication process. -Application-Cloud-Download-2 | Authorization | Must implement Authorization process. - - - --------------------------------------------------------------------------------- - -## Infrastructure - -- **Deep Packet Inspection**: **DPI** provides techniques to analyze the payload - of each packet, adding an extra layer of security. **DPI** can detect and - neutralize attacks that would be missed by other security mechanisms. - -- A **DoS** protection in order to avoid that the Infrastructure is no more - accessible for a period of time. - -- **Scanning tools** such as **SATS** and **DAST** assessments perform - vulnerability scans on the source code and data flows on web applications. - Many of these scanning tools run different security tests that stress - applications under certain attack scenarios to discover security issues. - -- **IDS & IPS**: **IDS** detect and log inappropriate, incorrect, or anomalous - activity. **IDS** can be located in the telecommunications networks and/or - within the host server or computer. Telecommunications carriers build - intrusion detection capability in all network connections to routers and - servers, as well as offering it as a service to enterprise customers. Once - **IDS** systems have identified an attack, **IPS** ensures that malicious - packets are blocked before they cause any harm to backend systems and - networks. **IDS** typically functions via one or more of three systems: - - 1. Pattern matching. - 2. Anomaly detection. - 3. Protocol behavior. - - - - - -Domain | Object | Recommendations ----------------------------------- | ------------- | ---------------------------------------------------------- -Application-Cloud-Infrastructure-1 | Packet | Should implement a DPI. -Application-Cloud-Infrastructure-2 | DoS | Must implement a DoS protection. -Application-Cloud-Infrastructure-3 | Test | Should implement scanning tools like SATS and DAST. -Application-Cloud-Infrastructure-4 | Log | Should implement security tools (IDS and IPS). -Application-Cloud-Infrastructure-5 | App integrity | Applications must be signed by the code signing authority. - - - --------------------------------------------------------------------------------- - -## Transport - -For data transport, it is necessary to **encrypt data end-to-end**. To prevent -**MITM** attacks, no third party should be able to interpret transported data. -Another aspect is the data anonymization in order to protect the leakage of -private information on the user or any other third party. - -The use of standards such as **IPSec** provides "_private and secure -communications over IP networks, through the use of cryptographic security -services, is a set of protocols using algorithms to transport secure data over -an IP network._". In addition, **IPSec** operates at the network layer of the -**OSI** model, contrary to previous standards that operate at the application -layer. This makes its application independent and means that users do not need -to configure each application to **IPSec** standards. - -**IPSec** provides the services below : - -- Confidentiality: A service that makes it impossible to interpret data if it is - not the recipient. It is the encryption function that provides this service by - transforming intelligible (unencrypted) data into unintelligible (encrypted) - data. -- Authentication: A service that ensures that a piece of data comes from where - it is supposed to come from. -- Integrity: A service that consists in ensuring that data has not been tampered - with accidentally or fraudulently. -- Replay Protection: A service that prevents attacks by re-sending a valid - intercepted packet to the network for the same authorization. This service is - provided by the presence of a sequence number. -- Key management: Mechanism for negotiating the length of encryption keys - between two **IPSec** elements and exchange of these keys. - -An additional means of protection would be to do the monitoring between users -and the cloud as a **CASB** will provide. - - - -Domain | Object | Recommendations ------------------------------ | ----------------------------------------- | --------------------------------- -Application-Cloud-Transport-1 | Integrity, confidentiality and legitimacy | Should implement IPSec standards. - diff --git a/docs/2_Architecture_Guides/2_Security_Blueprint/8_Update_OTA.md b/docs/2_Architecture_Guides/2_Security_Blueprint/8_Update_OTA.md deleted file mode 100644 index 60ae8e4..0000000 --- a/docs/2_Architecture_Guides/2_Security_Blueprint/8_Update_OTA.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -title: Update (Over The Air) ---- - -Updating applications and firmware is essential for the development of new -features and even more to fix security bugs. However, if a malicious third party -manages to alter the content during transport, it could alter the functioning of -the system and/or applications. The security of the updates is therefore a -critical point to evaluate in order to guarantee the integrity, the -confidentiality and the legitimacy of the transmitted data. - -## Attack Vectors - -Updates Over The Air are one of the most common points where an attacker will -penetrate. An OTA update mechanism is one of the highest threats in the system. -If an attacker is able to install his own application or firmware on the system, -he can get the same level of access that the original application or firmware -had. From that point, the intruder can get unfettered access to the rest of the -system, which might include making modifications, downloading other pieces of -software, and stealing assets. - -### Man In The Middle (MITM) - -The man-in-the-middle attack is the most classic example of an attack, where an -adversary inserts himself between two communicating entities and grabs whatever -is being communicated. In the case of OTA attacks, the connection in the network -may be intercepted: - -* On the internet, before the cloud back-end. -* At the base station, 3G,4G,5G connection to the internet. -* At the receiving antenna, connection to the car. -* Between the receiving antenna and the gateway router (if present), connection - within the car. -* Between the gateway router and the target component (IVI, In-Vehicle - Infotainment unit). - -There are many ways to mount a MITM attack. For example, proxy tools like Burp -Proxy can be used to intercept web traffic as a man-in-the-middle. Under the -guise of being a testing tool, the proxy server is often used in attack -scenarios. It runs on a variety of platforms. - -As another example, false base station attacks are known to be fairly easy to -set-up. The problem is apparently fairly prevalent in countries like China and -in the UK. These fake base stations are sometimes just eavesdropping on the -communication, but others have the potential to do serious harm. - -Defenses against MITM attacks include encrypted and signed data pipes. -Furthermore, architects and developers are also recommended to encrypt and sign -the payloads that are being passed over these pipes, to defend against perusal -of the data. - -### Man At The End (MATE) - -The man-at-the-end attack is when an intruder analyzes the end-point of the -communication when software is accessing the data communication. This is a more -severe attack type where the attacker can: - -* Steal keys. - * For example, a simple debugging session in running software could reveal a - key used in memory. -* Tamper software. - * For example, replacing just one function call in software with a NOP (i.e. - no operation) can drastically change the behavior of the program. -* Jam branches of control. - * For example, making a program take one branch of control rather than the - intended branch can mean the difference between an authorized and a - non-authorized installation. -* Modify important data. - * For example, if the data changed is a key or data leading to a control path, - then this attack can be severe. - * In the case of OTA updates, MATE attacks are particularly problematic for - the system. One of the consequences of MATE attacks can be installed - software that allows installation of any other software. For example, an - attacker might install remote access software to control any part of the - system. - --------------------------------------------------------------------------------- - -## Acronyms and Abbreviations - -The following table lists the terms utilized within this part of the document. - -Acronyms or Abbreviations | Description -------------------------- | ------------------------------------------------------------------------- -_FOTA_ | **F**irmware **O**ver **T**he **A**ir -_MATE_ | **M**an **A**t **T**he **E**nd -_MITM_ | **M**an **I**n **T**he **M**iddle -_OTA_ | **O**ver **T**he **A**ir -_SOTA_ | **S**oftware **O**ver **T**he **A**ir -_TUF_ | **T**he **U**pdate **F**ramework - -# Firmware Over The Air - -The firmware update is critical since its alteration back to compromise the -entire system. It is therefore necessary to take appropriate protective -measures. - -AGL includes the _meta-updater_ Yocto layer that enables OTA software updates -via [Uptane](https://uptane.github.io), an automotive-specific extension to [The -Update Framework](https://theupdateframework.github.io/). Uptane and TUF are -open standards that define a secure protocol for delivering and verifying -updates even when the servers and network--internet and car-internal--aren't -fully trusted. - -_meta-updater_ includes the application -[`aktualizr`](https://github.com/advancedtelematic/aktualizr), developed -Advanced Telematic Systems (now part of HERE Technologies) that enables OTA for -an ECU. `aktualizr` combined with Uptane is suitable for updating the firmware, -software, and other packages on even functionally critical ECUs. `aktualizr` can -be enabled with the free, open souce backend -[`ota-community-edition`](https://github.com/advancedtelematic/ota-community-edition). - -This FOTA update mechanism can be enabled through the `agl-sota` feature. - -## Building - -To build an AGL image that uses `aktualizr`, the following can be used. - -``` -source meta-agl/scripts/aglsetup.sh -m agl-sota -``` - -During the build, _meta-updater_ will use credentials downloaded from -`ota-community-edition` to sign metadata verifying the build as authentic. These -signatures are part of the Uptane framework and are used to verify FOTA updates. - -## Atomic Upgrades with Rollbacks - -`aktualizr`'s primary method of updating firmware is to use `libostree` with -binary diffs. The binary diffs use the least amout of bandwidth, and by it's -nature `libostree` stores current and previous firmware versions on disk or in -flash memory to allow for rollbacks. - -`libostree` is a content addressable object store much like `git`. Versions are -specified via SHA2-256. These hashes are signed in the Uptane metadata and are -robust against cryptographic compromise. - -# Software Over The Air - -Software updates in connected vehicles are a very useful feature, which can -deliver significant benefits. If not implemented with security in mind, software -updates can incur serious vulnerabilities. Any software update system must -ensure that not only are the software updates to devices done in a secure way, -but also that the repositories and servers hosting these updates are adequately -protected. As the process of updating software migrates from a Dealership update -model towards an **OTA** update model, securing these processes becomes a high -priority. - -**SOTA** is made possible by **AppFw** (See Platform part). It will be possible -to manage in a simple way the packets (i.g. Android like). - -Domain | Improvement -------------- | ----------------- -Update-SOTA-1 | Part to complete. \ No newline at end of file diff --git a/docs/2_Architecture_Guides/2_Security_Blueprint/9_Secure_development.md b/docs/2_Architecture_Guides/2_Security_Blueprint/9_Secure_development.md deleted file mode 100644 index 9cbe3b4..0000000 --- a/docs/2_Architecture_Guides/2_Security_Blueprint/9_Secure_development.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: Secure development ---- - -In order to save a lot of time in code auditing, developers must follow coding -guidelines. - -## Secure build - -### Kernel build - -Tools like: - -- [Code optimisation](https://github.com/jduck/lk-reducer). -- [Kernel Drivers test](https://github.com/ucsb-seclab/dr_checker) with - [docs](https://www.usenix.org/system/files/conference/usenixsecurity17/sec17-machiry.pdf). - -Domain | Improvement ------------------------ | ------------ -SecureDev-SecureBuild-1 | Add content. - -## App/Widget signatures - -Domain | Improvement ----------------------- | ------------ -SecureDev-Signatures-1 | Add content. - -## Code audit - -These tools are used to check the correct implementation of functionalities and -compliance with related good practices. - -- [Continuous Code Quality](https://www.sonarqube.org/). - -Domain | Improvement ---------------------- | ----------------------------------------------------- -SecureDev-CodeAudit-1 | Add CVE analyser. -SecureDev-CodeAudit-2 | [OSSTMM](http://www.isecom.org/mirror/OSSTMM.3.pdf). - -### SATS - -- [RATS](https://github.com/andrew-d/rough-auditing-tool-for-security) (Maybe to - old). -- [Flaw Finder](https://www.dwheeler.com/flawfinder/). - -- [wiki - list](https://en.wikipedia.org/wiki/List_of_tools_for_static_code_analysis). - -- [Mathematical - approach](https://perso.univ-rennes1.fr/david.lubicz/planches/David_Pichardie.pdf). - -It is necessary to verify that the application code does not use functions that -are depreciated and recognized as unsecured or cause problems. - -### DATS - -- [wiki - list](https://en.wikipedia.org/wiki/Dynamic_program_analysis#Example_tools). \ No newline at end of file diff --git a/docs/2_Architecture_Guides/2_Security_Blueprint/Annexes.md b/docs/2_Architecture_Guides/2_Security_Blueprint/Annexes.md deleted file mode 100644 index c279203..0000000 --- a/docs/2_Architecture_Guides/2_Security_Blueprint/Annexes.md +++ /dev/null @@ -1,578 +0,0 @@ ---- -title: Annexes ---- - -The first part resumed all the configurations you must implement without any -explications since all the explanations are given as and when in the document. - -- The _config_ tag quickly identifies the configurations and the recommendations - to take. - -- The _note_ tag allows you to notify some additional details. - -- The _todo_ tag shows the possible improvements. - -The second one allows to visualize all the todo notes in order to have a global -vision of the possible improvements of the document. - -# Config notes - - -Domain | Object | Recommendations --------------------- | ---------- | ---------------------------------- -Hardware-Integrity-1 | Bootloader | Must control bootloader integrity. -Hardware-Integrity-2 | Board | Must use a HSM. -Hardware-Integrity-3 | RTC | Must not be alterable. - -Domain | Object | Recommendations ----------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- -Hardware-Certificate-1 | System | Shall allow storing dedicated certificates. -Hardware-Certificate-2 | ECU | The ECU must verify the certification authority hierarchy. -Hardware-Certificate-3 | System | Allow the modification of certificates only if the source can be authenticated by a certificate already stored or in the higher levels of the chain of trust. - -Domain | Object | Recommendations ------------------ | ---------- | ------------------------------------------------------------------------------------ -Hardware-Memory-1 | ECU | The ECU shall never expose the unencrypted key in RAM when using cryptographic keys. -Hardware-Memory-2 | Bootloader | Internal NVM only -Hardware-Module-3 | - | HSM must be used to secure keys. - -Domain | _Variable_ / `Config` name | `Value` ----------------------- | -------------------------- | ------- -Boot-Image-Selection-1 | `CONFIG_BOOTDELAY` | `-2` -Boot-Image-Selection-2 | _bootdelay_ | `-2` - -Domain | `Config` name | _State_ -------------------------- | ---------------------------- | -------- -Boot-Image-Authenticity-1 | `CONFIG_FIT` | _Enable_ -Boot-Image-Authenticity-2 | `CONFIG_FIT_SIGNATURE` | _Enable_ -Boot-Image-Authenticity-3 | `CONFIG_RSA` | _Enable_ -Boot-Image-Authenticity-4 | `CONFIG_OF_CONTROL` | _Enable_ -Boot-Image-Authenticity-5 | `CONFIG_OF_SEPARATE` | _Enable_ -Boot-Image-Authenticity-6 | `CONFIG_DEFAULT_DEVICE_TREE` | _Enable_ - -Domain | Communication modes | _State_ --------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- -Boot-Communication-1 | `USB` | _Disabled_ and _Compiled-out_ if not required. -Boot-Communication-2 | `USB` | Else, Kernel should be configured to only enable the minimum required USB devices and filesystems should be treated with special care. -Boot-Communication-3 | `Ethernet` | _Disabled_ -Boot-Communication-4 | U-boot and sboot `DOCSIS` | _Disabled_ -Boot-Communication-5 | `Serial ports` | _Disabled_ - -Domain | `Config` name | _State_ ------------------------- | ----------------------- | ------------- -Boot-Communication-USB-1 | `CONFIG_CMD_USB` | _Not defined_ -Boot-Communication-USB-2 | `CONFIG_USB_UHCI` | _Not defined_ -Boot-Communication-USB-3 | `CONFIG_USB_KEYBOARD` | _Not defined_ -Boot-Communication-USB-4 | `CONFIG_USB_STORAGE` | _Not defined_ -Boot-Communication-USB-5 | `CONFIG_USB_HOST_ETHER` | _Not defined_ - -Domain | Communication modes | _State_ --------------------- | -------------------- | --------------------------------------------------------------------------------------------- -Boot-Communication-1 | `Network interfaces` | Preferably _no network interface is allowed_, otherwise, restrict the services to those used. - -Domain | Object | Recommendations --------------------- | --------------------------------- | ------------------------------------------------------------- -Boot-Communication-1 | `Services`, `ports` and `devices` | Restrict the `services`, `ports` and `devices` to those used. - -Domain | `Command` name | _State_ --------------------------- | -------------- | --------- -Boot-Communication-Flash-1 | `do_nand` | _Disable_ - -Domain | `Config` name | `Value` ----------------------- | --------------------------------------- | --------- -Boot-Consoles-Serial-1 | `CONFIG_SILENT_CONSOLE` | `Disable` -Boot-Consoles-Serial-2 | `CONFIG_SYS_DEVICE_NULLDEV` | `Disable` -Boot-Consoles-Serial-3 | `CONFIG_SILENT_CONSOLE_UPDATE_ON_RELOC` | `Disable` - -Domain | `Environment variable` name | _State_ ----------------------- | --------------------------- | ------------- -Boot-Consoles-Serial-1 | `INC_DEBUG_PRINT` | _Not defined_ - -Domain | `Config` name | _State_ --------------------------- | ---------------------------- | --------- -Boot-Consoles-Variables-1 | `CONFIG_ENV_IS_IN_MMC` | `#undef` -Boot-Consoles-Variables-2 | `CONFIG_ENV_IS_IN_EEPROM` | `#undef` -Boot-Consoles-Variables-3 | `CONFIG_ENV_IS_IN_FLASH` | `#undef` -Boot-Consoles-Variables-4 | `CONFIG_ENV_IS_IN_DATAFLASH` | `#undef` -Boot-Consoles-Variables-5 | `CONFIG_ENV_IS_IN_FAT` | `#undef` -Boot-Consoles-Variables-6 | `CONFIG_ENV_IS_IN_NAND` | `#undef` -Boot-Consoles-Variables-7 | `CONFIG_ENV_IS_IN_NVRAM` | `#undef` -Boot-Consoles-Variables-8 | `CONFIG_ENV_IS_IN_ONENAND` | `#undef` -Boot-Consoles-Variables-9 | `CONFIG_ENV_IS_IN_SPI_FLASH` | `#undef` -Boot-Consoles-Variables-10 | `CONFIG_ENV_IS_IN_REMOTE` | `#undef` -Boot-Consoles-Variables-11 | `CONFIG_ENV_IS_IN_UBI` | `#undef` -Boot-Consoles-Variables-12 | `CONFIG_ENV_IS_NOWHERE` | `#define` - -Domain | `Command` name | _State_ ------------------------ | -------------- | ---------- -Boot-Consoles-MemDump-1 | `md` | _Disabled_ -Boot-Consoles-MemDump-2 | `mm` | _Disabled_ -Boot-Consoles-MemDump-3 | `nm` | _Disabled_ -Boot-Consoles-MemDump-4 | `mw` | _Disabled_ -Boot-Consoles-MemDump-5 | `cp` | _Disabled_ -Boot-Consoles-MemDump-6 | `mwc` | _Disabled_ -Boot-Consoles-MemDump-7 | `mdc` | _Disabled_ -Boot-Consoles-MemDump-8 | `mtest` | _Disabled_ -Boot-Consoles-MemDump-9 | `loopw` | _Disabled_ - -Domain | `Config` name | `Value` --------------------- | -------------- | -------------------------------------- -Kernel-General-MAC-1 | CONFIG_IP_NF_SECURITY | m -Kernel-General-MAC-2 | CONFIG_IP6_NF_SECURITY | m -Kernel-General-MAC-3 | CONFIG_EXT2_FS_SECURITY | y -Kernel-General-MAC-4 | CONFIG_EXT3_FS_SECURITY | y -Kernel-General-MAC-5 | CONFIG_EXT4_FS_SECURITY | y -Kernel-General-MAC-6 | CONFIG_SECURITY | y -Kernel-General-MAC-7 | CONFIG_SECURITY_SMACK | y -Kernel-General-MAC-8 | CONFIG_TMPFS_XATTR | y - -Domain | `Config` name | `Value` ----------------------- | -------------- | ------- -Kernel-General-kexec-1 | `CONFIG_KEXEC` | `n` - -Domain | `Config` name | `Value` ---------------------------- | --------------- | ------- -Kernel-General-IPAutoConf-1 | `CONFIG_IP_PNP` | `n` - -Domain | `Config` name | `Value` -------------------------------- | ----------------------- | ------- -Kernel-General-SysCtl_SysCall-1 | `CONFIG_SYSCTL_SYSCALL` | `n` - -Domain | `Config` name | `Value` ----------------------------- | --------------- | ------- -Kernel-General-LegacyLinux-1 | `CONFIG_USELIB` | `n` - -Domain | `Config` name | `Value` ---------------------------- | ------------------------------ | ------- -Kernel-General-FirmHelper-1 | `CONFIG_FW_LOADER_USER_HELPER` | `n` - -Domain | `Config` name | `Value` ----------------------------- | ---------------------- | ------- -Kernel-General-PanicOnOOPS-1 | `CONFIG_PANIC_ON_OOPS` | `y` - -Domain | `Config` name | `Value` --------------------------- | -------------------- | ------- -Kernel-General-SocketMon-1 | `CONFIG_PACKET_DIAG` | `n` -Kernel-General-SocketMon-2 | `CONFIG_UNIX_DIAG` | `n` - -Domain | `Config` name | `Value` ------------------------- | ---------------- | ------- -Kernel-General-BPF_JIT-1 | `CONFIG_BPF_JIT` | `n` - -Domain | `Config` name | `Value` ------------------------------- | ------------------------- | ------- -Kernel-General-ModuleSigning-1 | `CONFIG_MODULE_SIG_FORCE` | `y` - -Domain | `Variable` name | `Value` ------------------------------- | ------------------------- | ------- -Kernel-General-ModuleSigning-2 | `kernel.modules_disabled` | `1` - -Domain | Object | _State_ ------------------------- | ------------------- | ---------- -Kernel-General-Drivers-1 | `USB` | _Disabled_ -Kernel-General-Drivers-2 | `PCMCIA` | _Disabled_ -Kernel-General-Drivers-3 | Other `hotplug` bus | _Disabled_ - -Domain | `compiler` and `linker` options | _State_ --------------------------------- | ------------------------------- | -------- -Kernel-General-IndependentExec-1 | `-pie -fpic` | _Enable_ - -Domain | `compiler` and `linker` options | _State_ ---------------------------------- | ------------------------------- | -------- -Kernel-General-OverwriteAttacks-1 | `-z,relro` | _Enable_ -Kernel-General-OverwriteAttacks-2 | `-z,now` | _Enable_ - -Domain | Object | Recommendations -------------------------------- | --------------- | -------------------------------- -Kernel-General-LibraryLinking-1 | Dynamic linking | Should generally not be allowed. - -Domain | `Config` name | `Value` ------------------------------- | ---------------- | ------- -Kernel-Memory-RestrictAccess-1 | `CONFIG_DEVKMEM` | `n` - -Domain | `Config` name | `Value` ------------------------- | ------------------- | ------- -Kernel-Memory-CoreDump-1 | `CONFIG_PROC_KCORE` | `n` - -Domain | `Config` name | `Value` --------------------- | ------------- | ------- -Kernel-Memory-Swap-1 | `CONFIG_SWAP` | `n` - -Domain | `Config` name | `Value` ------------------------------- | --------------------- | ------- -Kernel-Memory-LoadAllSymbols-1 | `CONFIG_KALLSYMS` | `n` -Kernel-Memory-LoadAllSymbols-2 | `CONFIG_KALLSYMS_ALL` | `n` - -Domain | `Config` name | `Value` ---------------------- | -------------------------- | ------- -Kernel-Memory-Stack-1 | `CONFIG_CC_STACKPROTECTOR` | `y` - -Domain | `Config` name | `Value` ----------------------- | --------------- | ------- -Kernel-Memory-Access-1 | `CONFIG_DEVMEM` | `n` - -Domain | `Config` name | `Value` ------------------------------- | --------------------- | ------- -Kernel-Memory-CrossMemAttach-1 | `CROSS_MEMORY_ATTACH` | `n` - -Domain | `compiler` and `linker` options | _State_ ------------------------------ | ------------------------------- | -------- -Kernel-Memory-StackSmashing-1 | `-fstack-protector-all` | _Enable_ - -Domain | `compiler` options and `config` name | `Value` -------------------------------- | ------------------------------------ | ------- -Kernel-Memory-BufferOverflows-1 | `-D_FORTIFY_SOURCE` | `2` -Kernel-Memory-BufferOverflows-2 | `CONFIG_FORTIFY_SOURCE` | `y` - -Domain | `Config` name | `Value` ------------------------- | ---------------------------- | ------- -Kernel-Consoles-Serial-1 | `CONFIG_SERIAL_8250` | `n` -Kernel-Consoles-Serial-2 | `CONFIG_SERIAL_8250_CONSOLE` | `n` -Kernel-Consoles-Serial-3 | `CONFIG_SERIAL_CORE` | `n` -Kernel-Consoles-Serial-4 | `CONFIG_SERIAL_CORE_CONSOLE` | `n` - -Domain | `Config` name | `Value` ------------------------------ | ------------------------- | ----------------------------------- -Kernel-Consoles-CommandLine-1 | `CONFIG_CMDLINE_BOOL` | `y` -Kernel-Consoles-CommandLine-2 | `CONFIG_CMDLINE` | `"insert kernel command line here"` -Kernel-Consoles-CommandLine-3 | `CONFIG_CMDLINE_OVERRIDE` | `y` - -Domain | `Config` name | `Value` ----------------------- | ------------- | ------- -Kernel-Consoles-KDBG-1 | `CONFIG_KGDB` | `n` - -Domain | `Config` name | `Value` ------------------------ | -------------------- | ------- -Kernel-Consoles-SysRQ-1 | `CONFIG_MAGIC_SYSRQ` | `n` - -Domain | `Config` name | `Value` ------------------------------- | -------------------- | ------- -Kernel-Consoles-BinaryFormat-1 | `CONFIG_BINFMT_MISC` | `n` - -Domain | `Config` name | `Value` ----------------------- | ------------------- | ------- -Kernel-Debug-Symbols-1 | `CONFIG_DEBUG_INFO` | `n` - -Domain | `Config` name | `Value` ----------------------- | ---------------- | ------- -Kernel-Debug-Kprobes-1 | `CONFIG_KPROBES` | `n` - -Domain | `Config` name | `Value` ----------------------- | --------------- | ------- -Kernel-Debug-Tracing-1 | `CONFIG_FTRACE` | `n` - -Domain | `Config` name | `Value` ------------------------- | ------------------ | ------- -Kernel-Debug-Profiling-1 | `CONFIG_OPROFILE` | `n` -Kernel-Debug-Profiling-2 | `CONFIG_PROFILING` | `n` - -Domain | `Config` name | `Value` ------------------------- | ------------------------- | ------- -Kernel-Debug-OOPSOnBUG-1 | `CONFIG_DEBUG_BUGVERBOSE` | `n` - -Domain | `Config` name | `Value` ------------------- | --------------------- | ------- -Kernel-Debug-Dev-1 | `CONFIG_DEBUG_KERNEL` | `n` -Kernel-Debug-Dev-2 | `CONFIG_EMBEDDED` | `n` - -Domain | `Config` name | `Value` -------------------------- | ----------------- | ------- -Kernel-Debug-FileSystem-1 | `CONFIG_DEBUG_FS` | `n` - -Domain | `Config` name | `Value` ------------------- | ------------- | ------- -Kernel-Debug-BUG-1 | `CONFIG_BUG` | `n` - -Domain | `Config` name | `Value` ------------------------- | ----------------- | ------- -Kernel-Debug-CoreDumps-1 | `CONFIG_COREDUMP` | `n` - -Domain | `File` name | `Value` ----------------------------- | -------------------------------- | ------- -Kernel-Debug-AdressDisplay-1 | `/proc/sys/kernel/kptr_restrict` | `1` - -Domain | `File` or `Directorie` name | _State_ ----------------------------- | --------------------------- | ----------------------------- -Kernel-Debug-AdressDisplay-1 | `/boot/vmlinuz*` | _Readable Only for root user_ -Kernel-Debug-AdressDisplay-2 | `/boot/System.map*` | _Readable Only for root user_ -Kernel-Debug-AdressDisplay-3 | `/sys/kernel/debug/` | _Readable Only for root user_ -Kernel-Debug-AdressDisplay-4 | `/proc/slabinfo` | _Readable Only for root user_ - -Domain | `File` name | `Value` --------------------- | --------------------------------- | ------- -Kernel-Debug-DMESG-1 | `/proc/sys/kernel/dmesg_restrict` | `1` - -Domain | `Config` name | `Value` ---------------------- | ----------------- | ------- -Kernel-Debug-Config-1 | `CONFIG_IKCONFIG` | `n` - -Domain | `Config` name | `Value` ------------------------- | --------------- | ------- -Kernel-FileSystems-NFS-1 | `CONFIG_NFSD` | `n` -Kernel-FileSystems-NFS-2 | `CONFIG_NFS_FS` | `n` - -Domain | `Partition` | `Value` --------------------------- | ------------------- | ----------------------------------------------------------------- -Kernel-FileSystems-Mount-1 | `/boot` | `nosuid`, `nodev` and `noexec`. -Kernel-FileSystems-Mount-2 | `/var` & `/tmp` | In `/etc/fstab` or `vfstab`, add `nosuid`, `nodev` and `noexec`. -Kernel-FileSystems-Mount-3 | _Non-root local_ | If type is `ext2` or `ext3` and mount point not '/', add `nodev`. -Kernel-FileSystems-Mount-4 | _Removable storage_ | Add `nosuid`, `nodev` and `noexec`. -Kernel-FileSystems-Mount-5 | _Temporary storage_ | Add `nosuid`, `nodev` and `noexec`. -Kernel-FileSystems-Mount-6 | `/dev/shm` | Add `nosuid`, `nodev` and `noexec`. -Kernel-FileSystems-Mount-7 | `/dev` | Add `nosuid` and `noexec`. - -Domain | `Config` name | _State_ or `Value` --------------------------- | ----------------------- | ----------------------------------------------------------------------- -Kernel-FileSystems-Mount-1 | `CONFIG_DEVTMPFS_MOUNT` | _Disabled_ or add remount with `noexec` and `nosuid` to system startup. - -Domain | `Label` name | Recommendations ------------------- | ------------ | ----------------------------------------------------------- -Kernel-MAC-Floor-1 | `^` | Only for privileged system services. -Kernel-MAC-Floor-2 | `*` | Used for device files or `/tmp` Access restriction via DAC. - -Domain | `Label` name | Recommendations -------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------- -Kernel-MAC-System-1 | `System` | Process should write only to file with transmute attribute. -Kernel-MAC-System-2 | `System::run` | Files are created with the directory label from user and system domain (transmute) Lock is implicit with `w`. -Kernel-MAC-System-3 | `System::Shared` | Files are created with the directory label from system domain (transmute) User domain has locked privilege. -Kernel-MAC-System-4 | `System::Log` | Some limitation may impose to add `w` to enable append. -Kernel-MAC-System-5 | `System::Sub` | Isolation of risky Subsystem. - -Domain | `Label` name | Recommendations -------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- -Kernel-MAC-System-1 | `User::Pkg::$AppID` | Only one Label is allowed per App. A data directory is created by the AppFw in `rwx` mode. -Kernel-MAC-System-2 | `User::Home` | AppFw needs to create a directory in `/home/$USER/App-Shared` at first launch if not present with label app-data access is `User::App-Shared` without transmute. -Kernel-MAC-System-3 | `User::App-Shared` | Shared space between all App running for a given user. - -Domain | Object | Recommendations ------------------- | -------------- | ------------------------------------ -Platform-SystemD-1 | Security model | Use Namespaces for containerization. -Platform-SystemD-2 | Security model | Use CGroups to organise processes. - -Domain | Object | Recommendations ---------------- | -------------- | ------------------------------------ -Platform-DBus-1 | Security model | Use D-Bus as IPC. -Platform-DBus-2 | Security model | Apply D-BUS security patches: [D-Bus CVE](https://www.cvedetails.com/vulnerability-list/vendor_id-13442/D-bus-Project.html) - -Domain | `Tool` name | _State_ --------------------- | ----------- | ------- -Platform-Utilities-1 | `connman` | _Used_ as a connection manager. -Platform-Utilities-2 | `bluez` | _Used_ as a Bluetooth manager. -Platform-Utilities-3 | `gstreamer` | _Used_ to manage multimedia file format. -Platform-Utilities-4 | `alsa` | _Used_ to provides an API for sound card device drivers. - -Domain | Object | Recommendations ----------------------- | -------------- | -------------------------------- -Platform-AGLFw-AppFw-1 | Security model | Use the AppFw as Security model. - -Domain | Object | Recommendations ------------------------ | ----------- | ------------------------------------- -Platform-AGLFw-Cynara-1 | Permissions | Use Cynara as policy-checker service. - -Domain | `Tool` name | _State_ --------------------- | ----------- | ---------------------------------------------------------------------- -Platform-Utilities-1 | `busybox` | _Used_ to provide a number of tools. Do not compile development tools. - -Domain | `Utility` name and normal `path` | _State_ ---------------------- | ---------------------------------------------------- | ---------- -Platform-Utilities-1 | `chgrp` in `/bin/chgrp` | _Disabled_ -Platform-Utilities-2 | `chmod` in `/bin/chmod` | _Disabled_ -Platform-Utilities-3 | `chown` in `/bin/chown` | _Disabled_ -Platform-Utilities-4 | `dmesg` in `/bin/dmesg` | _Disabled_ -Platform-Utilities-5 | `Dnsdomainname` in `/bin/dnsdomainname` | _Disabled_ -Platform-Utilities-6 | `dropbear`, Remove "dropbear" from `/etc/init.d/rcs` | _Disabled_ -Platform-Utilities-7 | `Editors` in (vi) `/bin/vi` | _Disabled_ -Platform-Utilities-8 | `find` in `/bin/find` | _Disabled_ -Platform-Utilities-9 | `gdbserver` in `/bin/gdbserver` | _Disabled_ -Platform-Utilities-10 | `hexdump` in `/bin/hexdump` | _Disabled_ -Platform-Utilities-11 | `hostname` in `/bin/hostname` | _Disabled_ -Platform-Utilities-12 | `install` in `/bin/install` | _Disabled_ -Platform-Utilities-13 | `iostat` in `/bin/iostat` | _Disabled_ -Platform-Utilities-14 | `killall` in `/bin/killall` | _Disabled_ -Platform-Utilities-15 | `klogd` in `/sbin/klogd` | _Disabled_ -Platform-Utilities-16 | `logger` in `/bin/logger` | _Disabled_ -Platform-Utilities-17 | `lsmod` in `/sbin/lsmod` | _Disabled_ -Platform-Utilities-18 | `pmap` in `/bin/pmap` | _Disabled_ -Platform-Utilities-19 | `ps` in `/bin/ps` | _Disabled_ -Platform-Utilities-20 | `ps` in `/bin/ps` | _Disabled_ -Platform-Utilities-21 | `rpm` in `/bin/rpm` | _Disabled_ -Platform-Utilities-22 | `SSH` | _Disabled_ -Platform-Utilities-23 | `stbhotplug` in `/sbin/stbhotplug` | _Disabled_ -Platform-Utilities-24 | `strace` in `/bin/trace` | _Disabled_ -Platform-Utilities-25 | `su` in `/bin/su` | _Disabled_ -Platform-Utilities-26 | `syslogd` in (logger) `/bin/logger` | _Disabled_ -Platform-Utilities-27 | `top` in `/bin/top` | _Disabled_ -Platform-Utilities-28 | `UART` in `/proc/tty/driver/` | _Disabled_ -Platform-Utilities-29 | `which` in `/bin/which` | _Disabled_ -Platform-Utilities-30 | `who` and `whoami` in `/bin/whoami` | _Disabled_ -Platform-Utilities-31 | `awk` (busybox) | _Enabled_ -Platform-Utilities-32 | `cut` (busybox) | _Enabled_ -Platform-Utilities-33 | `df` (busybox) | _Enabled_ -Platform-Utilities-34 | `echo` (busybox) | _Enabled_ -Platform-Utilities-35 | `fdisk` (busybox) | _Enabled_ -Platform-Utilities-36 | `grep` (busybox) | _Enabled_ -Platform-Utilities-37 | `mkdir` (busybox) | _Enabled_ -Platform-Utilities-38 | `mount` (vfat) (busybox) | _Enabled_ -Platform-Utilities-39 | `printf` (busybox) | _Enabled_ -Platform-Utilities-40 | `sed` in `/bin/sed` (busybox) | _Enabled_ -Platform-Utilities-41 | `tail` (busybox) | _Enabled_ -Platform-Utilities-42 | `tee` (busybox) | _Enabled_ -Platform-Utilities-43 | `test` (busybox) | _Enabled_ - -Domain | Object | Recommendations ---------------------- | ---------------- | ----------------------------------------------------- -Platform-Users-root-1 | Main application | Should not execute as root. -Platform-Users-root-2 | UI | Should run in a context on a user with no capability. - -Domain | `Utility` name | _State_ ---------------------- | -------------- | ------------- -Platform-Users-root-3 | `login` | _Not allowed_ -Platform-Users-root-4 | `su` | _Not allowed_ -Platform-Users-root-5 | `ssh` | _Not allowed_ -Platform-Users-root-6 | `scp` | _Not allowed_ -Platform-Users-root-7 | `sftp` | _Not allowed_ - -Domain | Object | Recommendations --------------------------- | --------- | ----------------------------------------------------------------------- -Application-Installation-1 | AppFw | Provide offline-mode in order to install app with the base image. -Application-Installation-2 | Integrity | Allow the installation of applications only if their integrity is good. - -Domain | Tech name | Recommendations ----------------------------------- | --------- | -------------------------------------------------------------------------- -Connectivity-BusAndConnector-Bus-1 | CAN | Implement hardware solution in order to prohibit sending unwanted signals. - -Domain | Tech name | Recommendations ------------------------------------------ | --------- | ---------------------------------------------------------------------- -Connectivity-BusAndConnector-Connectors-1 | USB | Must be disabled. If not, only enable the minimum require USB devices. -Connectivity-BusAndConnector-Connectors-2 | USB | Confidential data exchanged with the ECU over USB must be secure. -Connectivity-BusAndConnector-Connectors-3 | USB | USB Boot on a ECU must be disable. -Connectivity-BusAndConnector-Connectors-4 | OBD-II | Must be disabled outside garages. - -Domain | Object | Recommendations ------------------------ | ------ | ------------------------------------------------------------------ -Connectivity-Wireless-1 | Update | Always follow the latest updates of remote communication channels. - -Domain | Tech name or object | Recommendations ----------------------------- | ------------------- | ------------------------------------------------------------------------- -Connectivity-Wireless-Wifi-1 | WEP, PSK, TKIP | Disabled -Connectivity-Wireless-Wifi-2 | WPA2 and AES-CCMP | Used -Connectivity-Wireless-Wifi-3 | WPA2 | Should protect data sniffing. -Connectivity-Wireless-Wifi-4 | PSK | Changing regularly the password. -Connectivity-Wireless-Wifi-5 | Device | Upgraded easily in software or firmware to have the last security update. - -Domain | Tech name | Recommendations ---------------------------------- | ------------- | ------------------------------------------------------------ -Connectivity-Wireless-Bluetooth-1 | BLE | Use with caution. -Connectivity-Wireless-Bluetooth-2 | Bluetooth | Monitoring -Connectivity-Wireless-Bluetooth-3 | SSP | Avoid using the "Just Works" association model. -Connectivity-Wireless-Bluetooth-4 | Visibility | Configured by default as undiscoverable. Except when needed. -Connectivity-Wireless-Bluetooth-5 | Anti-scanning | Used, inter alia, to slow down brute force attacks. - -Domain | Tech name | Recommendations --------------------------------- | --------- | -------------------------- -Connectivity-Wireless-Cellular-1 | GPRS/EDGE | Avoid -Connectivity-Wireless-Cellular-2 | UMTS/HSPA | Protected against Jamming. - -Domain | Tech name | Recommendations ------------------------------ | --------- | -------------------------------------------- -Connectivity-Wireless-Radio-1 | RDS | Only audio output and meta concerning radio. - -Domain | Tech name | Recommendations ---------------------------- | --------- | ------------------------------------------------------ -Connectivity-Wireless-NFC-1 | NFC | Protected against relay and replay attacks. -Connectivity-Wireless-NFC-2 | Device | Disable unneeded and unapproved services and profiles. - -Domain | Object | Recommendations ----------------------------- | -------------- | -------------------------------------- -Application-Cloud-Download-1 | authentication | Must implement authentication process. -Application-Cloud-Download-2 | Authorization | Must implement Authorization process. - -Domain | Object | Recommendations ----------------------------------- | ------------- | ---------------------------------------------------------- -Application-Cloud-Infrastructure-1 | Packet | Should implement a DPI. -Application-Cloud-Infrastructure-2 | DoS | Must implement a DoS protection. -Application-Cloud-Infrastructure-3 | Test | Should implement scanning tools like SATS and DAST. -Application-Cloud-Infrastructure-4 | Log | Should implement security tools (IDS and IPS). -Application-Cloud-Infrastructure-5 | App integrity | Applications must be signed by the code signing authority. - -Domain | Object | Recommendations ------------------------------ | ----------------------------------------- | --------------------------------- -Application-Cloud-Transport-1 | Integrity, confidentiality and legitimacy | Should implement IPSec standards. - -# Todo notes - -Domain | Improvement ---------------- | ---------------------------------------------------- -Boot-Abstract-1 | More generic and add examples (The chain of trust). - -Domain | Improvement ---------------- | ------------------------------------------- -Boot-Abstract-1 | Review the definition of the "boot loader". - -Domain | Improvement ---------------- | ------------------------------------ -Boot-Consoles-1 | Secure loader: No reference earlier? - -Domain | Improvement ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- -Hypervisor-Abstract-1 | Complete Hypervisor part ([jailhouse](https://github.com/siemens/jailhouse) / [KVM](https://www.linux-kvm.org/page/Main_Page) / [Xen](https://www.xenproject.org/developers/teams/embedded-and-automotive.html)). - -Domain | Improvement --------------------------------- | ----------------------------- -Kernel-General-IndependentExec-1 | Kernel or/and platform part ? - -Domain | Improvement -------------------------------- | --------------- -Kernel-General-LibraryLinking-1 | Keep this part? - -Domain | Improvement -------------------- | -------------------------------- -Platform-Abstract-1 | Create a graphics and sound part. - -Domain | Improvement -------------------- | ----------- -Platform-Services-1 | SystemD ? -Platform-Services-2 | Secure daemon ? - -Domain | Improvement ------------------------------ | ------------------------ -Platform-Users-Capabilities-1 | Kernel or Platform-user? -Platform-Users-Capabilities-2 | Add config note. - -Domain | Improvement --------------------------- | ------------------------------ -Application-Installation-1 | Talk about AppFw offline mode. - -Domain | Improvement ------------------------ | ---------------------------------------------------------- -Application-Signature-1 | Add content (see secure build in Secure development part). - -Domain | Improvement ----------------------- | ------------ -Application-Services-1 | Add content (Which services?). -Application-Services-2 | Add Binder. - -Domain | Improvement ------------------------ | ----------------- -Connectivity-Abstract-1 | Improve abstract. - -Domain | Improvement ------------------------ | ------------------------------------------- -Connectivity-Wireless-1 | Add communication channels (RFID, ZigBee?). - -Domain | Improvement -------------- | ----------------- -Update-SOTA-1 | Part to complete. - -Domain | Improvement ------------------------ | ------------ -SecureDev-SecureBuild-1 | Add content. - -Domain | Improvement ----------------------- | ------------ -SecureDev-Signatures-1 | Add content. - -Domain | Improvement ---------------------- | ----------------------------------------------------- -SecureDev-CodeAudit-1 | Add CVE analyser. -SecureDev-CodeAudit-2 | [OSSTMM](http://www.isecom.org/mirror/OSSTMM.3.pdf). \ No newline at end of file diff --git a/docs/2_Architecture_Guides/2_Security_Blueprint/images/App-flow.png b/docs/2_Architecture_Guides/2_Security_Blueprint/images/App-flow.png deleted file mode 100644 index 7b87c29..0000000 Binary files a/docs/2_Architecture_Guides/2_Security_Blueprint/images/App-flow.png and /dev/null differ diff --git a/docs/2_Architecture_Guides/2_Security_Blueprint/images/App_signing_flow.png b/docs/2_Architecture_Guides/2_Security_Blueprint/images/App_signing_flow.png deleted file mode 100644 index 56a7c23..0000000 Binary files a/docs/2_Architecture_Guides/2_Security_Blueprint/images/App_signing_flow.png and /dev/null differ diff --git a/docs/2_Architecture_Guides/2_Security_Blueprint/images/WhiteBoxArchi.png b/docs/2_Architecture_Guides/2_Security_Blueprint/images/WhiteBoxArchi.png deleted file mode 100644 index d984d1a..0000000 Binary files a/docs/2_Architecture_Guides/2_Security_Blueprint/images/WhiteBoxArchi.png and /dev/null differ diff --git a/docs/2_Hardware_Support/1_Overview.md b/docs/2_Hardware_Support/1_Overview.md new file mode 100644 index 0000000..56dbd13 --- /dev/null +++ b/docs/2_Hardware_Support/1_Overview.md @@ -0,0 +1,48 @@ +--- +title: Supported Hardware +--- + +### Supported Hardware + +AGL makes two types of hardware support available: Reference BSPs and Community BSPs. + +1) **Reference Boards** have Board Support Packages (BSPs) that are maintained by their sponsoring companies and are included in our Jenkins CI system. Reference BSPs have snapshot builds that are made available daily and are fully validated with test results made available for every major AGL release. + +2) **Community Boards** have BSPs that are maintained as a best effort by the AGL community based on upstream BSPs. Community Boards include some of the most-used Hobbyist boards such as older automotive boards. + +The following table briefs about the various hardware platforms, supported by AGL : + +### AGL Reference Boards + +| BOARD | MACHINE | ARCHITECTURE | QUICK START GUIDE| LATEST SNAPSHOT | +|:---------------:|:--------------:|:------------:|:----------------:|:--------------------:| +| QEMU | qemu-x86-64 | x86 |[QEMU Quick Start](https://docs.automotivelinux.org/en/master/#0_Getting_Started/1_Quickstart/Using_Ready_Made_Images/#_top)| [qemu-x86-64](https://download.automotivelinux.org/AGL/snapshots/master/latest/qemux86-64/)| +| | qemu-arm | arm32 | | [qemu-arm](https://download.automotivelinux.org/AGL/snapshots/master/latest/qemuarm/)| +| | qemu-arm64 | arm64 | | [qemu-arm64](https://download.automotivelinux.org/AGL/snapshots/master/latest/qemuarm64/)| +| | | | +| RCar Gen 3 | h3ulcb | arm64 |[RCar Gen 3 Quick Start](https://docs.automotivelinux.org/en/master/#0_Getting_Started/1_Quickstart/Using_Ready_Made_Images/#3-r-car-h3sk-h3ulcb-board)| [h3ulcb-nogfx](https://download.automotivelinux.org/AGL/snapshots/master/latest/h3ulcb-nogfx/)| +| | h3-salvator-x | arm64 | +| | h3-kf | arm64 | +| | m3ulcb | arm64 | +| | m3-salvator-x | arm64 | +| | m3-kf | arm64 | +| | agl-refhw | arm64 | +| | | | +| Raspberry Pi | raspberrypi4 | arm64 |[Raspberry Pi Quick Start](https://docs.automotivelinux.org/en/master/#0_Getting_Started/1_Quickstart/Using_Ready_Made_Images/#2-raspberry-pi-4)|[raspberrypi4](https://download.automotivelinux.org/AGL/snapshots/master/latest/raspberrypi4/)| + +**Note:** Latest stable release source tar and binary for all the boards can be found [here](https://wiki.automotivelinux.org/agl-distro/release-notes#latest_stable_release) + +### Community Supported Boards + +| BOARD | MACHINE | ARCHITECTURE | +|:-------------:|:---------------------:|:-------------:| +| BeagleBone | bbe | arm32 | +| | beaglebone | arm32 | +| | | | +| i.MX 6 | cubox-i | arm32 | +| | imx6qdlsabreauto | arm32 | +| | | | +| i.MX 8 | imx8mqevk | arm64 | +| | imx8mqevk-viv | arm64 | +| | | | +| virtio | virtio-aarch64 | arm64 | diff --git a/docs/2_Hardware_Support/2_Supported_Hardware_Images.md b/docs/2_Hardware_Support/2_Supported_Hardware_Images.md new file mode 100644 index 0000000..83f3902 --- /dev/null +++ b/docs/2_Hardware_Support/2_Supported_Hardware_Images.md @@ -0,0 +1,97 @@ +--- +title: Supported Hardware Images +--- + + + +### Supported Hardware Images + +AGL supports a variety of interfaces, each requiring unique setup configuration. + +#### 1. In-Vehicle Infotainment (IVI) + +**Supported boards** : + +AGL Reference Boards [QEMU, RCar Gen 3, Raspberry Pi 4](./Overview.md), & agl-refhw + +Community supported Boards [BBE, i. MX 6, i. MX 8](./Overview.md) + +* Qt Based : + + * Setting up flags at `aglsetup` script : + + ```sh + $ source meta-agl/scripts/aglsetup.sh -f -m $MACHINE -b build-$MACHINE agl-demo + + #To enable Developer Options + $ source meta-agl/scripts/aglsetup.sh -f -m $MACHINE -b build-$MACHINE agl-demo agl-devel + ``` + + * Building target image : + + ```sh + $ time bitbake agl-demo-platform + ``` + +* HTML5 Based : + + * Setting up flags at `aglsetup` script : + + ```sh + $ source meta-agl/scripts/aglsetup.sh -f -m $MACHINE -b build-$MACHINE agl-demo + + # To enable Developer Options + $ source meta-agl/scripts/aglsetup.sh -f -m $MACHINE -b build-$MACHINE agl-demo agl-devel + ``` + + * Building target image : + + ```sh + $ time bitbake agl-demo-platform-html5 + ``` + + +#### 2. Instrument Cluster + +**Supported boards** : + +AGL Reference Boards [QEMU, RCar Gen 3, & Raspberry Pi 4](./Overview.md) + +* Setting up flags at `aglsetup` script : + + ```sh + $ source meta-agl/scripts/aglsetup.sh -f -m $MACHINE -b build-$MACHINE agl-demo + + # To enable Developer Options + $ source meta-agl/scripts/aglsetup.sh -f -m $MACHINE -b build-$MACHINE agl-demo agl-devel + ``` + +* Building target image : + + ```sh + $ time bitbake agl-cluster-demo + ``` + +#### 3. Telematics + +Headless demo platform for low-spec boards. + +**Supported boards** : + +Community supported Boards [BeagleBone](./Overview.md) + + +* Setting up flags at `aglsetup` script : + + ```sh + $ source meta-agl/scripts/aglsetup.sh -f -m $MACHINE -b build-$MACHINE agl-demo + + # To enable Developer Options + $ source meta-agl/scripts/aglsetup.sh -f -m $MACHINE -b build-$MACHINE agl-demo agl-devel + ``` + +* Building target image : + + ```sh + $ time bitbake agl-telematics-demo + ``` diff --git a/docs/3_Architecture_Guides/1_Introduction/1_Overview.md b/docs/3_Architecture_Guides/1_Introduction/1_Overview.md new file mode 100644 index 0000000..0648aa9 --- /dev/null +++ b/docs/3_Architecture_Guides/1_Introduction/1_Overview.md @@ -0,0 +1,53 @@ +--- +title: Overview +--- + +The AGL Unified Code Base (UCB) is a Linux distribution built from the ground up +through a joint effort by automakers and suppliers to deliver a modern +in-vehicle infotainment and connected car experience for consumers. Further +helping reduce fragmentation and facilitate innovation in the development +process. The following use cases are in development or planned to be developed : + + - In Vehicle Infotainment (IVI) + - Instrument Cluster (IC) + - Telematics + - and more : + - Heads-up Display (HUD) + - Advanced Driver Assistance Systems (ADAS) + - Autonomous Driving (AD) + +The goal of the UCB platform is to provide 70-80% of the starting +point for a production project. This enables automakers and suppliers to focus +their resources on customizing the other 20-30% to meet their unique product needs. + +The [System Architecture Team](https://wiki.automotivelinux.org/agl-sat) defines the overall architecture of the AGL +software according to the business requirements established by the [Steering Committee](https://www.automotivelinux.org/about/steering-committee/). + +There are multiple parallel efforts in the areas of the following, with most having specialized [Expert Groups +(EG)](https://wiki.automotivelinux.org/#active_expert_groups) : + + - [App Framework and Security](https://wiki.automotivelinux.org/eg-app-fw) + - [Navigation](https://wiki.automotivelinux.org/eg-navi) + - [Speech](https://wiki.automotivelinux.org/eg-speech) + - [UI and Graphics](https://wiki.automotivelinux.org/eg-ui-graphics) + - [Connectivity](https://wiki.automotivelinux.org/eg-connectivity) + - [Continuous Integration and Test](https://wiki.automotivelinux.org/eg-ciat) + - [Instrument Cluster](https://wiki.automotivelinux.org/eg-ic) + - In Vehicle Infotainment (IVI) + - [Reference Hardware System Architecture](https://wiki.automotivelinux.org/eg-rhsa) + - Telematics + - [Requirements Specification](https://wiki.automotivelinux.org/eg-requirements-specification) + - [Vehicle to Cloud](https://wiki.automotivelinux.org/eg-v2c) + - [Virtualization](https://wiki.automotivelinux.org/eg-virt) + +The Automotive Grade Linux Software Architecture diagram is below. The architecture consists +of five layers. The App/HMI layer contains applications with their associated business logic and +HMI. + +![Architecture Diagram](images/architecture.jpg) + +The Application Framework layer provides the APIs for creating both managing and running +applications on an AGL system. The Services layer contains user space services that all +applications can access. The Operating System (OS) layer provides the Linux kernel and device +drivers along with standard OS utilities. For IVI (In Vehicle Infotainment) +system a full fledged demo is [available](../../0_Getting_Started/1_Quickstart/Using_Ready_Made_Images.md). \ No newline at end of file diff --git a/docs/3_Architecture_Guides/1_Introduction/2_AGL_Requirements_Specifications.md b/docs/3_Architecture_Guides/1_Introduction/2_AGL_Requirements_Specifications.md new file mode 100644 index 0000000..b15202a --- /dev/null +++ b/docs/3_Architecture_Guides/1_Introduction/2_AGL_Requirements_Specifications.md @@ -0,0 +1,8 @@ +--- +title: AGL Requirements Specifications +--- + + + + +[**AGL Requirements Specifications PDF**](AGL Requirements Specifications.pdf) diff --git a/docs/3_Architecture_Guides/1_Introduction/AGL Requirements Specifications.pdf b/docs/3_Architecture_Guides/1_Introduction/AGL Requirements Specifications.pdf new file mode 100644 index 0000000..c5be950 Binary files /dev/null and b/docs/3_Architecture_Guides/1_Introduction/AGL Requirements Specifications.pdf differ diff --git a/docs/3_Architecture_Guides/1_Introduction/images/architecture.jpg b/docs/3_Architecture_Guides/1_Introduction/images/architecture.jpg new file mode 100644 index 0000000..e83cbc4 Binary files /dev/null and b/docs/3_Architecture_Guides/1_Introduction/images/architecture.jpg differ diff --git a/docs/3_Architecture_Guides/2_Security_Blueprint/1_Overview.md b/docs/3_Architecture_Guides/2_Security_Blueprint/1_Overview.md new file mode 100644 index 0000000..ee5e7f7 --- /dev/null +++ b/docs/3_Architecture_Guides/2_Security_Blueprint/1_Overview.md @@ -0,0 +1,250 @@ +--- +title: Overview +--- + +Modern cars have become a lot more technologically sophisticated and different +than those of the past. We are seeing a wider range of new features and +functionality, with a lot more complex software. It is fair to say that the cars +being introduced to the market today have much more in common with computing +devices like cell phones, than their predecessors did. Modern car manufacturers +are also integrating support for a broad range of communication technologies for +these “connected” cars. With the advent of such vehicles, Linux has become a +natural choice for the software platform, with Automotive Grade Linux as a +promising example. + +From a security point of view, the remote capabilities of a connected car +results in a much larger attack surface. This opens a whole new world of +security vulnerabilities that need to be considered during the architectural +design. History shows that physical access to a device is sufficient for a +hacker to gain root privileges. This makes the car a hostile environment. + +The Security Blueprint documents the security features that are included as part +of Automotive Grade Linux (AGL) and identifies areas that need to be addressed +from a security perspective as part of AGL. It also gives guidance around +existing technologies and solutions. + +Security domains will allow us to create a set of tests verifying the security +of Automotive Grade Linux. + +This document is firstly based on an existing AGL security-blueprint. + +**For security to be effective, the concepts must be simple. And by default, +anything that is not allowed is forbidden.** + +We will cover topics starting from the lowest level (_Hardware_) up to the +highest levels (_Connectivity_ and _Application_). We will move quickly on +_Hardware_ and _Connectivity_ because this is not supported at our level. +Solutions of connectivity problems concern updates and secured settings while +hardware securing is related to the manufacturers. + +## Adversaries + +Adversaries and attackers within the Automotive space. + +- 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 information on ECUs that have been +previously compromised and have access to softwares and instructions developed +by other members of car modification forums. The goal of the enthusiast hacker +could be, but is not limited to, adding extra horse power to the car or hacking +it just for fun. + +- Corrupt Automotive Dealers + +Corrupt automotive dealers 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 Criminals + +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 control of the Over-The-Air (OTA) servers or the +In-Vehicle Infotainment (IVI) systems. This is very much like the role of +organized criminals in other industries such as paid media today. Their goal is +to extort money from OEMs and/or governments by threatening to disable multiple +vehicles. + +- Malware Developers + +Malware developers have developed malicious software to attack and compromise a +large number of vehicles. The malicious software is usually designed to spread +from one vehicle to another. Usually, the goal is to take control of multiple +machines and then sell access to them for malicious purposes like +denial-of-service (DoS) attacks or theft of private information and data. + +- Security Researchers + +Security researchers are ‘self-publicized’ security consultants trying to make a +name for themselves. They have access to 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 gain or just to gain personal understanding with +a sense of helping make things more secure. + +## Attack Goals + +In today’s connected vehicle, more and more functionality is moving to software +control, meaning that the threat of attack becomes greater and greater. We see +car features like navigation and summoning, car access/engine start, and +motor/ECU upgrades all controlled through software and connections to the cloud. +The risk of attack is high because there are high value targets in play. + +Here, we outline some of the major threats categories along with some sample +attackers, example attacks, and a relative importance. These threat categories +are intended to be general examples. There can be many nuances to threat types. +Additionally, there can be many sub-attacks that eventually lead to these higher +level attack goals. + +| Threat Category | Sample Attacker | Example Attacks | Relative Importance | +|-------------------------------|-----------------------------------------|-------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------| +| Vehicle theft | Individual, organized criminals | Send the car to an unplanned destination, get a key for the car, gain control of the unlock mechanism | Reduced likelihood of future vehicle purchases (Profit Later), bad press (Brand Integrity) | +| Reduced vehicle functionality | Terrorist groups, disgruntled employees | Lock the driver out of the car, cause the car to crash, block access to infotainment system | Inability sell paid-for apps and content (Profit Now), bad press (Brand Integrity), possible loss of life (Physical Injury) | +| Vehicle hacking | Vehicle owner, competitor | Get content without paying, modify DRM licenses, unlock of after-market features, theft of IP | Loss of sales for content and features (Profit Now), lawsuits from content owners (Profit Later), loss of competitive advantage (Profit Later) | +| Sensitive asset theft | Organized criminals, blackmailers | Steal credit card numbers, health information, camera data, steal bandwidth | Bad press (Brand Integrity), lawsuits from vehicle owners (Profit Later) | + +The Automotive Grade Linux (AGL) initiative builds upon open-source software +including Linux and Tizen to offer a flexible application framework. However, +the security provisions of the app framework, Cynara, and the security manager +only go so far in keeping the biggest threats at bay. As experience has shown, +providing a constrained app (like that in the Android Open Source Platform) and +store development flow, signature verification, DAC sandboxing, and MAC (SMACK) +controls over the platform can have a certain amount of success with the +security of the system. However, the openness of the system invites many +researchers, hobbyists and hackers and financially motivated attackers to +compromise the system for their own gains. + +As AGL arrives on modern automobiles, this is inevitably inviting many capable +actors to modify, attack, and compromise these well thought-out systems and +their applications. With concerns like safety and security, the auto industry +cannot afford to go the way of consumer devices like phones and tablets where +security problems are encountered on a frequent basis. It is imperative to use a +layered approach and defense-in-depth to protect the system from inevitable +attack. + +## Assets and Security Categorization + +This section outlines some of the assets that are likely to be found in the +vehicle and their relative sensitivity from an attack point of view. +Additionally, the final column on the right lists some of the recommended +protection types that can be applied to these types of assets (Note that the +empty cells refer to the cells above them). A good protection approach will give +priority to the most sensitive assets, using a defense-in-depth approach to +cover these assets. Less sensitive assets are treated at a lower priority, +typically protected with fewer protection techniques. A more fine-grained +prioritization of the the assets in a concrete vehicle network can be achieved +with detailed threat analysis which considers the topology of the vehicle +network and access-controls that are in-place. e.g. the EVITA framework for +attack trees. + +| Asset Category | Examples | Sensitivity | Recommended Protection Types | +|-------------------|--------------------------------------------------------------------------------|-------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Software | ECU software, infotainment software, OS images | Critical | Key Management, Mutual Asymmetric Authentication, HSM and WhiteBox Encryption, Message Integrity Checks, Hardening/SW Protection, Program Transforms/ Obfuscation, Integrity Verification, Secure OS | +| Car Access | Biometric data, car keys | | | +| Payment Data | Credit cards, User profile critical data | | | +| Recordings | Internal camera recording, internal audio recording, external camera recording | High | Encryption, Message Integrity Checks, Hardening/SW Protection, Program Transforms / Obfuscation | +| User Profile | Usernames and passwords, customization, calendar, contacts | | | +| Location | GPS coordinates, vehicle usage data | | | +| Purchased Content | Video, audio, licenses | | | +| Teleconference | Chat, audio, video | Medium | SW Protection, Program Transforms / Obfuscation, Authenticated encryption for transmission | +| Vehicle data | Vehicle info, sensor data | | | +| Navigation data | Static and dynamic maps | | | +| 3rd party data | Home automation commands, cloud game data | | | + +## Hardening term + +The term Hardening refers to the tools, techniques and processes required in +order to reduce the attack surface on an embedded system, such as an embedded +control unit (**ECU**) or other managed devices. The target for all hardening +activities is to prevent the execution of invalid binaries on the device, and to +prevent copying of security related data from the device. + +## AGL security overview + +AGL roots are based on security concepts. Those concepts are implemented by the +security framework as shown in this picture: + +![AGL architecture](images/WhiteBoxArchi.png) + +-------------------------------------------------------------------------------- + +# Acronyms and Abbreviations + +The following table lists the strongest terms utilized within all this document. + +| Acronyms or Abbreviations | Description | +|---------------------------|-------------------------------------| +| _AGL_ | **A**utomotive **G**rade **L**inux | +| _ECU_ | **E**lectronic **C**ontrol **U**nit | + +-------------------------------------------------------------------------------- + +# References + +- [security-blueprint](http://docs.automotivelinux.org/docs/architecture/en/dev/reference/security/01-overview.html). + - _http:// + docs.automotivelinux.org/docs/architecture/en/dev/reference/security/01-overview.html_ +- **[2017]** - [kernel + security](https://www.kernel.org/doc/Documentation/security/). + - _https:// www.kernel.org/doc/Documentation/security/_ +- **[2017]** - [Systemd integration and user + management](http://iot.bzh/download/public/2017/AMM-Dresden/AGL-systemd.pdf). + - _http:// iot.bzh/download/public/2017/AMM-Dresden/AGL-systemd.pdf_ +- **[2017]** - [AGL - Application Framework + Documentation](http://iot.bzh/download/public/2017/SDK/AppFw-Documentation-v3.1.pdf). + - _http:// iot.bzh/download/public/2017/SDK/AppFw-Documentation-v3.1.pdf_ +- **[2017]** - [Improving Vehicle + Cybersecurity](https://access.atis.org/apps/group_public/download.php/35648/ATIS-I-0000059.pdf). + - _https:// + access.atis.org/apps/group_public/download.php/35648/ATIS-I-0000059.pdf_ +- **[2016]** - [AGL framework + overview](http://docs.automotivelinux.org/docs/apis_services/en/dev/reference/af-main/0-introduction.html). + - _http:// + docs.automotivelinux.org/docs/apis_services/en/dev/reference/af-main/0-introduction.html_ +- **[2016]** - + [SecureBoot-SecureSoftwareUpdates](http://iot.bzh/download/public/2016/publications/SecureBoot-SecureSoftwareUpdates.pdf). + - _http:// + iot.bzh/download/public/2016/publications/SecureBoot-SecureSoftwareUpdates.pdf_ +- **[2016]** - [Linux Automotive + Security](http://iot.bzh/download/public/2016/security/Linux-Automotive-Security-v10.pdf). + - _http:// + iot.bzh/download/public/2016/security/Linux-Automotive-Security-v10.pdf_ +- **[2016]** - [Automotive Security Best + Practices](https://www.mcafee.com/it/resources/white-papers/wp-automotive-security.pdf). + - _https:// + www.mcafee.com/it/resources/white-papers/wp-automotive-security.pdf_ +- **[2016]** - [Gattacking Bluetooth Smart + Devices](http://gattack.io/whitepaper.pdf). + - _http:// gattack.io/whitepaper.pdf_ +- **[2015]** - [Comprehensive Experimental Analysis of Automotive Attack + Surfaces](http://www.cs.wayne.edu/fengwei/15fa-csc6991/slides/8-CarHackingUsenixSecurity.pdf). + - _http:// + www.cs.wayne.edu/fengwei/15fa-csc6991/slides/8-CarHackingUsenixSecurity.pdf_ +- **[2015]** - [Security in Automotive Bus + Systems](http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.92.728&rep=rep1&type=pdf). + - _http:// + citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.92.728&rep=rep1&type=pdf_ +- **[2014]** - [IOActive Remote Attack + Surface](https://www.ioactive.com/pdfs/IOActive_Remote_Attack_Surfaces.pdf). + - _https:// www.ioactive.com/pdfs/IOActive_Remote_Attack_Surfaces.pdf_ +- **[2011]** - [A practical attack against GPRS/EDGE/UMTS/HSPA mobile data + communications](https://media.blackhat.com/bh-dc-11/Perez-Pico/BlackHat_DC_2011_Perez-Pico_Mobile_Attacks-wp.pdf). + - _https:// + media.blackhat.com/bh-dc-11/Perez-Pico/BlackHat_DC_2011_Perez-Pico_Mobile_Attacks-wp.pdf_ +- **[2011]** - [Comprehensive Experimental Analyses of Automotive Attack + Surfaces](http://www.autosec.org/pubs/cars-usenixsec2011.pdf). + - _http:// www.autosec.org/pubs/cars-usenixsec2011.pdf_ +- **[2010]** - [Relay Attacks on Passive Keyless Entry and Start Systems in + Modern Cars](https://eprint.iacr.org/2010/332.pdf). + - _https:// eprint.iacr.org/2010/332.pdf_ +- **[2010]** - [Wifi attacks wep + wpa](https://matthieu.io/dl/wifi-attacks-wep-wpa.pdf). + - _https:// matthieu.io/dl/wifi-attacks-wep-wpa.pdf_ +- **[2008]** - + [SMACK](http://schaufler-ca.com/yahoo_site_admin/assets/docs/SmackWhitePaper.257153003.pdf). + - _http:// + schaufler-ca.com/yahoo_site_admin/assets/docs/SmackWhitePaper.257153003.pdf_ diff --git a/docs/3_Architecture_Guides/2_Security_Blueprint/2_Hardware.md b/docs/3_Architecture_Guides/2_Security_Blueprint/2_Hardware.md new file mode 100644 index 0000000..328dd15 --- /dev/null +++ b/docs/3_Architecture_Guides/2_Security_Blueprint/2_Hardware.md @@ -0,0 +1,64 @@ +--- +title: Hardware +--- + +The Automotive Grade Linux platform is a Linux distribution with **AGL** +compliant applications and services. The platform includes the following +hardware: + +- SoC (System-on-Chip). +- Memory (RAM, ROM, storage, etc.). +- Peripherals. + +You will find in this first part everything that concerns the hardware security. +The goal is to protect system against all attacks that are trying to gain +additional privileges by recovering and/or changing cryptographic keys in order +to alter the integrity of the boot. We should also prevent hardware +modifications in order to achieve this goal. We will expose below some examples +of possible configurations. + +-------------------------------------------------------------------------------- + +## Acronyms and Abbreviations + +The following table lists the terms utilized within this part of the document. + +Acronyms or Abbreviations | Description +------------------------- | -------------------------------------- +_HSM_ | **H**ardware **S**ecurity **M**odule +_NVM_ | **N**on-**V**olatile **M**emory +_SHE_ | **S**ecure **H**ardware **E**xtensions + +-------------------------------------------------------------------------------- + +## Integrity + +The board must store hardcoded cryptographic keys in order to verify among +others the _integrity_ of the _bootloader_. Manufacturers can use **HSM** and +**SHE** to enhance the security of their board. + +Domain | Object | Recommendations +-------------------- | ---------- | ---------------------------------- +Hardware-Integrity-1 | Bootloader | Must control bootloader integrity. +Hardware-Integrity-2 | Board | Must use a HSM. +Hardware-Integrity-3 | RTC | Must not be alterable. + +-------------------------------------------------------------------------------- + +## Certificates + +Domain | Object | Recommendations +---------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- +Hardware-Certificate-1 | System | Shall allow storing dedicated certificates. +Hardware-Certificate-2 | ECU | The ECU must verify the certification authority hierarchy. +Hardware-Certificate-3 | System | Allow the modification of certificates only if the source can be authenticated by a certificate already stored or in the higher levels of the chain of trust. + +-------------------------------------------------------------------------------- + +## Memory + +Domain | Object | Recommendations +----------------- | ---------- | ------------------------------------------------------------------------------------ +Hardware-Memory-1 | ECU | The ECU shall never expose the unencrypted key in RAM when using cryptographic keys. +Hardware-Memory-2 | Bootloader | Internal NVM only +Hardware-Module-3 | - | HSM must be used to secure keys. \ No newline at end of file diff --git a/docs/3_Architecture_Guides/2_Security_Blueprint/3_Secure_Boot.md b/docs/3_Architecture_Guides/2_Security_Blueprint/3_Secure_Boot.md new file mode 100644 index 0000000..cdaa84c --- /dev/null +++ b/docs/3_Architecture_Guides/2_Security_Blueprint/3_Secure_Boot.md @@ -0,0 +1,261 @@ +--- +title: Secure Boot +--- + +Domain | Improvement +--------------- | ---------------------------------------------------- +Boot-Abstract-1 | More generic and add examples (The chain of trust). + +Secure boot refers to preventing malicious software applications and +“unauthorized” operating systems from loading during the system start-up +process. The goal is to protect users from rootkits and other low-level malware +attacks. Modern bootloaders come with features that can be used to enable secure +boot in the system. + +**Boot Hardening**: Steps/requirements to configure the boot sequence, in order +to restrict the device from executing anything other than the approved software +image. + +In this part, we will see a series of settings that will allow us to improve +security during boot phase. For the purposes of reference and explanation, we +are providing guidance on how to configure an embedded device that runs with a +3.10.17 Linux kernel. If the integrity is not checked or if a critical error +occurs, the system must boot on a very stable backup image. + +**Requirements**: These requirements must be met even if an alternative version +of the Linux kernel is chosen. + +**Recommendations**: Detailed best practices that should be applied in order to +secure a device. Although they are not currently listed as hard 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. + +Domain | Improvement +--------------- | ------------------------------------------- +Boot-Abstract-1 | Review the definition of the "boot loader". + +**Boot loader**: The boot loader consists of the Primary boot loader residing in +**OTP** memory, sboot, U-Boot and Secure loader residing in external flash (NAND +or SPI/NOR flash memory). The CPU on power on or reset executes the primary boot +loader. The **OTP** primary boot loader makes the necessary initial system +configuration and then loads the secondary boot loader sboot from external flash +memory to ram memory. The sboot then loads the U-Boot along with the Secure +loader. U-Boot then verifies the Kernel/system image integrity, then loads the +Kernel/system image before passing control to it. + +-------------------------------------------------------------------------------- + +## Acronyms and Abbreviations + +The following table lists the terms utilized within this part of the document. + +Acronyms or Abbreviations | Description +------------------------- | ----------------------------------------------------------------------- +_FUSE_ | **F**ilesystem in **U**ser**S**pac**E** +_OTP_ | **O**ne-**T**ime-**P**rogrammable +_DOCSIS_ | **D**ata **O**ver **C**able **S**ervice **I**nterface **S**pecification + +# Image + +## Image selection + +The boot process shall be uninterruptible and shall irrevocably boot the image +as specified in the boot environment. + +In U-Boot set the "_bootdelay_" environment variable and/or define +`CONFIG_BOOTDELAY` to _-2_. + +Domain | _Variable_ / `Config` name | `Value` +---------------------- | -------------------------- | ------- +Boot-Image-Selection-1 | `CONFIG_BOOTDELAY` | `-2` +Boot-Image-Selection-2 | _bootdelay_ | `-2` + +-------------------------------------------------------------------------------- + +## Image authenticity + +It shall not be possible to boot from an unverified image. The secure boot +feature in U-Boot shall be enabled. The secure boot feature is available from +U-Boot 2013.07 version. To enable the secure boot feature, enable the following +features: + +```sh +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 verification. +CONFIG_OF_CONTROL: Enables Flattened Device Tree (FDT) configuration. +CONFIG_OF_SEPARATE: Enables separate build of u-Boot from the device tree. +CONFIG_DEFAULT_DEVICE_TREE: Specifies the default Device Tree used for the run-time configuration of U-Boot. +``` + +Generate the U-Boot image with public keys to validate and load the image. It +shall use RSA2048 and SHA256 for authentication. + +Domain | `Config` name | _State_ +------------------------- | ---------------------------- | -------- +Boot-Image-Authenticity-1 | `CONFIG_FIT` | _Enable_ +Boot-Image-Authenticity-2 | `CONFIG_FIT_SIGNATURE` | _Enable_ +Boot-Image-Authenticity-3 | `CONFIG_RSA` | _Enable_ +Boot-Image-Authenticity-4 | `CONFIG_OF_CONTROL` | _Enable_ +Boot-Image-Authenticity-5 | `CONFIG_OF_SEPARATE` | _Enable_ +Boot-Image-Authenticity-6 | `CONFIG_DEFAULT_DEVICE_TREE` | _Enable_ + +# Communication modes + +## Disable USB, Serial and DOCSIS Support + +To disable USB support in U-Boot, following config's shall not be defined: + +``` +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. +CONFIG_USB_STORAGE: Enables the USB storage devices. +CONFIG_USB_HOST_ETHER: Enables USB Ethernet adapter support. +``` + +In addition, disable unnecessary communication modes like Ethernet, Serial +ports, DOCSIS in U-Boot and sboot that are not necessary. + +Linux Kernel support for USB should be compiled-out if not required. If it is +needed, the Linux Kernel should be configured to only enable the minimum +required USB devices. User-initiated USB-filesystems should be treated with +special care. Whether or not the filesystems are mounted in userspace +(**FUSE**), restricted mount options should be observed. + +Domain | Communication modes | _State_ +-------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- +Boot-Communication-1 | `USB` | _Disabled_ and _Compiled-out_ if not required. +Boot-Communication-2 | `USB` | Else, Kernel should be configured to only enable the minimum required USB devices and filesystems should be treated with special care. +Boot-Communication-3 | `Ethernet` | _Disabled_ +Boot-Communication-4 | U-boot and sboot `DOCSIS` | _Disabled_ +Boot-Communication-5 | `Serial ports` | _Disabled_ + +Domain | `Config` name | _State_ +------------------------ | ----------------------- | ------------- +Boot-Communication-USB-1 | `CONFIG_CMD_USB` | _Not defined_ +Boot-Communication-USB-2 | `CONFIG_USB_UHCI` | _Not defined_ +Boot-Communication-USB-3 | `CONFIG_USB_KEYBOARD` | _Not defined_ +Boot-Communication-USB-4 | `CONFIG_USB_STORAGE` | _Not defined_ +Boot-Communication-USB-5 | `CONFIG_USB_HOST_ETHER` | _Not defined_ + +-------------------------------------------------------------------------------- + +## Disable all unused Network Interfaces + +Only used network interfaces should be enabled. Where possible, services should +also be limited to those necessary. + +Domain | Communication modes | _State_ +-------------------- | -------------------- | --------------------------------------------------------------------------------------------- +Boot-Communication-1 | `Network interfaces` | Preferably _no network interface is allowed_, otherwise, restrict the services to those used. + +## Remove or Disable Unnecessary Services, Ports, and Devices + +Restrict the `services`, `ports` and `devices` to those used. + +Domain | Object | Recommendations +-------------------- | --------------------------------- | ------------------------------------------------------------- +Boot-Communication-1 | `Services`, `ports` and `devices` | Restrict the `services`, `ports` and `devices` to those used. + +## Disable flash access + +**Recommendation**: + +In U-Boot following flash memory commands shall be disabled: + +**NAND**: Support for nand flash access available through `do_nand` has to be +disabled. + +Domain | `Command` name | _State_ +-------------------------- | -------------- | --------- +Boot-Communication-Flash-1 | `do_nand` | _Disable_ + +Similarly sboot should disable flash access support through command line if any. + +# Consoles + +## Disable serial console + +Serial console output shall be disabled. To disable console output in U-Boot, +set the following macros: + +Domain | `Config` name | `Value` +---------------------- | --------------------------------------- | --------- +Boot-Consoles-Serial-1 | `CONFIG_SILENT_CONSOLE` | `Disable` +Boot-Consoles-Serial-2 | `CONFIG_SYS_DEVICE_NULLDEV` | `Disable` +Boot-Consoles-Serial-3 | `CONFIG_SILENT_CONSOLE_UPDATE_ON_RELOC` | `Disable` + +Domain | Improvement +--------------- | ------------------------------------ +Boot-Consoles-1 | Secure loader: No reference earlier? + +And set "**silent**" environment variable. For the Secure loader, disable the +traces by not defining the below macro: + +Domain | `Environment variable` name | _State_ +---------------------- | --------------------------- | ------------- +Boot-Consoles-Serial-1 | `INC_DEBUG_PRINT` | _Not defined_ + +For sboot proper configuration needs to be done to disable the serial console. + +-------------------------------------------------------------------------------- + +## Immutable environment variables + +In U-Boot, ensure Kernel command line, boot commands, boot delay and other +environment variables are immutable. This will prevent side-loading of alternate +images, by restricting the boot selection to only the image in FLASH. + +The environment variables shall be part of the text region in U-Boot as default +environment variable and not in non-volatile memory. + +Remove configuration options related to non-volatile memory, such as: + +Domain | `Config` name | _State_ +-------------------------- | ---------------------------- | --------- +Boot-Consoles-Variables-1 | `CONFIG_ENV_IS_IN_MMC` | `#undef` +Boot-Consoles-Variables-2 | `CONFIG_ENV_IS_IN_EEPROM` | `#undef` +Boot-Consoles-Variables-3 | `CONFIG_ENV_IS_IN_FLASH` | `#undef` +Boot-Consoles-Variables-4 | `CONFIG_ENV_IS_IN_DATAFLASH` | `#undef` +Boot-Consoles-Variables-5 | `CONFIG_ENV_IS_IN_FAT` | `#undef` +Boot-Consoles-Variables-6 | `CONFIG_ENV_IS_IN_NAND` | `#undef` +Boot-Consoles-Variables-7 | `CONFIG_ENV_IS_IN_NVRAM` | `#undef` +Boot-Consoles-Variables-8 | `CONFIG_ENV_IS_IN_ONENAND` | `#undef` +Boot-Consoles-Variables-9 | `CONFIG_ENV_IS_IN_SPI_FLASH` | `#undef` +Boot-Consoles-Variables-10 | `CONFIG_ENV_IS_IN_REMOTE` | `#undef` +Boot-Consoles-Variables-11 | `CONFIG_ENV_IS_IN_UBI` | `#undef` +Boot-Consoles-Variables-12 | `CONFIG_ENV_IS_NOWHERE` | `#define` + +-------------------------------------------------------------------------------- + +## (Recommendation) Removal of memory dump commands + +In U-Boot, following commands shall be disabled to avoid memory dumps: + +``` +md : Memory Display command. +mm : Memory modify command - auto incrementing address. +nm : Memory modify command - constant address. +mw : Memory write. +cp : Memory copy. +mwc : Memory write cyclic. +mdc : Memory display cyclic. +mtest : Simple ram read/write test. +loopw : Infinite write loop on address range. +``` + +Domain | `Command` name | _State_ +----------------------- | -------------- | ---------- +Boot-Consoles-MemDump-1 | `md` | _Disabled_ +Boot-Consoles-MemDump-2 | `mm` | _Disabled_ +Boot-Consoles-MemDump-3 | `nm` | _Disabled_ +Boot-Consoles-MemDump-4 | `mw` | _Disabled_ +Boot-Consoles-MemDump-5 | `cp` | _Disabled_ +Boot-Consoles-MemDump-6 | `mwc` | _Disabled_ +Boot-Consoles-MemDump-7 | `mdc` | _Disabled_ +Boot-Consoles-MemDump-8 | `mtest` | _Disabled_ +Boot-Consoles-MemDump-9 | `loopw` | _Disabled_ + +Similarly, memory dump support shall be disabled from sboot. \ No newline at end of file diff --git a/docs/3_Architecture_Guides/2_Security_Blueprint/4_Hypervisor.md b/docs/3_Architecture_Guides/2_Security_Blueprint/4_Hypervisor.md new file mode 100644 index 0000000..61cc227 --- /dev/null +++ b/docs/3_Architecture_Guides/2_Security_Blueprint/4_Hypervisor.md @@ -0,0 +1,17 @@ +--- +title: Hypervisor +--- + +**Definition** : "A hypervisor or virtual machine monitor (VMM) is computer +software, firmware or hardware that creates and runs virtual machines". + +It must include a signature verification (possibly delegated). + +Domain | Improvement +--------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- +Hypervisor-Abstract-1 | Complete Hypervisor part ([jailhouse](https://github.com/siemens/jailhouse) / [KVM](https://www.linux-kvm.org/page/Main_Page) / [Xen](https://www.xenproject.org/developers/teams/embedded-and-automotive.html)). + +## Native or Bare-metal hypervisors + +These hypervisors run directly on the host's hardware to control the hardware +and to manage guest operating systems. Those are the ones we're interested in. \ No newline at end of file diff --git a/docs/3_Architecture_Guides/2_Security_Blueprint/5_Kernel.md b/docs/3_Architecture_Guides/2_Security_Blueprint/5_Kernel.md new file mode 100644 index 0000000..33e24d5 --- /dev/null +++ b/docs/3_Architecture_Guides/2_Security_Blueprint/5_Kernel.md @@ -0,0 +1,941 @@ +--- +title: Kernel +--- + +**System Hardening:** Best practices associated with the configuration of an +embedded Linux based operating system. This section includes both hardening of +the kernel itself, as well as specific configurations and patches used to +protect against known vulnerabilities within the build and configuration of the +root filesystem. + +At the Kernel level, we must ensure that no console can be launched. It could be +used to change the behavior of the system or to have more information about it. +Another aspect is the protection of the memory used by the Kernel. + +The next sub-sections contain information on various kernel configuration +options to enhance the security in the kernel (3.10.17) and also for +applications compiled to take advantage of these security features. +Additionally, there are also configuration options that protect from known +vulnerable configuration options. Here's a high level summary of various kernel +configurations that shall be required for deployment. + +## Kernel Version + +The choice of kernel version for the AGL system is essential to its security. +Depending on the type of board and eventual production system, different kernel +versions are used. For example, one of the systems under study uses the Linux +kernel version 3.10, while another uses the Linux kernel version 4.4. For the +Linux kernel version 3.10.31, there are 25 known vulnerabilities. These +vulnerabilities would allow an attacker to gain privileges, bypass access +restrictions, allow memory to be corrupted, or cause denial of service. In +contrast, the Linux kernel version of 4.4 has many fewer known vulnerabilities. +For this reason, we would in general recommend the later kernel version as a +basis for the platform. + +Note that, although there are fewer known vulnerabilities in the most recent +kernel versions there may be many unknown vulnerabilities underlying. A rule of +thumb is to update the kernel as much as possible to avoid the problems you do +know, but you should not be complacent in the trust that you place in it. A +defense-in-depth approach would then apply. + +If there are constraints and dependencies in upgrading to a newer kernel version +(e.g. device drivers, board support providers) and you are forced to an older +Linux kernel version, there need to be additional provisions made to reduce the +risk of kernel exploits, which can include memory monitoring, watch-dog +services, and system call hooking. In this case, further defense-in-depth +techniques may be required to mitigate the risk of attacks to known +vulnerabilities, which can also include runtime integrity verification of +components that are vulnerable to tampering. + +## Kernel Build Configuration + +The kernel build configuration is extremely important for determining the level +of access to services and to reduce the breadth of the attack surface. Linux +contains a great and flexible number of capabilities and this is only controlled +through the build configuration. For example, the `CONFIG_MODULES` parameter +allows kernel modules to be loaded at runtime extending the capabilities of the +kernel. This capability needs to be either inhibited or controlled at runtime +through other configuration parameters. For example, `CONFIG_MODULE_SIG_FORCE=y` +ensures that only signed modules are loaded. There is a very large number of +kernel configuration parameters, and these are discussed in detail in this +section. + +# General configuration + +## Mandatory Access Control + +Kernel should controls access with labels and policy. + +Domain | `Config` name | `Value` +-------------------- | -------------- | -------------------------------------- +Kernel-General-MAC-1 | CONFIG_IP_NF_SECURITY | m +Kernel-General-MAC-2 | CONFIG_IP6_NF_SECURITY | m +Kernel-General-MAC-3 | CONFIG_EXT2_FS_SECURITY | y +Kernel-General-MAC-4 | CONFIG_EXT3_FS_SECURITY | y +Kernel-General-MAC-5 | CONFIG_EXT4_FS_SECURITY | y +Kernel-General-MAC-6 | CONFIG_SECURITY | y +Kernel-General-MAC-7 | CONFIG_SECURITY_SMACK | y +Kernel-General-MAC-8 | CONFIG_TMPFS_XATTR | y + +Please also refer to the [Mandatory Access Control documentation in +Platform](5_Platform.md). You can also find useful documentation and +links on wikipedia about +[**MAC**](https://en.wikipedia.org/wiki/Mandatory_access_control) and about +[**SMACK**](https://en.wikipedia.org/wiki/Simplified_Mandatory_Access_Control_Kernel). + +-------------------------------------------------------------------------------- + +## Disable kexec + +**Kexec** is a system call that enables you to load and boot into another kernel +from the currently running kernel. This feature is not required in a production +environment. + + + +Domain | `Config` name | `Value` +---------------------- | -------------- | ------- +Kernel-General-kexec-1 | `CONFIG_KEXEC` | `n` + + + + + +**kexec** can load arbitrary kernels but signing of new kernel can be enforced +like it is can be enforced for new modules. + +-------------------------------------------------------------------------------- + +## Disable kernel IP auto-configuration + +It is preferable to have an IP configuration performed using a user-space tool +as these tend to have more validation. We do not want the network interface +coming up until the system has come up properly. + + + +Domain | `Config` name | `Value` +--------------------------- | --------------- | ------- +Kernel-General-IPAutoConf-1 | `CONFIG_IP_PNP` | `n` + + + +-------------------------------------------------------------------------------- + +## Disable Sysctl syscall support + +Enabling this will result in code being included that is hard to maintain and +not well tested. + + + +Domain | `Config` name | `Value` +------------------------------- | ----------------------- | ------- +Kernel-General-SysCtl_SysCall-1 | `CONFIG_SYSCTL_SYSCALL` | `n` + + + +-------------------------------------------------------------------------------- + +## Disable Legacy Linux Support + +There are some Kernel Configs which are present only to support legacy binaries. +See also "Consoles" part in order to disabling support for legacy binary +formats. The `uselib` system call, in particular, has no valid use in any +`libc6` or `uclibc` system in recent times. This configuration is supported in +**Linux 3.15 and greater** and thus should only be disabled for such versions. + + + +Domain | `Config` name | `Value` +---------------------------- | --------------- | ------- +Kernel-General-LegacyLinux-1 | `CONFIG_USELIB` | `n` + + + +-------------------------------------------------------------------------------- + +## Disable firmware auto-loading user mode helper + +The firmware auto loading helper, which is a utility executed by the kernel on +`hotplug` events requiring firmware, can to be set `setuid`. As a result of +this, the helper utility is an attractive target for attackers with control of +physical ports on the device. Disabling this configuration that is supported in +**Linux 3.9 and greater**. + + + +Domain | `Config` name | `Value` +--------------------------- | ------------------------------ | ------- +Kernel-General-FirmHelper-1 | `CONFIG_FW_LOADER_USER_HELPER` | `n` + + + + + +It doesn't strictly need to be `setuid`, there is an option of shipping firmware +builtin into kernel without initrd/filesystem. + + + +-------------------------------------------------------------------------------- + +## Enable Kernel Panic on OOPS + +When fuzzing the kernel or attempting kernel exploits attackers are likely to +trigger kernel OOPSes. Setting the behavior on OOPS to PANIC can impede their +progress. + +This configuration is supported in **Linux 3.5 and greater** and thus should +only be enabled for such versions. + + + +Domain | `Config` name | `Value` +---------------------------- | ---------------------- | ------- +Kernel-General-PanicOnOOPS-1 | `CONFIG_PANIC_ON_OOPS` | `y` + + + +-------------------------------------------------------------------------------- + + + +## Disable socket monitoring interface + +These monitors can be used to inspect shared file descriptors on Unix Domain +sockets or traffic on 'localhost' which is otherwise assumed to be confidential. + +The `CONFIG_PACKET_DIAG` configuration is supported in **Linux 3.7 and greater** +and thus should only be disabled for such versions. + +The `CONFIG_UNIX_DIAG` configuration is supported in **Linux 3.3 and greater** +and thus should only be disabled for such versions. + + + +Domain | `Config` name | `Value` +-------------------------- | -------------------- | ------- +Kernel-General-SocketMon-1 | `CONFIG_PACKET_DIAG` | `n` +Kernel-General-SocketMon-2 | `CONFIG_UNIX_DIAG` | `n` + + + +-------------------------------------------------------------------------------- + +## Disable BPF JIT + +The BPF JIT can be used to create kernel-payloads from firewall table rules. + +This configuration for is supported in **Linux 3.16 and greater** and thus +should only be disabled for such versions. + + + +Domain | `Config` name | `Value` +------------------------ | ---------------- | ------- +Kernel-General-BPF_JIT-1 | `CONFIG_BPF_JIT` | `n` + + + +-------------------------------------------------------------------------------- + +## Enable Enforced Module Signing + +The kernel should never allow an unprivileged user the ability to load specific +kernel modules, since that would provide a facility to unexpectedly extend the +available attack surface. + +To protect against even privileged users, systems may need to either disable +module loading entirely, or provide signed modules (e.g. +`CONFIG_MODULE_SIG_FORCE`, or dm-crypt with LoadPin), to keep from having root +load arbitrary kernel code via the module loader interface. + +This configuration is supported in **Linux 3.7 and greater** and thus should +only be enabled for such versions. + + + +Domain | `Config` name | `Value` +------------------------------ | ------------------------- | ------- +Kernel-General-ModuleSigning-1 | `CONFIG_MODULE_SIG_FORCE` | `y` + + + +It is also possible to block the loading of modules after startup with +"kernel.modules_disabled". + + + +Domain | `Variable` name | `Value` +------------------------------ | ------------------------- | ------- +Kernel-General-ModuleSigning-2 | `kernel.modules_disabled` | `1` + + + +-------------------------------------------------------------------------------- + + + +## Disable all USB, PCMCIA (and other `hotplug` bus) drivers that aren't needed + +To reduce the attack surface, the driver enumeration, probe, and operation +happen in the kernel. The driver data is parsed by the kernel, so any logic bugs +in these drivers can become kernel exploits. + + + +Domain | Object | _State_ +------------------------ | ------------------- | ---------- +Kernel-General-Drivers-1 | `USB` | _Disabled_ +Kernel-General-Drivers-2 | `PCMCIA` | _Disabled_ +Kernel-General-Drivers-3 | Other `hotplug` bus | _Disabled_ + + + +-------------------------------------------------------------------------------- + +## Position Independent Executables + + + +Domain | Improvement +-------------------------------- | ----------------------------- +Kernel-General-IndependentExec-1 | Kernel or/and platform part ? + + + + + +Domain | `compiler` and `linker` options | _State_ +-------------------------------- | ------------------------------- | -------- +Kernel-General-IndependentExec-1 | `-pie -fpic` | _Enable_ + + + +Produce a position independent executable on targets which supports it. + +-------------------------------------------------------------------------------- + +## Prevent Overwrite Attacks + +`-z,relro` 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. + + + +Domain | `compiler` and `linker` options | _State_ +--------------------------------- | ------------------------------- | -------- +Kernel-General-OverwriteAttacks-1 | `-z,relro` | _Enable_ +Kernel-General-OverwriteAttacks-2 | `-z,now` | _Enable_ + + + +During program load, all dynamic symbols are resolved, allowing for the complete +GOT to be marked read-only (due to `-z relro` above). This prevents GOT +overwrite attacks. For very large application, this can incur some performance +loss during initial load while symbols are resolved, but this shouldn't be an +issue for daemons. + +-------------------------------------------------------------------------------- + + + +## Library linking + + + +Domain | Improvement +------------------------------- | --------------- +Kernel-General-LibraryLinking-1 | Keep this part? + + + +It is recommended that dynamic linking should generally not be allowed. This +will avoid the user from replacing a library with malicious library. + + + +Domain | Object | Recommendations +------------------------------- | --------------- | -------------------------------- +Kernel-General-LibraryLinking-1 | Dynamic linking | Should generally not be allowed. + +Linking everything statically doesn't change anything wrt security as binaries +will live under same user:group as libraries and setuid executables ignore +`LD_PRELOAD/LD_LIBRARY_PATH`. It also increases RSS footprint and creates +problems with upgrading. + +# Memory + +## Restrict access to kernel memory + +The /dev/kmem file in Linux systems is directly mapped to kernel virtual memory. +This can be disastrous if an attacker gains root access, as the attacker would +have direct access to kernel virtual memory. + +To disable the /dev/kmem file, which is very infrequently used by applications, +the following kernel option should be set in the compile-time kernel +configuration: + +Domain | `Config` name | `Value` +------------------------------ | ---------------- | ------- +Kernel-Memory-RestrictAccess-1 | `CONFIG_DEVKMEM` | `n` + +In case applications in userspace need /dev/kmem support, it should be available +only for authenticated applications. + +-------------------------------------------------------------------------------- + +## Disable access to a kernel core dump + +This kernel configuration disables access to a kernel core dump from user space. +If enabled, it gives attackers a useful view into kernel memory. + + + +Domain | `Config` name | `Value` +------------------------ | ------------------- | ------- +Kernel-Memory-CoreDump-1 | `CONFIG_PROC_KCORE` | `n` + + + +-------------------------------------------------------------------------------- + +## Disable swap + +If not disabled, attackers can enable swap at runtime, add pressure to the +memory subsystem and then scour the pages written to swap for useful +information. + + + +Domain | `Config` name | `Value` +-------------------- | ------------- | ------- +Kernel-Memory-Swap-1 | `CONFIG_SWAP` | `n` + + + + + +- Enabling swap at runtime require `CAP_SYS_ADMIN`. +- Swap block device is usually under root:disk. +- Linux never swaps kernel pages. +- If swap disabling is not possible, swap encryption should be enabled. + + + +-------------------------------------------------------------------------------- + + + +## Disable "Load All Symbols" + +There is a /proc/kallsyms file which exposes the kernel memory space address of +many kernel symbols (functions, variables, etc...). This information is useful +to attackers in identifying kernel versions/configurations and in preparing +payloads for the exploits of kernel space. + +Both `KALLSYMS_ALL` and `KALLSYMS` shall be disabled; + + + +Domain | `Config` name | `Value` +------------------------------ | --------------------- | ------- +Kernel-Memory-LoadAllSymbols-1 | `CONFIG_KALLSYMS` | `n` +Kernel-Memory-LoadAllSymbols-2 | `CONFIG_KALLSYMS_ALL` | `n` + + + +-------------------------------------------------------------------------------- + +## Stack protection + +To prevent stack-smashing, similar to the stack protector used for ELF programs +in user-space, the kernel can protect its internal stacks as well. + +This configuration is supported in **Linux 3.11 and greater** and thus should +only be enabled for such versions. + +This configuration also requires building the kernel with the **gcc compiler 4.2 +or greater**. + + + +Domain | `Config` name | `Value` +--------------------- | -------------------------- | ------- +Kernel-Memory-Stack-1 | `CONFIG_CC_STACKPROTECTOR` | `y` + + + +Other defenses include things like shadow stacks. + +-------------------------------------------------------------------------------- + +## Disable access to /dev/mem + +The /dev/mem file in Linux systems is directly mapped to physical memory. This +can be disastrous if an attacker gains root access, as the attacker would have +direct access to physical memory through this convenient device file. It may not +always be possible to disable such file, as some applications might need such +support. In that case, then this device file should be available only for +authenticated applications. + +This configuration is supported in **Linux 4.0 and greater** and thus should +only be disabled for such versions. + + + +Domain | `Config` name | `Value` +---------------------- | --------------- | ------- +Kernel-Memory-Access-1 | `CONFIG_DEVMEM` | `n` + + + +-------------------------------------------------------------------------------- + + + +## Disable cross-memory attach + +Disable the process_vm_*v syscalls which allow one process to peek/poke the +virtual memory of another. + +This configuration is supported in **Linux 3.5 and greater** and thus should +only be disabled for such versions. + + + +Domain | `Config` name | `Value` +------------------------------ | --------------------- | ------- +Kernel-Memory-CrossMemAttach-1 | `CROSS_MEMORY_ATTACH` | `n` + + + +-------------------------------------------------------------------------------- + +## Stack Smashing Attacks + + + +Domain | `compiler` and `linker` options | _State_ +----------------------------- | ------------------------------- | -------- +Kernel-Memory-StackSmashing-1 | `-fstack-protector-all` | _Enable_ + + + +Emit extra code to check for buffer overflows, such as stack smashing attacks. + +-------------------------------------------------------------------------------- + +## Detect Buffer Overflows + +Domain | `compiler` options and `config` name | `Value` +------------------------------- | ------------------------------------ | ------- +Kernel-Memory-BufferOverflows-1 | `-D_FORTIFY_SOURCE` | `2` +Kernel-Memory-BufferOverflows-2 | `CONFIG_FORTIFY_SOURCE` | `y` + +Helps detect some buffer overflow errors. + +# Serial + +## Disable serial console + +The serial console should be disabled to prevent an attacker from accessing this +powerful interface. + +Domain | `Config` name | `Value` +------------------------ | ---------------------------- | ------- +Kernel-Consoles-Serial-1 | `CONFIG_SERIAL_8250` | `n` +Kernel-Consoles-Serial-2 | `CONFIG_SERIAL_8250_CONSOLE` | `n` +Kernel-Consoles-Serial-3 | `CONFIG_SERIAL_CORE` | `n` +Kernel-Consoles-Serial-4 | `CONFIG_SERIAL_CORE_CONSOLE` | `n` + +-------------------------------------------------------------------------------- + +## Bake-in the kernel command-line + +The kernel command-line is used to control many aspects of the booting kernel, +and is prone to tampering as they are passed in RAM with little to no reverse +validation on these parameters. To prevent this type of attack, the kernel shall +be configured to ignore commands line arguments, and use pre-configured (compile +time) options instead. + +Set the kernel command line in the `CONFIG_CMDLINE KConfig` item and then pass +no arguments from the bootloader. + + + +Domain | `Config` name | `Value` +----------------------------- | ------------------------- | ----------------------------------- +Kernel-Consoles-CommandLine-1 | `CONFIG_CMDLINE_BOOL` | `y` +Kernel-Consoles-CommandLine-2 | `CONFIG_CMDLINE` | `"insert kernel command line here"` +Kernel-Consoles-CommandLine-3 | `CONFIG_CMDLINE_OVERRIDE` | `y` + + + +It is recommended that any per-device settings (e.g: MAC addresses, serial +numbers, etc.) be stored and accessed from read-only memory (or files), and that +any such parameters be verified (signature checking) prior to their use. + +-------------------------------------------------------------------------------- + +## Disable KGDB + +The Linux kernel supports KGDB over USB and console ports. These mechanisms are +controlled by the `kgdbdbgp` and `kgdboc` kernel command-line parameters. It is +important to ensure that no shipping product contains a kernel with KGDB +compiled-in. + + + +Domain | `Config` name | `Value` +---------------------- | ------------- | ------- +Kernel-Consoles-KDBG-1 | `CONFIG_KGDB` | `n` + + + +-------------------------------------------------------------------------------- + +## Disable magic sysrq support + +On a few architectures, you can access a powerful debugger interface from the +keyboard. The same powerful interface can be present on the serial console +(responding to serial break) of Linux on other architectures. Disable to avoid +potentially exposing this powerful backdoor. + + + +Domain | `Config` name | `Value` +----------------------- | -------------------- | ------- +Kernel-Consoles-SysRQ-1 | `CONFIG_MAGIC_SYSRQ` | `n` + + + +-------------------------------------------------------------------------------- + +## Disable support for binary formats other than ELF + +This will make possible to plug wrapper-driven binary formats into the kernel. +It enables support for binary formats other than ELF. Providing the ability to +use alternate interpreters would assist an attacker in discovering attack +vectors. + + + +Domain | `Config` name | `Value` +------------------------------ | -------------------- | ------- +Kernel-Consoles-BinaryFormat-1 | `CONFIG_BINFMT_MISC` | `n` + +# Debug + +No debuggers shall be present on the file system. This includes, but is not +limited to, the GNU Debugger client/server (commonly known in their short form +names such as the `gdb` and `gdbserver` executable binaries respectively), the +`LLDB` next generation debugger or the `TCF` (Target Communications Framework) +agnostic framework. Including these binaries as part of the file system will +facilitate an attacker's ability to reverse engineer and debug (either locally +or remotely) any process that is currently executing on the device. + +## Kernel debug symbols + +Debug symbols should always be removed from production kernels as they provide a +lot of information to attackers. + + + +Domain | `Config` name | `Value` +---------------------- | ------------------- | ------- +Kernel-Debug-Symbols-1 | `CONFIG_DEBUG_INFO` | `n` + + + +These kernel debug symbols are enabled by other config items in the kernel. Care +should be taken to disable those also. If `CONFIG_DEBUG_INFO` cannot be +disabled, then enabling `CONFIG_DEBUG_INFO_REDUCED` is second best. + + + +At least `CONFIG_DEBUG_INFO_REDUCED` should be always enabled for developers to +convert addresses in oops messages to line numbers. + + + +-------------------------------------------------------------------------------- + +## Disable Kprobes + +Kprobes enables you to dynamically break into any kernel routine and collect +debugging and performance information non-disruptively. You can trap at almost +any kernel code address, specifying a handler routine to be invoked when the +breakpoint is hit. + + + +Domain | `Config` name | `Value` +---------------------- | ---------------- | ------- +Kernel-Debug-Kprobes-1 | `CONFIG_KPROBES` | `n` + + + +-------------------------------------------------------------------------------- + +## Disable Tracing + +FTrace enables the kernel to trace every kernel function. Providing kernel trace +functionality would assist an attacker in discovering attack vectors. + + + +Domain | `Config` name | `Value` +---------------------- | --------------- | ------- +Kernel-Debug-Tracing-1 | `CONFIG_FTRACE` | `n` + + + +-------------------------------------------------------------------------------- + +## Disable Profiling + +Profiling and OProfile enables profiling the whole system, include the kernel, +kernel modules, libraries, and applications. Providing profiling functionality +would assist an attacker in discovering attack vectors. + + + +Domain | `Config` name | `Value` +------------------------ | ------------------ | ------- +Kernel-Debug-Profiling-1 | `CONFIG_OPROFILE` | `n` +Kernel-Debug-Profiling-2 | `CONFIG_PROFILING` | `n` + + + +-------------------------------------------------------------------------------- + +## Disable OOPS print on BUG() + +The output from OOPS print can be helpful in Return Oriented Programming (ROP) +when trying to determine the effectiveness of an exploit. + + + +Domain | `Config` name | `Value` +------------------------ | ------------------------- | ------- +Kernel-Debug-OOPSOnBUG-1 | `CONFIG_DEBUG_BUGVERBOSE` | `n` + + + +-------------------------------------------------------------------------------- + +## Disable Kernel Debugging + +There are development-only branches of code in the kernel enabled by the +`DEBUG_KERNEL` conf. This should be disabled to compile-out these branches. + + + +Domain | `Config` name | `Value` +------------------ | --------------------- | ------- +Kernel-Debug-Dev-1 | `CONFIG_DEBUG_KERNEL` | `n` +Kernel-Debug-Dev-2 | `CONFIG_EMBEDDED` | `n` + + + +In some kernel versions, disabling this requires also disabling +`CONFIG_EMBEDDED`, and `CONFIG_EXPERT`. Disabling `CONFIG_EXPERT` makes it +impossible to disable `COREDUMP`, `DEBUG_BUGVERBOSE`, `NAMESPACES`, `KALLSYMS` +and `BUG`. In which case it is better to leave this enabled than enable the +others. + +-------------------------------------------------------------------------------- + + + +## Disable the kernel debug filesystem + +The kernel debug filesystem presents a lot of useful information and means of +manipulation of the kernel to an attacker. + + + +Domain | `Config` name | `Value` +------------------------- | ----------------- | ------- +Kernel-Debug-FileSystem-1 | `CONFIG_DEBUG_FS` | `n` + + + +-------------------------------------------------------------------------------- + +## Disable BUG() support + +The kernel will display backtrace and register information for BUGs and WARNs in +kernel space, making it easier for attackers to develop exploits. + + + +Domain | `Config` name | `Value` +------------------ | ------------- | ------- +Kernel-Debug-BUG-1 | `CONFIG_BUG` | `n` + + + +-------------------------------------------------------------------------------- + +## Disable core dumps + +Core dumps provide a lot of debug information for hackers. So disabling core +dumps are recommended in production builds. + +This configuration is supported in **Linux 3.7 and greater** and thus should +only be disabled for such versions. + + + +Domain | `Config` name | `Value` +------------------------ | ----------------- | ------- +Kernel-Debug-CoreDumps-1 | `CONFIG_COREDUMP` | `n` + + + +-------------------------------------------------------------------------------- + + + +## Kernel Address Display Restriction + +When attackers try to develop "run anywhere" exploits for kernel +vulnerabilities, they frequently need to know the location of internal kernel +structures. By treating kernel addresses as sensitive information, those +locations are not visible to regular local users. + +**/proc/sys/kernel/kptr_restrict is set to "1"** to block the reporting of known +kernel address leaks. + + + +Domain | `File` name | `Value` +---------------------------- | -------------------------------- | ------- +Kernel-Debug-AdressDisplay-1 | `/proc/sys/kernel/kptr_restrict` | `1` + + + +Additionally, various files and directories should be readable only by the root +user: `/boot/vmlinuz*`, `/boot/System.map*`, `/sys/kernel/debug/`, +`/proc/slabinfo` + + + +Domain | `File` or `Directorie` name | _State_ +---------------------------- | --------------------------- | ----------------------------- +Kernel-Debug-AdressDisplay-1 | `/boot/vmlinuz*` | _Readable Only for root user_ +Kernel-Debug-AdressDisplay-2 | `/boot/System.map*` | _Readable Only for root user_ +Kernel-Debug-AdressDisplay-3 | `/sys/kernel/debug/` | _Readable Only for root user_ +Kernel-Debug-AdressDisplay-4 | `/proc/slabinfo` | _Readable Only for root user_ + + + +-------------------------------------------------------------------------------- + +## DMESG Restrictions + +When attackers try to develop "run anywhere" exploits for vulnerabilities, they +frequently will use `dmesg` output. By treating `dmesg` output as sensitive +information, this output is not available to the attacker. + +**/proc/sys/kernel/dmesg_restrict can be set to "1"** to treat dmesg output as +sensitive. + + + +Domain | `File` name | `Value` +-------------------- | --------------------------------- | ------- +Kernel-Debug-DMESG-1 | `/proc/sys/kernel/dmesg_restrict` | `1` + + + +Enable the below compiler and linker options when building user-space +applications to avoid stack smashing, buffer overflow attacks. + +-------------------------------------------------------------------------------- + + + +## Disable /proc/config.gz + +It is extremely important to not expose the kernel configuration used on a +production device to a potential attacker. With access to the kernel config, it +could be possible for an attacker to build a custom kernel for the device that +may disable critical security features. + + + +Domain | `Config` name | `Value` +--------------------- | ----------------- | ------- +Kernel-Debug-Config-1 | `CONFIG_IKCONFIG` | `n` + +# File System + +## Disable all file systems not needed + +To reduce the attack surface, file system data is parsed by the kernel, so any +logic bugs in file system drivers can become kernel exploits. + +### Disable NFS file system + +NFS FileSystems are useful during development phases, but this can be a very +helpful way for an attacker to get files when you are in production mode, so we +must disable them. + + + +Domain | `Config` name | `Value` +------------------------ | --------------- | ------- +Kernel-FileSystems-NFS-1 | `CONFIG_NFSD` | `n` +Kernel-FileSystems-NFS-2 | `CONFIG_NFS_FS` | `n` + + + +-------------------------------------------------------------------------------- + + + +## Partition Mount Options + +There are several security restrictions that can be set on a filesystem when it +is mounted. Some common security options include, but are not limited to: + +`nosuid` - Do not allow set-user-identifier or set-group-identifier bits to take +effect. + +`nodev` - Do not interpret character or block special devices on the filesystem. + +`noexec` - Do not allow execution of any binaries on the mounted filesystem. + +`ro` - Mount filesystem as read-only. + +The following flags shall be used for mounting common filesystems: + + + +Domain | `Partition` | `Value` +-------------------------- | ------------------- | ----------------------------------------------------------------- +Kernel-FileSystems-Mount-1 | `/boot` | `nosuid`, `nodev` and `noexec`. +Kernel-FileSystems-Mount-2 | `/var` & `/tmp` | In `/etc/fstab` or `vfstab`, add `nosuid`, `nodev` and `noexec`. +Kernel-FileSystems-Mount-3 | _Non-root local_ | If type is `ext2` or `ext3` and mount point not '/', add `nodev`. +Kernel-FileSystems-Mount-4 | _Removable storage_ | Add `nosuid`, `nodev` and `noexec`. +Kernel-FileSystems-Mount-5 | _Temporary storage_ | Add `nosuid`, `nodev` and `noexec`. +Kernel-FileSystems-Mount-6 | `/dev/shm` | Add `nosuid`, `nodev` and `noexec`. +Kernel-FileSystems-Mount-7 | `/dev` | Add `nosuid` and `noexec`. + + + +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. + + + +Domain | `Config` name | _State_ or `Value` +-------------------------- | ----------------------- | ----------------------------------------------------------------------- +Kernel-FileSystems-Mount-1 | `CONFIG_DEVTMPFS_MOUNT` | _Disabled_ or add remount with `noexec` and `nosuid` to system startup. \ No newline at end of file diff --git a/docs/3_Architecture_Guides/2_Security_Blueprint/6_Platform.md b/docs/3_Architecture_Guides/2_Security_Blueprint/6_Platform.md new file mode 100644 index 0000000..2112fdc --- /dev/null +++ b/docs/3_Architecture_Guides/2_Security_Blueprint/6_Platform.md @@ -0,0 +1,921 @@ +--- +title: Platform +--- + +The Automotive Grade Linux platform is a Linux distribution with **AGL** +compliant applications and services. The platform includes the following +software: + +- Linux **BSP** configured for reference boards. +- Proprietary device drivers for common peripherals on reference boards. +- Application framework. +- Windows/layer management (graphics). +- Sound resource management. +- An atomic software update system (chapter Update). +- Building and debug tools (based on Yocto project). + + + +Domain | Improvement +------------------- | -------------------------------- +Platform-Abstract-1 | Create a graphics and sound part. + + + +This part focuses on the AGL platform including all tools and techniques used to +upgrade the security and downgrade the danger. It must be possible to apply the +two fundamental principles written at the very beginning of the document. First +of all, security management must remain simple. You must also prohibit +everything by default, and then define a set of authorization rules. As cases to +deal with, we must: + +- Implement a **MAC** for processes and files. +- Limit communication between applications (_SystemBus_ and _SystemD_ part). +- Prohibit all tools used during development mode (_Utilities_ and _Services_ + part). +- Manage user capabilities (_Users_ part). +- Manage application permissions and policies (_AGLFw_ part). + + + +The tools and concepts used to meet these needs are only examples. Any other +tool that meets the need can be used. + + + +In AGL, as in many other embedded systems, different security mechanisms settle +in the core layers to ensure isolation and data privacy. While the Mandatory +Access Control layer (**SMACK**) provides global security and isolation, other +mechanisms like **Cynara** are required to check application's permissions at +runtime. Applicative permissions (also called "_privileges_") may vary depending +on the user and the application being run: an application should have access to +a given service only if it is run by the proper user and if the appropriate +permissions are granted. + +## Discretionary Access Control + +**D**iscretionary **A**ccess **C**ontrol (**DAC**) is the traditional Linux +method of separating users and groups from one another. In a shared environment +where multiple users have access to a computer or network, Unix IDs have offered +a way to contain access within privilege areas for individuals, or shared among +the group or system. The Android system took this one step further, assigning +new user IDs for each App. This was never the original intention of Linux UIDs, +but was able to provide Android’s initial security element: the ability to +sandbox applications. + +Although AGL mentions use of **DAC** for security isolation, the weight of the +security responsibility lies in the **M**andatory **A**ccess **C**ontrol +(**MAC**) and **Cynara**. Furthermore, there are system services with unique +UIDs. however,the system does not go to the extreme of Android, where every +application has its own UID. All sandboxing (app isolation) in AGL is handled in +the **MAC** contexts. + +## Mandatory Access Control + +**M**andatory **A**ccess **C**ontrol (**MAC**) is an extension to **DAC**, +whereby extended attributes (xattr) are associated with the filesystem. In the +case of AGL, the smackfs filesystem allows files and directories to be +associated with a SMACK label, providing the ability of further discrimination +on access control. A SMACK label is a simple null terminated character string +with a maximum of 255 bytes. While it doesn’t offer the richness of an SELinux +label, which provides a user, role,type, and level, the simplicity of a single +value makes the overall design far less complex. There is arguably less chance +of the security author making mistakes in the policies set forth. + +-------------------------------------------------------------------------------- + + + +## Acronyms and Abbreviations + +The following table lists the terms utilized within this part of the document. + +Acronyms or Abbreviations | Description +------------------------- | -------------------------------------------------------------- +_ACL_ | **A**ccess **C**ontrol **L**ists +_alsa_ | **A**dvanced **L**inux **S**ound **A**rchitecture +_API_ | **A**pplication **P**rogramming **I**nterface +_AppFw_ | **App**lication **F**rame**w**ork +_BSP_ | **B**oard **S**upport **P**ackage +_Cap_ | **Cap**abilities +_DAC_ | **D**iscretionary **A**ccess **C**ontrol +_DDOS_ | **D**istributed **D**enial **O**f **S**ervice +_DOS_ | **D**enial **O**f **S**ervice +_IPC_ | **I**nter-**P**rocess **C**ommunication +_MAC_ | **M**andatory **A**ccess **C**ontrol +_PAM_ | **P**luggable **A**uthentication **M**odules +_SMACK_ | **S**implified **M**andatory **A**ccess **C**ontrol **K**ernel + +# Mandatory Access Control + + + +We decided to put the **MAC** protection on the platform part despite the fact +that it applies to the kernel too, since its use will be mainly at the platform +level (except floor part). + + + +**M**andatory **A**ccess **C**ontrol (**MAC**) is a protection provided by the +Linux kernel that requires a **L**inux **S**ecurity **M**odule (**LSM**). AGL +uses an **LSM** called **S**implified **M**andatory **A**ccess **C**ontrol +**K**ernel (**SMACK**). This protection involves the creation of **SMACK** +labels as part of the extended attributes **SMACK** labels to the file extended +attributes. And a policy is also created to define the behaviour of each label. + +The kernel access controls is based on these labels and this policy. If there is +no rule, no access will be granted and as a consequence, what is not explicitly +authorized is forbidden. + +There are two types of **SMACK** labels: + +- **Execution SMACK** (Attached to the process): Defines how files are + _accessed_ and _created_ by that process. +- **File Access SMACK** (Written to the extended attribute of the file): Defines + _which_ process can access the file. + +By default a process executes with its File Access **SMACK** label unless an +Execution **SMACK** label is defined. + +AGL's **SMACK** scheme is based on the _Tizen 3 Q2/2015_. It divides the System +into the following domains: + +- Floor. +- System. +- Applications, Services and User. + +See [AGL security framework +review](http://iot.bzh/download/public/2017/AMMQ1Tokyo/AGL-security-framework-review.pdf) +and [Smack White +Paper](http://schaufler-ca.com/yahoo_site_admin/assets/docs/SmackWhitePaper.257153003.pdf) +for more information. + +-------------------------------------------------------------------------------- + + + +## Floor + +The _floor_ domain includes the base system services and any associated data and +libraries. This data remains unchanged at runtime. Writing to floor files or +directories is allowed only in development mode or during software installation +or upgrade. + +The following table details the _floor_ domain: + +Label | Name | Execution **SMACK** | File Access **SMACK** +----- | ----- | ------------------- | --------------------------------------- +`-` | Floor | `r-x` for all | Only kernel and internal kernel thread. +`^` | Hat | `---` for all | `rx` on all domains. +`*` | Star | `rwx` for all | None + + + +- The Hat label is Only for privileged system services (currently only + systemd-journal). Useful for backup or virus scans. No file with this label + should exist except in the debug log. + +- The Star label is used for device files or `/tmp` Access restriction managed + via **DAC**. Individual files remain protected by their **SMACK** label. + + + +Domain | `Label` name | Recommendations +------------------ | ------------ | ----------------------------------------------------------- +Kernel-MAC-Floor-1 | `^` | Only for privileged system services. +Kernel-MAC-Floor-2 | `*` | Used for device files or `/tmp` Access restriction via DAC. + + + +-------------------------------------------------------------------------------- + + + +## System + +The _system_ domain includes a reduced set of core system services of the OS and +any associated data. This data may change at runtime. + +The following table details the _system_ domain: + +Label | Name | Execution **SMACK** | File Access **SMACK** +---------------- | --------- | ----------------------------------------------- | --------------------- +`System` | System | None | Privileged processes +`System::Run` | Run | `rwxatl` for User and System label | None +`System::Shared` | Shared | `rwxatl` for system domain `r-x` for User label | None +`System::Log` | Log | `rwa` for System label `xa` for user label | None +`System::Sub` | SubSystem | Subsystem Config files | SubSystem only + + + +Domain | `Label` name | Recommendations +------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------- +Kernel-MAC-System-1 | `System` | Process should write only to file with transmute attribute. +Kernel-MAC-System-2 | `System::run` | Files are created with the directory label from user and system domain (transmute) Lock is implicit with `w`. +Kernel-MAC-System-3 | `System::Shared` | Files are created with the directory label from system domain (transmute) User domain has locked privilege. +Kernel-MAC-System-4 | `System::Log` | Some limitation may impose to add `w` to enable append. +Kernel-MAC-System-5 | `System::Sub` | Isolation of risky Subsystem. + + + +-------------------------------------------------------------------------------- + + + +## Applications, Services and User + +The _application_, _services_ and _user_ domain includes code that provides +services to the system and user, as well as any associated data. All code +running on this domain is under _Cynara_ control. + +The following table details the _application_, _services_ and _user_ domain: + +Label | Name | Execution **SMACK** | File Access **SMACK** +------------------- | ------ | --------------------------------------------------------------------------- | --------------------------- +`User::Pkg::$AppID` | AppID | `rwx` (for files created by the App). `rx` for files installed by **AppFw** | $App runtime executing $App +`User::Home` | Home | `rwx-t` from System label `r-x-l` from App | None +`User::App-Shared` | Shared | `rwxat` from System and User domains label of $User | None + + + +Domain | `Label` name | Recommendations +------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- +Kernel-MAC-System-1 | `User::Pkg::$AppID` | Only one Label is allowed per App. A data directory is created by the AppFw in `rwx` mode. +Kernel-MAC-System-2 | `User::Home` | AppFw needs to create a directory in `/home/$USER/App-Shared` at first launch if not present with label app-data access is `User::App-Shared` without transmute. +Kernel-MAC-System-3 | `User::App-Shared` | Shared space between all App running for a given user. + + + +## Attack Vectors + +There are 4 major components to the system: + +- The LSM kernel module. +- The `smackfs` filesystem. +- Basic utilities for policy management and checking. +- The policy/configuration data. + +As with any mandatory access system, the policy management needs to be carefully +separated from the checking, as the management utilities can become a convenient +point of attack. Dynamic additions to the policy system need to be carefully +verified, as the ability to update the policies is often needed, but introduces +a possible threat. Finally, even if the policy management is well secured, the +policy checking and failure response to that checking is also of vital +importance to the smooth operation of the system. + +While **MAC** is a certainly a step up in security when compared to DAC, there +are still many ways to compromise a SMACK-enabled Linux system. Some of these +ways are as follows: + +- Disabling SMACK at invocation of the kernel (with command-line: + security=none). +- Disabling SMACK in the kernel build and redeploying the kernel. +- Changing a SMACK attribute of a file or directory at install time. +- Tampering with a process with the CAP_MAC_ADMIN privilege. +- Setting/Re-setting the SMACK label of a file. +- Tampering with the default domains (i.e. + /etc/smack/accesses.d/default-access-domains). +- Disabling or tampering with the SMACK filesystem (i.e. /smackfs). +- Adding policies with `smackload` (adding the utility if not present). +- Changing labels with `chsmack` (adding the utility if not present). + +# SystemD + +`afm-system-daemon` is used to: + +- Manage users and user sessions. +- Setup applications and services (_CGroups_, _namespaces_, autostart, + permissions). +- Use of `libsystemd` for its programs (event management, **D-Bus** interface). + + + +Domain | Object | Recommendations +------------------ | -------------- | ------------------------------------ +Platform-SystemD-1 | Security model | Use Namespaces for containerization. +Platform-SystemD-2 | Security model | Use CGroups to organise processes. + + + +See [systemd integration and user +management](http://iot.bzh/download/public/2017/AMM-Dresden/AGL-systemd.pdf) for +more information. + +## Benefits + +- Removal of one privileged process: **afm-user-daemon** +- Access and use of high level features: + + - Socket activation. + - Management of users and integration of **PAM**. + - Dependency resolution to services. + - `Cgroups` and resource control. + - `Namespaces` containerization. + - Autostart of required API. + - Permissions and security settings. + - Network management. + + + +## CGroups + +Control Groups offer a lot of features, with the most useful ones you can +control: Memory usage, how much CPU time is allocated, how much device I/O is +allowed or which devices can be accessed. **SystemD** uses _CGroups_ to organise +processes (each service is a _CGroups_, and all processes started by that +service use that _CGroups_). By default, **SystemD** automatically creates a +hierarchy of slice, scope and service units to provide a unified structure for +the _CGroups_ tree. With the `systemctl` command, you can further modify this +structure by creating custom slices. Currently, in AGL, there are 2 slices +(**user.slice** and **system.slice**). + +## Namespaces + +### User side + +There are several ways of authenticating users (Key Radio Frequency, Phone, +Gesture, ...). Each authentication provides dynamic allocation of **uids** to +authenticated users. **Uids** is used to ensure privacy of users and **SMACK** +for applications privacy. + +First, the user initiates authentication with **PAM** activation. **PAM** +Standard offers highly configurable authentication with modular design like face +recognition, Voice identification or with a password. Then users should access +identity services with services and applications. + +# D-Bus + +D-Bus is a well-known **IPC** (Inter-Process Communication) protocol (and +daemon) that helps applications to talk to each other. The use of D-Bus is great +because it allows to implement discovery and signaling. + +The D-Bus session is by default addressed by environment variable +`DBUS_SESSION_BUS_ADDRESS`. Using **systemd** variable +`DBUS_SESSION_BUS_ADDRESS` is automatically set for user sessions. D-Bus usage +is linked to permissions. + +D-Bus has already had several [security +issues](https://www.cvedetails.com/vulnerability-list/vendor_id-13442/D-bus-Project.html) +(mostly **DoS** issues), to allow applications to keep talking to each other. It +is important to protect against this type of attack to keep the system more +stable. + + + + +Domain | Object | Recommendations +--------------- | -------------- | ------------------------------------ +Platform-DBus-1 | Security model | Use D-Bus as IPC. +Platform-DBus-2 | Security model | Apply D-BUS security patches: [D-Bus CVE](https://www.cvedetails.com/vulnerability-list/vendor_id-13442/D-bus-Project.html) + + + +# System services and daemons + + + +Domain | Improvement +------------------- | ----------- +Platform-Services-1 | SystemD ? +Platform-Services-2 | Secure daemon ? + + + +## Tools + +- **connman**: An internet connection manager designed to be slim and to use as + few resources as possible. It is a fully modular system that can be extended, + through plug-ins, to support all kinds of wired or wireless technologies. +- **bluez** is a Bluetooth stack. Its goal is to program an implementation of + the Bluetooth wireless standards specifications. In addition to the basic + stack, the `bluez-utils` and `bluez-firmware` packages contain low level + utilities such as `dfutool` which can interrogate the Bluetooth adapter + chipset in order to determine whether its firmware can be upgraded. +- **gstreamer** is a pipeline-based multimedia framework. It can be used to + build a system that reads files in one format, processes them, and exports + them in another format. +- **alsa** is a software framework and part of the Linux kernel that provides an + **API** for sound card device drivers. + + + +Domain | `Tool` name | _State_ +-------------------- | ----------- | ------- +Platform-Utilities-1 | `connman` | _Used_ as a connection manager. +Platform-Utilities-2 | `bluez` | _Used_ as a Bluetooth manager. +Platform-Utilities-3 | `gstreamer` | _Used_ to manage multimedia file format. +Platform-Utilities-4 | `alsa` | _Used_ to provides an API for sound card device drivers. + + + +# Application framework/model (**AppFw**) + +The AGL application framework consists of several inter-working parts: + +- **SMACK**: The kernel level **LSM** (**L**inux **S**ecurity **M**odule) that + performs extended access control of the system. +- **Cynara**: the native gatekeeper daemon used for policy handling, updating to + the database and policy checking. +- Security Manager: a master service, through which all security events are + intended to take place. +- Several native application framework utilities: `afm-main-binding`, + `afm-user-daemon`, `afm-system-daemon`. + +The application framework manages: + +- The applications and services management: Installing, Uninstalling, Listing, + ... +- The life cycle of applications: Start -> (Pause, Resume) -> Stop. +- Events and signals propagation. +- Privileges granting and checking. +- API for interaction with applications. + + + +- The **security model** refers to the security model used to ensure security + and to the tools that are provided for implementing that model. It's an + implementation detail that should not impact the layers above the application + framework. + +- The **security model** refers to how **DAC** (**D**iscretionary **A**ccess + **C**ontrol), **MAC** (Mandatory Access Control) and `Capabilities` are used + by the system to ensure security and privacy. It also includes features of + reporting using audit features and by managing logs and alerts. + + + +The **AppFw** uses the security model to ensure the security and the privacy of +the applications that it manages. It must be compliant with the underlying +security model. But it should hide it to the applications. + + + +Domain | Object | Recommendations +---------------------- | -------------- | -------------------------------- +Platform-AGLFw-AppFw-1 | Security model | Use the AppFw as Security model. + + + +See [AGL AppFw Privileges +Management](http://docs.automotivelinux.org/docs/devguides/en/dev/reference/iotbzh2016/appfw/03-AGL-AppFW-Privileges-Management.pdf) +and [AGL - Application Framework +Documentation](http://iot.bzh/download/public/2017/SDK/AppFw-Documentation-v3.1.pdf) +for more information. + + + +The Security Manager communicates policy information to **Cynara**, which +retains information in its own database in the format of a text file with +comma-separated values (CSV). There are provisions to retain a copy of the CSV +text file when the file is being updated. + +Runtime checking occurs through **Cynara**. Each application that is added to +the framework has its own instantiation of a SMACK context and D-bus bindings. +The afb_daemon and Binder form a web-service that is communicated to through +http or a websocket from the application-proper. This http or websocket +interface uses a standard unique web token for API communication. + +![Application Framework Flow](images/App-flow.png) + +## Cynara + +There's a need for another mechanism responsible for checking applicative +permissions: Currently in AGL, this task depends on a policy-checker service +(**Cynara**). + +- Stores complex policies in databases. +- "Soft" security (access is checked by the framework). + +Cynara interact with **D-Bus** in order to deliver this information. + +Cynara consists of several parts: + +- Cynara: a daemon for controlling policies and responding to access control + requests. +- Database: a spot to hold policies. +- Libraries: several static and dynamic libraries for communicating with Cynara. + +The daemon communicates to the libraries over Unix domain sockets. The database +storage format is a series of CSV-like files with an index file. + +There are several ways that an attacker can manipulate policies of the Cynara +system: + +- Disable Cynara by killing the process. +- Tamper with the Cynara binary on-disk or in-memory. +- Corrupt the database controlled by Cynara. +- Tamper with the database controlled by Cynara. +- Highjack the communication between Cynara and the database. + +The text-based database is the weakest part of the system and although there are +some consistency mechanisms in place (i.e. the backup guard), these mechanisms +are weak at best and can be countered by an attacker very easily. + + + +Domain | Object | Recommendations +----------------------- | ----------- | ------------------------------------- +Platform-AGLFw-Cynara-1 | Permissions | Use Cynara as policy-checker service. + + + +### Policies + +- Policy rules: + + - Are simple - for pair [application context, privilege] there is straight + answer (single Policy Type): [ALLOW / DENY / ...]. + - No code is executed (no script). + - Can be easily cached and managed. + +- Application context (describes id of the user and the application credentials) + It is build of: + + - UID of the user that runs the application. + - **SMACK** label of application. + +## Holding policies + +Policies are kept in buckets. Buckets are set of policies which have additional +a property of default answer, the default answer is yielded if no policy matches +searched key. Buckets have names which might be used in policies (for +directions). + +## Attack Vectors + +The following attack vectors are not completely independent. While attackers may +have varying levels of access to an AGL system, experience has shown that a +typical attack can start with direct access to a system, find the +vulnerabilities, then proceed to automate the attack such that it can be invoked +from less accessible standpoint (e.g. remotely). Therefore, it is important to +assess all threat levels, and protect the system appropriately understanding +that direct access attacks are the door-way into remote attacks. + +### Remote Attacks + +The local web server interface used for applications is the first point of +attack, as web service APIs are well understood and easily intercepted. The +local web server could potentially be exploited by redirecting web requests +through the local service and exploiting the APIs. While there is the use of a +security token on the web service API, this is weak textual matching at best. +This will not be difficult to spoof. It is well known that [API Keys do not +provide any real security](http://nordicapis.com/why-api-keys-are-not-enough/). + +It is likely that the architectural inclusion of an http / web-service interface +provided the most flexibility for applications to be written natively or in +HTML5. However, this flexibility may trade-off with security concerns. For +example, if a native application were linked directly to the underlying +framework services, there would be fewer concerns over remote attacks coming +through the web-service interface. + +Leaving the interface as designed, mitigations to attacks could include further +securing the interface layer with cryptographic protocols: e.g. encrypted +information passing, key exchange (e.g. Elliptic-Curve Diffie-Hellman). + +### User-level Native Attacks + +- Modifying the CSV data-base +- Modifying the SQLite DB +- Tampering with the user-level binaries +- Tampering with the user daemons +- Spoofing the D-bus Interface +- Adding executables/libraries + +With direct access to the device, there are many security concerns on the native +level. For example, as **Cynara** uses a text file data-base with +comma-separated values (CSV), an attacker could simply modify the data-base to +escalate privileges of an application. Once a single application has all the +privileges possible on the system, exploits can come through in this manner. +Similarly the SQLite database used by the Security Manager is not much different +than a simple text file. There are many tools available to add, remove, modify +entries in an SQLite data-base. + +On the next level, a common point of attack is to modify binaries or daemons for +exploiting functionality. There are many Linux tools available to aid in this +regard, including: [IDA Pro](https://www.hex-rays.com/products/ida/index.shtml), +and [radare2](https://rada.re/r/). With the ability to modify binaries, an +attacker can do any number of activities including: removing calls to security +checks, redirecting control to bypass verification functionality, ignoring +security policy handling, escalating privileges, etc. + +Additionally, another attack vector would be to spoof the D-bus interface. D-bus +is a message passing system built upon Inter-Process Communication (IPC), where +structured messages are passed based upon a protocol. The interface is generic +and well documented. Therefore, modifying or adding binaries/libraries to spoof +this interface is a relatively straight-forward process. Once the interface has +been spoofed, the attacker can issue any number of commands that lead into +control of low-level functionality. + +Protecting a system from native attacks requires a methodical approach. First, +the system should reject processes that are not sanctioned to run. +Signature-level verification at installation time will help in this regard, but +run-time integrity verification is much better. Signatures need to originate +from authorized parties, which is discussed further in a later section on the +Application Store. + +On the next level, executables should not be allowed to do things where they +have not been granted permission. DAC and SMACK policies can help in this +regard. On the other hand, there remain concerns with memory accesses, system +calls, and other process activity that may go undetected. For this reason, a +secure environment which monitors all activity can give indication of all +unauthorized activity on the system. + +Finally, it is very difficult to catch attacks of direct tampering in a system. +These types of attacks require a defense-in-depth approach, where complementary +software protection and hardening techniques are needed. Tamper-resistance and +anti-reverse-engineering technologies include program +transformations/obfuscation, integrity verification, and white-box cryptography. +If applied in a mutually-dependent fashion and considering performance/security +tradeoffs, the approach can provide an effective barrier to direct attacks to +the system. Furthermore, the use of threat monitoring provides a valuable +telemetry/analytics capability and the ability to react and renew a system under +attack. + +### Root-level Native Attacks + +- Tampering the system daemon +- Tampering Cynara +- Tampering the security manager +- Disabling SMACK +- Tampering the kernel + +Once root-level access (i.e. su) has been achieved on the device, there are many +ways to compromise the system. The system daemon, **Cynara**, and the security +manager are vulnerable to tampering attacks. For example, an executable can be +modified in memory to jam a branch, jump to an address, or disregard a check. +This can be as simple as replacing a branch instruction with a NOP, changing a +memory value, or using a debugger (e.g. gdb, IDA) to change an instruction. +Tampering these executables would mean that policies can be ignored and +verification checks can be bypassed. + +Without going so far as to tamper an executable, the **SMACK** system is also +vulnerable to attack. For example, if the kernel is stopped and restarted with +the *security=none* flag, then SMACK is not enabled. Furthermore, `systemd` +starts the loading of **SMACK** rules during start-up. If this start-up process +is interfered with, then **SMACK** will not run. Alternatively, new policies can +be added with `smackload` allowing unforeseen privileges to alternative +applications/executables. + +Another intrusion on the kernel level is to rebuild the kernel (as it is +open-source) and replace it with a copy that has **SMACK** disabled, or even +just the **SMACK** filesystem (`smackfs`) disabled. Without the extended label +attributes, the **SMACK** system is disabled. + +Root-level access to the device has ultimate power, where the entire system can +be compromised. More so, a system with this level access allows an attacker to +craft a simpler *point-attack* which can operate on a level requiring fewer +privileges (e.g. remote access, user-level access). + +## Vulnerable Resources + +### Resource: `afm-user-daemon` + +The `afm-user-daemon` is in charge of handling applications on behalf of a user. +Its main tasks are: + +- Enumerate applications that the end user can run and keep this list available + on demand. +- Start applications on behalf of the end user, set user running environment, + set user security context. +- List current runnable or running applications. +- Stop (aka pause), continue (aka resume), terminate a running instance of a + given application. +- Transfer requests for installation/uninstallation of applications to the + corresponding system daemon afm-system-daemon. + +The `afm-user-daemon` launches applications. It builds a secure environment for +the application before starting it within that environment. Different kinds of +applications can be launched, based on a configuration file that describes how +to launch an application of a given kind within a given launching mode: local or +remote. Launching an application locally means that the application and its +binder are launched together. Launching an application remotely translates in +only launching the application binder. + +The UI by itself has to be activated remotely by a request (i.e. HTML5 +homescreen in a browser). Once launched, running instances of the application +receive a `runid` that identifies them. `afm-user-daemon` manages the list of +applications that it has launched. When owning the right permissions, a client +can get the list of running instances and details about a specific running +instance. It can also terminate, stop or continue a given application. If the +client owns the right permissions, `afm-user-daemon` delegates the task of +installing and uninstalling applications to `afm-system-daemon`. + +`afm-user-daemon` is launched as a `systemd` service attached to a user session. +Normally, the service file is located at +/usr/lib/systemd/user/afm-user-daemon.service. + +Attacker goals: + +- Disable `afm-user-daemon`. +- Tamper with the `afm-user-daemon` configuration. + - /usr/lib/systemd/user/afm-user-daemon.service. + - Application(widget) config.xml file. + - /etc/afm/afm-launch.conf (launcher configuration). + +- Escalate user privileges to gain more access with `afm-user-daemon`. +- Install malicious application (widget). +- Tamper with `afm-user-daemon` on disk or in memory. + +### Resource: `afm-system-daemon` + +The `afm-system-daemon` is in charge of installing applications on the AGL +system. Its main tasks are: + +- Install applications and setup security framework for newly installed + applications. +- Uninstall applications. + +`afm-system-daemon` is launched as a `systemd` service attached to system. +Normally, the service file is located at +/lib/systemd/system/afm-systemdaemon.service. + +Attacker goals: + +- Disable `afm-system-daemon`. +- Tamper with the `afm-system-daemon` configuration. +- Tamper `afm-system-daemon` on disk or in memory. + +### Resource `afb-daemon` + +`afb-binder` is in charge of serving resources and features through an HTTP +interface. `afb-daemon` is in charge of binding one instance of an application +to the AGL framework and AGL system. The application and its companion binder +run in a secured and isolated environment set for them. Applications are +intended to access to AGL system through the binder. `afb-daemon` binders serve +files through HTTP protocol and offers developers the capability to expose +application API methods through HTTP or WebSocket protocol. + +Binder bindings are used to add APIs to `afb-daemon`. The user can write a +binding for `afb-daemon`. The binder `afb-daemon` serves multiple purposes: + +1. It acts as a gateway for the application to access the system. +2. It acts as an HTTP server for serving files to HTML5 applications. +3. It allows HTML5 applications to have native extensions subject to security + enforcement for accessing hardware resources or for speeding up parts of + algorithm. + +Attacker goals: + +- Break from isolation. +- Disable `afb-daemon`. +- Tamper `afb-demon` on disk or in memory. +- Tamper **capabilities** by creating/installing custom bindings for + `afb-daemon`. + +# Utilities + +- **busybox**: Software that provides several stripped-down Unix tools in a + single executable file. Of course, it will be necessary to use a "production" + version of **busybox** in order to avoid all the tools useful only in + development mode. + + + +Domain | `Tool` name | _State_ +-------------------- | ----------- | ---------------------------------------------------------------------- +Platform-Utilities-1 | `busybox` | _Used_ to provide a number of tools. Do not compile development tools. + + + +## Functionalities to exclude in production mode + +In production mode, a number of tools must be disabled to prevent an attacker +from finding logs for example. This is useful to limit the visible surface and +thus complicate the fault finding process. The tools used only in development +mode are marked by an '**agl-devel**' feature. When building in production mode, +these tools will not be compiled. + + + +Domain | `Utility` name and normal `path` | _State_ +--------------------- | ---------------------------------------------------- | ---------- +Platform-Utilities-1 | `chgrp` in `/bin/chgrp` | _Disabled_ +Platform-Utilities-2 | `chmod` in `/bin/chmod` | _Disabled_ +Platform-Utilities-3 | `chown` in `/bin/chown` | _Disabled_ +Platform-Utilities-4 | `dmesg` in `/bin/dmesg` | _Disabled_ +Platform-Utilities-5 | `Dnsdomainname` in `/bin/dnsdomainname` | _Disabled_ +Platform-Utilities-6 | `dropbear`, Remove "dropbear" from `/etc/init.d/rcs` | _Disabled_ +Platform-Utilities-7 | `Editors` in (vi) `/bin/vi` | _Disabled_ +Platform-Utilities-8 | `find` in `/bin/find` | _Disabled_ +Platform-Utilities-9 | `gdbserver` in `/bin/gdbserver` | _Disabled_ +Platform-Utilities-10 | `hexdump` in `/bin/hexdump` | _Disabled_ +Platform-Utilities-11 | `hostname` in `/bin/hostname` | _Disabled_ +Platform-Utilities-12 | `install` in `/bin/install` | _Disabled_ +Platform-Utilities-13 | `iostat` in `/bin/iostat` | _Disabled_ +Platform-Utilities-14 | `killall` in `/bin/killall` | _Disabled_ +Platform-Utilities-15 | `klogd` in `/sbin/klogd` | _Disabled_ +Platform-Utilities-16 | `logger` in `/bin/logger` | _Disabled_ +Platform-Utilities-17 | `lsmod` in `/sbin/lsmod` | _Disabled_ +Platform-Utilities-18 | `pmap` in `/bin/pmap` | _Disabled_ +Platform-Utilities-19 | `ps` in `/bin/ps` | _Disabled_ +Platform-Utilities-20 | `ps` in `/bin/ps` | _Disabled_ +Platform-Utilities-21 | `rpm` in `/bin/rpm` | _Disabled_ +Platform-Utilities-22 | `SSH` | _Disabled_ +Platform-Utilities-23 | `stbhotplug` in `/sbin/stbhotplug` | _Disabled_ +Platform-Utilities-24 | `strace` in `/bin/trace` | _Disabled_ +Platform-Utilities-25 | `su` in `/bin/su` | _Disabled_ +Platform-Utilities-26 | `syslogd` in (logger) `/bin/logger` | _Disabled_ +Platform-Utilities-27 | `top` in `/bin/top` | _Disabled_ +Platform-Utilities-28 | `UART` in `/proc/tty/driver/` | _Disabled_ +Platform-Utilities-29 | `which` in `/bin/which` | _Disabled_ +Platform-Utilities-30 | `who` and `whoami` in `/bin/whoami` | _Disabled_ +Platform-Utilities-31 | `awk` (busybox) | _Enabled_ +Platform-Utilities-32 | `cut` (busybox) | _Enabled_ +Platform-Utilities-33 | `df` (busybox) | _Enabled_ +Platform-Utilities-34 | `echo` (busybox) | _Enabled_ +Platform-Utilities-35 | `fdisk` (busybox) | _Enabled_ +Platform-Utilities-36 | `grep` (busybox) | _Enabled_ +Platform-Utilities-37 | `mkdir` (busybox) | _Enabled_ +Platform-Utilities-38 | `mount` (vfat) (busybox) | _Enabled_ +Platform-Utilities-39 | `printf` (busybox) | _Enabled_ +Platform-Utilities-40 | `sed` in `/bin/sed` (busybox) | _Enabled_ +Platform-Utilities-41 | `tail` (busybox) | _Enabled_ +Platform-Utilities-42 | `tee` (busybox) | _Enabled_ +Platform-Utilities-43 | `test` (busybox) | _Enabled_ + + + +The _Enabled_ Unix/Linux utilities above shall be permitted as they are often +used in the start-up scripts and for USB logging. If any of these utilities are +not required by the device then those should be removed. + + + +# Users + +The user policy can group users by function within the car. For example, we can +consider a driver and his passengers. Each user is assigned to a single group to +simplify the management of space security. + +## Root Access + +The main applications, those that provide the principal functionality of the +embedded device, should not execute with root identity or any capability. + +If the main application is allowed to execute at any capability, then the entire +system is at the mercy of the said application's good behaviour. Problems arise +when an application is compromised and able to execute commands which could +consistently and persistently compromise the system by implanting rogue +applications. + +It is suggested that the middleware and the UI should run in a context on a user +with no capability and all persistent resources should be maintained without any +capability. + +One way to ensure this is by implementing a server-client paradigm. Services +provided by the system's drivers can be shared this way. The other advantage of +this approach is that multiple applications can share the same resources at the +same time. + + + +Domain | Object | Recommendations +--------------------- | ---------------- | ----------------------------------------------------- +Platform-Users-root-1 | Main application | Should not execute as root. +Platform-Users-root-2 | UI | Should run in a context on a user with no capability. + + + +Root access should not be allowed for the following utilities: + + + +Domain | `Utility` name | _State_ +--------------------- | -------------- | ------------- +Platform-Users-root-3 | `login` | _Not allowed_ +Platform-Users-root-4 | `su` | _Not allowed_ +Platform-Users-root-5 | `ssh` | _Not allowed_ +Platform-Users-root-6 | `scp` | _Not allowed_ +Platform-Users-root-7 | `sftp` | _Not allowed_ + + + +Root access should not be allowed for the console device. The development +environment should allow users to login with pre-created user accounts. + +Switching to elevated privileges shall be allowed in the development environment +via `sudo`. + +-------------------------------------------------------------------------------- + + + +## Capabilities + + + +Domain | Improvement +----------------------------- | ------------------------ +Platform-Users-Capabilities-1 | Kernel or Platform-user? +Platform-Users-Capabilities-2 | Add config note. + + + +The goal is to restrict functionality that will not be useful in **AGL**. They +are integrated into the **LSM**. Each privileged transaction is associated with +a capability. These capabilities are divided into three groups: + +- e: Effective: This means the capability is “activated”. +- p: Permitted: This means the capability can be used/is allowed. +- i: Inherited: The capability is kept by child/subprocesses upon execve() for + example. diff --git a/docs/3_Architecture_Guides/2_Security_Blueprint/7_Application.md b/docs/3_Architecture_Guides/2_Security_Blueprint/7_Application.md new file mode 100644 index 0000000..c08d06e --- /dev/null +++ b/docs/3_Architecture_Guides/2_Security_Blueprint/7_Application.md @@ -0,0 +1,125 @@ +--- +title: Application +--- + +**Application Hardening**: Best practices to apply to the build and release of +user space applications, in order to reduce the number of attack surfaces used +by potential attackers. + +The term of Application (App) has a very wide definition in **AGL**. Almost +anything which is not in the core Operating System (OS) is an Application. +Applications can be included in the base software package (image) or can be +added at run-time. + +Application containment is achieved using the following protections: + +- Linux Native protection + - Mandatory Access Control (**MAC**) +- AGL Platform protections + - Origin Tracking and Validation + - Application Privilege Management and Enforcement via Cynara + - Authenticated Transport via D-Bus + +## Application Types + +AGL provides a framework for applications to be written in different forms: + +- Web application: HTML5 + JavaScript +- Qt application: in a QML file +- Native application: in C + +While there is no harm in providing multiple types of applications, from a +security perspective this does increase the attack surface for an intruder. The +application framework (**AppFw**) consists of a number of utilities and daemons +which provide context for the applications. Isolation is provided through +**SMACK** labels. + +## Application Store + +Although the Tizen system has defined a [system of App signing and signing +flow](https://wiki.tizen.org/Security/Tizen_3.X_Overview#Application_Singing_and_Certificates) +to avoid the spread of unauthorized Apps that might contain malware. At this +point, it is unclear how much of this flow AGL will adopt. However, judging from +the experience, it is an essential topic. For example, the Google Play Store +controls the authorization of Apps through signing, and still, there are [many +accounts of Apps containing malware on the +store](http://www.eweek.com/mobile/researchers-find-132-malware-infected-android-apps-on-google-play). + +Tizen defines 5 levels of certificates and signing at each level, including an +author, testing distributor, public level store distributor, partner level store +distributor, and platform level store distributor. AGL may define a different +number of third parties, but at a minimum an author and store distributor should +be defined. + +![App Signing Flow](images/App_signing_flow.png) + +Once the number of signatures has been established, verification of those +signatures needs to be done at a minimum at installation time on the AGL device. +It is important to ensure the robustness/integrity of the public key used for +signature verification. If the public key is modified, then this compromised key +can be used to verify an attacker's private key signature. + +Further to this, installation-time verification is limited. Attacks can happen +to apps in-memory at runtime. Any modifications made after installation will be +missed by installation-time verification. Integrity verification that runs +during execution makes for a more complete security story. + +-------------------------------------------------------------------------------- + +## Acronyms and Abbreviations + +The following table lists the terms utilized within this part of the document. + +Acronyms or Abbreviations | Description +------------------------- | ---------------------------------------------------- +_3GPP_ | **3**rd **G**eneration **P**artnership **P**roject +_CASB_ | **C**loud **A**ccess **S**ecurity **B**roker +_DAST_ | **D**ynamic **A**pplication **S**ecurity **T**esting +_DPI_ | **D**eep **P**acket **I**nspection +_IDS_ | **I**ntrusion **D**etection **S**ystems +_IPS_ | **I**ntrusion **P**revention **S**ystems +_IPSec_ | **I**nternet **P**rotocol **Sec**urity +_LSM_ | **L**inux **S**ecurity **M**odule +_MITM_ | **M**an **I**n **T**he **M**iddle +_OSI_ | **O**pen **S**ystems **I**nterconnection +_SATS_ | **S**tatic **A**pplication **S**ecurity **T**esting + +# Local + +Domain | Improvement +-------------------------- | ------------------------------ +Application-Installation-1 | Talk about AppFw offline mode. + +## Installation + +Applications can be delivered and installed with the base image using a special +offline-mode provided by the **AppFw**. Apps can also be installed at run time. + +During early release, default Apps are installed on the image at first boot. + +Domain | Object | Recommendations +-------------------------- | --------- | ----------------------------------------------------------------------- +Application-Installation-1 | AppFw | Provide offline-mode in order to install app with the base image. +Application-Installation-2 | Integrity | Allow the installation of applications only if their integrity is good. + +# Local + +## Privilege Management + +Application privileges are managed by **Cynara** and the security manager in the +**AppFw**. For more details, please refer to the **AppFw** documentation in +Platform part. + +# App Signature + +Domain | Improvement +----------------------- | ---------------------------------------------------------- +Application-Signature-1 | Add content (see secure build in Secure development part). + + +# Services + +Domain | Improvement +---------------------- | ------------ +Application-Services-1 | Add content (Which services?). +Application-Services-2 | Add Binder. \ No newline at end of file diff --git a/docs/3_Architecture_Guides/2_Security_Blueprint/8_Connectivity.md b/docs/3_Architecture_Guides/2_Security_Blueprint/8_Connectivity.md new file mode 100644 index 0000000..076c0e0 --- /dev/null +++ b/docs/3_Architecture_Guides/2_Security_Blueprint/8_Connectivity.md @@ -0,0 +1,487 @@ +--- +title: Connectivity +--- + +This part shows different Connectivity attacks on the car. + +Domain | Improvement +----------------------- | ----------------- +Connectivity-Abstract-1 | Improve abstract. + + + +-------------------------------------------------------------------------------- + + + +## Acronyms and Abbreviations + +The following table lists the terms utilized within this part of the document. + +Acronyms or Abbreviations | Description +------------------------- | --------------------------------------------------------------------------------- +_ARP_ | **A**ddress **R**esolution **P**rotocol +_BLE_ | **B**luetooth **L**ow **E**nergy +_CAN_ | **C**ar **A**rea **N**etwork +_CCMP_ | **C**ounter-Mode/**C**BC-**M**ac **P**rotocol +_EDGE_ | **E**nhanced **D**ata **R**ates for **GSM** **E**volution - Evolution of **GPRS** +_GEA_ | **G**PRS **E**ncryption **A**lgorithm +_GPRS_ | **G**eneral **P**acket **R**adio **S**ervice (2,5G, 2G+) +_GSM_ | **G**lobal **S**ystem for **M**obile Communications (2G) +_HSPA_ | **H**igh **S**peed **P**acket **A**ccess (3G+) +_IMEI_ | **I**nternational **M**obile **E**quipment **I**dentity +_LIN_ | **L**ocal **I**nterconnect **N**etwork +_MOST_ | **M**edia **O**riented **S**ystem **T**ransport +_NFC_ | **N**ear **F**ield **C**ommunication +_OBD_ | **O**n-**B**oard **D**iagnostics +_PATS_ | **P**assive **A**nti-**T**heft **S**ystem +_PKE_ | **P**assive **K**eyless **E**ntry +_PSK_ | **P**hase-**S**hift **K**eying +_RDS_ | **R**adio **D**ata **S**ystem +_RFID_ | **R**adio **F**requency **I**dentification +_RKE_ | **R**emote **K**eyless **E**ntry +_SDR_ | **S**oftware **D**efined **R**adio +_SSP_ | **S**ecure **S**imple **P**airing +_TKIP_ | **T**emporal **K**ey **I**ntegrity **P**rotocol +_TPMS_ | **T**ire **P**ressure **M**onitoring **S**ystem +_UMTS_ | **U**niversal **M**obile **T**elecommunications **S**ystem (3G) +_USB_ | **U**niversal **S**erial **B**us +_WEP_ | **W**ired **E**quivalent **P**rivacy +_WPA_ | **W**ifi **P**rotected **A**ccess + +# Bus + +We only speak about the **CAN** bus to take an example, because the different +attacks on bus like _FlewRay_, _ByteFlight_, _Most_ and _Lin_ use retro +engineering and the main argument to improve their security is to encrypt data +packets. We just describe them a bit: + +- **CAN**: Controller Area Network, developed in the early 1980s, is an + event-triggered controller network for serial communication with data rates up + to one MBit/s. **CAN** messages are classified over their respective + identifier. **CAN** controller broadcast their messages to all connected nodes + and all receiving nodes decide independently if they process the message. +- **FlewRay**: Is a deterministic and error-tolerant high-speed bus. With a data + rate up to 10 MBit/s. +- **ByteFlight**: Is used for safety-critical applications in motor vehicles + like air-bags. Byteflight runs at 10Mbps over 2 or 3 wires plastic optical + fibers. +- **Most**: Media Oriented System Transport, is used for transmitting audio, + video, voice, and control data via fiber optic cables. The speed is, for the + synchronous way, up to 24 MBit/s and asynchronous way up to 14 MBit/s. + **MOST** messages include always a clear sender and receiver address. +- **LIN**: Local Interconnect Network, is a single-wire subnet work for + low-cost, serial communication between smart sensors and actuators with + typical data rates up to 20 kBit/s. It is intended to be used from the year + 2001 on everywhere in a car, where the bandwidth and versatility of a **CAN** + network is not required. + +On just about every vehicle, **ECU**s (**E**lectronic **C**ontrol **U**nits) +communicate over a CAN bus, which is a two-wire bus using hardware arbitration +for messages sent on the shared medium. This is essentially a *trusted* network +where all traffic is visible to all controllers and any controller can send any +message. + +A malicious **ECU** on the CAN bus can easily inject messages destined for any +other device, including things like the instrument cluster and the head unit. +There are common ways for hardware to do USB to CAN and open source software to +send and receive messages. For example, there is a driver included in the Linux +kernel that can be used to send/receive CAN signals. A malicious device on the +CAN bus can cause a great number of harmful things to happen to the system, +including: sending bogus information to other devices, sending unintended +commands to ECUs, causing DOS (Denial Of Service) on the CAN bus, etc. + + + +Domain | Tech name | Recommendations +---------------------------------- | --------- | -------------------------------------------------------------------------- +Connectivity-BusAndConnector-Bus-1 | CAN | Implement hardware solution in order to prohibit sending unwanted signals. + + + +See [Security in Automotive Bus +Systems](http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.92.728&rep=rep1&type=pdf) +for more information. + +# Connectors + +For the connectors, we supposed that they were disabled by default. For example, +the **USB** must be disabled to avoid attacks like BadUSB. If not, configure the +Kernel to only enable the minimum require **USB** devices. The connectors used +to diagnose the car like **OBD-II** must be disabled outside garages. + + + +Domain | Tech name | Recommendations +----------------------------------------- | --------- | ---------------------------------------------------------------------- +Connectivity-BusAndConnector-Connectors-1 | USB | Must be disabled. If not, only enable the minimum require USB devices. +Connectivity-BusAndConnector-Connectors-2 | USB | Confidential data exchanged with the ECU over USB must be secure. +Connectivity-BusAndConnector-Connectors-3 | USB | USB Boot on a ECU must be disable. +Connectivity-BusAndConnector-Connectors-4 | OBD-II | Must be disabled outside garages. + + + +# Wireless + +In this part, we talk about possible remote attacks on a car, according to the +different areas of possible attacks. For each communication channels, we +describe attacks and how to prevent them with some recommendations. The main +recommendation is to always follow the latest updates of these remote +communication channels. + + + +Domain | Object | Recommendations +----------------------- | ------ | ------------------------------------------------------------------ +Connectivity-Wireless-1 | Update | Always follow the latest updates of remote communication channels. + + + +We will see the following parts: + +- [Wifi](#wifi) + +- [Bluetooth](#bluetooth) + +- [Cellular](#cellular) + +- [Radio](#radio) + +- [NFC](#nfc) + + + +Domain | Improvement +----------------------- | ------------------------------------------- +Connectivity-Wireless-1 | Add communication channels (RFID, ZigBee?). + + + +-------------------------------------------------------------------------------- + +For existing automotive-specific means, we take examples of existing system +attacks from the _IOActive_ document ([A Survey of Remote Automotive Attack +Surfaces](https://www.ioactive.com/pdfs/IOActive_Remote_Attack_Surfaces.pdf)) +and from the ETH document ([Relay Attacks on Passive Keyless Entry and Start +Systems in Modern Cars](https://eprint.iacr.org/2010/332.pdf)). + +- [Telematics](https://www.ioactive.com/pdfs/IOActive_Remote_Attack_Surfaces.pdf#%5B%7B%22num%22%3A40%2C%22gen%22%3A0%7D%2C%7B%22name%22%3A%22XYZ%22%7D%2C60%2C720%2C0%5D) + +- [Passive Anti-Theft System + (PATS)](https://www.ioactive.com/pdfs/IOActive_Remote_Attack_Surfaces.pdf#%5B%7B%22num%22%3A11%2C%22gen%22%3A0%7D%2C%7B%22name%22%3A%22XYZ%22%7D%2C60%2C574%2C0%5D) + +- [Tire Pressure Monitoring System + (TPMS)](https://www.ioactive.com/pdfs/IOActive_Remote_Attack_Surfaces.pdf#%5B%7B%22num%22%3A17%2C%22gen%22%3A0%7D%2C%7B%22name%22%3A%22XYZ%22%7D%2C60%2C720%2C0%5D) + +- [Remote Keyless Entry/Start + (RKE)](https://www.ioactive.com/pdfs/IOActive_Remote_Attack_Surfaces.pdf#%5B%7B%22num%22%3A26%2C%22gen%22%3A0%7D%2C%7B%22name%22%3A%22XYZ%22%7D%2C60%2C720%2C0%5D) + +- [Passive Keyless Entry (PKE)](https://eprint.iacr.org/2010/332.pdf) + +-------------------------------------------------------------------------------- + + + +## Wifi + +### Attacks + +We can differentiate existing attacks on wifi in two categories: Those on +**WEP** and those on **WPA**. + +- **WEP** attacks: + + - **FMS**: (**F**luhrer, **M**antin and **S**hamir attack) is a "Stream cipher + attack on the widely used RC4 stream cipher. The attack allows an attacker + to recover the key in an RC4 encrypted stream from a large number of + messages in that stream." + - **KoreK**: "Allows the attacker to reduce the key space". + - **PTW**: (**P**yshkin **T**ews **W**einmann attack). + - **Chopchop**: Found by KoreK, "Weakness of the CRC32 checksum and the lack + of replay protection." + - **Fragmentation** + +- **WPA** attacks: + + - **Beck and Tews**: Exploit weakness in **TKIP**. "Allow the attacker to + decrypt **ARP** packets and to inject traffic into a network, even allowing + him to perform a **DoS** or an **ARP** poisoning". + - [KRACK](https://github.com/kristate/krackinfo): (K)ey (R)einstallation + (A)tta(ck) ([jira AGL + SPEC-1017](https://jira.automotivelinux.org/browse/SPEC-1017)). + +### Recommendations + +- Do not use **WEP**, **PSK** and **TKIP**. + +- Use **WPA2** with **CCMP**. + +- Should protect data sniffing. + + + +Domain | Tech name or object | Recommendations +---------------------------- | ------------------- | ------------------------------------------------------------------------- +Connectivity-Wireless-Wifi-1 | WEP, PSK, TKIP | Disabled +Connectivity-Wireless-Wifi-2 | WPA2 and AES-CCMP | Used +Connectivity-Wireless-Wifi-3 | WPA2 | Should protect data sniffing. +Connectivity-Wireless-Wifi-4 | PSK | Changing regularly the password. +Connectivity-Wireless-Wifi-5 | Device | Upgraded easily in software or firmware to have the last security update. + + + +See [Wifi attacks WEP WPA](https://matthieu.io/dl/wifi-attacks-wep-wpa.pdf) and +[Breaking wep and wpa (Beck and +Tews)](https://dl.aircrack-ng.org/breakingwepandwpa.pdf) for more information. + +-------------------------------------------------------------------------------- + + + +## Bluetooth + +### Attacks + +- **Bluesnarfing** attacks involve an attacker covertly gaining access to your + Bluetooth-enabled device for the purpose of retrieving information, including + addresses, calendar information or even the device's **I**nternational + **M**obile **E**quipment **I**dentity. With the **IMEI**, an attacker could + route your incoming calls to his cell phone. +- **Bluebugging** is a form of Bluetooth attack often caused by a lack of + awareness. Similar to bluesnarfing, bluebugging accesses and uses all phone + features but is limited by the transmitting power of class 2 Bluetooth radios, + normally capping its range at 10-15 meters. +- **Bluejacking** is the sending of unsolicited messages. +- **BLE**: **B**luetooth **L**ow **E**nergy + [attacks](https://www.usenix.org/system/files/conference/woot13/woot13-ryan.pdf). +- **DoS**: Drain a device's battery or temporarily paralyze the phone. + +### Recommendations + +- Not allowing Bluetooth pairing attempts without the driver's first manually + placing the vehicle in pairing mode. +- Monitoring. +- Use **BLE** with caution. +- For v2.1 and later devices using **S**ecure **S**imple **P**airing (**SSP**), + avoid using the "Just Works" association model. The device must verify that an + authenticated link key was generated during pairing. + + + +Domain | Tech name | Recommendations +--------------------------------- | ------------- | ------------------------------------------------------------ +Connectivity-Wireless-Bluetooth-1 | BLE | Use with caution. +Connectivity-Wireless-Bluetooth-2 | Bluetooth | Monitoring +Connectivity-Wireless-Bluetooth-3 | SSP | Avoid using the "Just Works" association model. +Connectivity-Wireless-Bluetooth-4 | Visibility | Configured by default as undiscoverable. Except when needed. +Connectivity-Wireless-Bluetooth-5 | Anti-scanning | Used, inter alia, to slow down brute force attacks. + + + +See [Low energy and the automotive +transformation](http://www.ti.com/lit/wp/sway008/sway008.pdf), [Gattacking +Bluetooth Smart Devices](http://gattack.io/whitepaper.pdf), [Comprehensive +Experimental Analyses of Automotive Attack +Surfaces](http://www.autosec.org/pubs/cars-usenixsec2011.pdf) and [With Low +Energy comes Low +Security](https://www.usenix.org/system/files/conference/woot13/woot13-ryan.pdf) +for more information. + +-------------------------------------------------------------------------------- + + + +## Cellular + +### Attacks + +- **IMSI-Catcher**: Is a telephone eavesdropping device used for intercepting + mobile phone traffic and tracking location data of mobile phone users. + Essentially a "fake" mobile tower acting between the target mobile phone and + the service provider's real towers, it is considered a man-in-the-middle + (**MITM**) attack. + +- Lack of mutual authentication (**GPRS**/**EDGE**) and encryption with + **GEA0**. + +- **Fall back** from **UMTS**/**HSPA** to **GPRS**/**EDGE** (Jamming against + **UMTS**/**HSPA**). + +- 4G **DoS** attack. + +### Recommendations + +- Check antenna legitimacy. + + + +Domain | Tech name | Recommendations +-------------------------------- | --------- | -------------------------- +Connectivity-Wireless-Cellular-1 | GPRS/EDGE | Avoid +Connectivity-Wireless-Cellular-2 | UMTS/HSPA | Protected against Jamming. + + + +See [A practical attack against GPRS/EDGE/UMTS/HSPA mobile data +communications](https://media.blackhat.com/bh-dc-11/Perez-Pico/BlackHat_DC_2011_Perez-Pico_Mobile_Attacks-wp.pdf) +for more information. + +-------------------------------------------------------------------------------- + +## Radio + +### Attacks + +- Interception of data with low cost material (**SDR** with hijacked DVB-T/DAB + for example). + +### Recommendations + +- Use the **R**adio **D**ata **S**ystem (**RDS**) only to send signals for audio + output and meta concerning radio. + + + +Domain | Tech name | Recommendations +----------------------------- | --------- | -------------------------------------------- +Connectivity-Wireless-Radio-1 | RDS | Only audio output and meta concerning radio. + + + +-------------------------------------------------------------------------------- + + + +## NFC + +### Attacks + +- **MITM**: Relay and replay attack. + +### Recommendations + +- Should implements protection against relay and replay attacks (Tokens, + etc...). +- Disable unneeded and unapproved services and profiles. +- NFC should be use encrypted link (secure channel). A standard key agreement + protocol like Diffie-Hellmann based on RSA or Elliptic Curves could be applied + to establish a shared secret between two devices. +- Automotive NFC device should be certified by NFC forum entity: The NFC Forum + Certification Mark shows that products meet global interoperability standards. +- NFC Modified Miller coding is preferred over NFC Manchester coding. + + + +Domain | Tech name | Recommendations +--------------------------- | --------- | ------------------------------------------------------ +Connectivity-Wireless-NFC-1 | NFC | Protected against relay and replay attacks. +Connectivity-Wireless-NFC-2 | Device | Disable unneeded and unapproved services and profiles. + + + +# Cloud + +## Download + +- **authentication**: Authentication is the security process that validates the + claimed identity of a device, entity or person, relying on one or more + characteristics bound to that device, entity or person. + +- **Authorization**: Parses the network to allow access to some or all network + functionality by providing rules and allowing access or denying access based + on a subscriber's profile and services purchased. + + + +Domain | Object | Recommendations +---------------------------- | -------------- | -------------------------------------- +Application-Cloud-Download-1 | authentication | Must implement authentication process. +Application-Cloud-Download-2 | Authorization | Must implement Authorization process. + + + +-------------------------------------------------------------------------------- + +## Infrastructure + +- **Deep Packet Inspection**: **DPI** provides techniques to analyze the payload + of each packet, adding an extra layer of security. **DPI** can detect and + neutralize attacks that would be missed by other security mechanisms. + +- A **DoS** protection in order to avoid that the Infrastructure is no more + accessible for a period of time. + +- **Scanning tools** such as **SATS** and **DAST** assessments perform + vulnerability scans on the source code and data flows on web applications. + Many of these scanning tools run different security tests that stress + applications under certain attack scenarios to discover security issues. + +- **IDS & IPS**: **IDS** detect and log inappropriate, incorrect, or anomalous + activity. **IDS** can be located in the telecommunications networks and/or + within the host server or computer. Telecommunications carriers build + intrusion detection capability in all network connections to routers and + servers, as well as offering it as a service to enterprise customers. Once + **IDS** systems have identified an attack, **IPS** ensures that malicious + packets are blocked before they cause any harm to backend systems and + networks. **IDS** typically functions via one or more of three systems: + + 1. Pattern matching. + 2. Anomaly detection. + 3. Protocol behavior. + + + + + +Domain | Object | Recommendations +---------------------------------- | ------------- | ---------------------------------------------------------- +Application-Cloud-Infrastructure-1 | Packet | Should implement a DPI. +Application-Cloud-Infrastructure-2 | DoS | Must implement a DoS protection. +Application-Cloud-Infrastructure-3 | Test | Should implement scanning tools like SATS and DAST. +Application-Cloud-Infrastructure-4 | Log | Should implement security tools (IDS and IPS). +Application-Cloud-Infrastructure-5 | App integrity | Applications must be signed by the code signing authority. + + + +-------------------------------------------------------------------------------- + +## Transport + +For data transport, it is necessary to **encrypt data end-to-end**. To prevent +**MITM** attacks, no third party should be able to interpret transported data. +Another aspect is the data anonymization in order to protect the leakage of +private information on the user or any other third party. + +The use of standards such as **IPSec** provides "_private and secure +communications over IP networks, through the use of cryptographic security +services, is a set of protocols using algorithms to transport secure data over +an IP network._". In addition, **IPSec** operates at the network layer of the +**OSI** model, contrary to previous standards that operate at the application +layer. This makes its application independent and means that users do not need +to configure each application to **IPSec** standards. + +**IPSec** provides the services below : + +- Confidentiality: A service that makes it impossible to interpret data if it is + not the recipient. It is the encryption function that provides this service by + transforming intelligible (unencrypted) data into unintelligible (encrypted) + data. +- Authentication: A service that ensures that a piece of data comes from where + it is supposed to come from. +- Integrity: A service that consists in ensuring that data has not been tampered + with accidentally or fraudulently. +- Replay Protection: A service that prevents attacks by re-sending a valid + intercepted packet to the network for the same authorization. This service is + provided by the presence of a sequence number. +- Key management: Mechanism for negotiating the length of encryption keys + between two **IPSec** elements and exchange of these keys. + +An additional means of protection would be to do the monitoring between users +and the cloud as a **CASB** will provide. + + + +Domain | Object | Recommendations +----------------------------- | ----------------------------------------- | --------------------------------- +Application-Cloud-Transport-1 | Integrity, confidentiality and legitimacy | Should implement IPSec standards. + diff --git a/docs/3_Architecture_Guides/2_Security_Blueprint/9_Update_OTA.md b/docs/3_Architecture_Guides/2_Security_Blueprint/9_Update_OTA.md new file mode 100644 index 0000000..60ae8e4 --- /dev/null +++ b/docs/3_Architecture_Guides/2_Security_Blueprint/9_Update_OTA.md @@ -0,0 +1,154 @@ +--- +title: Update (Over The Air) +--- + +Updating applications and firmware is essential for the development of new +features and even more to fix security bugs. However, if a malicious third party +manages to alter the content during transport, it could alter the functioning of +the system and/or applications. The security of the updates is therefore a +critical point to evaluate in order to guarantee the integrity, the +confidentiality and the legitimacy of the transmitted data. + +## Attack Vectors + +Updates Over The Air are one of the most common points where an attacker will +penetrate. An OTA update mechanism is one of the highest threats in the system. +If an attacker is able to install his own application or firmware on the system, +he can get the same level of access that the original application or firmware +had. From that point, the intruder can get unfettered access to the rest of the +system, which might include making modifications, downloading other pieces of +software, and stealing assets. + +### Man In The Middle (MITM) + +The man-in-the-middle attack is the most classic example of an attack, where an +adversary inserts himself between two communicating entities and grabs whatever +is being communicated. In the case of OTA attacks, the connection in the network +may be intercepted: + +* On the internet, before the cloud back-end. +* At the base station, 3G,4G,5G connection to the internet. +* At the receiving antenna, connection to the car. +* Between the receiving antenna and the gateway router (if present), connection + within the car. +* Between the gateway router and the target component (IVI, In-Vehicle + Infotainment unit). + +There are many ways to mount a MITM attack. For example, proxy tools like Burp +Proxy can be used to intercept web traffic as a man-in-the-middle. Under the +guise of being a testing tool, the proxy server is often used in attack +scenarios. It runs on a variety of platforms. + +As another example, false base station attacks are known to be fairly easy to +set-up. The problem is apparently fairly prevalent in countries like China and +in the UK. These fake base stations are sometimes just eavesdropping on the +communication, but others have the potential to do serious harm. + +Defenses against MITM attacks include encrypted and signed data pipes. +Furthermore, architects and developers are also recommended to encrypt and sign +the payloads that are being passed over these pipes, to defend against perusal +of the data. + +### Man At The End (MATE) + +The man-at-the-end attack is when an intruder analyzes the end-point of the +communication when software is accessing the data communication. This is a more +severe attack type where the attacker can: + +* Steal keys. + * For example, a simple debugging session in running software could reveal a + key used in memory. +* Tamper software. + * For example, replacing just one function call in software with a NOP (i.e. + no operation) can drastically change the behavior of the program. +* Jam branches of control. + * For example, making a program take one branch of control rather than the + intended branch can mean the difference between an authorized and a + non-authorized installation. +* Modify important data. + * For example, if the data changed is a key or data leading to a control path, + then this attack can be severe. + * In the case of OTA updates, MATE attacks are particularly problematic for + the system. One of the consequences of MATE attacks can be installed + software that allows installation of any other software. For example, an + attacker might install remote access software to control any part of the + system. + +-------------------------------------------------------------------------------- + +## Acronyms and Abbreviations + +The following table lists the terms utilized within this part of the document. + +Acronyms or Abbreviations | Description +------------------------- | ------------------------------------------------------------------------- +_FOTA_ | **F**irmware **O**ver **T**he **A**ir +_MATE_ | **M**an **A**t **T**he **E**nd +_MITM_ | **M**an **I**n **T**he **M**iddle +_OTA_ | **O**ver **T**he **A**ir +_SOTA_ | **S**oftware **O**ver **T**he **A**ir +_TUF_ | **T**he **U**pdate **F**ramework + +# Firmware Over The Air + +The firmware update is critical since its alteration back to compromise the +entire system. It is therefore necessary to take appropriate protective +measures. + +AGL includes the _meta-updater_ Yocto layer that enables OTA software updates +via [Uptane](https://uptane.github.io), an automotive-specific extension to [The +Update Framework](https://theupdateframework.github.io/). Uptane and TUF are +open standards that define a secure protocol for delivering and verifying +updates even when the servers and network--internet and car-internal--aren't +fully trusted. + +_meta-updater_ includes the application +[`aktualizr`](https://github.com/advancedtelematic/aktualizr), developed +Advanced Telematic Systems (now part of HERE Technologies) that enables OTA for +an ECU. `aktualizr` combined with Uptane is suitable for updating the firmware, +software, and other packages on even functionally critical ECUs. `aktualizr` can +be enabled with the free, open souce backend +[`ota-community-edition`](https://github.com/advancedtelematic/ota-community-edition). + +This FOTA update mechanism can be enabled through the `agl-sota` feature. + +## Building + +To build an AGL image that uses `aktualizr`, the following can be used. + +``` +source meta-agl/scripts/aglsetup.sh -m agl-sota +``` + +During the build, _meta-updater_ will use credentials downloaded from +`ota-community-edition` to sign metadata verifying the build as authentic. These +signatures are part of the Uptane framework and are used to verify FOTA updates. + +## Atomic Upgrades with Rollbacks + +`aktualizr`'s primary method of updating firmware is to use `libostree` with +binary diffs. The binary diffs use the least amout of bandwidth, and by it's +nature `libostree` stores current and previous firmware versions on disk or in +flash memory to allow for rollbacks. + +`libostree` is a content addressable object store much like `git`. Versions are +specified via SHA2-256. These hashes are signed in the Uptane metadata and are +robust against cryptographic compromise. + +# Software Over The Air + +Software updates in connected vehicles are a very useful feature, which can +deliver significant benefits. If not implemented with security in mind, software +updates can incur serious vulnerabilities. Any software update system must +ensure that not only are the software updates to devices done in a secure way, +but also that the repositories and servers hosting these updates are adequately +protected. As the process of updating software migrates from a Dealership update +model towards an **OTA** update model, securing these processes becomes a high +priority. + +**SOTA** is made possible by **AppFw** (See Platform part). It will be possible +to manage in a simple way the packets (i.g. Android like). + +Domain | Improvement +------------- | ----------------- +Update-SOTA-1 | Part to complete. \ No newline at end of file diff --git a/docs/3_Architecture_Guides/2_Security_Blueprint/A_Secure_development.md b/docs/3_Architecture_Guides/2_Security_Blueprint/A_Secure_development.md new file mode 100644 index 0000000..9cbe3b4 --- /dev/null +++ b/docs/3_Architecture_Guides/2_Security_Blueprint/A_Secure_development.md @@ -0,0 +1,58 @@ +--- +title: Secure development +--- + +In order to save a lot of time in code auditing, developers must follow coding +guidelines. + +## Secure build + +### Kernel build + +Tools like: + +- [Code optimisation](https://github.com/jduck/lk-reducer). +- [Kernel Drivers test](https://github.com/ucsb-seclab/dr_checker) with + [docs](https://www.usenix.org/system/files/conference/usenixsecurity17/sec17-machiry.pdf). + +Domain | Improvement +----------------------- | ------------ +SecureDev-SecureBuild-1 | Add content. + +## App/Widget signatures + +Domain | Improvement +---------------------- | ------------ +SecureDev-Signatures-1 | Add content. + +## Code audit + +These tools are used to check the correct implementation of functionalities and +compliance with related good practices. + +- [Continuous Code Quality](https://www.sonarqube.org/). + +Domain | Improvement +--------------------- | ----------------------------------------------------- +SecureDev-CodeAudit-1 | Add CVE analyser. +SecureDev-CodeAudit-2 | [OSSTMM](http://www.isecom.org/mirror/OSSTMM.3.pdf). + +### SATS + +- [RATS](https://github.com/andrew-d/rough-auditing-tool-for-security) (Maybe to + old). +- [Flaw Finder](https://www.dwheeler.com/flawfinder/). + +- [wiki + list](https://en.wikipedia.org/wiki/List_of_tools_for_static_code_analysis). + +- [Mathematical + approach](https://perso.univ-rennes1.fr/david.lubicz/planches/David_Pichardie.pdf). + +It is necessary to verify that the application code does not use functions that +are depreciated and recognized as unsecured or cause problems. + +### DATS + +- [wiki + list](https://en.wikipedia.org/wiki/Dynamic_program_analysis#Example_tools). \ No newline at end of file diff --git a/docs/3_Architecture_Guides/2_Security_Blueprint/B_Annexes.md b/docs/3_Architecture_Guides/2_Security_Blueprint/B_Annexes.md new file mode 100644 index 0000000..c279203 --- /dev/null +++ b/docs/3_Architecture_Guides/2_Security_Blueprint/B_Annexes.md @@ -0,0 +1,578 @@ +--- +title: Annexes +--- + +The first part resumed all the configurations you must implement without any +explications since all the explanations are given as and when in the document. + +- The _config_ tag quickly identifies the configurations and the recommendations + to take. + +- The _note_ tag allows you to notify some additional details. + +- The _todo_ tag shows the possible improvements. + +The second one allows to visualize all the todo notes in order to have a global +vision of the possible improvements of the document. + +# Config notes + + +Domain | Object | Recommendations +-------------------- | ---------- | ---------------------------------- +Hardware-Integrity-1 | Bootloader | Must control bootloader integrity. +Hardware-Integrity-2 | Board | Must use a HSM. +Hardware-Integrity-3 | RTC | Must not be alterable. + +Domain | Object | Recommendations +---------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- +Hardware-Certificate-1 | System | Shall allow storing dedicated certificates. +Hardware-Certificate-2 | ECU | The ECU must verify the certification authority hierarchy. +Hardware-Certificate-3 | System | Allow the modification of certificates only if the source can be authenticated by a certificate already stored or in the higher levels of the chain of trust. + +Domain | Object | Recommendations +----------------- | ---------- | ------------------------------------------------------------------------------------ +Hardware-Memory-1 | ECU | The ECU shall never expose the unencrypted key in RAM when using cryptographic keys. +Hardware-Memory-2 | Bootloader | Internal NVM only +Hardware-Module-3 | - | HSM must be used to secure keys. + +Domain | _Variable_ / `Config` name | `Value` +---------------------- | -------------------------- | ------- +Boot-Image-Selection-1 | `CONFIG_BOOTDELAY` | `-2` +Boot-Image-Selection-2 | _bootdelay_ | `-2` + +Domain | `Config` name | _State_ +------------------------- | ---------------------------- | -------- +Boot-Image-Authenticity-1 | `CONFIG_FIT` | _Enable_ +Boot-Image-Authenticity-2 | `CONFIG_FIT_SIGNATURE` | _Enable_ +Boot-Image-Authenticity-3 | `CONFIG_RSA` | _Enable_ +Boot-Image-Authenticity-4 | `CONFIG_OF_CONTROL` | _Enable_ +Boot-Image-Authenticity-5 | `CONFIG_OF_SEPARATE` | _Enable_ +Boot-Image-Authenticity-6 | `CONFIG_DEFAULT_DEVICE_TREE` | _Enable_ + +Domain | Communication modes | _State_ +-------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- +Boot-Communication-1 | `USB` | _Disabled_ and _Compiled-out_ if not required. +Boot-Communication-2 | `USB` | Else, Kernel should be configured to only enable the minimum required USB devices and filesystems should be treated with special care. +Boot-Communication-3 | `Ethernet` | _Disabled_ +Boot-Communication-4 | U-boot and sboot `DOCSIS` | _Disabled_ +Boot-Communication-5 | `Serial ports` | _Disabled_ + +Domain | `Config` name | _State_ +------------------------ | ----------------------- | ------------- +Boot-Communication-USB-1 | `CONFIG_CMD_USB` | _Not defined_ +Boot-Communication-USB-2 | `CONFIG_USB_UHCI` | _Not defined_ +Boot-Communication-USB-3 | `CONFIG_USB_KEYBOARD` | _Not defined_ +Boot-Communication-USB-4 | `CONFIG_USB_STORAGE` | _Not defined_ +Boot-Communication-USB-5 | `CONFIG_USB_HOST_ETHER` | _Not defined_ + +Domain | Communication modes | _State_ +-------------------- | -------------------- | --------------------------------------------------------------------------------------------- +Boot-Communication-1 | `Network interfaces` | Preferably _no network interface is allowed_, otherwise, restrict the services to those used. + +Domain | Object | Recommendations +-------------------- | --------------------------------- | ------------------------------------------------------------- +Boot-Communication-1 | `Services`, `ports` and `devices` | Restrict the `services`, `ports` and `devices` to those used. + +Domain | `Command` name | _State_ +-------------------------- | -------------- | --------- +Boot-Communication-Flash-1 | `do_nand` | _Disable_ + +Domain | `Config` name | `Value` +---------------------- | --------------------------------------- | --------- +Boot-Consoles-Serial-1 | `CONFIG_SILENT_CONSOLE` | `Disable` +Boot-Consoles-Serial-2 | `CONFIG_SYS_DEVICE_NULLDEV` | `Disable` +Boot-Consoles-Serial-3 | `CONFIG_SILENT_CONSOLE_UPDATE_ON_RELOC` | `Disable` + +Domain | `Environment variable` name | _State_ +---------------------- | --------------------------- | ------------- +Boot-Consoles-Serial-1 | `INC_DEBUG_PRINT` | _Not defined_ + +Domain | `Config` name | _State_ +-------------------------- | ---------------------------- | --------- +Boot-Consoles-Variables-1 | `CONFIG_ENV_IS_IN_MMC` | `#undef` +Boot-Consoles-Variables-2 | `CONFIG_ENV_IS_IN_EEPROM` | `#undef` +Boot-Consoles-Variables-3 | `CONFIG_ENV_IS_IN_FLASH` | `#undef` +Boot-Consoles-Variables-4 | `CONFIG_ENV_IS_IN_DATAFLASH` | `#undef` +Boot-Consoles-Variables-5 | `CONFIG_ENV_IS_IN_FAT` | `#undef` +Boot-Consoles-Variables-6 | `CONFIG_ENV_IS_IN_NAND` | `#undef` +Boot-Consoles-Variables-7 | `CONFIG_ENV_IS_IN_NVRAM` | `#undef` +Boot-Consoles-Variables-8 | `CONFIG_ENV_IS_IN_ONENAND` | `#undef` +Boot-Consoles-Variables-9 | `CONFIG_ENV_IS_IN_SPI_FLASH` | `#undef` +Boot-Consoles-Variables-10 | `CONFIG_ENV_IS_IN_REMOTE` | `#undef` +Boot-Consoles-Variables-11 | `CONFIG_ENV_IS_IN_UBI` | `#undef` +Boot-Consoles-Variables-12 | `CONFIG_ENV_IS_NOWHERE` | `#define` + +Domain | `Command` name | _State_ +----------------------- | -------------- | ---------- +Boot-Consoles-MemDump-1 | `md` | _Disabled_ +Boot-Consoles-MemDump-2 | `mm` | _Disabled_ +Boot-Consoles-MemDump-3 | `nm` | _Disabled_ +Boot-Consoles-MemDump-4 | `mw` | _Disabled_ +Boot-Consoles-MemDump-5 | `cp` | _Disabled_ +Boot-Consoles-MemDump-6 | `mwc` | _Disabled_ +Boot-Consoles-MemDump-7 | `mdc` | _Disabled_ +Boot-Consoles-MemDump-8 | `mtest` | _Disabled_ +Boot-Consoles-MemDump-9 | `loopw` | _Disabled_ + +Domain | `Config` name | `Value` +-------------------- | -------------- | -------------------------------------- +Kernel-General-MAC-1 | CONFIG_IP_NF_SECURITY | m +Kernel-General-MAC-2 | CONFIG_IP6_NF_SECURITY | m +Kernel-General-MAC-3 | CONFIG_EXT2_FS_SECURITY | y +Kernel-General-MAC-4 | CONFIG_EXT3_FS_SECURITY | y +Kernel-General-MAC-5 | CONFIG_EXT4_FS_SECURITY | y +Kernel-General-MAC-6 | CONFIG_SECURITY | y +Kernel-General-MAC-7 | CONFIG_SECURITY_SMACK | y +Kernel-General-MAC-8 | CONFIG_TMPFS_XATTR | y + +Domain | `Config` name | `Value` +---------------------- | -------------- | ------- +Kernel-General-kexec-1 | `CONFIG_KEXEC` | `n` + +Domain | `Config` name | `Value` +--------------------------- | --------------- | ------- +Kernel-General-IPAutoConf-1 | `CONFIG_IP_PNP` | `n` + +Domain | `Config` name | `Value` +------------------------------- | ----------------------- | ------- +Kernel-General-SysCtl_SysCall-1 | `CONFIG_SYSCTL_SYSCALL` | `n` + +Domain | `Config` name | `Value` +---------------------------- | --------------- | ------- +Kernel-General-LegacyLinux-1 | `CONFIG_USELIB` | `n` + +Domain | `Config` name | `Value` +--------------------------- | ------------------------------ | ------- +Kernel-General-FirmHelper-1 | `CONFIG_FW_LOADER_USER_HELPER` | `n` + +Domain | `Config` name | `Value` +---------------------------- | ---------------------- | ------- +Kernel-General-PanicOnOOPS-1 | `CONFIG_PANIC_ON_OOPS` | `y` + +Domain | `Config` name | `Value` +-------------------------- | -------------------- | ------- +Kernel-General-SocketMon-1 | `CONFIG_PACKET_DIAG` | `n` +Kernel-General-SocketMon-2 | `CONFIG_UNIX_DIAG` | `n` + +Domain | `Config` name | `Value` +------------------------ | ---------------- | ------- +Kernel-General-BPF_JIT-1 | `CONFIG_BPF_JIT` | `n` + +Domain | `Config` name | `Value` +------------------------------ | ------------------------- | ------- +Kernel-General-ModuleSigning-1 | `CONFIG_MODULE_SIG_FORCE` | `y` + +Domain | `Variable` name | `Value` +------------------------------ | ------------------------- | ------- +Kernel-General-ModuleSigning-2 | `kernel.modules_disabled` | `1` + +Domain | Object | _State_ +------------------------ | ------------------- | ---------- +Kernel-General-Drivers-1 | `USB` | _Disabled_ +Kernel-General-Drivers-2 | `PCMCIA` | _Disabled_ +Kernel-General-Drivers-3 | Other `hotplug` bus | _Disabled_ + +Domain | `compiler` and `linker` options | _State_ +-------------------------------- | ------------------------------- | -------- +Kernel-General-IndependentExec-1 | `-pie -fpic` | _Enable_ + +Domain | `compiler` and `linker` options | _State_ +--------------------------------- | ------------------------------- | -------- +Kernel-General-OverwriteAttacks-1 | `-z,relro` | _Enable_ +Kernel-General-OverwriteAttacks-2 | `-z,now` | _Enable_ + +Domain | Object | Recommendations +------------------------------- | --------------- | -------------------------------- +Kernel-General-LibraryLinking-1 | Dynamic linking | Should generally not be allowed. + +Domain | `Config` name | `Value` +------------------------------ | ---------------- | ------- +Kernel-Memory-RestrictAccess-1 | `CONFIG_DEVKMEM` | `n` + +Domain | `Config` name | `Value` +------------------------ | ------------------- | ------- +Kernel-Memory-CoreDump-1 | `CONFIG_PROC_KCORE` | `n` + +Domain | `Config` name | `Value` +-------------------- | ------------- | ------- +Kernel-Memory-Swap-1 | `CONFIG_SWAP` | `n` + +Domain | `Config` name | `Value` +------------------------------ | --------------------- | ------- +Kernel-Memory-LoadAllSymbols-1 | `CONFIG_KALLSYMS` | `n` +Kernel-Memory-LoadAllSymbols-2 | `CONFIG_KALLSYMS_ALL` | `n` + +Domain | `Config` name | `Value` +--------------------- | -------------------------- | ------- +Kernel-Memory-Stack-1 | `CONFIG_CC_STACKPROTECTOR` | `y` + +Domain | `Config` name | `Value` +---------------------- | --------------- | ------- +Kernel-Memory-Access-1 | `CONFIG_DEVMEM` | `n` + +Domain | `Config` name | `Value` +------------------------------ | --------------------- | ------- +Kernel-Memory-CrossMemAttach-1 | `CROSS_MEMORY_ATTACH` | `n` + +Domain | `compiler` and `linker` options | _State_ +----------------------------- | ------------------------------- | -------- +Kernel-Memory-StackSmashing-1 | `-fstack-protector-all` | _Enable_ + +Domain | `compiler` options and `config` name | `Value` +------------------------------- | ------------------------------------ | ------- +Kernel-Memory-BufferOverflows-1 | `-D_FORTIFY_SOURCE` | `2` +Kernel-Memory-BufferOverflows-2 | `CONFIG_FORTIFY_SOURCE` | `y` + +Domain | `Config` name | `Value` +------------------------ | ---------------------------- | ------- +Kernel-Consoles-Serial-1 | `CONFIG_SERIAL_8250` | `n` +Kernel-Consoles-Serial-2 | `CONFIG_SERIAL_8250_CONSOLE` | `n` +Kernel-Consoles-Serial-3 | `CONFIG_SERIAL_CORE` | `n` +Kernel-Consoles-Serial-4 | `CONFIG_SERIAL_CORE_CONSOLE` | `n` + +Domain | `Config` name | `Value` +----------------------------- | ------------------------- | ----------------------------------- +Kernel-Consoles-CommandLine-1 | `CONFIG_CMDLINE_BOOL` | `y` +Kernel-Consoles-CommandLine-2 | `CONFIG_CMDLINE` | `"insert kernel command line here"` +Kernel-Consoles-CommandLine-3 | `CONFIG_CMDLINE_OVERRIDE` | `y` + +Domain | `Config` name | `Value` +---------------------- | ------------- | ------- +Kernel-Consoles-KDBG-1 | `CONFIG_KGDB` | `n` + +Domain | `Config` name | `Value` +----------------------- | -------------------- | ------- +Kernel-Consoles-SysRQ-1 | `CONFIG_MAGIC_SYSRQ` | `n` + +Domain | `Config` name | `Value` +------------------------------ | -------------------- | ------- +Kernel-Consoles-BinaryFormat-1 | `CONFIG_BINFMT_MISC` | `n` + +Domain | `Config` name | `Value` +---------------------- | ------------------- | ------- +Kernel-Debug-Symbols-1 | `CONFIG_DEBUG_INFO` | `n` + +Domain | `Config` name | `Value` +---------------------- | ---------------- | ------- +Kernel-Debug-Kprobes-1 | `CONFIG_KPROBES` | `n` + +Domain | `Config` name | `Value` +---------------------- | --------------- | ------- +Kernel-Debug-Tracing-1 | `CONFIG_FTRACE` | `n` + +Domain | `Config` name | `Value` +------------------------ | ------------------ | ------- +Kernel-Debug-Profiling-1 | `CONFIG_OPROFILE` | `n` +Kernel-Debug-Profiling-2 | `CONFIG_PROFILING` | `n` + +Domain | `Config` name | `Value` +------------------------ | ------------------------- | ------- +Kernel-Debug-OOPSOnBUG-1 | `CONFIG_DEBUG_BUGVERBOSE` | `n` + +Domain | `Config` name | `Value` +------------------ | --------------------- | ------- +Kernel-Debug-Dev-1 | `CONFIG_DEBUG_KERNEL` | `n` +Kernel-Debug-Dev-2 | `CONFIG_EMBEDDED` | `n` + +Domain | `Config` name | `Value` +------------------------- | ----------------- | ------- +Kernel-Debug-FileSystem-1 | `CONFIG_DEBUG_FS` | `n` + +Domain | `Config` name | `Value` +------------------ | ------------- | ------- +Kernel-Debug-BUG-1 | `CONFIG_BUG` | `n` + +Domain | `Config` name | `Value` +------------------------ | ----------------- | ------- +Kernel-Debug-CoreDumps-1 | `CONFIG_COREDUMP` | `n` + +Domain | `File` name | `Value` +---------------------------- | -------------------------------- | ------- +Kernel-Debug-AdressDisplay-1 | `/proc/sys/kernel/kptr_restrict` | `1` + +Domain | `File` or `Directorie` name | _State_ +---------------------------- | --------------------------- | ----------------------------- +Kernel-Debug-AdressDisplay-1 | `/boot/vmlinuz*` | _Readable Only for root user_ +Kernel-Debug-AdressDisplay-2 | `/boot/System.map*` | _Readable Only for root user_ +Kernel-Debug-AdressDisplay-3 | `/sys/kernel/debug/` | _Readable Only for root user_ +Kernel-Debug-AdressDisplay-4 | `/proc/slabinfo` | _Readable Only for root user_ + +Domain | `File` name | `Value` +-------------------- | --------------------------------- | ------- +Kernel-Debug-DMESG-1 | `/proc/sys/kernel/dmesg_restrict` | `1` + +Domain | `Config` name | `Value` +--------------------- | ----------------- | ------- +Kernel-Debug-Config-1 | `CONFIG_IKCONFIG` | `n` + +Domain | `Config` name | `Value` +------------------------ | --------------- | ------- +Kernel-FileSystems-NFS-1 | `CONFIG_NFSD` | `n` +Kernel-FileSystems-NFS-2 | `CONFIG_NFS_FS` | `n` + +Domain | `Partition` | `Value` +-------------------------- | ------------------- | ----------------------------------------------------------------- +Kernel-FileSystems-Mount-1 | `/boot` | `nosuid`, `nodev` and `noexec`. +Kernel-FileSystems-Mount-2 | `/var` & `/tmp` | In `/etc/fstab` or `vfstab`, add `nosuid`, `nodev` and `noexec`. +Kernel-FileSystems-Mount-3 | _Non-root local_ | If type is `ext2` or `ext3` and mount point not '/', add `nodev`. +Kernel-FileSystems-Mount-4 | _Removable storage_ | Add `nosuid`, `nodev` and `noexec`. +Kernel-FileSystems-Mount-5 | _Temporary storage_ | Add `nosuid`, `nodev` and `noexec`. +Kernel-FileSystems-Mount-6 | `/dev/shm` | Add `nosuid`, `nodev` and `noexec`. +Kernel-FileSystems-Mount-7 | `/dev` | Add `nosuid` and `noexec`. + +Domain | `Config` name | _State_ or `Value` +-------------------------- | ----------------------- | ----------------------------------------------------------------------- +Kernel-FileSystems-Mount-1 | `CONFIG_DEVTMPFS_MOUNT` | _Disabled_ or add remount with `noexec` and `nosuid` to system startup. + +Domain | `Label` name | Recommendations +------------------ | ------------ | ----------------------------------------------------------- +Kernel-MAC-Floor-1 | `^` | Only for privileged system services. +Kernel-MAC-Floor-2 | `*` | Used for device files or `/tmp` Access restriction via DAC. + +Domain | `Label` name | Recommendations +------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------- +Kernel-MAC-System-1 | `System` | Process should write only to file with transmute attribute. +Kernel-MAC-System-2 | `System::run` | Files are created with the directory label from user and system domain (transmute) Lock is implicit with `w`. +Kernel-MAC-System-3 | `System::Shared` | Files are created with the directory label from system domain (transmute) User domain has locked privilege. +Kernel-MAC-System-4 | `System::Log` | Some limitation may impose to add `w` to enable append. +Kernel-MAC-System-5 | `System::Sub` | Isolation of risky Subsystem. + +Domain | `Label` name | Recommendations +------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- +Kernel-MAC-System-1 | `User::Pkg::$AppID` | Only one Label is allowed per App. A data directory is created by the AppFw in `rwx` mode. +Kernel-MAC-System-2 | `User::Home` | AppFw needs to create a directory in `/home/$USER/App-Shared` at first launch if not present with label app-data access is `User::App-Shared` without transmute. +Kernel-MAC-System-3 | `User::App-Shared` | Shared space between all App running for a given user. + +Domain | Object | Recommendations +------------------ | -------------- | ------------------------------------ +Platform-SystemD-1 | Security model | Use Namespaces for containerization. +Platform-SystemD-2 | Security model | Use CGroups to organise processes. + +Domain | Object | Recommendations +--------------- | -------------- | ------------------------------------ +Platform-DBus-1 | Security model | Use D-Bus as IPC. +Platform-DBus-2 | Security model | Apply D-BUS security patches: [D-Bus CVE](https://www.cvedetails.com/vulnerability-list/vendor_id-13442/D-bus-Project.html) + +Domain | `Tool` name | _State_ +-------------------- | ----------- | ------- +Platform-Utilities-1 | `connman` | _Used_ as a connection manager. +Platform-Utilities-2 | `bluez` | _Used_ as a Bluetooth manager. +Platform-Utilities-3 | `gstreamer` | _Used_ to manage multimedia file format. +Platform-Utilities-4 | `alsa` | _Used_ to provides an API for sound card device drivers. + +Domain | Object | Recommendations +---------------------- | -------------- | -------------------------------- +Platform-AGLFw-AppFw-1 | Security model | Use the AppFw as Security model. + +Domain | Object | Recommendations +----------------------- | ----------- | ------------------------------------- +Platform-AGLFw-Cynara-1 | Permissions | Use Cynara as policy-checker service. + +Domain | `Tool` name | _State_ +-------------------- | ----------- | ---------------------------------------------------------------------- +Platform-Utilities-1 | `busybox` | _Used_ to provide a number of tools. Do not compile development tools. + +Domain | `Utility` name and normal `path` | _State_ +--------------------- | ---------------------------------------------------- | ---------- +Platform-Utilities-1 | `chgrp` in `/bin/chgrp` | _Disabled_ +Platform-Utilities-2 | `chmod` in `/bin/chmod` | _Disabled_ +Platform-Utilities-3 | `chown` in `/bin/chown` | _Disabled_ +Platform-Utilities-4 | `dmesg` in `/bin/dmesg` | _Disabled_ +Platform-Utilities-5 | `Dnsdomainname` in `/bin/dnsdomainname` | _Disabled_ +Platform-Utilities-6 | `dropbear`, Remove "dropbear" from `/etc/init.d/rcs` | _Disabled_ +Platform-Utilities-7 | `Editors` in (vi) `/bin/vi` | _Disabled_ +Platform-Utilities-8 | `find` in `/bin/find` | _Disabled_ +Platform-Utilities-9 | `gdbserver` in `/bin/gdbserver` | _Disabled_ +Platform-Utilities-10 | `hexdump` in `/bin/hexdump` | _Disabled_ +Platform-Utilities-11 | `hostname` in `/bin/hostname` | _Disabled_ +Platform-Utilities-12 | `install` in `/bin/install` | _Disabled_ +Platform-Utilities-13 | `iostat` in `/bin/iostat` | _Disabled_ +Platform-Utilities-14 | `killall` in `/bin/killall` | _Disabled_ +Platform-Utilities-15 | `klogd` in `/sbin/klogd` | _Disabled_ +Platform-Utilities-16 | `logger` in `/bin/logger` | _Disabled_ +Platform-Utilities-17 | `lsmod` in `/sbin/lsmod` | _Disabled_ +Platform-Utilities-18 | `pmap` in `/bin/pmap` | _Disabled_ +Platform-Utilities-19 | `ps` in `/bin/ps` | _Disabled_ +Platform-Utilities-20 | `ps` in `/bin/ps` | _Disabled_ +Platform-Utilities-21 | `rpm` in `/bin/rpm` | _Disabled_ +Platform-Utilities-22 | `SSH` | _Disabled_ +Platform-Utilities-23 | `stbhotplug` in `/sbin/stbhotplug` | _Disabled_ +Platform-Utilities-24 | `strace` in `/bin/trace` | _Disabled_ +Platform-Utilities-25 | `su` in `/bin/su` | _Disabled_ +Platform-Utilities-26 | `syslogd` in (logger) `/bin/logger` | _Disabled_ +Platform-Utilities-27 | `top` in `/bin/top` | _Disabled_ +Platform-Utilities-28 | `UART` in `/proc/tty/driver/` | _Disabled_ +Platform-Utilities-29 | `which` in `/bin/which` | _Disabled_ +Platform-Utilities-30 | `who` and `whoami` in `/bin/whoami` | _Disabled_ +Platform-Utilities-31 | `awk` (busybox) | _Enabled_ +Platform-Utilities-32 | `cut` (busybox) | _Enabled_ +Platform-Utilities-33 | `df` (busybox) | _Enabled_ +Platform-Utilities-34 | `echo` (busybox) | _Enabled_ +Platform-Utilities-35 | `fdisk` (busybox) | _Enabled_ +Platform-Utilities-36 | `grep` (busybox) | _Enabled_ +Platform-Utilities-37 | `mkdir` (busybox) | _Enabled_ +Platform-Utilities-38 | `mount` (vfat) (busybox) | _Enabled_ +Platform-Utilities-39 | `printf` (busybox) | _Enabled_ +Platform-Utilities-40 | `sed` in `/bin/sed` (busybox) | _Enabled_ +Platform-Utilities-41 | `tail` (busybox) | _Enabled_ +Platform-Utilities-42 | `tee` (busybox) | _Enabled_ +Platform-Utilities-43 | `test` (busybox) | _Enabled_ + +Domain | Object | Recommendations +--------------------- | ---------------- | ----------------------------------------------------- +Platform-Users-root-1 | Main application | Should not execute as root. +Platform-Users-root-2 | UI | Should run in a context on a user with no capability. + +Domain | `Utility` name | _State_ +--------------------- | -------------- | ------------- +Platform-Users-root-3 | `login` | _Not allowed_ +Platform-Users-root-4 | `su` | _Not allowed_ +Platform-Users-root-5 | `ssh` | _Not allowed_ +Platform-Users-root-6 | `scp` | _Not allowed_ +Platform-Users-root-7 | `sftp` | _Not allowed_ + +Domain | Object | Recommendations +-------------------------- | --------- | ----------------------------------------------------------------------- +Application-Installation-1 | AppFw | Provide offline-mode in order to install app with the base image. +Application-Installation-2 | Integrity | Allow the installation of applications only if their integrity is good. + +Domain | Tech name | Recommendations +---------------------------------- | --------- | -------------------------------------------------------------------------- +Connectivity-BusAndConnector-Bus-1 | CAN | Implement hardware solution in order to prohibit sending unwanted signals. + +Domain | Tech name | Recommendations +----------------------------------------- | --------- | ---------------------------------------------------------------------- +Connectivity-BusAndConnector-Connectors-1 | USB | Must be disabled. If not, only enable the minimum require USB devices. +Connectivity-BusAndConnector-Connectors-2 | USB | Confidential data exchanged with the ECU over USB must be secure. +Connectivity-BusAndConnector-Connectors-3 | USB | USB Boot on a ECU must be disable. +Connectivity-BusAndConnector-Connectors-4 | OBD-II | Must be disabled outside garages. + +Domain | Object | Recommendations +----------------------- | ------ | ------------------------------------------------------------------ +Connectivity-Wireless-1 | Update | Always follow the latest updates of remote communication channels. + +Domain | Tech name or object | Recommendations +---------------------------- | ------------------- | ------------------------------------------------------------------------- +Connectivity-Wireless-Wifi-1 | WEP, PSK, TKIP | Disabled +Connectivity-Wireless-Wifi-2 | WPA2 and AES-CCMP | Used +Connectivity-Wireless-Wifi-3 | WPA2 | Should protect data sniffing. +Connectivity-Wireless-Wifi-4 | PSK | Changing regularly the password. +Connectivity-Wireless-Wifi-5 | Device | Upgraded easily in software or firmware to have the last security update. + +Domain | Tech name | Recommendations +--------------------------------- | ------------- | ------------------------------------------------------------ +Connectivity-Wireless-Bluetooth-1 | BLE | Use with caution. +Connectivity-Wireless-Bluetooth-2 | Bluetooth | Monitoring +Connectivity-Wireless-Bluetooth-3 | SSP | Avoid using the "Just Works" association model. +Connectivity-Wireless-Bluetooth-4 | Visibility | Configured by default as undiscoverable. Except when needed. +Connectivity-Wireless-Bluetooth-5 | Anti-scanning | Used, inter alia, to slow down brute force attacks. + +Domain | Tech name | Recommendations +-------------------------------- | --------- | -------------------------- +Connectivity-Wireless-Cellular-1 | GPRS/EDGE | Avoid +Connectivity-Wireless-Cellular-2 | UMTS/HSPA | Protected against Jamming. + +Domain | Tech name | Recommendations +----------------------------- | --------- | -------------------------------------------- +Connectivity-Wireless-Radio-1 | RDS | Only audio output and meta concerning radio. + +Domain | Tech name | Recommendations +--------------------------- | --------- | ------------------------------------------------------ +Connectivity-Wireless-NFC-1 | NFC | Protected against relay and replay attacks. +Connectivity-Wireless-NFC-2 | Device | Disable unneeded and unapproved services and profiles. + +Domain | Object | Recommendations +---------------------------- | -------------- | -------------------------------------- +Application-Cloud-Download-1 | authentication | Must implement authentication process. +Application-Cloud-Download-2 | Authorization | Must implement Authorization process. + +Domain | Object | Recommendations +---------------------------------- | ------------- | ---------------------------------------------------------- +Application-Cloud-Infrastructure-1 | Packet | Should implement a DPI. +Application-Cloud-Infrastructure-2 | DoS | Must implement a DoS protection. +Application-Cloud-Infrastructure-3 | Test | Should implement scanning tools like SATS and DAST. +Application-Cloud-Infrastructure-4 | Log | Should implement security tools (IDS and IPS). +Application-Cloud-Infrastructure-5 | App integrity | Applications must be signed by the code signing authority. + +Domain | Object | Recommendations +----------------------------- | ----------------------------------------- | --------------------------------- +Application-Cloud-Transport-1 | Integrity, confidentiality and legitimacy | Should implement IPSec standards. + +# Todo notes + +Domain | Improvement +--------------- | ---------------------------------------------------- +Boot-Abstract-1 | More generic and add examples (The chain of trust). + +Domain | Improvement +--------------- | ------------------------------------------- +Boot-Abstract-1 | Review the definition of the "boot loader". + +Domain | Improvement +--------------- | ------------------------------------ +Boot-Consoles-1 | Secure loader: No reference earlier? + +Domain | Improvement +--------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- +Hypervisor-Abstract-1 | Complete Hypervisor part ([jailhouse](https://github.com/siemens/jailhouse) / [KVM](https://www.linux-kvm.org/page/Main_Page) / [Xen](https://www.xenproject.org/developers/teams/embedded-and-automotive.html)). + +Domain | Improvement +-------------------------------- | ----------------------------- +Kernel-General-IndependentExec-1 | Kernel or/and platform part ? + +Domain | Improvement +------------------------------- | --------------- +Kernel-General-LibraryLinking-1 | Keep this part? + +Domain | Improvement +------------------- | -------------------------------- +Platform-Abstract-1 | Create a graphics and sound part. + +Domain | Improvement +------------------- | ----------- +Platform-Services-1 | SystemD ? +Platform-Services-2 | Secure daemon ? + +Domain | Improvement +----------------------------- | ------------------------ +Platform-Users-Capabilities-1 | Kernel or Platform-user? +Platform-Users-Capabilities-2 | Add config note. + +Domain | Improvement +-------------------------- | ------------------------------ +Application-Installation-1 | Talk about AppFw offline mode. + +Domain | Improvement +----------------------- | ---------------------------------------------------------- +Application-Signature-1 | Add content (see secure build in Secure development part). + +Domain | Improvement +---------------------- | ------------ +Application-Services-1 | Add content (Which services?). +Application-Services-2 | Add Binder. + +Domain | Improvement +----------------------- | ----------------- +Connectivity-Abstract-1 | Improve abstract. + +Domain | Improvement +----------------------- | ------------------------------------------- +Connectivity-Wireless-1 | Add communication channels (RFID, ZigBee?). + +Domain | Improvement +------------- | ----------------- +Update-SOTA-1 | Part to complete. + +Domain | Improvement +----------------------- | ------------ +SecureDev-SecureBuild-1 | Add content. + +Domain | Improvement +---------------------- | ------------ +SecureDev-Signatures-1 | Add content. + +Domain | Improvement +--------------------- | ----------------------------------------------------- +SecureDev-CodeAudit-1 | Add CVE analyser. +SecureDev-CodeAudit-2 | [OSSTMM](http://www.isecom.org/mirror/OSSTMM.3.pdf). \ No newline at end of file diff --git a/docs/3_Architecture_Guides/2_Security_Blueprint/images/App-flow.png b/docs/3_Architecture_Guides/2_Security_Blueprint/images/App-flow.png new file mode 100644 index 0000000..7b87c29 Binary files /dev/null and b/docs/3_Architecture_Guides/2_Security_Blueprint/images/App-flow.png differ diff --git a/docs/3_Architecture_Guides/2_Security_Blueprint/images/App_signing_flow.png b/docs/3_Architecture_Guides/2_Security_Blueprint/images/App_signing_flow.png new file mode 100644 index 0000000..56a7c23 Binary files /dev/null and b/docs/3_Architecture_Guides/2_Security_Blueprint/images/App_signing_flow.png differ diff --git a/docs/3_Architecture_Guides/2_Security_Blueprint/images/WhiteBoxArchi.png b/docs/3_Architecture_Guides/2_Security_Blueprint/images/WhiteBoxArchi.png new file mode 100644 index 0000000..d984d1a Binary files /dev/null and b/docs/3_Architecture_Guides/2_Security_Blueprint/images/WhiteBoxArchi.png differ diff --git a/docs/3_Developer_Guides/1_Application_Framework/1_Introduction.md b/docs/3_Developer_Guides/1_Application_Framework/1_Introduction.md deleted file mode 100644 index 957858a..0000000 --- a/docs/3_Developer_Guides/1_Application_Framework/1_Introduction.md +++ /dev/null @@ -1,150 +0,0 @@ ---- -title: Introduction ---- - -# Foreword - -The AGL Application Framework is nothing new. However, the implementation used up until -the `lamprey` release has been retired starting with the `marlin` release and replaced -by a redesigned Application Framework one. However, this new implementation isn't a 1:1 -replacement, and as such it doesn't provide all of the features of the previous -Application Framework. Some of those will be added back over time, others have been -discarded in favor of more modern and/or widely-used alternatives. - -# Introduction - -As a provider of an integrated solution to build up on, AGL needs to define a reliable -and well-specified method for managing the deployment and integration of applications -and services, as well as the way they can interact with the rest of the system. - -This is achieved by providing a common set of rules and components, known as the -Application Framework. By ensuring conformity to those rules, application developers -can have a good understanding of the requirements for creating and packaging -applications targeting AGL-based systems. Likewise, system developers and integrators -have a clear path for including such applications in AGL-based products. - -The Application Framework's scope extends to the following areas: -- system services integration and lifecycle management -- user session management, including user-level applications and services lifecycle - management -- inter-process communication - -In order to be as simple as possible and avoid any unneded custom implementation, the -Application Framework relies mainly on third-party technologies and/or software -components, most of those being maintained under the -[freedesktop.org](https://www.freedesktop.org) umbrella. Those include: - - -- [systemd](https://www.freedesktop.org/wiki/Software/systemd/): system services and user session services management - - -- [D-Bus](https://www.freedesktop.org/wiki/Software/dbus/): inter-process communication - - -- [Desktop Entry specification](https://www.freedesktop.org/wiki/Specifications/desktop-entry-spec/): - application enumeration and startup - -AGL also provides reference implementations whenever possible and relevant, located in -the [meta-agl](/3_Developer_Guides/6_AGL_Layers/2_meta-agl/) layer under `meta-app-framework`. At the -moment, the Application Framework contains 2 such components: - -- `agl-session`: `systemd` unit files for user sessions management - -- `applaunchd`: application launcher service - -# Services management - -Both system and user services are managed by `systemd`, which provides a number of -important features, such as dependency management or service monitoring: when starting -a service, `systemd` will ensure any other units this service depends on are available, -and otherwise start those dependencies. Similarly, `systemd` can automatically restart -a crashed service, ensuring minimal downtime. - -`systemd` also provides an efficient first layer of security through its -[sandboxing](https://www.freedesktop.org/software/systemd/man/systemd.exec.html#Sandboxing) -and other security-related options. - -It is also well integrated with D-Bus and can be used for a more fine-grained control -over D-Bus activated services: by delegating the actual service startup to `systemd`, -developers can take advantage of some of its advanced features, allowing for improved -reliability and security. - -Each service should be represented by a `systemd` unit file installed to the appropriate -location. More details can be obtained from the [Creating a New Service](/3_Developer_Guides/2_Creating_a_New_Service/) -document. - -# User session management - -Similarly, user sessions and the services they rely on are also managed by `systemd`. - -AGL provides 2 `systemd` units: - - -1\. `agl-session@.service` is a template system service for managing user sessions; it -takes a username or UID as a parameter, creating a session for the desired user. -Instanciating this service can be achieved by enabling `agl-session@USER.service`, for -example by executing the following command on a running system: - -``` -$ systemctl enable agl-session@USER.service -``` - -By default, AGL enables this service as `agl-session@agl-driver.service`, running as -user `agl-driver`. - -*Note: while you can create sessions for as many users as needed, only one instance of -`agl-session@.service` is allowed per user.* - - -2\. `agl-session.target` is a user target for managing user services and their -dependencies. It is started by `agl-session@.service`. - -By default, `agl-compositor` is part of this target. It is therefore automatically -started for user `agl-driver`. - -Any other service needed as part of the user session should similarly depend on this -target by appending the following lines to their unit file: - -``` -[Install] -WantedBy=agl-session.target -``` - -# Inter-process communication - -In order to provide a "standard", language-independent IPC mechanism and avoid the need -for maintaining custom bindings for each programming language to be used on top of AGL, -the Application Framework promotes the use of [D-Bus](https://www.freedesktop.org/wiki/Software/dbus/) -as the preferred way for applications to interact with services. - -Most services already included in AGL provide one or several D-Bus interfaces, and can -therefore interact with D-Bus capable applications and services without requiring any -additional component. Those services include, among others: - -- [ConnMan](https://git.kernel.org/pub/scm/network/connman/connman.git/): network connectivity - -- [BlueZ](http://www.bluez.org/): Bluetooth connectivity - -- [oFono](https://git.kernel.org/pub/scm/network/ofono/ofono.git): telephony and modem - management - -- [GeoClue](https://gitlab.freedesktop.org/geoclue/geoclue/-/wikis/home): geolocation - -# Application launcher service - -As mentioned above, the Application Framework follows the guidelines of the -[Desktop Entry specification](https://www.freedesktop.org/wiki/Specifications/desktop-entry-spec/) -for application enumeration and startup. - -As no simple reference implementation exists for this part of the specification, AGL -provides an application launcher service named `applaunchd`. This service is part of the -default user session, and as such is automatically started on session startup. It can -therefore be considered always available. - -`applaunchd` enumerates applications installed on the system and provides a D-bus -interface for services and applications to: -- query the list of available applications -- request the startup and/or activation of a specific application -- be notified when applications are started or terminated - -`applaunchd` is described with more details in [the following document](../2_Application_Startup/). diff --git a/docs/3_Developer_Guides/1_Application_Framework/2_Application_Startup.md b/docs/3_Developer_Guides/1_Application_Framework/2_Application_Startup.md deleted file mode 100644 index 4841ce5..0000000 --- a/docs/3_Developer_Guides/1_Application_Framework/2_Application_Startup.md +++ /dev/null @@ -1,184 +0,0 @@ ---- -title: Application Startup ---- - -# Introduction - -At system runtime, it may be necessary for applications to start other applications -on demand. Such actions can be executed in reaction to a user request, or they may -be needed to perform a specific task. - -In order to do so, running applications and services need an established way of -discovering installed applications and executing those. The -[Desktop Entry specification](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html) -defines how applications can be discovered by using `.desktop` files, but there's no -simple reference implementation for this function. - -In order to provide a language-independent interface for applications and service to -use, AGL includes `applaunchd`, a user service part of the default session. - -*Note: as mentioned [previously](1_Introduction/), services are managed using `systemd` -and are therefore not in the scope of this document.* - -# Application launcher service - -The purpose of `applaunchd` is to enumerate applications available on the system and -provide a way for other applications to query this list and start those on demand. -It is also able to notify clients of the startup and termination of applications it -manages. - -To that effect, `applaunchd` provides a D-Bus interface other applications can use -in order to execute those actions. - -*Note: `applaunchd` will only send notifications for applications it started; it isn't -aware of applications started by other means (`systemd`, direct executable call...), -and therefore can't send notifications for those.* - -## Application discovery - -On startup, `applaunchd` inspects all `.desktop` files present under the `applications/` -subfolder of any element of the `XDG_DATA_DIRS` environment variable, ignoring all entries -containing either the `NoDisplay=true` or `Hidden=true` lines. - -It then looks for the following keys: -- `Terminal` -- `DBusActivatable` - -If the desktop entry file contains the `Terminal` key set to `true`, then the application -is marked as a non-graphical one. As such, it won't be included in the applications list -if the client requests only graphical applications. - -If `DBusActivatable` is set to `true`, then the application is marked as D-Bus activated. -Additionally, `applaunchd` will search for a corresponding D-Bus service file in case this -line is missing. This is a workaround allowing D-Bus activated applications providing -an incomplete desktop entry file (i.e missing the `DBusActivatable` key) to be -identified as such. - -### Requirements for D-Bus activation - -`applaunchd` will always start D-Bus activatable applications using D-Bus activation -instead of executing the command line stated in the desktop entry file. - -This is handled by calling the `Activate` method of the -[org.freedesktop.Application](https://specifications.freedesktop.org/desktop-entry-spec/1.1/ar01s07.html) -interface with an empty argument. - -As a consequence, all D-Bus activatable applications **must** implement this D-Bus -interface. - -## Application identifiers - -Each application is identified by a unique Application ID. Although this ID can be -any valid string, it is highly recommended to use the "reverse DNS" convention in order -to avoid potential name collisions and ease D-Bus integration. - -The application ID is set in the desktop entry file itself for -[graphical applications](../3_Creating_a_New_Application/#graphical-applications): -it is the value of the `StartupWMClass` field, which must be identical to the `app-id` -advertised through the Wayland XDG toplevel protocol. In case this field is missing -(as is usually the case for non-graphical application), the application ID will be the -desktop entry file name, stripped from its `.desktop` extension. - -## D-Bus interface - -The `applaunchd` D-Bus interface is named `org.automotivelinux.AppLaunch`. The object -path for `applaunchd` is `/org/automotivelinux/AppLaunch`. The interface provides methods -for the following actions: -- retrieve the list of available applications; the client can choose to retrieve all - available applications, or only those suitable for a graphical environment -- request an application to be started - -Moreover, signals are available for clients to be notified when an application has -successfully started or its execution terminated. - -### Applications list - -The `listApplications` method allows clients to retrieve the list of available applications. -It takes one boolean argument named `graphical`: -- if set to `true`, only applications suitable for graphical environments are returned -- otherwise, the list contains all applications - -This method returns an array of variants (type `av`), each element being a structure made up -of 3 strings (type `(sss)`): -- the application ID -- the application's displayed name -- the full path to the application icon file (or an empty string if no icon was specified in - the application's desktop entry file) - -### Application startup request - -Applications can be started by using the `start` method, passing the corresponding application -ID as the only argument. This method doesn't return any data. - -If the application is already running, `applaunchd` won't start another instance, but instead -emit a `started` signal to notify clients the application is ready. - -### Status notifications - -The `org.automotivelinux.AppLaunch` interface provides 2 signals clients can connect to: -- `started` indicates an application has started - - for D-Bus activated applications, it is emitted upon successful completion of the - call to the `Activate` method of the `org.freedesktop.Application` interface - - for other applications, this signal is emitted as soon as the child process has been - successfully created -- `terminated` is emitted when an application quits - -Both signals have an additional argument named `appid`, containing the ID of the application -affected by the event. - -As mentioned above, the `started` signal is also emitted if `applaunchd` receives a request to -start an already running application. This can be useful, for example, when switching between -graphical applications: -- the application switcher doesn't need to track the state of each application; instead, it can - simply send a `start` request to `applaunchd` every time the user requests to switch to another - application -- the desktop environment then receives the `started` signal, indicating it should activate the - window with the corresponding `app-id` - -## Testing - -`applaunchd` can be manually tested using the `gdbus` command-line tool: - -1. Query the application list (graphical applications only): - -``` -$ gdbus call --session --dest "org.automotivelinux.AppLaunch" \ - --object-path "/org/automotivelinux/AppLaunch" \ - --method "org.automotivelinux.AppLaunch.listApplications" \ - true -``` - -This command will output something similar to what follows: - -``` -([<('navigation', 'Navigation', '/usr/share/icons/hicolor/scalable/navigation.svg')>, - <('settings', 'Settings', '/usr/share/icons/hicolor/scalable/settings.svg')>, - <('dashboard', 'Dashboard', '/usr/share/icons/hicolor/scalable/dashboard.svg')>, - <('hvac', 'HVAC', '/usr/share/icons/hicolor/scalable/hvac.svg')>, - <('org.freedesktop.weston.wayland-terminal', 'Weston Terminal', '/usr/share/icons/Adwaita/scalable/apps/utilities-terminal-symbolic.svg')>],) -``` - -2. Request startup of the `org.freedesktop.weston.wayland-terminal` application: - -``` -$ gdbus call --session --dest "org.automotivelinux.AppLaunch" \ - --object-path "/org/automotivelinux/AppLaunch" \ - --method "org.automotivelinux.AppLaunch.start" \ - "org.freedesktop.weston.wayland-terminal" -``` - -3. Monitor signals emitted by `applaunchd`: - -``` -$ gdbus monitor --session --dest "org.automotivelinux.AppLaunch" -``` - -This results in the following output when starting, then exiting, the -`org.freedesktop.weston.wayland-terminal` application: - -``` -Monitoring signals from all objects owned by org.automotivelinux.AppLaunch -The name org.automotivelinux.AppLaunch is owned by :1.4 -/org/automotivelinux/AppLaunch: org.automotivelinux.AppLaunch.started ('org.freedesktop.weston.wayland-terminal',) -/org/automotivelinux/AppLaunch: org.automotivelinux.AppLaunch.terminated ('org.freedesktop.weston.wayland-terminal',) -``` diff --git a/docs/3_Developer_Guides/1_Setting_Up_AGL_SDK.md b/docs/3_Developer_Guides/1_Setting_Up_AGL_SDK.md deleted file mode 100644 index d3f01fb..0000000 --- a/docs/3_Developer_Guides/1_Setting_Up_AGL_SDK.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: Setting Up AGL SDK ---- - -AGL provides a pre-built ready-made Software Development Kit (SDK) to help -quickstart the service and application development process. - -1. Download the prebuilt SDK : - - Please open the link below and download .sh file for desired machine. - - **Note:** The links provided are for the master branch. If you want SDK for specific branch than change the name from master to specific branch. - - - **x86** : [qemux86-64](https://download.automotivelinux.org/AGL/snapshots/master/latest/qemux86-64/deploy/sdk/) - - **Note:** .sh file will be with name "poky-agl-glibc-x86_64-agl-demo-platform-crosssdk-corei7-64-qemux86-64-toolchain-$(version number).sh" where version number is regularly updated on the site. - - - - **ARM 32 bit** : [qemuarm](https://download.automotivelinux.org/AGL/snapshots/master/latest/qemuarm/deploy/sdk/) - - **Note:** .sh file will be with name " poky-agl-glibc-x86_64-agl-demo-platform-crosssdk-armv7vet2hf-neon-vfpv4-qemuarm-toolchain-$(version number).sh" where version number is regularly updated on the site. - - - - **AARCH64 - ARM 64bit** : [qemuarm64](https://download.automotivelinux.org/AGL/snapshots/master/latest/qemuarm64/deploy/sdk/) - - **Note:** .sh file will be with name " poky-agl-glibc-x86_64-agl-demo-platform-crosssdk-aarch64-qemuarm64-toolchain-$(version number).sh" where version number is regularly updated on the site. - - - *Henceforth,* **qemux86-64** *is used in these guides, unless specified - otherwise. We also use the 'agl-demo-platform-crosssdk' as example.* - -2. Create application development directory and copy SDK into them : - - **Note:** In the copy command below change the file name with name of your downloaded .sh file. In the example below file name is based on x86 - - ```sh - $ mkdir ~/agl-app - $ cp ~/Downloads/poky-agl-glibc-x86_64-agl-demo-platform-crosssdk-*.sh ~/agl-app/ - $ cd ~/agl-app - ``` - -3. Install the downloaded SDK : - - **Note:** In commands below again change the file name based on your downloaded .sh file - - - ```sh - $ chmod 777 poky-agl-glibc-x86_64-agl-demo-platform-crosssdk-*.sh - $ mkdir agl-sdk/ - $ ./poky-agl-glibc-x86_64-agl-demo-platform-crosssdk-*.sh - ``` - Select target directory for SDK : `~/agl-app/agl-sdk` - - ```sh - Automotive Grade Linux SDK installer version 14.0.0 - ============================================================= - Enter target directory for SDK (default: /opt/agl-sdk/10.90.0+snapshot-corei7-64): ~/agl-app/agl-sdk - You are about to install the SDK to "/home/boron/agl-app/agl-sdk". Proceed [Y/n]? Y - Extracting SDK..........................................................................................................................................done - Setting it up...done - SDK has been successfully set up and is ready to be used. - Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g. - $ . /home/boron/agl-app/agl-sdk/environment-setup-corei7-64-agl-linux - ``` - -4. Source the SDK environment setup, each time you wish to use the SDK in a new shell session : - - ```sh - $ source ~/agl-app/agl-sdk/environment-setup-corei7-64-agl-linux - ``` diff --git a/docs/3_Developer_Guides/2_Creating_a_New_Service.md b/docs/3_Developer_Guides/2_Creating_a_New_Service.md deleted file mode 100644 index 0fb2453..0000000 --- a/docs/3_Developer_Guides/2_Creating_a_New_Service.md +++ /dev/null @@ -1,151 +0,0 @@ ---- -title: Creating a New Service ---- - -Services are software running in the background and providing, as their name suggests, -various services to other software: access to specific system hardware, connectivity -management, and network servers. Services can be split into 2 categories: - -- **System services:** those usually run as a privileged user and make use of shared system - resources which they should have exclusive access to - -- **User services:** such services run as part of an unprivileged user's session and can - only be called by said user - -# Basic requirements - -The only mandatory requirement is that service packages provide a `.service` file -so they can be properly managed by `systemd`. This file must be installed to a specific -location, determined by the service type (system or user): - -- `/usr/lib/systemd/system/` for system services - -- `/usr/lib/systemd/user/` for user services - -Below is an example of a simple user service, running in a graphical session and -therefore requiring a compositor to be already running before the service starts: - -``` -[Unit] -Requires=agl-compositor.service -After=agl-compositor.service - -[Service] -Type=simple -ExecStart=/usr/bin/homescreen -Restart=on-failure - -[Install] -WantedBy=agl-session.target -``` - -The `WantedBy=agl-session.target` indicates the service is part of the default AGL -user session, as mentioned in the [Application Framework](../1_Application_Framework/1_Introduction/#user-session-management) -documentation. - -The `Restart=on-failure` directive ensures the service will be automatically -restarted by `systemd` in case it crashes. - -More details about `systemd` service files can be found in the -[systemd documentation](https://www.freedesktop.org/software/systemd/man/systemd.service.html). - -# D-Bus activation - -Services can also provide a D-Bus interface. In this case, they need not be started -on system boot (or user session startup in the case of user services) but can be -automatically started only when a client sends a request to the D-Bus name the service -registers. - -D-Bus activated services must name their `systemd` service file `dbus-NAME.service` -where `NAME` is the D-Bus name registered by the service. This file must include the -following lines: - -``` -[Service] -Type=dbus -BusName=NAME -ExecStart=/path/to/executable -``` - -In addition, they must provide a D-Bus service file named `NAME.service` and installed -to one of the following locations: - -- `/usr/share/dbus-1/system-services` for system services - -- `/usr/share/dbus-1/services` for user services - -The contents of the D-Bus service file must be the following: - -``` -[D-BUS Service] -Name=NAME -Exec=/path/to/executable -SystemdService=dbus-NAME.service -``` - -This ensures the service can be safely activated through D-Bus and no conflict will occur -between `systemd` and the D-Bus daemon. - -More details about D-Bus activation can be found in the -[D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html#message-bus-starting-services), -under the "Message Bus Starting Services (Activation)" section. - -# Services startup - -For D-Bus activated services, no additional action is required as those will be automatically -started whenever needed. Other services, however, need a few more steps in order to be -executed on system or session startup. - -## System services - -System services can take advantage of the Yocto `systemd` class which automates the process of -enabling such services. - -1\. Ensure the recipe inherits from the `systemd` class: - -``` -inherit systemd -``` - -2\. Declare the system services that needs to be enabled on boot: - -``` -SYSTEMD_SERVICE:${PN} = "NAME.service" -``` - -3\. Ensure the `FILES` variable includes the systemd service directory the corresponding -file will be installed to: - -``` -FILES:${PN} = "\ - ... - ${systemd_system_unitdir}/* \ -" -``` - -## User services - -The `systemd` class doesn't provide an equivalent mechanism for user services. This must -therefore be done manually as part of the package's install process. - -1\. Make the service a part of the user session: - -``` -do_install:append() { - install -d ${D}${systemd_user_unitdir}/agl-session.target.wants - ln -s ../NAME.service ${D}${systemd_user_unitdir}/agl-session.target.wants/NAME.service -} -``` - -This ensures `agl-session.target` depends on `NAME.service`, the latter being therefore -automatically started on session creation. - -2\. Ensure the `FILES` variable includes the systemd service directory the corresponding -file will be installed to: - -``` -FILES:${PN} = "\ - ... - ${systemd_user_unitdir}/* \ -" -``` diff --git a/docs/3_Developer_Guides/3_Creating_a_New_Application.md b/docs/3_Developer_Guides/3_Creating_a_New_Application.md deleted file mode 100644 index ed89ecc..0000000 --- a/docs/3_Developer_Guides/3_Creating_a_New_Application.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -title: Creating a New Application ---- - -Applications are: - -- Software designed to perform a specific task during a limited amount of time. -- Graphical interface allowing user to interact with. - -Applications are executed by `applaunchd`, the AGL -[application launcher service](../1_Application_Framework/2_Application_Startup/). - -# Basic requirements - -In order to be enumerated by `applaunchd`, applications must provide the a `.desktop` file, as -defined by the [Desktop Entry specification](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html). - -The desktop entry file should be installed to `/usr/share/applications` (or the `applications` -sub-directory of any entry present in the `XDG_DATA_DIRS` environment variable) and have a -meaningful name. It is considered good practice to use reverse-DNS notation for the desktop -entry file name, following the recommendations of the [D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names): -- this avoids potential name collisions with other desktop entry files -- it makes it easier to enable [D-Bus activation](#d-bus-activation) during the application - development cycle if needed -- for [graphical applications](#graphical-applications), it ensures the chosen Wayland `app-id` - will be unique - -Such a file must contain at least the following keys: -- `Type`: desktop entry type, must be set to `Application` -- `Name`: application name, as it should be displayed in menus and application launchers -- `Exec`: full path to the main executable - -Below is an example of a minimal desktop entry file: - -``` -[Desktop Entry] -Type=Application -Name=Example Application -Exec=/usr/bin/example-app -``` - -Graphical applications must also provide an `Icon` entry pointing to the application icon. -The value for this entry must either be the full path to the icon's file or, for icons part -of an existing [icon theme](https://specifications.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html), -the name of an element of this theme. - -In addition, a number of optional fields can be used to change how `applaunchd` will consider the -application: -- `Version`: version of the Desktop Entry Specification the file conforms to, must be `1.5` -- `Hidden`: boolean value, if `true` the application is always ignored by `applaunchd` and - won't be listed nor executed -- `Terminal`: boolean value, if `true` the application is excluded when requesting the list of - graphical applications from `applaunchd` -- `DBusActivatable`: boolean value, must be `true` for [D-Bus activated applications](#d-bus-activation) -- `Implements`: list of D-Bus interfaces the application implements, only used for D-Bus activated - applications. - -Finally, graphical applications may also define the `StartupWMClass` key in some cases. Please -refer to the [graphical applications](#graphical-applications) section for more information. - -# D-Bus activation - -Similarly to [services](../2_Creating_a_New_Service/#d-bus-activation), applications can -also be activated through D-Bus. - -Such applications must name their `.desktop` file after the D-Bus name they register. In addition, -this file must contain the following entries: - -``` -DBusActivatable=true -Implements=IFACE1;IFACE2;... -``` - -Where `IFACEn` are the names of the D-Bus interfaces the application implements. - -In addition, they must provide a D-Bus service file named `NAME.service` and installed -to `/usr/share/dbus-1/services`. - -The contents of the D-Bus service file must be the following: - -``` -[D-BUS Service] -Name=NAME -Exec=/path/to/executable -``` - -For example, an application registering the `org.automotivelinux.Example` D-Bus name -and implementing the `org.automotivelinux.Example.Search1` and `org.automotivelinux.Example.Execute1` -interfaces would provide the following files: - -* Desktop entry (`/usr/share/applications/org.automotivelinux.Example.desktop`): - -``` -[Desktop Entry] -Type=Application -Version=1.5 -Name=Example Application -Exec=/usr/bin/example-app -Icon=example-icon -Terminal=false -DBusActivatable=true -Implements=org.automotivelinux.Example.Search1;org.automotivelinux.Example.Execute1 -``` - -* D-Bus service file (`/usr/share/dbus-1/services/org.automotivelinux.Example.service`): - -``` -[D-BUS Service] -Name=org.automotivelinux.Example -Exec=/usr/bin/example-app -``` - -*Note: in addition to their own D-Bus interface, D-Bus activated applications must also -implement the `org.freedesktop.Application` interface as defined in the -[Desktop Entry specification](https://specifications.freedesktop.org/desktop-entry-spec/1.1/ar01s07.html).* - -# Graphical applications - -In addition, graphical applications need to comply with a few more requirements: - -1\. Each application must set a Wayland application ID appropriately as soon as its main window -is created. - -2\. The `app-id` must be specified in the desktop entry file by adding the following line: - -``` -StartupWMClass=APP_ID -``` - -3\. The desktop entry file must be named `APP_ID.desktop`. - -Doing so will ensure other software can associate the actual `app-id` to the proper application. - -*Note: application ID's are set using the [XDG toplevel](https://wayland-book.com/xdg-shell-basics/xdg-toplevel.html) -Wayland interface.* diff --git a/docs/3_Developer_Guides/4_Creating_a_custom_recipe.md b/docs/3_Developer_Guides/4_Creating_a_custom_recipe.md deleted file mode 100644 index f8650e8..0000000 --- a/docs/3_Developer_Guides/4_Creating_a_custom_recipe.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Creating a Custom Recipe ---- - - -For adding a custom linux software/service like cannelloni you have to do the following steps: - -1. Add repo via devtool (gitrepo stands for the url) - - ``` - devtool add gitrepo - ``` -2. Try to bitbake, if it is working go to step 3 - - ``` - bitbake packagename (gitrepo name) - ``` - If it is not working you can do (repeating) following steps until it is working - - 1. change/modify the recipe in /workspace/recipe/packagename - 2. change/modify the sources in /workspace/sources/packagename - 3. bitbake packagename - - Now update the recipe, if you do this the first time you have to adapt the license and the LIC-File-Checksum - - ``` - devtool update-recipce packagename - ``` - -3. Build the recipe and image with devtool - - ``` - devtool build packagename - devtool build-image agl-demo-platform - ``` - - If that is working you could add it to git/gerrit. You have to add your recipe to a layer. - - 1. Copy files to the recipe - 2. add recipe to a packagegroup - -4. Git - - ``` - git review - git review -s - git remote -v update - ``` -![Build recipe](images/AGL_add_recipe.png) \ No newline at end of file diff --git a/docs/3_Developer_Guides/5_General_setup.md b/docs/3_Developer_Guides/5_General_setup.md deleted file mode 100644 index af05096..0000000 --- a/docs/3_Developer_Guides/5_General_setup.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: Generic devices setup ---- - -## Camera setup on RPi4 - -This assumes that you'll be using the Raspberry Pi Camera Module, which can -easily hooked on the board using the LVDS connector. Further more information -about how to connect it, could be found at -[Installing a Raspberry Pi camera](https://www.raspberrypi.com/documentation/accessories/camera.html#installing-a-raspberry-pi-camera) - -With the camera installed, you'll need to enable it by editing /boot/config.txt -file (if you're booting an AGL image over a sd-card it will be there by -default, otherwise -- in case of doing netboot, you'll have to create -manually) and add the following entry: - - - ## start_x - ## Set to "1" to enable the camera module. - ## - ## Enabling the camera requires gpu_mem option to be specified with a value - ## of at least 128. - ## - ## Default 0 - ## - start_x=1 - -And reboot your device. Afterwards, after logging it, make sure that you have -the /dev/video0 device created. You could also use v4l2-ctl to verify -that is indeed usable as a capture device: - - $ v4l2-ctl -d /dev/video0 --all - -In order to test out video playback, use the following gstreamer pipeline: - - $ gst-launch-1.0 v4l2src device=/dev/video0 ! \ - video/x-raw,width=640,height=480 ! waylandsink fullscreen=true - -Alternatively, using [camera-gstreamer](https://gerrit.automotivelinux.org/gerrit/gitweb?p=apps/camera-gstreamer.git;a=summary) -application could might be another possibility, but you'll have to build it -yourself and add it in the image. - -This includes an example on how to create a xdg-toplevel surface and create a -gstreamer pipeline, instead of relaying on waylandsink to create one for you, -in a programmatic fashion. - -## Display setup on RPi4 - -This assumes that you'll be using the Raspberry Pi 7'' display. Installation -can be found at [Rpi Display page](https://www.raspberrypi.com/documentation/accessories/display.html). - -If booting over the network, the dtb should already contain the ft5406 dtb, -while booting over sd-card the following show be in the /boot/config.txt -file: - - dtoverlay=rpi-ft5406-overlay - -Once the board boots up, you should get a rainbow like effect and afterwards -booting up would display debug scrolling over. You'll need to adjust the -orientation as the 800x480 is in portrait. Edit /etc/xdg/weston/weston.ini and -add a new output entry, like the following: - - [output] - name=DSI-1 - transform=90 - -Note that for the Qt platform, the homescreen application, together with the -other demo applications, is tailored specifically for a 1080p display and it -will display incorrectly on such a smaller display. - -## Testing out video camera without a real device - -While the above requires having a real video camera device, one can use out -the [vivid module](https://docs.kernel.org/admin-guide/media/vivid.html?highlight=vivid#the-virtual-video-test-driver-vivid) -to try out your custom application or just testing out camera functionality in AGL. - -You should normally have the module present, not loaded, for either **rpi4** or for -**h3ulcb** boards. Load the module, like in the following command: - - modprobe vivid allocators=0x1 - -Have a look at the kernel ring buffer to see what capture devices are created -and use as source: - - $ gst-launch-1.0 v4l2src device=/dev/videoXX ! \ - video/x-raw,width=640,height=480 ! waylandsink fullscreen=true - -making sure to replace /dev/videoXX with correct capture device. You can check -that easily using the v4l2-ctl mentioned above. - -Note that using camera-gstreamer will attempt to find the first available -capture device, so if you happen to have to another one before the one created -by this module it might not work. You can bypass that, by just making a symlink -from /dev/videoXX to /dev/video0 to make first available capture device. diff --git a/docs/3_Developer_Guides/6_AGL_Layers/1_Overview.md b/docs/3_Developer_Guides/6_AGL_Layers/1_Overview.md deleted file mode 100644 index dec8054..0000000 --- a/docs/3_Developer_Guides/6_AGL_Layers/1_Overview.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Overview ---- - -The [AGL Project](https://www.automotivelinux.org/) is an automotive-specific -development environment that provides a Linux distribution -([AGL UCB](https://www.automotivelinux.org/software/unified-code-base)). - -AGL uses layers designed to be compatible with the -[Yocto Project](https://www.yoctoproject.org) and the -[OpenEmbedded Project (OE)](https://www.openembedded.org/wiki/Main_Page). - -This section provides information about the layers used by the AGL Project: - -* **`meta-agl`**: Minimal set of software needed to create an AGL distribution - used to boot a system. - AGL profiles are built on top of this minimal set of software. - -* **`meta-agl-demo`**: Provides a reference or demo platform and applications - for the AGL Distribution. - The reference UI is part of the `meta-agl-demo` layer. - -* **`meta-agl-devel`**: Contains components under development or being tested. - This layer also contains software packages that OEMs need but do not exist - in AGL. diff --git a/docs/3_Developer_Guides/6_AGL_Layers/2_meta-agl.md b/docs/3_Developer_Guides/6_AGL_Layers/2_meta-agl.md deleted file mode 100644 index 1ac45a6..0000000 --- a/docs/3_Developer_Guides/6_AGL_Layers/2_meta-agl.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: meta-agl ---- - -## Introduction - -The `meta-agl` layer provides the minimal set of software -to boot an AGL Distribution system. -You use this layer as the minimal core on which to build AGL profiles. - -**NOTE:** The `meta-agl` layer does not include a reference UI. - The reference UI is included as part of the - [`meta-agl-demo`](3_meta-agl-demo.md) layer. - Furthermore, `meta-agl` does not include additional components, such - as security, which are part of the - `meta-agl-extra` layer. - -## Sub-Layers - -The `meta-agl` layer itself contains many sub-layers and files. -Following is a "tree" look at the layer: - -``` -. -├── docs -├── meta-agl -├── meta-agl-bsp -├── meta-agl-distro -├── meta-agl-profile-cluster -├── meta-agl-profile-cluster-qt5 -├── meta-agl-profile-core -├── meta-agl-profile-graphical -├── meta-agl-profile-graphical-html5 -├── meta-agl-profile-graphical-qt5 -├── meta-agl-profile-hud -├── meta-agl-profile-telematics -├── meta-app-framework -├── meta-netboot -├── meta-security -├── README-AGL.md -├── README.md -├── scripts -├── templates -``` - -This list provides some overview information on the files and sub-layers -in `meta-agl`: - -* `docs`: Contains files that support AGL documentation. -* `meta-agl`: Contains layer configuration for the `meta-agl` layer. -* `meta-agl-bsp`: Contains adaptations for recipes and required packages - to boot an AGL distribution on targeted hardware and emulation (i.e. QEMU). -* `meta-agl-distro`: Contains distro configuration and supporting scripts. -* `meta-agl-profile-cluster`: The middleware for the AGL cluster profile. - The set of packages required for AGL Cluster Distribution. - Profiles include support for Wayland images. -* `meta-agl-profile-cluster-qt5`: The middleware for the AGL Qt5-based cluster profile. - The set of packages required for AGL Qt5-based Cluster Distribution. - Profiles include support for Wayland images with Qt5. -* `meta-agl-profile-core`: Configuration and recipes for the AGL core profiles. -* `meta-agl-profile-graphical`: Configuration and recipes supporting graphical user - interfaces. -* `meta-agl-profile-graphical-html5`: Configuration and recipes supporting profiles - with HTML user interface support. -* `meta-agl-profile-graphical-qt5`: Configuration and recipes supporting profiles - with Qt5-based user interface support. -* `meta-agl-profile-hud`: Configuration and recipes supporting profiles with - Head-Up-Display (HUD) support. -* `meta-agl-profile-telematics`: Configuration and recipes supporting profiles with - telematics support. -* `meta-app-framework`: Configuration and recipes supporting the AGL Application - Framework. -* `meta-netboot`: Contains recipes and configuration adjustments to allow network - boot through network block device (NBD) since network file system (NFS) does not - support security labels. -* `meta-security`: Configuration and recipes supporting security applications. -* `scripts`: AGL development setup and support scripts. -* `templates`: Base, feature, and machine templates used in the AGL development - environment. - -## Packagegroups - -This section describes the AGL -[packagegroup](https://yoctoproject.org/docs/3.1.4/dev-manual/dev-manual.html#usingpoky-extend-customimage-customtasks) -design: - -* packagegroup-agl-image-minimal - - packagegroup-agl-core-automotive.bb - packagegroup-agl-core-connectivity.bb - packagegroup-agl-core-graphics.bb - packagegroup-agl-core-kernel.bb - packagegroup-agl-core-multimedia.bb - packagegroup-agl-core-navi-lbs.bb - packagegroup-agl-core-os-commonlibs.bb - packagegroup-agl-core-security.bb - packagegroup-agl-core-speech-services.bb - - The previous list of Packagegroups are used to create the `agl-image-minimal` image, - which is a small image just capable of allowing a device to boot. - - Subsystem should maintain packagegroup-agl-core-[subsystem].bb which should - hold sufficient packages to build `agl-image-minimal`. - -* packagegroup-agl-image-ivi - - packagegroup-agl-ivi-automotive.bb - packagegroup-agl-ivi-connectivity.bb - packagegroup-agl-ivi-graphics.bb - packagegroup-agl-ivi-kernel.bb - packagegroup-agl-ivi-multimedia.bb - packagegroup-agl-ivi-navi-lbs.bb - packagegroup-agl-ivi-os-commonlibs.bb - packagegroup-agl-ivi-security.bb - packagegroup-agl-ivi-speech-services.bb - - The previous list of Packagegroups are used to create the `agl-image-ivi` - image, which is a baseline image (i.e. Service Layer and Operating System - Layer defined in AGL Spec v1.0) for the AGL profiles. - -* packagegroup-agl-test.bb - - Additional tools used in QA tests (for agl-image*-qa). - diff --git a/docs/3_Developer_Guides/6_AGL_Layers/3_meta-agl-demo.md b/docs/3_Developer_Guides/6_AGL_Layers/3_meta-agl-demo.md deleted file mode 100644 index c560989..0000000 --- a/docs/3_Developer_Guides/6_AGL_Layers/3_meta-agl-demo.md +++ /dev/null @@ -1,159 +0,0 @@ ---- -title: meta-agl-demo ---- - -## Introduction - -The `meta-agl-demo` layer is the reference user interface layer for the DEMO -platform of Automotive Grade Linux (AGL). -The layer provides a reference platform and applications. -The BitBake target name for the DEMO platform is `agl-demo-platform`, which is -the full DEMO platform image. - -## Layer Dependencies - -This section describes dependencies for the `meta-agl-demo` layer. -Dependencies are grouped into base, hardware, and feature dependencies. - -### Base Dependencies - -The `meta-agl-demo` layer has the following base dependencies: - -- Yocto Project Release: - - - URI: git://git.yoctoproject.org/poky - - Branch: "thud" - - Tested Revision: See the - [`default.xml`](https://github.com/leon-anavi/AGL-repo/blob/master/default.xml) - manifest file for the `AGL-repo` repository for revision information. - -- AGL `meta-agl` Layer: - - - URI: https://gerrit.automotivelinux.org/gerrit/AGL/meta-agl - - Branch: "master" - -- OpenEmbedded `meta-openembedded` Layer: - - - Branch: "thud" - - Tested Revision: See the - [`default.xml`](https://github.com/leon-anavi/AGL-repo/blob/master/default.xml) - manifest file for the `AGL-repo` repository for revision information. - - Specifically, out of `meta-openembedded`, these sub-layers are used: - - - `meta-oe` - - `meta-multimedia` - - `meta-networking` - - `meta-python` - -- Yocto Project `meta-qt5` Layer from the - [OpenEmbedded Layer Index](https://layers.openembedded.org/layerindex/branch/master/layers/): - - - URI: https://github.com/meta-qt5/meta-qt5.git - - Branch: "thud" - - Tested Revision: See the - [`default.xml`](https://github.com/leon-anavi/AGL-repo/blob/master/default.xml) - manifest file for the `AGL-repo` repository for revision information. - -### Hardware Dependencies - -Aside from the previously listed base dependencies, if you are using a -[supported Renesas board](../../0_Getting_Started/2_Building_AGL_Image/5_3_RCar_Gen_3.md) -supported Renesas board, these dependencies exist: - -- AGL's `meta-renesas` Layer: - - - URI: https://gerrit.automotivelinux.org/gerrit/AGL/meta-renesas - -### Feature Dependencies - -The `meta-agl-demo` layer has the following AGL [feature](../../0_Getting_Started/2_Building_AGL_Image/3_Initializing_Your_Build_Environment.md#agl-features) -dependencies: - -- Yocto Project `meta-security` Layer: - - - URI: https://git.yoctoproject.org/cgit/cgit.cgi/meta-security - - Branch: "master" - - Tested Revision: See the - [`default.xml`](https://github.com/leon-anavi/AGL-repo/blob/master/default.xml) - manifest file for the `AGL-repo` repository for revision information. - -- AGL's `meta-app-framework` Layer within the `meta-agl` Layer: - - - URI: https://gerrit.automotivelinux.org/gerrit/gitweb?p=AGL/meta-agl.git - - Branch: "master" - -**The `agl-sota` Feature:** - -- Here Technologies' `meta-updater` Layer: - - - URI: https://github.com/advancedtelematic/meta-updater/ - - Branch: "thud" - -- Here Technologies' `meta-updater-qemux86-64` Layer: - - - URI: https://github.com/advancedtelematic/meta-updater-qemux86-64/ - - Branch: "thud" - -- OpenEmbedded's `meta-openembedded` Layer: - - - URI: https://github.com/openembedded/meta-openembedded - - Branch: "thud" - - Tested Revision: See the - [`default.xml`](https://github.com/leon-anavi/AGL-repo/blob/master/default.xml) - manifest file for the `AGL-repo` repository for revision information. - - Specifically, out of `meta-openembedded`, these sub-layers are used: - - - `meta-filesystems` - - `meta-oe` - - `meta-python` - -**The `agl-netboot` Feature:** - -- AGL's `meta-netboot` Layer within the `meta-agl` Layer: - - - URI: https://gerrit.automotivelinux.org/gerrit/gitweb?p=AGL/meta-agl.git - - Branch: "master" - - -## Packagegroups - -AGL DEMO Platform's [packagegroups](https://www.yoctoproject.org/docs/3.1.4/dev-manual/dev-manual.html#usingpoky-extend-customimage-customtasks) -consist of the following: - -- packagegroup-agl-demo-platform - - This packagegroup is used for generating the `agl-demo-platform` image, - which is the full image for the AGL distributions IVI profile. You can see the - recipe (i.e. `agl-demo-platform.bb`) that installs the - `packagegroup-agl-demo-platform` packagegroup [here](https://git.automotivelinux.org/AGL/meta-agl-demo/tree/recipes-platform/images/agl-demo-platform.bb). - - As meta-agl's design of packagegroups, the `agl-demo-platform.bb` recipe installs - only `packagegroup-agl-demo-platform` and the packages of the DEMO applications. - - ``agl-demo-platform`` contains the following three packagegroups: - - * `packagegroup-agl-image-minimal` - * `packagegroup-agl-image-ivi` - * `packagegroup-agl-demo-platform` - -- packagegroup-agl-appfw* - - These packagegroups contain packages for the AGL distribution's - Application Framework. Subsystem should maintain - `packagegroup-agl-appfw-[subsystem].bb`, which should hold sufficient packages - for the Application Framework. - - Subsystems also can maintain their own packagegroups using appropriate - `recipes-*/`. - - For example, Qt5 has two packagegroups in `meta-agl-demo`: - `packagegroup-agl-appfw-native-qt5` and `packagegroup-agl-demo-qt-examples`, - which are under `recipes-qt/`. - - The `packagegroup-agl-appfw-native-qt5` is included by `packagegroup-agl-appfw-native` because Qt5 belongs to native application framework of AGL Distro. - - Because the `packagegroup-agl-demo-qt-examples` is not mandatory for the AGL - Application Framework and the AGL DEMO, the packagegroup is added to the layer's - `local.conf` file only when needed. \ No newline at end of file diff --git a/docs/3_Developer_Guides/6_AGL_Layers/4_meta-agl-devel.md b/docs/3_Developer_Guides/6_AGL_Layers/4_meta-agl-devel.md deleted file mode 100644 index 8932b82..0000000 --- a/docs/3_Developer_Guides/6_AGL_Layers/4_meta-agl-devel.md +++ /dev/null @@ -1,143 +0,0 @@ ---- -title: meta-agl-devel ---- - -## Introduction - -The `meta-agl-devel` layer contains components that are being tested or -still in development. -The layer also contains software packages that Original Equipment -Manufacturers (OEMs) need but are not included in the AGL software. - -## Sub-Layers - -The `meta-agl-devel` layer contains the following files and sub-layers: - -``` -. -├── meta-agl-telemetry -├── meta-audio-4a-framework -├── meta-audio-soundmanager-framework -├── meta-egvirt -├── meta-gstrecorder-rcar-gen3 -├── meta-hmi-framework -├── meta-oem-extra-libs -├── README.md -├── templates -``` - -The following list provides a summary of these sub-layers: - -* `meta-agl-telemetry`: Provides the smallest AGL image. - The image is designed to be used when a device requires restricted - scope of responsibilites (e.g. collecting vehicle telemetry). - -* `meta-audio-4a-framework`: A collection of recipes used for the - first integration of 4A (i.e. Advanced AGL Audio Architecture). - -* `meta-pipewire`: A collection of recipes used for the integration - of the pipewire sound system. - -* `meta-audio-soundmanager-framework`: Supports the Soundmanager - Audio Framework features, which maps to the `agl-audio-soundmanager-framework` - AGL feature. - -* `meta-egvirt`: The AGL Virtualization Expert Group (EG-VIRT) layer. - This layer supports the design, test, implementation, and assessment - of virtualization technologies (e.g. containers, hypervisors, system - partitioners, and so forth) aimed at AGL ARMv8 and Intel platforms. - -* `meta-gstrecorder-rcar-gen3`: Supports streaming audio and video for - the Pro and Premier board kits (e.g. - [Renesas R-Car Starter Kit Pro Board](https://www.elinux.org/R-Car/Boards/M3SK) - and - [Renesas R-Car Starter Kit Premier Board](https://www.elinux.org/R-Car/Boards/H3SK)). - -* `meta-hmi-framework`: Provides AGL's Human Machine Interface (HMI) framework - through resource management consisting of sounds, windows, and input control. - For more information, see the - [HMI-Framework Page](https://wiki.automotivelinux.org/hmiframework) of the - AGL Wiki. - -* `meta-oem-extra-libs`: Provides libraries and software packages needed by - OEMs but not provided by the AGL software. - -* `templates`: Feature templates that support the `meta-agl-devel` layer. - -## Additional Sub-Layer Information - -This section provides additional information for the `meta-egvirt`, -`meta-oem-extra-libs`, and `meta-hmi-framework` layers. - -### Virtualization Support - -The `meta-egvirt` layer enables virtualization support in AGL. -The AGL Virtualization Expert (EG-VIRT) group is responsible -for design and implementation of AGL virtualization solutions -(.e.g the Virtualization platform architecture of AGL). -You can read about EG-VERT's efforts on the -"[Virtualization Expert Group's](https://wiki.automotivelinux.org/eg-virt)" -page of the AGL wiki. - -Additionally, you can learn more about virtualization as it applies to AGL -by reading -"[The Automotive Grade Linux Software Defined Connected Car Architecture](https://www.automotivelinux.org/wp-content/uploads/sites/4/2018/06/agl_software_defined_car_jun18.pdf)" -whitepaper. - -### OEM Extra Libraries - -The `meta-oem-extra-libs` layer provides additional software packages many OEMs need -but are not part of the AGL source. -Following is the list of packages this layer provides: - - * boost - * fixesproto - * imagemagick - * iptables - * Xorg-macros - * zlib - * eglibc = glibc - * libcurl - * libgif - * libneon - * mongoose - * fuse - * protocol buffers - * bsdiff - * module-init-tools - * libcroco - * libtiff - * librsvg - * libpcap - -To add these packages to your library, you need to include the -`agl-oem-extra-libs` AGL feature when you initialize your build -environment using the `aglsetup.sh` script. - -For information on how to use the `aglsetup.sh` script to initialize -your build environment, see the -"[Initializing Your Build Environment](../../0_Getting_Started/2_Building_AGL_Image/3_Initializing_Your_Build_Environment.md)" -section. - -Once you have included the AGL feature, you can build your image. - -### HMI Framework - -The `meta-hmi-framework` layer supports the Human-Machine Interface (HMI) Framework. -The HMI-Framework is the User Interface (UI) to control the Infotainment System. -Work continues to close the gap between the user experience of a smart phone -and the Infotainment System in a vehicle, for example. - -You can find more out about HMI Framework progress on the -"[HMI Framework](https://wiki.automotivelinux.org/hmiframework)" page on the AGL Wiki. - -To add HMI Framework support to your image, you need to include the -`hmi-framework` AGL feature when you initialize your build -environment using the `aglsetup.sh` script. - -For information on how to use the `aglsetup.sh` script to initialize -your build environment, see the -"[Initializing Your Build Environment](../../0_Getting_Started/2_Building_AGL_Image/3_Initializing_Your_Build_Environment.md)" -section. - -Once you have included the AGL feature, you can build your image. \ No newline at end of file diff --git a/docs/3_Developer_Guides/images/AGL_add_recipe.png b/docs/3_Developer_Guides/images/AGL_add_recipe.png deleted file mode 100644 index 07b44b6..0000000 Binary files a/docs/3_Developer_Guides/images/AGL_add_recipe.png and /dev/null differ diff --git a/docs/4_APIs_and_Services/FIXME.md b/docs/4_APIs_and_Services/FIXME.md deleted file mode 100644 index e69de29..0000000 diff --git a/docs/4_Developer_Guides/1_Application_Framework/1_Introduction.md b/docs/4_Developer_Guides/1_Application_Framework/1_Introduction.md new file mode 100644 index 0000000..957858a --- /dev/null +++ b/docs/4_Developer_Guides/1_Application_Framework/1_Introduction.md @@ -0,0 +1,150 @@ +--- +title: Introduction +--- + +# Foreword + +The AGL Application Framework is nothing new. However, the implementation used up until +the `lamprey` release has been retired starting with the `marlin` release and replaced +by a redesigned Application Framework one. However, this new implementation isn't a 1:1 +replacement, and as such it doesn't provide all of the features of the previous +Application Framework. Some of those will be added back over time, others have been +discarded in favor of more modern and/or widely-used alternatives. + +# Introduction + +As a provider of an integrated solution to build up on, AGL needs to define a reliable +and well-specified method for managing the deployment and integration of applications +and services, as well as the way they can interact with the rest of the system. + +This is achieved by providing a common set of rules and components, known as the +Application Framework. By ensuring conformity to those rules, application developers +can have a good understanding of the requirements for creating and packaging +applications targeting AGL-based systems. Likewise, system developers and integrators +have a clear path for including such applications in AGL-based products. + +The Application Framework's scope extends to the following areas: +- system services integration and lifecycle management +- user session management, including user-level applications and services lifecycle + management +- inter-process communication + +In order to be as simple as possible and avoid any unneded custom implementation, the +Application Framework relies mainly on third-party technologies and/or software +components, most of those being maintained under the +[freedesktop.org](https://www.freedesktop.org) umbrella. Those include: + + +- [systemd](https://www.freedesktop.org/wiki/Software/systemd/): system services and user session services management + + +- [D-Bus](https://www.freedesktop.org/wiki/Software/dbus/): inter-process communication + + +- [Desktop Entry specification](https://www.freedesktop.org/wiki/Specifications/desktop-entry-spec/): + application enumeration and startup + +AGL also provides reference implementations whenever possible and relevant, located in +the [meta-agl](/3_Developer_Guides/6_AGL_Layers/2_meta-agl/) layer under `meta-app-framework`. At the +moment, the Application Framework contains 2 such components: + +- `agl-session`: `systemd` unit files for user sessions management + +- `applaunchd`: application launcher service + +# Services management + +Both system and user services are managed by `systemd`, which provides a number of +important features, such as dependency management or service monitoring: when starting +a service, `systemd` will ensure any other units this service depends on are available, +and otherwise start those dependencies. Similarly, `systemd` can automatically restart +a crashed service, ensuring minimal downtime. + +`systemd` also provides an efficient first layer of security through its +[sandboxing](https://www.freedesktop.org/software/systemd/man/systemd.exec.html#Sandboxing) +and other security-related options. + +It is also well integrated with D-Bus and can be used for a more fine-grained control +over D-Bus activated services: by delegating the actual service startup to `systemd`, +developers can take advantage of some of its advanced features, allowing for improved +reliability and security. + +Each service should be represented by a `systemd` unit file installed to the appropriate +location. More details can be obtained from the [Creating a New Service](/3_Developer_Guides/2_Creating_a_New_Service/) +document. + +# User session management + +Similarly, user sessions and the services they rely on are also managed by `systemd`. + +AGL provides 2 `systemd` units: + + +1\. `agl-session@.service` is a template system service for managing user sessions; it +takes a username or UID as a parameter, creating a session for the desired user. +Instanciating this service can be achieved by enabling `agl-session@USER.service`, for +example by executing the following command on a running system: + +``` +$ systemctl enable agl-session@USER.service +``` + +By default, AGL enables this service as `agl-session@agl-driver.service`, running as +user `agl-driver`. + +*Note: while you can create sessions for as many users as needed, only one instance of +`agl-session@.service` is allowed per user.* + + +2\. `agl-session.target` is a user target for managing user services and their +dependencies. It is started by `agl-session@.service`. + +By default, `agl-compositor` is part of this target. It is therefore automatically +started for user `agl-driver`. + +Any other service needed as part of the user session should similarly depend on this +target by appending the following lines to their unit file: + +``` +[Install] +WantedBy=agl-session.target +``` + +# Inter-process communication + +In order to provide a "standard", language-independent IPC mechanism and avoid the need +for maintaining custom bindings for each programming language to be used on top of AGL, +the Application Framework promotes the use of [D-Bus](https://www.freedesktop.org/wiki/Software/dbus/) +as the preferred way for applications to interact with services. + +Most services already included in AGL provide one or several D-Bus interfaces, and can +therefore interact with D-Bus capable applications and services without requiring any +additional component. Those services include, among others: + +- [ConnMan](https://git.kernel.org/pub/scm/network/connman/connman.git/): network connectivity + +- [BlueZ](http://www.bluez.org/): Bluetooth connectivity + +- [oFono](https://git.kernel.org/pub/scm/network/ofono/ofono.git): telephony and modem + management + +- [GeoClue](https://gitlab.freedesktop.org/geoclue/geoclue/-/wikis/home): geolocation + +# Application launcher service + +As mentioned above, the Application Framework follows the guidelines of the +[Desktop Entry specification](https://www.freedesktop.org/wiki/Specifications/desktop-entry-spec/) +for application enumeration and startup. + +As no simple reference implementation exists for this part of the specification, AGL +provides an application launcher service named `applaunchd`. This service is part of the +default user session, and as such is automatically started on session startup. It can +therefore be considered always available. + +`applaunchd` enumerates applications installed on the system and provides a D-bus +interface for services and applications to: +- query the list of available applications +- request the startup and/or activation of a specific application +- be notified when applications are started or terminated + +`applaunchd` is described with more details in [the following document](../2_Application_Startup/). diff --git a/docs/4_Developer_Guides/1_Application_Framework/2_Application_Startup.md b/docs/4_Developer_Guides/1_Application_Framework/2_Application_Startup.md new file mode 100644 index 0000000..4841ce5 --- /dev/null +++ b/docs/4_Developer_Guides/1_Application_Framework/2_Application_Startup.md @@ -0,0 +1,184 @@ +--- +title: Application Startup +--- + +# Introduction + +At system runtime, it may be necessary for applications to start other applications +on demand. Such actions can be executed in reaction to a user request, or they may +be needed to perform a specific task. + +In order to do so, running applications and services need an established way of +discovering installed applications and executing those. The +[Desktop Entry specification](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html) +defines how applications can be discovered by using `.desktop` files, but there's no +simple reference implementation for this function. + +In order to provide a language-independent interface for applications and service to +use, AGL includes `applaunchd`, a user service part of the default session. + +*Note: as mentioned [previously](1_Introduction/), services are managed using `systemd` +and are therefore not in the scope of this document.* + +# Application launcher service + +The purpose of `applaunchd` is to enumerate applications available on the system and +provide a way for other applications to query this list and start those on demand. +It is also able to notify clients of the startup and termination of applications it +manages. + +To that effect, `applaunchd` provides a D-Bus interface other applications can use +in order to execute those actions. + +*Note: `applaunchd` will only send notifications for applications it started; it isn't +aware of applications started by other means (`systemd`, direct executable call...), +and therefore can't send notifications for those.* + +## Application discovery + +On startup, `applaunchd` inspects all `.desktop` files present under the `applications/` +subfolder of any element of the `XDG_DATA_DIRS` environment variable, ignoring all entries +containing either the `NoDisplay=true` or `Hidden=true` lines. + +It then looks for the following keys: +- `Terminal` +- `DBusActivatable` + +If the desktop entry file contains the `Terminal` key set to `true`, then the application +is marked as a non-graphical one. As such, it won't be included in the applications list +if the client requests only graphical applications. + +If `DBusActivatable` is set to `true`, then the application is marked as D-Bus activated. +Additionally, `applaunchd` will search for a corresponding D-Bus service file in case this +line is missing. This is a workaround allowing D-Bus activated applications providing +an incomplete desktop entry file (i.e missing the `DBusActivatable` key) to be +identified as such. + +### Requirements for D-Bus activation + +`applaunchd` will always start D-Bus activatable applications using D-Bus activation +instead of executing the command line stated in the desktop entry file. + +This is handled by calling the `Activate` method of the +[org.freedesktop.Application](https://specifications.freedesktop.org/desktop-entry-spec/1.1/ar01s07.html) +interface with an empty argument. + +As a consequence, all D-Bus activatable applications **must** implement this D-Bus +interface. + +## Application identifiers + +Each application is identified by a unique Application ID. Although this ID can be +any valid string, it is highly recommended to use the "reverse DNS" convention in order +to avoid potential name collisions and ease D-Bus integration. + +The application ID is set in the desktop entry file itself for +[graphical applications](../3_Creating_a_New_Application/#graphical-applications): +it is the value of the `StartupWMClass` field, which must be identical to the `app-id` +advertised through the Wayland XDG toplevel protocol. In case this field is missing +(as is usually the case for non-graphical application), the application ID will be the +desktop entry file name, stripped from its `.desktop` extension. + +## D-Bus interface + +The `applaunchd` D-Bus interface is named `org.automotivelinux.AppLaunch`. The object +path for `applaunchd` is `/org/automotivelinux/AppLaunch`. The interface provides methods +for the following actions: +- retrieve the list of available applications; the client can choose to retrieve all + available applications, or only those suitable for a graphical environment +- request an application to be started + +Moreover, signals are available for clients to be notified when an application has +successfully started or its execution terminated. + +### Applications list + +The `listApplications` method allows clients to retrieve the list of available applications. +It takes one boolean argument named `graphical`: +- if set to `true`, only applications suitable for graphical environments are returned +- otherwise, the list contains all applications + +This method returns an array of variants (type `av`), each element being a structure made up +of 3 strings (type `(sss)`): +- the application ID +- the application's displayed name +- the full path to the application icon file (or an empty string if no icon was specified in + the application's desktop entry file) + +### Application startup request + +Applications can be started by using the `start` method, passing the corresponding application +ID as the only argument. This method doesn't return any data. + +If the application is already running, `applaunchd` won't start another instance, but instead +emit a `started` signal to notify clients the application is ready. + +### Status notifications + +The `org.automotivelinux.AppLaunch` interface provides 2 signals clients can connect to: +- `started` indicates an application has started + - for D-Bus activated applications, it is emitted upon successful completion of the + call to the `Activate` method of the `org.freedesktop.Application` interface + - for other applications, this signal is emitted as soon as the child process has been + successfully created +- `terminated` is emitted when an application quits + +Both signals have an additional argument named `appid`, containing the ID of the application +affected by the event. + +As mentioned above, the `started` signal is also emitted if `applaunchd` receives a request to +start an already running application. This can be useful, for example, when switching between +graphical applications: +- the application switcher doesn't need to track the state of each application; instead, it can + simply send a `start` request to `applaunchd` every time the user requests to switch to another + application +- the desktop environment then receives the `started` signal, indicating it should activate the + window with the corresponding `app-id` + +## Testing + +`applaunchd` can be manually tested using the `gdbus` command-line tool: + +1. Query the application list (graphical applications only): + +``` +$ gdbus call --session --dest "org.automotivelinux.AppLaunch" \ + --object-path "/org/automotivelinux/AppLaunch" \ + --method "org.automotivelinux.AppLaunch.listApplications" \ + true +``` + +This command will output something similar to what follows: + +``` +([<('navigation', 'Navigation', '/usr/share/icons/hicolor/scalable/navigation.svg')>, + <('settings', 'Settings', '/usr/share/icons/hicolor/scalable/settings.svg')>, + <('dashboard', 'Dashboard', '/usr/share/icons/hicolor/scalable/dashboard.svg')>, + <('hvac', 'HVAC', '/usr/share/icons/hicolor/scalable/hvac.svg')>, + <('org.freedesktop.weston.wayland-terminal', 'Weston Terminal', '/usr/share/icons/Adwaita/scalable/apps/utilities-terminal-symbolic.svg')>],) +``` + +2. Request startup of the `org.freedesktop.weston.wayland-terminal` application: + +``` +$ gdbus call --session --dest "org.automotivelinux.AppLaunch" \ + --object-path "/org/automotivelinux/AppLaunch" \ + --method "org.automotivelinux.AppLaunch.start" \ + "org.freedesktop.weston.wayland-terminal" +``` + +3. Monitor signals emitted by `applaunchd`: + +``` +$ gdbus monitor --session --dest "org.automotivelinux.AppLaunch" +``` + +This results in the following output when starting, then exiting, the +`org.freedesktop.weston.wayland-terminal` application: + +``` +Monitoring signals from all objects owned by org.automotivelinux.AppLaunch +The name org.automotivelinux.AppLaunch is owned by :1.4 +/org/automotivelinux/AppLaunch: org.automotivelinux.AppLaunch.started ('org.freedesktop.weston.wayland-terminal',) +/org/automotivelinux/AppLaunch: org.automotivelinux.AppLaunch.terminated ('org.freedesktop.weston.wayland-terminal',) +``` diff --git a/docs/4_Developer_Guides/1_Setting_Up_AGL_SDK.md b/docs/4_Developer_Guides/1_Setting_Up_AGL_SDK.md new file mode 100644 index 0000000..d3f01fb --- /dev/null +++ b/docs/4_Developer_Guides/1_Setting_Up_AGL_SDK.md @@ -0,0 +1,70 @@ +--- +title: Setting Up AGL SDK +--- + +AGL provides a pre-built ready-made Software Development Kit (SDK) to help +quickstart the service and application development process. + +1. Download the prebuilt SDK : + + Please open the link below and download .sh file for desired machine. + + **Note:** The links provided are for the master branch. If you want SDK for specific branch than change the name from master to specific branch. + + - **x86** : [qemux86-64](https://download.automotivelinux.org/AGL/snapshots/master/latest/qemux86-64/deploy/sdk/) + + **Note:** .sh file will be with name "poky-agl-glibc-x86_64-agl-demo-platform-crosssdk-corei7-64-qemux86-64-toolchain-$(version number).sh" where version number is regularly updated on the site. + + + - **ARM 32 bit** : [qemuarm](https://download.automotivelinux.org/AGL/snapshots/master/latest/qemuarm/deploy/sdk/) + + **Note:** .sh file will be with name " poky-agl-glibc-x86_64-agl-demo-platform-crosssdk-armv7vet2hf-neon-vfpv4-qemuarm-toolchain-$(version number).sh" where version number is regularly updated on the site. + + + - **AARCH64 - ARM 64bit** : [qemuarm64](https://download.automotivelinux.org/AGL/snapshots/master/latest/qemuarm64/deploy/sdk/) + + **Note:** .sh file will be with name " poky-agl-glibc-x86_64-agl-demo-platform-crosssdk-aarch64-qemuarm64-toolchain-$(version number).sh" where version number is regularly updated on the site. + + + *Henceforth,* **qemux86-64** *is used in these guides, unless specified + otherwise. We also use the 'agl-demo-platform-crosssdk' as example.* + +2. Create application development directory and copy SDK into them : + + **Note:** In the copy command below change the file name with name of your downloaded .sh file. In the example below file name is based on x86 + + ```sh + $ mkdir ~/agl-app + $ cp ~/Downloads/poky-agl-glibc-x86_64-agl-demo-platform-crosssdk-*.sh ~/agl-app/ + $ cd ~/agl-app + ``` + +3. Install the downloaded SDK : + + **Note:** In commands below again change the file name based on your downloaded .sh file + + + ```sh + $ chmod 777 poky-agl-glibc-x86_64-agl-demo-platform-crosssdk-*.sh + $ mkdir agl-sdk/ + $ ./poky-agl-glibc-x86_64-agl-demo-platform-crosssdk-*.sh + ``` + Select target directory for SDK : `~/agl-app/agl-sdk` + + ```sh + Automotive Grade Linux SDK installer version 14.0.0 + ============================================================= + Enter target directory for SDK (default: /opt/agl-sdk/10.90.0+snapshot-corei7-64): ~/agl-app/agl-sdk + You are about to install the SDK to "/home/boron/agl-app/agl-sdk". Proceed [Y/n]? Y + Extracting SDK..........................................................................................................................................done + Setting it up...done + SDK has been successfully set up and is ready to be used. + Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g. + $ . /home/boron/agl-app/agl-sdk/environment-setup-corei7-64-agl-linux + ``` + +4. Source the SDK environment setup, each time you wish to use the SDK in a new shell session : + + ```sh + $ source ~/agl-app/agl-sdk/environment-setup-corei7-64-agl-linux + ``` diff --git a/docs/4_Developer_Guides/2_AGL_Layers/1_Overview.md b/docs/4_Developer_Guides/2_AGL_Layers/1_Overview.md new file mode 100644 index 0000000..dec8054 --- /dev/null +++ b/docs/4_Developer_Guides/2_AGL_Layers/1_Overview.md @@ -0,0 +1,25 @@ +--- +title: Overview +--- + +The [AGL Project](https://www.automotivelinux.org/) is an automotive-specific +development environment that provides a Linux distribution +([AGL UCB](https://www.automotivelinux.org/software/unified-code-base)). + +AGL uses layers designed to be compatible with the +[Yocto Project](https://www.yoctoproject.org) and the +[OpenEmbedded Project (OE)](https://www.openembedded.org/wiki/Main_Page). + +This section provides information about the layers used by the AGL Project: + +* **`meta-agl`**: Minimal set of software needed to create an AGL distribution + used to boot a system. + AGL profiles are built on top of this minimal set of software. + +* **`meta-agl-demo`**: Provides a reference or demo platform and applications + for the AGL Distribution. + The reference UI is part of the `meta-agl-demo` layer. + +* **`meta-agl-devel`**: Contains components under development or being tested. + This layer also contains software packages that OEMs need but do not exist + in AGL. diff --git a/docs/4_Developer_Guides/2_AGL_Layers/2_meta-agl.md b/docs/4_Developer_Guides/2_AGL_Layers/2_meta-agl.md new file mode 100644 index 0000000..1ac45a6 --- /dev/null +++ b/docs/4_Developer_Guides/2_AGL_Layers/2_meta-agl.md @@ -0,0 +1,124 @@ +--- +title: meta-agl +--- + +## Introduction + +The `meta-agl` layer provides the minimal set of software +to boot an AGL Distribution system. +You use this layer as the minimal core on which to build AGL profiles. + +**NOTE:** The `meta-agl` layer does not include a reference UI. + The reference UI is included as part of the + [`meta-agl-demo`](3_meta-agl-demo.md) layer. + Furthermore, `meta-agl` does not include additional components, such + as security, which are part of the + `meta-agl-extra` layer. + +## Sub-Layers + +The `meta-agl` layer itself contains many sub-layers and files. +Following is a "tree" look at the layer: + +``` +. +├── docs +├── meta-agl +├── meta-agl-bsp +├── meta-agl-distro +├── meta-agl-profile-cluster +├── meta-agl-profile-cluster-qt5 +├── meta-agl-profile-core +├── meta-agl-profile-graphical +├── meta-agl-profile-graphical-html5 +├── meta-agl-profile-graphical-qt5 +├── meta-agl-profile-hud +├── meta-agl-profile-telematics +├── meta-app-framework +├── meta-netboot +├── meta-security +├── README-AGL.md +├── README.md +├── scripts +├── templates +``` + +This list provides some overview information on the files and sub-layers +in `meta-agl`: + +* `docs`: Contains files that support AGL documentation. +* `meta-agl`: Contains layer configuration for the `meta-agl` layer. +* `meta-agl-bsp`: Contains adaptations for recipes and required packages + to boot an AGL distribution on targeted hardware and emulation (i.e. QEMU). +* `meta-agl-distro`: Contains distro configuration and supporting scripts. +* `meta-agl-profile-cluster`: The middleware for the AGL cluster profile. + The set of packages required for AGL Cluster Distribution. + Profiles include support for Wayland images. +* `meta-agl-profile-cluster-qt5`: The middleware for the AGL Qt5-based cluster profile. + The set of packages required for AGL Qt5-based Cluster Distribution. + Profiles include support for Wayland images with Qt5. +* `meta-agl-profile-core`: Configuration and recipes for the AGL core profiles. +* `meta-agl-profile-graphical`: Configuration and recipes supporting graphical user + interfaces. +* `meta-agl-profile-graphical-html5`: Configuration and recipes supporting profiles + with HTML user interface support. +* `meta-agl-profile-graphical-qt5`: Configuration and recipes supporting profiles + with Qt5-based user interface support. +* `meta-agl-profile-hud`: Configuration and recipes supporting profiles with + Head-Up-Display (HUD) support. +* `meta-agl-profile-telematics`: Configuration and recipes supporting profiles with + telematics support. +* `meta-app-framework`: Configuration and recipes supporting the AGL Application + Framework. +* `meta-netboot`: Contains recipes and configuration adjustments to allow network + boot through network block device (NBD) since network file system (NFS) does not + support security labels. +* `meta-security`: Configuration and recipes supporting security applications. +* `scripts`: AGL development setup and support scripts. +* `templates`: Base, feature, and machine templates used in the AGL development + environment. + +## Packagegroups + +This section describes the AGL +[packagegroup](https://yoctoproject.org/docs/3.1.4/dev-manual/dev-manual.html#usingpoky-extend-customimage-customtasks) +design: + +* packagegroup-agl-image-minimal + + packagegroup-agl-core-automotive.bb + packagegroup-agl-core-connectivity.bb + packagegroup-agl-core-graphics.bb + packagegroup-agl-core-kernel.bb + packagegroup-agl-core-multimedia.bb + packagegroup-agl-core-navi-lbs.bb + packagegroup-agl-core-os-commonlibs.bb + packagegroup-agl-core-security.bb + packagegroup-agl-core-speech-services.bb + + The previous list of Packagegroups are used to create the `agl-image-minimal` image, + which is a small image just capable of allowing a device to boot. + + Subsystem should maintain packagegroup-agl-core-[subsystem].bb which should + hold sufficient packages to build `agl-image-minimal`. + +* packagegroup-agl-image-ivi + + packagegroup-agl-ivi-automotive.bb + packagegroup-agl-ivi-connectivity.bb + packagegroup-agl-ivi-graphics.bb + packagegroup-agl-ivi-kernel.bb + packagegroup-agl-ivi-multimedia.bb + packagegroup-agl-ivi-navi-lbs.bb + packagegroup-agl-ivi-os-commonlibs.bb + packagegroup-agl-ivi-security.bb + packagegroup-agl-ivi-speech-services.bb + + The previous list of Packagegroups are used to create the `agl-image-ivi` + image, which is a baseline image (i.e. Service Layer and Operating System + Layer defined in AGL Spec v1.0) for the AGL profiles. + +* packagegroup-agl-test.bb + + Additional tools used in QA tests (for agl-image*-qa). + diff --git a/docs/4_Developer_Guides/2_AGL_Layers/3_meta-agl-demo.md b/docs/4_Developer_Guides/2_AGL_Layers/3_meta-agl-demo.md new file mode 100644 index 0000000..c560989 --- /dev/null +++ b/docs/4_Developer_Guides/2_AGL_Layers/3_meta-agl-demo.md @@ -0,0 +1,159 @@ +--- +title: meta-agl-demo +--- + +## Introduction + +The `meta-agl-demo` layer is the reference user interface layer for the DEMO +platform of Automotive Grade Linux (AGL). +The layer provides a reference platform and applications. +The BitBake target name for the DEMO platform is `agl-demo-platform`, which is +the full DEMO platform image. + +## Layer Dependencies + +This section describes dependencies for the `meta-agl-demo` layer. +Dependencies are grouped into base, hardware, and feature dependencies. + +### Base Dependencies + +The `meta-agl-demo` layer has the following base dependencies: + +- Yocto Project Release: + + - URI: git://git.yoctoproject.org/poky + - Branch: "thud" + - Tested Revision: See the + [`default.xml`](https://github.com/leon-anavi/AGL-repo/blob/master/default.xml) + manifest file for the `AGL-repo` repository for revision information. + +- AGL `meta-agl` Layer: + + - URI: https://gerrit.automotivelinux.org/gerrit/AGL/meta-agl + - Branch: "master" + +- OpenEmbedded `meta-openembedded` Layer: + + - Branch: "thud" + - Tested Revision: See the + [`default.xml`](https://github.com/leon-anavi/AGL-repo/blob/master/default.xml) + manifest file for the `AGL-repo` repository for revision information. + + Specifically, out of `meta-openembedded`, these sub-layers are used: + + - `meta-oe` + - `meta-multimedia` + - `meta-networking` + - `meta-python` + +- Yocto Project `meta-qt5` Layer from the + [OpenEmbedded Layer Index](https://layers.openembedded.org/layerindex/branch/master/layers/): + + - URI: https://github.com/meta-qt5/meta-qt5.git + - Branch: "thud" + - Tested Revision: See the + [`default.xml`](https://github.com/leon-anavi/AGL-repo/blob/master/default.xml) + manifest file for the `AGL-repo` repository for revision information. + +### Hardware Dependencies + +Aside from the previously listed base dependencies, if you are using a +[supported Renesas board](../../0_Getting_Started/2_Building_AGL_Image/5_3_RCar_Gen_3.md) +supported Renesas board, these dependencies exist: + +- AGL's `meta-renesas` Layer: + + - URI: https://gerrit.automotivelinux.org/gerrit/AGL/meta-renesas + +### Feature Dependencies + +The `meta-agl-demo` layer has the following AGL [feature](../../0_Getting_Started/2_Building_AGL_Image/3_Initializing_Your_Build_Environment.md#agl-features) +dependencies: + +- Yocto Project `meta-security` Layer: + + - URI: https://git.yoctoproject.org/cgit/cgit.cgi/meta-security + - Branch: "master" + - Tested Revision: See the + [`default.xml`](https://github.com/leon-anavi/AGL-repo/blob/master/default.xml) + manifest file for the `AGL-repo` repository for revision information. + +- AGL's `meta-app-framework` Layer within the `meta-agl` Layer: + + - URI: https://gerrit.automotivelinux.org/gerrit/gitweb?p=AGL/meta-agl.git + - Branch: "master" + +**The `agl-sota` Feature:** + +- Here Technologies' `meta-updater` Layer: + + - URI: https://github.com/advancedtelematic/meta-updater/ + - Branch: "thud" + +- Here Technologies' `meta-updater-qemux86-64` Layer: + + - URI: https://github.com/advancedtelematic/meta-updater-qemux86-64/ + - Branch: "thud" + +- OpenEmbedded's `meta-openembedded` Layer: + + - URI: https://github.com/openembedded/meta-openembedded + - Branch: "thud" + - Tested Revision: See the + [`default.xml`](https://github.com/leon-anavi/AGL-repo/blob/master/default.xml) + manifest file for the `AGL-repo` repository for revision information. + + Specifically, out of `meta-openembedded`, these sub-layers are used: + + - `meta-filesystems` + - `meta-oe` + - `meta-python` + +**The `agl-netboot` Feature:** + +- AGL's `meta-netboot` Layer within the `meta-agl` Layer: + + - URI: https://gerrit.automotivelinux.org/gerrit/gitweb?p=AGL/meta-agl.git + - Branch: "master" + + +## Packagegroups + +AGL DEMO Platform's [packagegroups](https://www.yoctoproject.org/docs/3.1.4/dev-manual/dev-manual.html#usingpoky-extend-customimage-customtasks) +consist of the following: + +- packagegroup-agl-demo-platform + + This packagegroup is used for generating the `agl-demo-platform` image, + which is the full image for the AGL distributions IVI profile. You can see the + recipe (i.e. `agl-demo-platform.bb`) that installs the + `packagegroup-agl-demo-platform` packagegroup [here](https://git.automotivelinux.org/AGL/meta-agl-demo/tree/recipes-platform/images/agl-demo-platform.bb). + + As meta-agl's design of packagegroups, the `agl-demo-platform.bb` recipe installs + only `packagegroup-agl-demo-platform` and the packages of the DEMO applications. + + ``agl-demo-platform`` contains the following three packagegroups: + + * `packagegroup-agl-image-minimal` + * `packagegroup-agl-image-ivi` + * `packagegroup-agl-demo-platform` + +- packagegroup-agl-appfw* + + These packagegroups contain packages for the AGL distribution's + Application Framework. Subsystem should maintain + `packagegroup-agl-appfw-[subsystem].bb`, which should hold sufficient packages + for the Application Framework. + + Subsystems also can maintain their own packagegroups using appropriate + `recipes-*/`. + + For example, Qt5 has two packagegroups in `meta-agl-demo`: + `packagegroup-agl-appfw-native-qt5` and `packagegroup-agl-demo-qt-examples`, + which are under `recipes-qt/`. + + The `packagegroup-agl-appfw-native-qt5` is included by `packagegroup-agl-appfw-native` because Qt5 belongs to native application framework of AGL Distro. + + Because the `packagegroup-agl-demo-qt-examples` is not mandatory for the AGL + Application Framework and the AGL DEMO, the packagegroup is added to the layer's + `local.conf` file only when needed. \ No newline at end of file diff --git a/docs/4_Developer_Guides/2_AGL_Layers/4_meta-agl-devel.md b/docs/4_Developer_Guides/2_AGL_Layers/4_meta-agl-devel.md new file mode 100644 index 0000000..8932b82 --- /dev/null +++ b/docs/4_Developer_Guides/2_AGL_Layers/4_meta-agl-devel.md @@ -0,0 +1,143 @@ +--- +title: meta-agl-devel +--- + +## Introduction + +The `meta-agl-devel` layer contains components that are being tested or +still in development. +The layer also contains software packages that Original Equipment +Manufacturers (OEMs) need but are not included in the AGL software. + +## Sub-Layers + +The `meta-agl-devel` layer contains the following files and sub-layers: + +``` +. +├── meta-agl-telemetry +├── meta-audio-4a-framework +├── meta-audio-soundmanager-framework +├── meta-egvirt +├── meta-gstrecorder-rcar-gen3 +├── meta-hmi-framework +├── meta-oem-extra-libs +├── README.md +├── templates +``` + +The following list provides a summary of these sub-layers: + +* `meta-agl-telemetry`: Provides the smallest AGL image. + The image is designed to be used when a device requires restricted + scope of responsibilites (e.g. collecting vehicle telemetry). + +* `meta-audio-4a-framework`: A collection of recipes used for the + first integration of 4A (i.e. Advanced AGL Audio Architecture). + +* `meta-pipewire`: A collection of recipes used for the integration + of the pipewire sound system. + +* `meta-audio-soundmanager-framework`: Supports the Soundmanager + Audio Framework features, which maps to the `agl-audio-soundmanager-framework` + AGL feature. + +* `meta-egvirt`: The AGL Virtualization Expert Group (EG-VIRT) layer. + This layer supports the design, test, implementation, and assessment + of virtualization technologies (e.g. containers, hypervisors, system + partitioners, and so forth) aimed at AGL ARMv8 and Intel platforms. + +* `meta-gstrecorder-rcar-gen3`: Supports streaming audio and video for + the Pro and Premier board kits (e.g. + [Renesas R-Car Starter Kit Pro Board](https://www.elinux.org/R-Car/Boards/M3SK) + and + [Renesas R-Car Starter Kit Premier Board](https://www.elinux.org/R-Car/Boards/H3SK)). + +* `meta-hmi-framework`: Provides AGL's Human Machine Interface (HMI) framework + through resource management consisting of sounds, windows, and input control. + For more information, see the + [HMI-Framework Page](https://wiki.automotivelinux.org/hmiframework) of the + AGL Wiki. + +* `meta-oem-extra-libs`: Provides libraries and software packages needed by + OEMs but not provided by the AGL software. + +* `templates`: Feature templates that support the `meta-agl-devel` layer. + +## Additional Sub-Layer Information + +This section provides additional information for the `meta-egvirt`, +`meta-oem-extra-libs`, and `meta-hmi-framework` layers. + +### Virtualization Support + +The `meta-egvirt` layer enables virtualization support in AGL. +The AGL Virtualization Expert (EG-VIRT) group is responsible +for design and implementation of AGL virtualization solutions +(.e.g the Virtualization platform architecture of AGL). +You can read about EG-VERT's efforts on the +"[Virtualization Expert Group's](https://wiki.automotivelinux.org/eg-virt)" +page of the AGL wiki. + +Additionally, you can learn more about virtualization as it applies to AGL +by reading +"[The Automotive Grade Linux Software Defined Connected Car Architecture](https://www.automotivelinux.org/wp-content/uploads/sites/4/2018/06/agl_software_defined_car_jun18.pdf)" +whitepaper. + +### OEM Extra Libraries + +The `meta-oem-extra-libs` layer provides additional software packages many OEMs need +but are not part of the AGL source. +Following is the list of packages this layer provides: + + * boost + * fixesproto + * imagemagick + * iptables + * Xorg-macros + * zlib + * eglibc = glibc + * libcurl + * libgif + * libneon + * mongoose + * fuse + * protocol buffers + * bsdiff + * module-init-tools + * libcroco + * libtiff + * librsvg + * libpcap + +To add these packages to your library, you need to include the +`agl-oem-extra-libs` AGL feature when you initialize your build +environment using the `aglsetup.sh` script. + +For information on how to use the `aglsetup.sh` script to initialize +your build environment, see the +"[Initializing Your Build Environment](../../0_Getting_Started/2_Building_AGL_Image/3_Initializing_Your_Build_Environment.md)" +section. + +Once you have included the AGL feature, you can build your image. + +### HMI Framework + +The `meta-hmi-framework` layer supports the Human-Machine Interface (HMI) Framework. +The HMI-Framework is the User Interface (UI) to control the Infotainment System. +Work continues to close the gap between the user experience of a smart phone +and the Infotainment System in a vehicle, for example. + +You can find more out about HMI Framework progress on the +"[HMI Framework](https://wiki.automotivelinux.org/hmiframework)" page on the AGL Wiki. + +To add HMI Framework support to your image, you need to include the +`hmi-framework` AGL feature when you initialize your build +environment using the `aglsetup.sh` script. + +For information on how to use the `aglsetup.sh` script to initialize +your build environment, see the +"[Initializing Your Build Environment](../../0_Getting_Started/2_Building_AGL_Image/3_Initializing_Your_Build_Environment.md)" +section. + +Once you have included the AGL feature, you can build your image. \ No newline at end of file diff --git a/docs/4_Developer_Guides/2_Creating_a_New_Service.md b/docs/4_Developer_Guides/2_Creating_a_New_Service.md new file mode 100644 index 0000000..0fb2453 --- /dev/null +++ b/docs/4_Developer_Guides/2_Creating_a_New_Service.md @@ -0,0 +1,151 @@ +--- +title: Creating a New Service +--- + +Services are software running in the background and providing, as their name suggests, +various services to other software: access to specific system hardware, connectivity +management, and network servers. Services can be split into 2 categories: + +- **System services:** those usually run as a privileged user and make use of shared system + resources which they should have exclusive access to + +- **User services:** such services run as part of an unprivileged user's session and can + only be called by said user + +# Basic requirements + +The only mandatory requirement is that service packages provide a `.service` file +so they can be properly managed by `systemd`. This file must be installed to a specific +location, determined by the service type (system or user): + +- `/usr/lib/systemd/system/` for system services + +- `/usr/lib/systemd/user/` for user services + +Below is an example of a simple user service, running in a graphical session and +therefore requiring a compositor to be already running before the service starts: + +``` +[Unit] +Requires=agl-compositor.service +After=agl-compositor.service + +[Service] +Type=simple +ExecStart=/usr/bin/homescreen +Restart=on-failure + +[Install] +WantedBy=agl-session.target +``` + +The `WantedBy=agl-session.target` indicates the service is part of the default AGL +user session, as mentioned in the [Application Framework](../1_Application_Framework/1_Introduction/#user-session-management) +documentation. + +The `Restart=on-failure` directive ensures the service will be automatically +restarted by `systemd` in case it crashes. + +More details about `systemd` service files can be found in the +[systemd documentation](https://www.freedesktop.org/software/systemd/man/systemd.service.html). + +# D-Bus activation + +Services can also provide a D-Bus interface. In this case, they need not be started +on system boot (or user session startup in the case of user services) but can be +automatically started only when a client sends a request to the D-Bus name the service +registers. + +D-Bus activated services must name their `systemd` service file `dbus-NAME.service` +where `NAME` is the D-Bus name registered by the service. This file must include the +following lines: + +``` +[Service] +Type=dbus +BusName=NAME +ExecStart=/path/to/executable +``` + +In addition, they must provide a D-Bus service file named `NAME.service` and installed +to one of the following locations: + +- `/usr/share/dbus-1/system-services` for system services + +- `/usr/share/dbus-1/services` for user services + +The contents of the D-Bus service file must be the following: + +``` +[D-BUS Service] +Name=NAME +Exec=/path/to/executable +SystemdService=dbus-NAME.service +``` + +This ensures the service can be safely activated through D-Bus and no conflict will occur +between `systemd` and the D-Bus daemon. + +More details about D-Bus activation can be found in the +[D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html#message-bus-starting-services), +under the "Message Bus Starting Services (Activation)" section. + +# Services startup + +For D-Bus activated services, no additional action is required as those will be automatically +started whenever needed. Other services, however, need a few more steps in order to be +executed on system or session startup. + +## System services + +System services can take advantage of the Yocto `systemd` class which automates the process of +enabling such services. + +1\. Ensure the recipe inherits from the `systemd` class: + +``` +inherit systemd +``` + +2\. Declare the system services that needs to be enabled on boot: + +``` +SYSTEMD_SERVICE:${PN} = "NAME.service" +``` + +3\. Ensure the `FILES` variable includes the systemd service directory the corresponding +file will be installed to: + +``` +FILES:${PN} = "\ + ... + ${systemd_system_unitdir}/* \ +" +``` + +## User services + +The `systemd` class doesn't provide an equivalent mechanism for user services. This must +therefore be done manually as part of the package's install process. + +1\. Make the service a part of the user session: + +``` +do_install:append() { + install -d ${D}${systemd_user_unitdir}/agl-session.target.wants + ln -s ../NAME.service ${D}${systemd_user_unitdir}/agl-session.target.wants/NAME.service +} +``` + +This ensures `agl-session.target` depends on `NAME.service`, the latter being therefore +automatically started on session creation. + +2\. Ensure the `FILES` variable includes the systemd service directory the corresponding +file will be installed to: + +``` +FILES:${PN} = "\ + ... + ${systemd_user_unitdir}/* \ +" +``` diff --git a/docs/4_Developer_Guides/3_Creating_a_New_Application.md b/docs/4_Developer_Guides/3_Creating_a_New_Application.md new file mode 100644 index 0000000..ed89ecc --- /dev/null +++ b/docs/4_Developer_Guides/3_Creating_a_New_Application.md @@ -0,0 +1,135 @@ +--- +title: Creating a New Application +--- + +Applications are: + +- Software designed to perform a specific task during a limited amount of time. +- Graphical interface allowing user to interact with. + +Applications are executed by `applaunchd`, the AGL +[application launcher service](../1_Application_Framework/2_Application_Startup/). + +# Basic requirements + +In order to be enumerated by `applaunchd`, applications must provide the a `.desktop` file, as +defined by the [Desktop Entry specification](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html). + +The desktop entry file should be installed to `/usr/share/applications` (or the `applications` +sub-directory of any entry present in the `XDG_DATA_DIRS` environment variable) and have a +meaningful name. It is considered good practice to use reverse-DNS notation for the desktop +entry file name, following the recommendations of the [D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names): +- this avoids potential name collisions with other desktop entry files +- it makes it easier to enable [D-Bus activation](#d-bus-activation) during the application + development cycle if needed +- for [graphical applications](#graphical-applications), it ensures the chosen Wayland `app-id` + will be unique + +Such a file must contain at least the following keys: +- `Type`: desktop entry type, must be set to `Application` +- `Name`: application name, as it should be displayed in menus and application launchers +- `Exec`: full path to the main executable + +Below is an example of a minimal desktop entry file: + +``` +[Desktop Entry] +Type=Application +Name=Example Application +Exec=/usr/bin/example-app +``` + +Graphical applications must also provide an `Icon` entry pointing to the application icon. +The value for this entry must either be the full path to the icon's file or, for icons part +of an existing [icon theme](https://specifications.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html), +the name of an element of this theme. + +In addition, a number of optional fields can be used to change how `applaunchd` will consider the +application: +- `Version`: version of the Desktop Entry Specification the file conforms to, must be `1.5` +- `Hidden`: boolean value, if `true` the application is always ignored by `applaunchd` and + won't be listed nor executed +- `Terminal`: boolean value, if `true` the application is excluded when requesting the list of + graphical applications from `applaunchd` +- `DBusActivatable`: boolean value, must be `true` for [D-Bus activated applications](#d-bus-activation) +- `Implements`: list of D-Bus interfaces the application implements, only used for D-Bus activated + applications. + +Finally, graphical applications may also define the `StartupWMClass` key in some cases. Please +refer to the [graphical applications](#graphical-applications) section for more information. + +# D-Bus activation + +Similarly to [services](../2_Creating_a_New_Service/#d-bus-activation), applications can +also be activated through D-Bus. + +Such applications must name their `.desktop` file after the D-Bus name they register. In addition, +this file must contain the following entries: + +``` +DBusActivatable=true +Implements=IFACE1;IFACE2;... +``` + +Where `IFACEn` are the names of the D-Bus interfaces the application implements. + +In addition, they must provide a D-Bus service file named `NAME.service` and installed +to `/usr/share/dbus-1/services`. + +The contents of the D-Bus service file must be the following: + +``` +[D-BUS Service] +Name=NAME +Exec=/path/to/executable +``` + +For example, an application registering the `org.automotivelinux.Example` D-Bus name +and implementing the `org.automotivelinux.Example.Search1` and `org.automotivelinux.Example.Execute1` +interfaces would provide the following files: + +* Desktop entry (`/usr/share/applications/org.automotivelinux.Example.desktop`): + +``` +[Desktop Entry] +Type=Application +Version=1.5 +Name=Example Application +Exec=/usr/bin/example-app +Icon=example-icon +Terminal=false +DBusActivatable=true +Implements=org.automotivelinux.Example.Search1;org.automotivelinux.Example.Execute1 +``` + +* D-Bus service file (`/usr/share/dbus-1/services/org.automotivelinux.Example.service`): + +``` +[D-BUS Service] +Name=org.automotivelinux.Example +Exec=/usr/bin/example-app +``` + +*Note: in addition to their own D-Bus interface, D-Bus activated applications must also +implement the `org.freedesktop.Application` interface as defined in the +[Desktop Entry specification](https://specifications.freedesktop.org/desktop-entry-spec/1.1/ar01s07.html).* + +# Graphical applications + +In addition, graphical applications need to comply with a few more requirements: + +1\. Each application must set a Wayland application ID appropriately as soon as its main window +is created. + +2\. The `app-id` must be specified in the desktop entry file by adding the following line: + +``` +StartupWMClass=APP_ID +``` + +3\. The desktop entry file must be named `APP_ID.desktop`. + +Doing so will ensure other software can associate the actual `app-id` to the proper application. + +*Note: application ID's are set using the [XDG toplevel](https://wayland-book.com/xdg-shell-basics/xdg-toplevel.html) +Wayland interface.* diff --git a/docs/4_Developer_Guides/4_Creating_a_custom_recipe.md b/docs/4_Developer_Guides/4_Creating_a_custom_recipe.md new file mode 100644 index 0000000..f8650e8 --- /dev/null +++ b/docs/4_Developer_Guides/4_Creating_a_custom_recipe.md @@ -0,0 +1,49 @@ +--- +title: Creating a Custom Recipe +--- + + +For adding a custom linux software/service like cannelloni you have to do the following steps: + +1. Add repo via devtool (gitrepo stands for the url) + + ``` + devtool add gitrepo + ``` +2. Try to bitbake, if it is working go to step 3 + + ``` + bitbake packagename (gitrepo name) + ``` + If it is not working you can do (repeating) following steps until it is working + + 1. change/modify the recipe in /workspace/recipe/packagename + 2. change/modify the sources in /workspace/sources/packagename + 3. bitbake packagename + + Now update the recipe, if you do this the first time you have to adapt the license and the LIC-File-Checksum + + ``` + devtool update-recipce packagename + ``` + +3. Build the recipe and image with devtool + + ``` + devtool build packagename + devtool build-image agl-demo-platform + ``` + + If that is working you could add it to git/gerrit. You have to add your recipe to a layer. + + 1. Copy files to the recipe + 2. add recipe to a packagegroup + +4. Git + + ``` + git review + git review -s + git remote -v update + ``` +![Build recipe](images/AGL_add_recipe.png) \ No newline at end of file diff --git a/docs/4_Developer_Guides/5_General_setup.md b/docs/4_Developer_Guides/5_General_setup.md new file mode 100644 index 0000000..af05096 --- /dev/null +++ b/docs/4_Developer_Guides/5_General_setup.md @@ -0,0 +1,94 @@ +--- +title: Generic devices setup +--- + +## Camera setup on RPi4 + +This assumes that you'll be using the Raspberry Pi Camera Module, which can +easily hooked on the board using the LVDS connector. Further more information +about how to connect it, could be found at +[Installing a Raspberry Pi camera](https://www.raspberrypi.com/documentation/accessories/camera.html#installing-a-raspberry-pi-camera) + +With the camera installed, you'll need to enable it by editing /boot/config.txt +file (if you're booting an AGL image over a sd-card it will be there by +default, otherwise -- in case of doing netboot, you'll have to create +manually) and add the following entry: + + + ## start_x + ## Set to "1" to enable the camera module. + ## + ## Enabling the camera requires gpu_mem option to be specified with a value + ## of at least 128. + ## + ## Default 0 + ## + start_x=1 + +And reboot your device. Afterwards, after logging it, make sure that you have +the /dev/video0 device created. You could also use v4l2-ctl to verify +that is indeed usable as a capture device: + + $ v4l2-ctl -d /dev/video0 --all + +In order to test out video playback, use the following gstreamer pipeline: + + $ gst-launch-1.0 v4l2src device=/dev/video0 ! \ + video/x-raw,width=640,height=480 ! waylandsink fullscreen=true + +Alternatively, using [camera-gstreamer](https://gerrit.automotivelinux.org/gerrit/gitweb?p=apps/camera-gstreamer.git;a=summary) +application could might be another possibility, but you'll have to build it +yourself and add it in the image. + +This includes an example on how to create a xdg-toplevel surface and create a +gstreamer pipeline, instead of relaying on waylandsink to create one for you, +in a programmatic fashion. + +## Display setup on RPi4 + +This assumes that you'll be using the Raspberry Pi 7'' display. Installation +can be found at [Rpi Display page](https://www.raspberrypi.com/documentation/accessories/display.html). + +If booting over the network, the dtb should already contain the ft5406 dtb, +while booting over sd-card the following show be in the /boot/config.txt +file: + + dtoverlay=rpi-ft5406-overlay + +Once the board boots up, you should get a rainbow like effect and afterwards +booting up would display debug scrolling over. You'll need to adjust the +orientation as the 800x480 is in portrait. Edit /etc/xdg/weston/weston.ini and +add a new output entry, like the following: + + [output] + name=DSI-1 + transform=90 + +Note that for the Qt platform, the homescreen application, together with the +other demo applications, is tailored specifically for a 1080p display and it +will display incorrectly on such a smaller display. + +## Testing out video camera without a real device + +While the above requires having a real video camera device, one can use out +the [vivid module](https://docs.kernel.org/admin-guide/media/vivid.html?highlight=vivid#the-virtual-video-test-driver-vivid) +to try out your custom application or just testing out camera functionality in AGL. + +You should normally have the module present, not loaded, for either **rpi4** or for +**h3ulcb** boards. Load the module, like in the following command: + + modprobe vivid allocators=0x1 + +Have a look at the kernel ring buffer to see what capture devices are created +and use as source: + + $ gst-launch-1.0 v4l2src device=/dev/videoXX ! \ + video/x-raw,width=640,height=480 ! waylandsink fullscreen=true + +making sure to replace /dev/videoXX with correct capture device. You can check +that easily using the v4l2-ctl mentioned above. + +Note that using camera-gstreamer will attempt to find the first available +capture device, so if you happen to have to another one before the one created +by this module it might not work. You can bypass that, by just making a symlink +from /dev/videoXX to /dev/video0 to make first available capture device. diff --git a/docs/4_Developer_Guides/images/AGL_add_recipe.png b/docs/4_Developer_Guides/images/AGL_add_recipe.png new file mode 100644 index 0000000..07b44b6 Binary files /dev/null and b/docs/4_Developer_Guides/images/AGL_add_recipe.png differ diff --git a/docs/5_APIs_and_Services/FIXME.md b/docs/5_APIs_and_Services/FIXME.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/5_Component_Documentation/0_AGL_components.md b/docs/5_Component_Documentation/0_AGL_components.md deleted file mode 100644 index a251b05..0000000 --- a/docs/5_Component_Documentation/0_AGL_components.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: AGL Components ---- - -## Components under development within AGL - -### Graphics - -- [The AGL compositor](1_agl-compositor.md) -- [Waltham receiver/transmitter configuration](2_waltham-receiver_waltham-transmitter.md) -- [DRM lease manager](4_drm-leasemanager.md) - - -### Sound - -- [Pipewire & Wireplumber](6_pipewire_wireplumber.md) -- [IC and Sound Manager](7_ic-sound-manager.md) - - -### Policies - -- [Rule based arbitrator](3_rba.md) - - -### Lifecycle management - -- [Application Framework](../3_Developer_Guides/1_Application_Framework/1_Introduction.md) diff --git a/docs/5_Component_Documentation/1_agl-compositor.md b/docs/5_Component_Documentation/1_agl-compositor.md deleted file mode 100644 index 437e6a7..0000000 --- a/docs/5_Component_Documentation/1_agl-compositor.md +++ /dev/null @@ -1,498 +0,0 @@ ---- -title: agl-compositor ---- - -# Wayland compositor - -When the AGL project was started, weston was chosen as the compositor, which is -the reference implementation of a Wayland compositor, while for window management -functionality it relied on *ivi-shell* (In-Vehicle Infotainment) together -with an extension, called [wayland-ivi-exension](https://github.com/GENIVI/wayland-ivi-extension). - -A demo platform image of AGL comes with a handful of demo applications, done -with the Qt, which abstracts the protocol communication between the client and -the compositor. Additional functionality was in place under the form of -library, to control and signal back to the compositor when applications were -started, among other things. - -Management of applications, starting, running and stopping them is done in AGL -with AppFW [Application Framework Management](../3_Developer_Guides/1_Application_Framework/1_Introduction.md), -which is an umbrella name to denote the suite of tools and daemons that handle -all of that. It is integrated with systemd and with the current security model. -Applications can use AppFW to hang off data, and to pass it down to -other services. Together with AppFW, applications could tell the compositor -which application to activate or to switch to. - - -## Simplifying the graphical stack - -Trimming down these abstractions, simplifying the way clients interact with the -compositor, and avoid using modules that aren't really maintained upstream were -the reasons behind looking at alternatives to ivi-shell. On the desktop, -[xdg-shell](https://gitlab.freedesktop.org/wayland/wayland-protocols/-/raw/master/stable/xdg-shell/xdg-shell.xml) -is currently de-facto protocol for handling all window management related -functionality. - -Wayland protocol has a window-like interface embedded into its protocol (called -wl_shell), but *xdg-shell* has long time ago deprecated it and instead -of adding it in the wayland protocol namespace, it was integrated -together with some other useful protocols, into -[wayland-protocols](https://gitlab.freedesktop.org/wayland/wayland-protocols) -project. The whole purpose of wayland-protocols is to enhance the Wayland -protocol with new functionality and bring new extensions entirely. Compositors -are free to implement, modify, enhance, and add new extensions to -wayland-protocols but they need to do so in consensus. - -Besides the core wayland protocol and extended functionality from -wayland-protocols, a compositor can provide and implement additional protocol -extensions (custom to that compositor). By using such private extensions we -align with the AGL project and its requirements, without compromising specific -functionality and allows to add or improve the current ones. With that in mind, -the approach was to create a new compositor, called -[agl-compositor](https://gerrit.automotivelinux.org/gerrit/admin/repos/src/agl-compositor) -and implement dedicated private extensions, rather than trying to modify weston -itself, which AGL project would have been required to keep and maintain for -itself, as a fork. - -## A compositor based on libweston - -The compositor used currently in AGL, just like weston, is built on top of -*libweston* and *libweston-desktop*. The latter, among other things, is required -as it provides the server side implementation of the xdg-shell protocol which -underlying toolkits (like Qt/Chromium project) makes use of to deliver -desktop-like functionality. The former is used to provide back-ends and -rendering support, effectively managing the HW, besides implementing the -wayland protocol. - -The high-level goal of [libweston](https://wayland.pages.freedesktop.org/weston/toc/libweston.html) is -to decouple the compositor from the shell implementation. - -Traditionally, clients were entirely separated from the window manager, the -desktop environment and the display server. In wayland all these are -conceptually under the same entity though they are implemented as different -(UNIX) processes, or as a different namespaces with front and back-end APIs, -exposed by libraries. The compositor and the shell driving the UI should be -seen as one and the same, and in practice, this happens on desktop -environments. For AGL, the shell client can be represented under different -forms, as well as the fact that the process management has another layer -baked-in to handle MAC (Mandatory Access Control) labels and use the -above-mentioned Application Framework. These are all tightly -integrated and therefore, the AGL compositor will not automatically start the -shell client, although there's code to handle that. - -## Specifying a shell client to be started by the compositor - -Nevertheless, one can modify the configuration file, add the shell client path, and the -compositor will attempt to start it. - -``` -[shell-client] -command=/path/to/your/client/shell -``` - - - -## Private extensions - -Compositors can define and implement custom extensions to further control -application behaviour. For AGL, we have two private extensions defined. -One targeted at defining surface roles commonly found in desktop environments -(like panels, and backgrounds), which a shell client would bind to, and one -targeted at regular application(s) that might require additional functionality: -being able to display/activate its own surface or other's application surface, -implement some kind of split screen management of windows, or -dialog/pop-ups that exhibit always-on-top property even if the active -surface has been changed. - -![Layers_And_Extensions](images/agl-compositor/drawing_shell.png) - -Clients can make use of these private extensions to define other kind of roles -for instance dialog/pop-ups or full-screen roles, and split windows vertically or -horizontally. It includes the ability to activate other applications, assuming -that the surfaces have been created, and the capability of delaying -presentation for the client shell. Doing so, all the information is displayed -at once, rather than waiting for the toolkit to map/show the surface. - -An application identification mechanism was required to be able to activate -other clients windows/surfaces. A string-based identifier name was chosen -which can be used by the client to set an application-based identifier using -the xdg-shell protocol. While there's nothing stopping the client to avoid -doing that, specifically, to avoid assigning an application identifier, -the compositor won't be able to find which surfaces matches to a particular -client, if one would want to activate/display it at some time in the future. - -### agl-shell - -Client shellls can make use of this protocol to define panels and background -roles for different surfaces. It includes to ability to activate other -applications, assuming that those are already running. Activation happens by -using using the app_id, respectively using set_app_id request as defined by the -xdg-shell protocol. Established client-side implementation of the xdg-shelll -protocol will have a function exposed which can be used to set an application -identifier. Further more, the compositor will not present/display anything to -the user as long the `ready()` is not requested. So, after creating the surfaces -assigning them panel and/or background roles, and they're fully loaded, -the client can then issue `ready()` request and the compositor will start -presenting. - -Please consult the [protocol file](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/agl-compositor.git;a=blob_plain;f=protocol/agl-shell.xml;hb=refs/heads/master) -as that is the authoritative way of getting the latest version. - -#### V2 updates - -Version 2 of the agl-shell protocol, while it is is not obligatory to be -supported by the shell client, it adds two new events: bound_ok and bound_fail -events. - -It has been observed that in some cases where we do not explicitly have a knob -in the toolkit to tell whether the application is a regular one (which doesn't -need to bind to the agl-shell protocol) or a one that needs to implement -agl-shell protocol might result in terminating the wayland connection. - -That happens because we can't have multiple clients bind to the agl-shell -protocol interface and was particularly visible when using regular -flutter applications with other shell clients (Qt homescreen, or WAM/chromum), -basically mashing together different kind of toolkits in the same image. Once -a client has already bound to the agl-shell protocol interface any other client -that attempts to do same will get its wayland connection severed and the -application will be terminated. - -These two events provide a race-free method in which the clients can tell if -they're in charge (of being the shell client) or their just regular -applications. Explicitly implementing this protocol if you have other means to -specify which type of application it is running wouldn't be required nor -necessary. But by using the protocol we can provide the same thing, -programmatically, without fearing that the wayland connection might be -severed, and implicitly taking down the application. - -#### V3 updates - -Version 3 of the agl-shell protocol adds 4 more events to signal out when the -application state was changed: started, activated, deactivated and terminated. - -Version 3 update was mostly prompted by an issue with start-up of applications -but also is part of the first steps to reduce and simplify a bit more -activation handling in the compositor. Specifically with this protocol update, -we can correctly orchestrate start-up and activation of applications. - -At the moment of adding this protocol update, the default compositor behaviour -is to display/activate applications as soon they're started, a feature which -we've called activate-by-default (and which is turned on by default). -But users can choose to disable that in such a way that activation is entirely -driven the shell client. - -Implicitly having this activate-by-default papered over various -issue when don't have that activation by default turned on. Supporting both -use-cases (activate-by-default, on and off) turned out to be cluster of -problems and regression over time. Not only that the amount of complexity in -the compositor is unwarranted and can simplified by telling the shell client -handle any window management interaction on its own. - -Further more, with this protocol update we also includes some events already -present in the agl-shell-desktop protocol like deactivate and terminate. - -### agl-shell-desktop - -This extension is targeted at keeping some of the functionally already -established in AGL as to a) allow applications display/activate other -surfaces/application window, and b) set further roles, specially dialog/window -pop-ups and split-type of surfaces. - -Clients can make use of this protocol to set further roles, like independently -positioned pop-up dialog windows, split type of surfaces or fullscreen ones. -Additional roles, and implicitly functionality can be added by extending the -protocol. These roles serve as hints for the compositor and should be used -before the actual surface creation takes place, such that the compositor can -take the necessary steps to satisfy those requirements. - -Please consult the [protocol file](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/agl-compositor.git;a=blob_plain;f=protocol/agl-shell-desktop.xml;hb=refs/heads/master) -as that is the authoritative way of getting the latest version. - -#### Additional surface roles in agl-shell-desktop - -Like mentioned earlier, the compositor is already making use of some (internal) -roles, and with this extension we add some further ones. These are: - -* split (there's vertical and a horizontal one) -* fullscreen -* dialog/pop-up - -Internally these are encoded with different values such that there's a -translation needed, between the protocol values and the internal ones. Besides -the roles, additional data can to be passed on, but only depending on the role. -It is highly recommend **to avoid** using the protocol to pass down information -between different applications using this communication channel. It is only -intended to help out with demo applications. Other sharing mechanism are -available in the AGL project that can satisfy those requirements. - -#### Receiving application state events from (other) applications - -agl-shell-desktop exposes two events which client can install handlers for, one -that signals when regular xdg application have been created, and one that -signals state changes (active/hidden) as well as destroyed/no longer present -surfaces. These events can be useful to add additional functionality if -needed. - -#### Activating (other) applications - -Both agl-shell and agl-shell-desktop have requests to activate other -application based on their xdg-shell app_id. In case the application is -present/running, it will attempt to make the surface backing that application -the current activate one, with each output having independently active -surfaces. - -## Explicit output - -The activation and setting surface roles requires passing a Wayland output -(wl_output). The output is the wayland interface representation of an output -and is **mandatory** to pass it down to the compositor when activating a surface. -Clients can retrieve it (the output) if they wish to place the surface on other -outputs by using the toolkits that expose the Wayland objects. A human-like -representation is provided by either the toolkit, or by using other extensions -implemented by the client, for instance [xdg-output](https://gitlab.freedesktop.org/wayland/wayland-protocols/-/raw/master/unstable/xdg-output/xdg-output-unstable-v1.xml) -is the one recommended way and provides a mapping between a human -representation of the output and the wayland one. - -One can also choose the output where the application can start, by configuring -directly the AGL compositor. Under the `[output]` section one can use -`agl-shell-app-id=appid` restart the AGL compositor unitd systemd service and -start the application. Currently this *only* applies to regular applications, the -client shell having to handle it in the code. - -## Available toolkits, application conversions and available eco-systems - -Users and OEM vendors alike have the possibility, depending on their use-cases, -to either use some kind of a toolkit (Qt/GTK) for writing application, -or use plain C and the wayland library to communicate with the compositor -directly, without any toolkit abstraction. - -Currently, the demo applications in AGL use the Qt platform with Chromium being -at this phase, a second-class citizen, being currently in the works of -achieving the same level of integration as QtWayland (the underlying library that -abstracts the Wayland interaction) has at this moment. The Qt platform has -long been favoured in embedded systems so it feels natural why AGL project -chose it over other alternatives. In the same time, as web applications are -for quite some time now permeating the application development scene, it also -felt natural to add support for a runtime that gives that option, which in AGL -was achieved with the help of the Chromium project. - -For normal applications, not needing the ability to activate or displaying -other's application surface, would basically mean that it would use what the -toolkit has to offer, simplifying the application handling even more. Under -Qt, the client shell can use QPA (Qt Platform Abstraction) to gain access to -Wayland primitives, and implicitly is being able use the private extensions. - -![Architecture Diagram](images/agl-compositor/arch_diagram.png) - -On the Chromium side of things, that happens indirectly, as Chromium doesn't -expose the Wayland primitives. Not only that, but on the Chromium platform, -there's another mid-layer component, called [WAM](https://github.com/webosose/wam) -(WebApplicationManager) with the purpose of handling web applications life-cycle. - -So, controlling and passing information from a web application, that resembles -that of a shell client, has to travel more than a few levels in the software -stack, until it reaches the lower layers in Chromium where the Wayland -communication and interaction takes place. Support for the private extension -was done at the Ozone interface abstraction, which Chromium projects uses now -to handle the display/graphical interaction with the lower stack levels. - -## Streaming buffers and receiving events to and from remote outputs - -Quite a common feature, in the infotainment market, is the ability to stream -out buffers/data to remote outputs. For instance, super-imposing the navigation -application, between the speedometer and tachometer, in the IC (Instrument -Cluster) of a car is such a scenario. Just like weston, the AGL compositor is -capable of loading up libweston modules and make use of them. And just like -weston, the AGL compositor loads up the remoting-plugin to achieve the same -thing. - -The remoting-plugin uses the DRM virtual output API from libweston together -with gstreamer pipeline to capture, using DMA buffers, the DRM output and to -stream it, remotely to another machine. They can be over the network, or -locally. - -Further more, to cope with situations where the output is just a -panel/display, without some kind of compositor driving it, the necessity of -handling input events is an important feature to have, giving the user to -possibility to manipulate the application/environment as he or she seems fit. -The compositor loads a plug-in that streams out the buffers to an output -remotely, with [another plug-in](2_waltham-receiver_waltham-transmitter.md) -handling the input events. The events, which are sent back from the display to -the compositor, are generated with the help of wayland-eque protocol that works -over the network, called [Waltham](https://github.com/waltham/waltham). - -Together, they provide proper means to achieve a seamless integration with -other display devices in the car cabin. - -## Policies and Role Base Arbitration - -The compositor contains an API useful for implementing user-defined policies. -It contains a policy engine, and installs by default an allow-all kind of -policy. The policy engine controls if the client using the private extensions -is permitted to perform those calls. Not only that, but with some policies, it -won't allow the client to bind to the interfaces in the first place. That -happens with the deny-all policy, which is able to retrieve the client's -SMACK label and compares it with the ones statically defined. - -In the works, there's a new policy model, called [Role Based -Arbitration](https://gerrit.automotivelinux.org/gerrit/admin/repos/staging/rba). -Internally, how it works, should be found at [RBA](3_rba.md). -While the other two policies are embedded into the compositor, the RBA policy -model is an off the-shell policy. Obviously, vendors and users can hook up -their own policies, just like RBA did. These all work towards satisfying -the driver distraction mitigation requirement for the AGL project, as to avoid -overwhelming the driver with too much information. - -Users wanting to create their own policy should create a specialized version -of the callbacks defined in `struct ivi_policy_api`. - -As there's no dynamic loading of policies you'll need to recompile the compositor -with that policy in mind, specifically like the following: - - $ meson -Dprefix=/path/to/install-compositor/ -Dpolicy-default=my_policy build_directory - -The default policy found in src/policy-default.c should more than sufficient to -get started on creating new ones. Users can either re-purpose the default -policy or create a new one entirely different, based on their needs. - -These are hooks in place by the policy engine control the creation, committing -and activation of surfaces (`ivi_policy_api::surface_create()`, -`ivi_policy_api::surface_commited()`, `ivi_policy_api::surface_activate()`), -among other situations. - -Users can customize the hooks by using some sort of database to retrieve the -application name to compare against, or incorporate some kind of policy rule -engine. Alternatively, one can use the deny-all policy engine which allows the -top panel applications to be used/displayed as permitted applications. - -### Reactive rules - -The policy engine is stateful, and allows the ability to inject back events, -such that it allows the user to add custom rules into a policy and, depending -on the event received by the policy engine, to execute a rule match for that -event. Further more, the framework allows adding new states and events and the -default implementation has code for handling events like showing or hiding the -application specified in the policy rule. The most common example to exemplify -this feature is the ability to show a custom application, like displaying the -rear view camera application, when the automobile has been put in reverse. - -For deadling with these kind of rules, `ivi_policy_api::policy_rule_allow_to_add()` -can be used to control if policy rules could be added or not. Finally, we have -`ivi_policy_api::policy_rule_try_event()` which is executed for each policy -rule added, by using the policy API `ivi_policy_add()` function. - -By default the policy framework it will add the 'show', and 'hide' events and -the 'start', 'stop' and 'reverse' states. An special type, assigned by default -is 'invalid'. A **state change** has to be propagated to the compositor, which can -happen by using `ivi_policy_state_change()` function, and which signals the -compositor the state change took place, in order to apply the policy rules, and -implicitly to call the event handler `ivi_policy_api::policy_rule_try_event()`. - -## Back-ends and specific options for agl-compositor - -The compositor has support for the following back-ends: - -* **DRM/KMS** - runs a stand-alone back-end, uses Direct Rendering Manager/Kernel - Modesetting and evdev, that is utilizes and runs on real or virtualized HW - (qemu/Vbox/etc). -* **Wayland** - runs as a Wayland application, nested in another Wayland compositor - instance -* **X11** - run as a x11 application, nested in a X11 display server instance - -### Building and running the compositor on different platforms - -The compositor can run on desktop machines as easily as it does on AGL -platform. It should infer, depending on the environment, if it is being -compiled with the AGL SDK, or with the host build system. Running would also -be inferred from the environment. - -The compositor has some additional configuration options like: - -* `--debug` - enables the screenshooter interface, useful if one would want to - take a screenshot using `agl-screenshooter` client. This might be seen as a - security risk to it only be enabled in the AGL platform if built with agl-devel - DISTRO FEATURES. - -Additional configuration ini options have been added to help with the CI -integration. Worth mentioning are: - -* `activate-by-default=[true]` - if the surface of the client should be - displayed when the application started. Present in the `[core]` section. - By default set to `true`. Setting it to `false` will not activate, - by default, the client's surface when started. -* `hide-cursor=[false]` - do not advertise pointer/cursor to clients. Present - in the `[core]` section. - -## Running with software rendering - -By default the compositor will attempt to use the GL-renderer, and implicitly -the GPU. One could instead use the CPU, by making use of the Pixman library. To -use it in the compositor append `--use-pixman` to the command line. This purely -software approach has the benefit that would not rely at all on any GL -implementatation or library. In constrast, even if the GL-renderer is used, -in some situations it won't be able to use the GPU supported implementation -and fallback to sofware based one, and for instance that might happen when -running in virtualized environments. - -Both approaches could end up not actually using the GPU, but the latter does -actually use the GL library and perform the operations in software, while the -former does not use any GL whatsover. All back-ends support disabling the -GL-render to make sure it does not interfere with the composing process. - -## Multiple output set-up and touch input devices - -There's no deterministic way in which the compositor enables the outputs and -depending on the input devices, specifically touch input devices, and the way -the connectors are wired, a touch input device might be associated with a -different output than the one intended. - -A consistent way, that survives a reboot, is to use -[udev rules](https://man7.org/linux/man-pages/man7/udev.7.html), which -libweston would be able to use such that a particular output is tied/associated -to a particular touch input device. - -For instance, assuming that you have a set-up consisting of 4 outputs, a 4 -touch input devices, when the outputs are being enabled the compositor -front-end will associate all 4 touch input device -- if they haven't been -previously being associated to a particular output, to the first enabled -output. - -In order to avoid that, and associate each touch input device to -their respective output an udev rule can be installed, for the default -seat (named `seat0`). - -Example of a udev rule: - -``` -SUBSYSTEM=="input", ATTRS{idVendor}=="222a", ATTRS{idProduct}=="004a", OWNER="display", ENV{ID_SEAT}="seat0", ENV{WL_OUTPUT}="HDMI-A-1" -SUBSYSTEM=="input", ATTRS{idVendor}=="222a", ATTRS{idProduct}=="004b", OWNER="display", ENV{ID_SEAT}="seat0", ENV{WL_OUTPUT}="HDMI-A-2" -SUBSYSTEM=="input", ATTRS{idVendor}=="222a", ATTRS{idProduct}=="004c", OWNER="display", ENV{ID_SEAT}="seat0", ENV{WL_OUTPUT}="HDMI-A-3" -SUBSYSTEM=="input", ATTRS{idVendor}=="222a", ATTRS{idProduct}=="004d", OWNER="display", ENV{ID_SEAT}="seat0", ENV{WL_OUTPUT}="HDMI-A-4" -``` - -Add the following under `/etc/udev/rules.d/91-output.rules` and reload udev -rules for these changes to take effect: - - $ udevadm control --reload-rules && udevadm trigger - -Note that in the above example, we use physical seat, named `seat0` which is -the default physical seat. You can verify that these changes have been applied by -checking the compositor logs (under `/run/platform/display/compositor.log` file) -You should be seeing `CONNECTOR-NO by udev` message like the following: - -``` -associating input device event0 with output HDMI-A-1 (HDMI-A-1 by udev) -``` - -vs - -``` -associating input device event0 with output HDMI-A-2 (none by udev) -``` - -where the rules are either incorrect or badly written. - -Retrieving device attributes could be done archaically using `lsusb` or `lspci` -or using `udevadm info -a /dev/input/event*` which can provide with a multitude -of attributes to use. In our above example we only relied `idVendor` and -`idProduct` but potentially other attributes might be used. diff --git a/docs/5_Component_Documentation/2_waltham-receiver_waltham-transmitter.md b/docs/5_Component_Documentation/2_waltham-receiver_waltham-transmitter.md deleted file mode 100644 index b98de32..0000000 --- a/docs/5_Component_Documentation/2_waltham-receiver_waltham-transmitter.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: Waltham receiver/transmitter ---- - -# Waltham - -[Waltham protocol](https://github.com/waltham/waltham) is a IPC library similar -to [Wayland](https://wayland.freedesktop.org), developed with networking in -mind. It operates over TCP sockets, while the wayland protocol only works -locally over a UNIX socket. It retains wayland-esque paradigm, making use of -XMLs to describe the protocol, and it follows an object-oriented design with an -asynchronous architecture. - -## Differences from Wayland to Waltham - -Some of the differences between Wayland and Waltham are: - -* Waltham uses TCP sockets for communication -* Waltham cannot send file descriptors -* Waltham API is minimal and symmetric between server and client sides -* Waltham does not provide an event loop implementation -* The registry implementation is left out of the library, only the interface is - provided -* No multi-threading support for sharing objects between threads - -## Waltham-transmitter and remoting plugin - -Surface sharing is not part of Waltham protocol, each system needs to implement -the most efficient way of passing by the buffers from one side to another. On -AGL, make use of remoting-plugin to enable surface sharing which uses GStreamer -as encoder/decoder. It uses libweston DRM virtual API to grab the buffers, and -then to stream them over the network. The gstreamer pipeline uses UDP while the -input events are communicated with Waltham protocol. The input part is handled -by *waltham-transmitter* plugin which provides an API to create remote -connections and push surfaces over the network and handles remote input. The -act of pushing surface is a misnomer, kept from the older, previous -implementation, and acts a notification mechanism from the transmitter side to -the remote side. - -## The receiver client - -waltham-receiver application is a wayland demo implementation which should be -running at the remote side. It is using Waltham protocol to obtain and process -remote input events which handled the transmitter side by the waltham-transmitter -plugin. It creates a similar gstreamer pipeline to process the incoming buffers -and draw and displaying them into a subsurface created by waylandsink. - -Contrary to expectations, the waltham receiver is the one that implements the -server side of the Waltham protocol and is capable of displaying the incoming -buffers but also process input events locally and forward them with the help of -the Waltham protocol back at the transmitter side, which in turn will update -the image contents and stream to the receiver, showing the changes caused by -that input. - - - ECU 1 ECU 2 - +---------------------------------------------+ +--------------------------------------+ - | +-----------------+ | | | - | | Application | | | +-----------+-----------+ | - | +-----------------+ | | | Gstreamer | | | - | ^ | Buffer ---------------> (Decode) | | | - | wayland | +-------------------/ | +-----------+ | | - | v | | (Ethernet) | | Waltham-receiver | | - | +----+---------------------+ | | --------------------> | | - | | | Transmitter plugin |<---------------------/ | +-----------------------+ | - | | | | | | Waltham-Protocol | ^ | - | | |---------------------| | | | wayland | | - | | | Remoting plugin |-------+ | | v | - | | | | | | +---------------------+ | - | | +---------------------+ | | | | | - | | | | | | compositor | | - | | compositor | | | | | | - | +------+-------------------+ | | +----------------+----+ | - | | | | | | - | v | | v | - | +------------+ | | +----------+ | - | | Display | | | | Display | | - | | | | | | | | - | +------------+ | | +----------+ | - +---------------------------------------------+ +--------------------------------------+ - -## Migrating/Placing applications on other outputs - -In order to start or place an application on the remoting-ouput output, we can -use `agl-shell-app-id` ini entry for that particular output. - - [transmitter-output] - name=transmitter-1 - mode=640x720@30 - host=192.168.20.99 - port=5005 - agl-shell-app-id= - -Alternatively, and programmatically, one can use the -[agl-shell-desktop](1_agl-compositor.md#private-extensions) protocol and inform -the compositor that it should migrate it to other, remote outputs. diff --git a/docs/5_Component_Documentation/3_rba.md b/docs/5_Component_Documentation/3_rba.md deleted file mode 100644 index 9661923..0000000 --- a/docs/5_Component_Documentation/3_rba.md +++ /dev/null @@ -1,1207 +0,0 @@ ---- -title: Rule Based Arbitrator (RBA) ---- - -# RBA - -Rule Based Arbitrator decides which of the content to display when a large number of contents to be displayed on the cockpit display device (CID, meter, HUD, etc.) occur simultaneously under a certain rule (arbitration). - -### 1. Overview - -#### 1.1 Purpose of this document - -This document describes the syntax of the Rule-based Arbitration Model. - -#### 1.2 Basic syntax - -The basic syntax of the Rule-based Arbitration Model is as follows. - -![Basic syntax](images/rba/Basic_syntax.png) - -Define the properties of the model element in {} after declaration of Model element keyword,　Model element ID. Each property depends on the element. The properties of the model element may also define other model elements. - -#### 1.3 Relationship between files and Model definitions - -The Rule-based Arbitration Model can be defined in multiple files. (The extension of the file will be ".rba") Firstly, define the Package model element in the file. - -Areas.rba -```shell -Package AreasPackage { - -} -``` -Content.rba -```shell -Package ContentsPackage { - -} -``` - -#### 1.4 Structure of Rule-based Arbitration Model - -The elements of the Rule-based Arbitration Model are as follows. Each inheritance relationship between elements is defined and expresses elements that can be described in PackagableElement. - -![model](images/rba/model.png) - -#### 1.5 Notation of Syntax Definition - -For Model element - -syntax: -```shell -Package [ID] { - description: [String] - [PackagableElement] -} -``` - -Description: - -| Syntax element | Description | -| :--- | :---- | -| description: 0..1 | Description | -| [PackagableElement] * | Child element Package,Display,Size,Constraint,PostConstraint,Scene,Event,Rule,Area,AreaSet,ViewContent,ViewContentSet| - -The multiplicity is expressed as follows: - -| Expression of multiplicity | Description | -| :--- | :--- | -| * | 0 or more | -| 1..* | 1 or more | -| 1 | 1 | -| 0..1 | 0 or 1 | - -Description of [] notation is as follows: - -| Syntax element | Description | -| :--- | :---- | -| [ID] | ID. A character string in which the first character is not a number. Only _ can be used for symbols, Space cannot be used. -| [String] | An arbitrary character string. specify it by enclosing with "". | -| [Number] | An integer that is greater than equal 0. | -| [expression] | An expression whose return value is a property type. | -| [] | Definition of other Model elements. Sometimes an abstract class is specified. | -| [ID of A] | Reference to other Model elements. A represents an element. | -| [X\|Y] | Indicates that you can describe X or Y. | - -### 2. Common - -#### 2.1 Package - -The Package element is the root element in the file. It has PackagableElement as a Child element and groups PackagableElements in arbitrary units. - -syntax: -```shell -Package [ID] { - description: [String] - [PackagableElement] -} -``` - -| Syntax element | Description | -| :--- | :---- | -| description: 0..1 | Description | -| [PackagableElement] * | Child element Package,Display,Size,Constraint,PostConstraint,Scene,Event,Rule,Area,AreaSet,ViewContent,ViewContentSet| - -Description example: -```shell -Package SamplePackage { - description: "This is a sample Packege" - Area SampleArea { - arbitrationPolicy: DEFAULT - sizeReference: SampleSize1 - visibility: NONE_VALUE - zorder: 3 - } - ViewContent SampleContent { - allocatable: [SampleArea1] - State NORMAL { - priority: STANDARD_VALUE - } - } -} -``` - -#### 2.2 Size - -Size is the size of Area and ViewContent. - -Syntax: - -```shell -Size [ID] { - description: [String] - width: [Number] - height: [Number] -} -``` - -| Syntax element | Description | -| :--- | :---- | -| description: 0..1 | Description of Size element | -| width: 1 | width | -| height: 1 | height | - -Description example: -```shell -Size ScreenSize { - description: " Screen size" - width: 200 - height: 200 -} -``` - -#### 2.3 Project - -The Project element is an element that can be defined only once in one project. -Like The Package element, it can be defined directly under the file. - -Syntax: -```shell -Project { - version: [String] -} -``` - -| Syntax element | Description | -| :--- | :---- | -|version: 1| Version of the Project| - -Description example: -```shell -Project { - version: "version 1.0" -} -``` - - -### 3. Area - -Area is a frame to display the ViewContent on the screen. Only one ViewContent is allocated to one Area at most. Since Arbitration is executed for each Area, the Arbitration Policy is defined. - -Syntax: - -```shell -Area [ID] { - description: [String] - arbitrationPolicy: [DEFAULT | FIRST_COME_FIRST | LAST_COME_FIRST | PRIORITY_FIRST_COME_FIRST | PRIORITY_LAST_COME_FIRST] - [[Size]| sizeReference:[ID of Size]] - [visibility|priority]:[Number|Expression] - zorder:[Number|Expression] -} -``` - -| Syntax element | Description | -| :--- | :---- | -| description: 0..1 | Description | -| arbitrationPolicy: 0..1 | Arbitration Policy for Area. Refer to "Types of Arbitration Policy" for the policies which can be specified. If not specified, consider it as "DEFAULT". -| [Size\|sizeReference:] 1..* | Size: Size definition.| -|| sizeReference: Reference to Size definition.| -|| ※One or more definitions of either Size or sizeReference are needed. Multiple definitions should be defined consecutively.| -| [visibility\|priority]: 1 | Value of Area. Describe the relative value for other Areas as an expression or set a numerical value.| -|| The following predefined value can be set as a String. NONE_VALUE, STANDARD_VALUE, MIN_VALUE, MAX_VALUE See " Value / Z order definition" for details. | -| zorder: 1 | Z order of Area. Describe the relative Z order for other Areas as an expression or set a numerical value. The following predefined value can be set as a String. | -||NONE_VALUE, STANDARD_VALUE, MIN_VALUE, MAX_VALUE See " Value / Z order definition" for details. | - - - -Types of Arbitration Policy - -| Arbitration Policy | Description | -| :--- | :---- | -| DEFAULT | Same as Priority and First Come First Arbitration. If the Arbitration Policy is not specified, it will be this type.| -| FIRST_COME_FIRST | First Come First Arbitration. Give priority to the request which occurred first. | -| LAST_COME_FIRST | Last Come First Arbitration. Give priority to the request which occurred later. | -| PRIORITY_FIRST_COME_FIRST | Priority and First Come First Arbitration. It follows the priority set to the Content. If the priority is the same, give priority to the request which occurred first. | -| PRIORITY_LAST_COME_FIRST | Priority and Last Come First Arbitration. It follows the priority set to the Content. If the priority is the same, give priority to the request which occurred later.| - -Description example: -```shell -Area SampleArea { - description: "This is a sample Area." - arbitrationPolicy: DEFAULT - Size Default { - width: 200 - height: 150 - } - sizeReference: SampleSize1 - visibility: NONE_VALUE - zorder: 3 -} -``` - -### 4. Value / Z order definition - -Values (visibility or priority) of area is the order of arbitrating of the area. The higher is arbitrated first. You can describe only one of the visibility or priority. -For the Z order (zorder), the higher one will be on the front of the screen. You can define values absolutely by number or define relatively to other areas by expressions. You can use comparison operators (> and <), equality operator (=) and That-of operator for the expressions. - -- Description example of value : -Visibility of SampleArea2 is 10, zorder is 5. -```shell -Area SampleArea2 { - visibility: 10 - zorder: 5 -} -``` -- Description example of comparison operator: -Priority of SampleArea1 is greater than SampleArea2. Zorder of SampleArea1 is less than SampleArea3. -```shell -Area SampleArea1 { - priority: > That-of SampleArea1 - zorder: < That-of SampleArea3 -} -``` -- Description example of range: -Visibility of SampleArea1 is greater than 1 and less than SampleArea2. Zorder of SampleArea1 is greater than SampleArea3 and less than SampleArea4. -```shell -Area SampleArea1 { - visibility: (> 1 AND < That-of SampleArea2) - zorder: (> That-of SampleArea3 AND < That-of SampleArea4) -} -``` - -- Description example of equality operator: -```shell -Area SampleArea1 { - visibility: = That-of SampleArea2 - zorder: = That-of SampleArea3 + That-of SampleArea2 -} -``` - -- Equality operator can be omitted. -```shell -Area SampleArea1 { - visibility: That-of SampleArea2 - zorder: That-of SampleArea3 + That-of SampleArea2 -} -``` - -### 5. ViewContent definition - -#### 5.1 ViewContent - -ViewContent is an object to be displayed in the Area. ViewContent has multiple states. When ViewContent is allocated to an Area, active state of theViewContent is displayed. Define the Area which can display ViewContent to the ViewContent. You can define several Areas. - -Syntax: -```shell -ViewContent [ID] { - description: [String] - allocatable: [ [ID of Area] | [ID of Set] ] - [ViewContentState] - [[Size]|sizeReference: [ID of Size]] - loserType: [GOOD_LOSER | DO_NOT_GIVEUP_UNTIL_WIN | NEVER_GIVEUP] -} -``` - -|Syntax element | Description| -| :--- | :---- | -|description: 0..1 | Description| -|allocatable: 0..* | Displayable Area. Specify the ID of displayable Areas or Sets with comma-separated.If don’t specify allocatable, should specify allocatable in the ViewContentSet that includes this ViewContent. | -| [ViewContentState] 1..* |Define the State of ViewContent.| -|[Size\|sizeReference:] 1..*|Size: Size definition| -||sizeReference: Reference to Size definition.| -||※One or more definitions of either Size or sizeReference are needed. Multiple definitions should be defined consecutively.| -|loserType: 0..1| Action on lost. Specify whether to cancel a request, if ViewContent is not displayed after arbitration. See "Types of Action on lost" for details. If not defined, consider it as "NEVER_GIVEUP".| - -Types of Action on lost - -|loserType | Description| -| :--- | :---- | -|GOOD_LOSER |When losing arbitration, cancel a request.| -|DO_NOT_GIVEUP_UNTIL_WIN |When the state is changed visible to invisible , cancel a request.| -|NEVER_GIVEUP|Keep a request.| - -Description example: -```shell -ViewContent Power { -description: " Warning from power management" - allocatable: [ - MessageArea, HUDMessageArea - ] - State Warning { - priority: > That-of Power.Attention - } - State Attention { - priority: > That-of TEL.Incoming - } -Size Default { -description: "Default size" -width: 200 -height: 200 -} - sizeReference: InterruptMessageSize - loserType: GOOD_LOSER -} -``` -#### 5.2 State(ViewContent) - -State is the state of the ViewContent. - -Syntax: -```shell -State [ID] { - description: [String] - [priority|value]: [Number|Expression] -} -``` - -|Syntax element | Description| -| :--- | :---- | -|description: 0..1 | Description -|[priority\|value]: 1 | Priority of ViewContent. | -||Describe the relative value for other State under ViewContent as an expression, or set a numerical value. | -||The following predefined value can be set as a String.NONE_VALUE, STANDARD_VALUE, MIN_VALUE, MAX_VALUE See "Priority definition"for details. | - -Description example: -```shell -State Warning { - description: "Display warning message" -priority: > That-of Attention -} -State Attention { - description: " Display attention message " -priority: > That-of TEL.Incoming -} -``` -### 6. Priority definition - -Define the priority of Content to the State under ViewContent or SoundContent (hereinafter, Content). The priority is used when the area / zone arbitration policy is "Priority and First Come First Arbitration" or "Priority and Last Come First Arbitration", the higher one is allocated first. Values can be defined absolutely by number or relative to other areas by expressions. You can describe only one of the visibility or priority. You can use comparison operators (> and <), equality operator (=) and That-of operator for the expressions. - -- Description example of value: -Priority of Warning is 10. -```shell -State Warning { - description: " Display warning message " -priority: 10 -} -``` -- Description example of comparison operator: -Value of Warning is greater than Attention. -
Value of Attention is greater than State Incoming of TEL of other Content. -
Value of Notice is less than Attention. -
※When referring to the State of another Content, refer to the Content ID and State ID by connecting with “.”. -```shell -State Warning { - value: > That-of Attention -} - -State Attention { - value: > That-of TEL.Incoming -} - -State Notice { - value: < That-of Attention -} -``` - -- Description example of range: Priority of Attention is greater than Incoming of TEL and less than Warning. -
※When referring to the State of another Content, refer to the Content ID and State ID by connecting with “.”. -```shell -State Attention { - priority: (> That-of TEL.Incoming AND < That-of Warning) -} -``` - -- Description example of equality operator:Value of Attention is equal to State Incoming of TEL of other Content. -```shell -State Attention { - priority: = That-of TEL.Incoming -} -``` -- Equality operator can be omitted. -```shell -State Attention { - priority: That-of TEL.Incoming -} -``` - -### 7. Screen layout definition - -#### 7.1. Display - -Display represents one screen. When defined more than one, it will be Multi-screen layout. -The Display defines the set of Areas to be allocated on the screen. - -Syntax: -```shell -Display [ID] { - description: [String] - [CompositeArea] - [[Size]|sizeReference:[ID of Size]] -} -``` - -|Syntax element | Description| -| :--- | :---- | -| description: 0..1 | Description| -|[CompositeArea] 1 | Component of the screen| -|[Size\|sizeReference:] 1 | Size: Size definition| -|| sizeReference: Reference to Size definition| -|| ※One or more definitions of either Size or sizeReference are needed. | - -Description example: -```shell -Display METER { - description:"Meter display definition" - Size FULLSCREEN { - width: 500 - height: 400 - } - CompositeArea METER_Root { - layout: FixedPositionLayout { - PositionContainer { - x: 100 - y: 100 - basePoint: LEFT_TOP - areaReference: SpeedMeterArea - } - } - } -} -``` - -#### 7.2. CompositeArea - -CompositeArea specifies an Area that becomes a component of Display. - -Syntax: -```shell -CompositeArea [ID] { - description: [String] - layout: [FixedPositionLayout] -} -``` - -|Syntax element | Description| -| :--- | :---- | -|description: 0..1 | Description | -|layout: [FixedPositionLayout] 1| Layout type of Area| - -Description example: -```shell -CompositeArea METER_Root { - description:" Definition of Area’s layout method" - layout: FixedPositionLayout { - PositionContainer { - x: 100 - y: 100 - basePoint: LEFT_TOP - areaReference: SpeedMeterArea - } - } -} -``` - -#### 7.3. FixedPositionLayout - -FixedPositionLayout declares that areas are laid out with fixed values. The specific position define by PositionContainer. - -Syntax: -```shell -FixedPositionLayout { - [PositionContainer] -} -``` - -|Syntax element | Description| -| :--- | :---- | -|[PositionContainer] 1..*| Position information.| - -```shell -FixedPositionLayout { - PositionContainer { - x: 100 - y: 100 - basePoint: LEFT_TOP - areaReference: SpeedMeterArea - } -} -``` -#### 7.4. PositionContainer - -PositionContainer specifies the display position of the Area. - -syntax: -```shell -PositionContainer { - x: [Number] - y: [Number] - basePoint: [Value] - areaReference: [ID of Area] - [Offset] -} -``` - -|Syntax element | Description| -| :--- | :---- | -|x: 1 |x position| -|y: 1 |y position| -|basePoint: 1 | Defined x, y position. The following predefined value can be set.| -|| CENTER_BOTTOM (Define x, y as the lower center position)| -|| CENTER_MIDDLE(Define x, y as center position)| -|| CENTER_TOP (Define x, y as the upper center position)| -||LEFT_BOTTOM (Define x, y as the lower left position)| -||LEFT_MIDDLE (Define x, y as the left center position)| -||LEFT_TOP (Define x, y as the upper left position)| -||RIGHT_BOTTOM (Define x, y as the lower right position)| -||RIGHT_MIDDLE (Define x, y as right center position)| -||RIGHT_TOP (Define x, y as the upper right position)| -|areaReference: 1| Area to be placed in Display. Specify ID of the Area.| -|[Offset] 0..*| Display position offset of AreaSpecify the position of the Area for each size.| - - -Description example: -```shell -FixedPositionLayout { - PositionContainer { - x: 100 - y: 100 - basePoint: LEFT_TOP - areaReference: SpeedMeterArea - Offset { x:-50 y:20 sizeReference: SpeedMeterArea } - } -} -``` -#### 7.5. Offset - -Offset is the offset position for each size. - -Syntax: -```shell -Offset { - description: [String] - x: [Number] - y: [Number] - sizeReference: [ID of Size] -} -``` - -|Syntax element | Description| -| :--- | :---- | -|description: 0..1| Description| -|x: 1| Offset from x position of PositionContainer.| -|y: 1| Offset from y position of PositionContainer.| -|sizeReference: 1| Size to apply the offset. Specify ID of Size.| -||※ This Size must be specified in Area.| - -Description example: -```shell -Offset { -description:"Offset" - x: 100 - y: -50 - sizeReference: SpeedMeterSize -} -``` - -### 8. Constraint defination - -Constraints can be defined according to the state of the Area/Zone and the state of the ViewContent/SoundContent. The syntax can be used for Constraints is shown below. - -- State reference of Area: - -|Name | Notation |Meaning| -| :--- | :---- | :---- | -|IsDisplayed | .isDisplayed()| The Area is displayed. (At this time, the ViewContent is necessarily allocated to the Area) True if the Area is displayed.| -|DisplayingContent| .displayingContent()| ViewContent which is displayed in the Area. When the Area is hidden or ViewContent is not allocated, it is not evaluated. -|AllocatedContent| .allocatedContent()| ViewContent which is allocated to the Area. Even if the Area is hidden after allocation, it is possible to refer to the allocated ViewContent.| -|IsHidden| .isHidden() |The Area is hidden. Regardless of whether the ViewContent is allocated to the Area or not,true if the Area is hidden.| -|ContentValue| .contentValue()| The value of the ViewContentState allocated to the Area. If ViewContent is not allocated to the Area, it is not evaluated.| -|ContentsList| .contentsList()| A set of ViewContent which is allocatable to the Area.| -|activeContents| .activeContents() |The set of active content amang the ViewContent which is allocatable to the Area| - -- State reference of ViewContent: - -|Name | Notation |Meaning| -| :--- | :---- | :---- | -|IsActive| .isActive()| True if there is a Content request of ViewContent.| -|IsVisible| .isVisible()| The ViewContent is displayed. True if the ViewContent is allocated to any Area.| -|StateValue |.stateValue() |Priority/value that is defined in active state of the ViewContent. When the ViewContent has no active state, it does not evaluate.| -|HasComeEarlierThan| .hasComeEarlierThan()| True if the ViewContentA’s request has come earlier than the ViewContentB’s. When the either ViewContent has been not requested, it does not evaluate.| -|HasComeLaterThan| .hasComeLaterThan() |True if the ViewContentA’s request has come later than the ViewContentB’s. When the either ViewContent has been not requested, it does not evaluate.| -|Allocatables| .allocatables()| A set of Areas where the ViewContent can be displayed.| - -- Scene reference: - -|Name | Notation |Meaning| -| :--- | :---- | :---- | -|IsOn| .isOn()| True if the Scene is valid.| -|Get| ..get()| Get scene property value.| - -- Stereotyope: - -|Name | Notation |Meaning| -| :--- | :---- | :---- | -|isTypeOf| .isTypeOf(“”)| Whether or not “” is used in the | -|||It can be applied to the following models Area,ViewContent| - -- Operator: - -|Name | Notation |Meaning| -| :--- | :---- | :---- | -|AND| AND | True if all Bool expressions are true.| -|OR| OR |True if any Bool expression is true.| -|Negation| ! | True if Bool expression is false.| -|Implication| -> | A -> B is equivalent to ((A AND B) OR !A).| -|Equal sign (Comparison of values)| = | True if the values shown on the left-hand side and the right-hand side are identical.The type of left-hand side and the right-hand side expressions must match.| -|Equal sign (Comparison of objects) | == | True if the values shown on the left-hand side and the right-hand side are identical.The type of left-hand side and the right-hand side expressions must match.| -|Comparison (greater than) | \> |True if the Number on the left-hand side is greater than the Number on the right-hand side.| -|Comparison (greater than)| \>= |True if the Number on the left-hand side is greater than equal to the Number on the right-hand side.| -|Comparison (less than)| < | True if the Number on the left-hand side is less than the Number on the right-hand side.| -|Comparison (less than)| <= | True if the Number on the left-hand side is less than the equal to Number on the right-hand side.| - -- Quantization symbol: - -|Name | Notation |Meaning| -| :--- | :---- | :---- | -|∀(For All) |For-All{ \| } | contains the ViewContentSet or the SoundContentSet, the AreaSet, the ZoneSet, and the One-time Set. True if is true for all set element .| -|∃(Exists)| Exists< Set\>{ \| } | contains the ViewContentSet or the SoundContentSet, the AreaSet, the ZoneSet, and the One-time Set. True if < Set\> has one or more elements that satisfy .| - -- Built-in defined Expression: - -|Name | Notation |Meaning| -| :--- | :---- | :---- | -|All Area| ALL_AREAS| A set of all the Areas defined in the Model.| -|All ViewContent| ALL_VIEWCONTENTS| A set of all the ViewContents defined in the Model.| -|IF-THEN-ELSE Syntax| IF ()THEN ELSE | The type of the expression must be identical, for the THEN clause, if the Bool expression is true, for THEN and ELSE clause ,if the Bool expression is false.| -|Let　Expression| let = | Evaluate 　as variable , which can then be referenced in subsequent expressions| -|||Can only be used inside the expression. For-All, Exists, Max, Min, Select| -|Pre-arbitration value specifier| (pre) | Refere to the state before arbitration of Area, ViewContent, Property.| - -**The syntax precedence and associativity are shown below:** - -|Priority| Name| Notation| Connectivity| -| :--- | :---- | :---- | :---- | -|1 |Parentheses| () |-| -|2| ∃(Exists)| Exists{ \| }|-| -|| ∀(For All)| For-All{ \| }| -| -|| IF-THEN-ELSE Syntax| IF () THEN ELSE | -| -||SetOf operator| { , }| -| -|| Pre-arbitration value specifier| (pre)| -| -|3|Predicate connector |.| Left| -|4 |Negation| ! | Right| -|5| Comparison (less than)| < | Left| -|| Comparison (greater than)| \> |Left| -|| Comparison (less than)| <= | Left| -|| Comparison (greater than)| \>= | Left| -|6| Equal sign (Comparison of values)| = | Left| -|| Equal sign (Comparison of objects)| == | Left| -|7| AND| AND |Left| -|8 |OR| OR | Left| -|9 |Implication| -\> | Left| - - -#### 8.1 Constraint - -Constraint describes constraint expressions. There are two types of constraint expressions Runtime constraints and Offline constraints. A Runtime constraint is a constraint expression that should be be true at the time of arbitration and controls the behavior of arbitration. An Offline constraint is a constraint expression that should be satisfied after arbitration and tests the arbitration result. - -Syntax: -```shell -Constraint [ID] { - description: [String] - runtime: [true|false] - [expression] -} -``` - -|Syntax element |Description| -| :--- | :---- | -|description: 0..1| Description| -|runtime: 1 |true: Runtime constraint| -||Arbitrate each Area / Zone to be true this constraint.| -||false: Offline constraint| -||Verify that this constraint is true after all Area arbitration.| -|[expression] 1| Constraint expression| - -Description example - -- AND/ OR/ Negation -
In the constraint expression, it is possible to express logical AND, logical OR, negation, which is a general logical operator, with AND, OR, and !. By using () you can also use in combination. - -Example: Content1 is displayed or Content2 and Content3 are not displayed at the same time. -```shell -Constraint SampleConstraint1 { -runtime: true -Content1.isVisible() OR !(Content2.isVisible() AND Content3.isVisible()) -} -``` -Example: SampleContent1 is displayed or SampleContent2 is not displayed. -```shell -Constraint SampleConstraint1 { - description: "Sample Constraint Expression" - runtime: true - SampleContent1.isVisible() OR !SampleContent2.isVisible() -} -``` - -- Implication - -Implications are false only if the left-hand side is true and the right-hand side is false, otherwise it is true. - -Example: SampleContent4 is displayed if there is a request of SampleContent4. -```shell -Constraint SampleConstraint3 { - runtime: true - SampleContent4.isActive() -> SampleContent4.isVisible() -} -``` - -Example: If SampleArea1 displays SampleContent3, SampleArea2 does not display SampleContent3. -```shell -Constraint SampleConstraint2 { - runtime: true - (SampleArea1.displayingContent() == SampleContent3) --> !(SampleArea2.displayingContent() == SampleContent3) -} -``` - -Example: If the value of the content displayed on SampleArea1 is higher than the value of the content displayed in SampleArea2, hide SampleArea2. -```shell -Constraint SampleConstraint2 { - runtime: true - (SampleArea1.contentValue() > SampleArea2.contentValue()) --> SampleArea2.isHidden()) -} -``` - -Example: If the value of property1 of the information received from other RBAModel (Project) is 1, Content10 is not displayed. -```shell -Constraint SampleConstraint { - (SampleScene1.isOn() AND SampleScene1.property1.get() = 1) - -> ! Content10.isVisible() -} -``` - -- For-All - -For-All targets a set, and it is true if all element of the set satisfies a lambda expression ({element name declaration | element condition}). -For the set, you can specify a defined set or an One-time set. (Refer to “Group definition” for more informations.) -
Example: If SampleContent1 is displayed, all Areas of AreaGroup1 is not displayed. -
It is assumed that "AreaGroup1" is defined as AreaSet. - -```shell -Constraint SampleConstraint { - runtime: true - SampleContent1.isVisible() -> -For-All AreaGroup1 { x | x.isHidden() } -} -``` - -- Exists - -Exists targets a set, and it is true if even one element of the set satisfies a Lambda expression ({element name declaration | element condition}). -
For the set, you can specify a defined set or an One-time set. (Refer to “Group definition” for more informations.) -
Example: If any Content of ContentGroup1 is displayed, all Areas of AreaGroup1 is not displayed. -
It is assumed that "ContentGroup1" is defined as ContentSet. -
It is assumed that "AreaGroup1" is defined as AreaSet. -```shell -Constraint SampleConstraint { - runtime: true - Exists ContentGroup1{ x | x.isVisible() } -> -For-All AreaGroup1 { x | x.isHidden() } -} -``` - -- IF-THEN-ELSE -Example: If the scene is SampleScene1, SampleContent4 is displayed, otherwise SampleContent4 is not displayed. - -```shell -Constraint SampleConstraint4 { - runtime: true - IF(SampleScene1.isOn()) - THEN - SampleContent4.isVisible() - ELSE - !SampleContent4.isVisible() -} -``` - -- (pre) -Example: If SampleContent 1 is displayed (before arbitration), SampleContent 2 is not displayed. -```shell -Constraint SampleConstraint { - runtime: true -(pre)SampleContent1.isVisible() -> !SampleContent2.isVisible() -} -``` - -- HasComeEarlierThan/HasComeLaterThan -Example: If request SampleContent 1 has come earlier then SampleContent 2, SampleContent 2 does not displayed. -```shell -Constraint SampleConstraint { - runtime: true -SampleContent1.hasComeEarlierThan(SampleContent2) -> !SampleContent2.isVisible() -} -``` -Below constraint behave as same as above. -```shell -Constraint SampleConstraint { - runtime: true -SampleContent2.hasComeLaterThan(SampleContent1) -> !SampleContent2.isVisible() -} -``` - -#### 8.2 Syntax sugar - -This syntax sugar simplifies the constraint expressions and improves their readability. You can use them like the existing constraint expressions. -Below are the syntax sugars that can be used. - -- Inequality（!=） -
It means that the left side value and the right side value are not equal. You can use this to compare objects. -True if the left side value and the right side value are not equal. -The types of expressions on the left and the right sides must match. - -|Type| Operator| -| :--- | :---- | -|Notation| != | -|ECE*| !( == )| - -*ECE: Equivalent constraint expression - -Description example: The ViewContent allocated to AreaA is not Content1. - -||| -| :--- | :---- | -|Notation| AreaA.allocatedContent() != Content1| -|ECE| !( AreaA.allocatedContent() == Content1)| - -- Allocation of Area/Zone -
It indicates that ViewContent/SoundContent is allocated to the Area/Zone. -True if theViewConten/SoundContentt is allocated to the Area/Zone. - -|Type| State reference of ViewContent| -| :--- | :---- | -|Notation| .isAllocatedTo()| -|ECE| .allocatedContent() == | - -Description example: The Content1 is allocated to the AreaA. - -||| -| :--- | :---- | -|Notation| Content1.isAllocatedTo(AreaA)| -|ECE| AreaA.allocatedContent() == Content1| - -- Allocation changing of Area/Zone -
It indicates a changing of the ViewContent’s/SoundContent’s allocated to the Area/Zone. -True if the changing happens. - -|Type |State reference of Area| -| :--- | :---- | -|Notation| .isChanged()| -|ECE| !((pre).allocatedContent() == .allocatedContent())| - -Description example: The ViewContent allocated to AreaA has changed. - -||| -| :--- | :---- | -|Notation| AreaA.isChanged()| -|ECE| !((pre)AreaA.allocatedContent() == AreaA.allocatedContent())| - -- Changing of a content allocated to Area/Zone -
It indicates whether a ViewContent/SoundContent allocated to the Area/Zone has changed to the specified ViewContent/SoundContent.True if the changing happens - -|Type |State reference of Area| -| :--- | :---- | -|Notation| .isTranslatedTo()| -|ECE| !((pre).allocatedContent() == ) AND (.allocatedContent() == )| - -Description example: A ViewContent allocated to the AreaA has changed to Content1. - -||| -| :--- | :---- | -|Notation| AreaA.isTranslatedTo(Content1)| -|ECE |!((pre)AreaA.allocatedContent() == Content1) AND (AreaA.allocatedContent() == Content1)| - -- Displaying in the Area -
It indicates whether the ViewContent displayed or not in the Area. -True if the ViewContent is displayed in the Area. - -|Type| State reference of ViewContent| -| :--- | :---- | -|Notation| .isDisplayedOn()| -|ECE| .isDisplayed() AND (.displayingContent() == )| - -Description example: The Content1 is displayed in the AreaA. - -||| -| :--- | :---- | -|Notation| Content1.isDisplayedOn(AreaA)| -|ECE| AreaA.isDisplayed() AND (AreaA.displayingContent() == Content1)| - -- Display changing of the Area -
It indicates whether the display of the Area changes or not. -True if the change happens. - -|Type |State reference of Area| -| :--- | :---- | -|Notation| .isChangedDisplay()| -|ECE |!((pre).displayingContent() == .displayingContent()) OR ((pre).isDisplayed() AND !.isDisplayed()) OR (!(pre).isDisplayed() AND .isDisplayed())| - -Description example: The display of the AreaA has changed. - -||| -| :--- | :---- | -|Notation |AreaA.isChangedDisplay()| -|ECE |!((pre)AreaA.displayingContent() == AreaA.displayingContent()) OR((pre)AreaA.isDisplayed() AND !AreaA.isDisplayed()) OR(!(pre)AreaA.isDisplayed() AND AreaA.isDisplayed())| - -- Changing of the displayed ViewContent to the specified ViewContent -
It indicates whether the ViewContent displayed in the Area has changed to anther specified ViewContent. -True if the change happens. - -|Type |State reference of Area| -| :--- | :---- | -|Notation| .isTranslatedViewTo()| -|ECE |(.isDisplayed()) AND (.displayingContent() == ) AND (!((pre).displayingContent() == ) OR !(pre) .isDisplayed())| - -Description example: A ViewContent displayed in the AreaA has changed to another Content1. - -||| -| :--- | :---- | -|Notation| AreaA.isTranslatedViewTo(Content1)| -|ECE| (AreaA.isDisplayed()) AND (AreaA.displayingContent() == Content1) AND (!((pre)AreaA.displayingContent() == Content1) OR !(pre)AreaA.isDisplayed())| - -- Hide a lower priority Area -
Compare the two Areas and hide the Area displaying a ViewContent with lower priority. - -|Type| State reference of Area| -| :--- | :---- | -|Notation| HideLowerPriority(, )| -|ECE| ((.contentValue() < .contentValue() -\> .isHidden()) AND (.contentValue() \> .contentValue() -\> .isHidden()))| - -Description example: AreaA and AreaB are compared to hide the Area which displays a ViewContent with lower priority. - -||| -| :--- | :---- | -|Notation| HideLowerPriority(AreaA, AreaB)| -|ECE| ((AreaA.contentValue() < AreaB.contentValue() -\> AreaA.isHidden()) AND (AreaA.contentValue() \> AreaB.contentValue() -\> AreaB.isHidden()))| - -### 9. Group definition - -#### 9.1 AreaSet - -When dealing with multiple Areas in the Constraint expression, in order to describe it simply, you can define multiple Areas together in one group. - -Syntax: -```shell -AreaSet [ID] { - description: [String] - target: [ [ID of Area] ] -} -``` - -|Syntax element | Description| -| :--- | :---- | -|description: | 0..1 Description| -|target: 0..* | Areas or AreaSets which compose the group. Specify the ID of the Area or the AreaSet with comma-separated.| - -Description example: -```shell -AreaSet MainScreen { - description: "Area constituting the main screen" - target: [SampleArea, SampleArea1, OtherAreaSet] -} -``` -#### 9.2 ViewContentSet - -When dealing with multiple ViewContents in the Constraint expression, in order to describe it simply, you can define multiple ViewContents together in one group. - -Syntax: -```shell -ViewContentSet [ID] { - description: [String] - allocatable: [ [ID of Area] ] - target: [ [ID of ViewContent] ] -} -``` - -|Syntax element | Description| -| :--- | :---- | -|description: | 0..1 Description| -|allocatable: 0..*| Displayable Areas or AreaSets.Specify the ID of the Areas or the AreaSets with comma-separated.| -|target: 0..*| ViewContents or ViewContentSets which compose the group. Specify the ID of the ViewContents or ViewContentSets with comma-separated.| - -Description example: -```shell -ViewContentSet InterruptContent{ - allocatable: [ - MessageArea, HUDMessageArea, InterruptAreaGroup - ] - target: [ - TEL,Power, ViewContentGroup - ] -} -``` - -#### 9.3 One-time Set - -Specify an set in the For-All or the Exists constraint, you can define the One-time set. - -Syntax: -```shell -{ [ID] } -``` - -|Syntax element | Description| -| :--- | :---- | -|[ID] 1..* |Element of the set. Specify the IDs of elements with comma-separated. -||The type of elements should be same.| -||At this time, Area and AreaSet regard it as the same type.( ViewContent and ViewContentSet are treat similarly.) - -- Description example: Define the One-time set as AreaSet. -```shell -Constraint SampleConstraint { - runtime: true - SampleContent1.isVisible() -> -For-All {Area1, Area2, Area3} { x | x.isHidden() } -} -``` - -- Description example: Define the One-time set as ViewContentSet. -```shell -Constraint SampleConstraint { - runtime: true - Exists {ViewContent1, ViewContentSet1} { x | x.isActive() -> x.isVisible() } -} -``` -### 10. Scene definition -#### 10.1 Scene -Scene comprehensively expresses the state at the time including the system, and it is used to switch the status of Area/Zone, View/Sound Content by Scene. You can also define the Global scene and share the results of arbitration among multiple RBA Models (Projects). - -Syntax: -```shell -Scene [ID] { - description: [String] - global: [true|false] - [Property] -} -``` - -|Syntax element | Description| -| :--- | :---- | -|description: 0..1| Description| -|global: 0..1| true: Global Scene for sharing arbitration results with other RBA Models (Projects).| -||false: Local Scene.| -||If not defined, consider it as "false".| -|[Property] 0..*| Information for sharing arbitration results with other RBA models (Projects).| -||Can define only if global is true.| - -Description example: -```shell -Scene AutoDrivingScene { - description: "In auto driving mode" -} - -Scene DisplayEventNotification { - global: true - int OverallPriority: 6 - int RiskSeverity: 3 - int RiskMargin: 1 -} -``` -#### 10.2 Property - -Property is arbitrary properties which is defined in the Scene. - -Syntax: -```shell -int [String]: [Number] -``` - -|Syntax element | Description| -| :--- | :---- | -|[String] 1 |Arbitrary Property name| -|[Number] 1 |Default value of Property. Positive integer can be specified.| - -Description example: -```shell -int RiskSeverity: 3 -``` - -### 11. Stereotype - -Syntax: -```shell -StereoType<[Target Model Name]> [ID] ([valiable]) @BEGIN@ -description: [String] - [Propaties of Element] -@END@ -``` - -|Syntax element | Description| -| :--- | :---- | -|description: 0..1| Description| -|[Target Model Name] 1| Identify the applicable model by describing the model element keywords| -||It can be applied to the Area, ViewContent models| -|[valiable] 0..*| Describe an arbitrary variable as the parameter to be replaced, which will be set in the property of the model element specified in [Target Model Name].If there are multiple variables, separate them with commas.| -|[Properties of Element] 1..*| Describe the properties of the model element specified in [Target Model Name].In the property, the value to be replaced is written in @{[variable]} .| -||The variables must match the variables described in ().| - -Description example: -```shell -Stereotype display_warnning (name,allocatable,priority) @BEGIN@ - description: “@{name}” - allocatable: [@{allocatable}] - Size WarnSize { - width: 300 - height: 100 - } - State NORMAL { piority: @{priority} } - -@END@ -``` - -### 12. Tag - -Syntax: -```shell -<<[Stereotype ID]>> | <<[Stereotype ID]>>{“[String]”} -``` - -|Syntax element | Description| -| :--- | :---- | -|[ID of Stereotype] 0..*| Can be assigned to Area, ViewContent| -||If StereoType is defined, then the child elements and attributes defined there will be expanded as child elements and attributes of this object| -||Multiple definitions can be made for a single model. To define more than one, define them consecutively.| -|[String] 0..* |Argument value| -||If there is no argument, it can be omitted| - -Description example: -```shell -ViewContent Warning_1 { - <>{ “Warning_01”,”Area1”,“1” } -} - -ViewContent Warning_2 { - <>{ “Warning_02”,”Area2”,”2” } -} - -Stereotype display_warnning (name,allocatable,priority) @BEGIN@ - description: “@{name}” - allocatable: [@{allocatable}] - Size WarnSize { - width: 300 - height: 100 - } - State NORMAL { piority: @{priority} } -@END@ -``` - -## Generate .json from .rba file -Download [prebuilt package](https://git.automotivelinux.org/staging/rba-tool/tree/tool_bin) - -- If some errors occur, RBAModel.json is not generated (exit code 1). -```` -java -cp ./ -jar JSONGenerator.jar "[path to model directory]" "[path to output directory]" -```` - -Example: - -- RBAModel.json file is generated in directory same as JSONGenerator.jar -```` -java -cp ./ -jar JSONGenerator.jar "./RBAModel.rba" -```` - -- RBAModel.json file is generated in ~/ directory -```` -java -cp ./ -jar JSONGenerator.jar "./RBAModel.rba" "~/" -```` -Note: For the reference .rba file is given under the path [prebuilt package/sample_model](https://git.automotivelinux.org/staging/rba-tool/tree/tool_bin/sample_model) diff --git a/docs/5_Component_Documentation/4_drm-leasemanager.md b/docs/5_Component_Documentation/4_drm-leasemanager.md deleted file mode 100644 index 3b7b2e9..0000000 --- a/docs/5_Component_Documentation/4_drm-leasemanager.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: DRM lease manager ---- - -# DRM Lease Manager - -## Overview - -The DRM Lease Manager is used in AGL to allocate display controller outputs to different processes. Each process has direct access to its allocated output via the kernel DRM interface, and is prevented from accessing any other outputs managed by the display controller. - -The display controller partitioning is made possible by using the kernel DRM Lease feature. For more information on the DRM lease functionality, please see the Linux kernel [DRM userspace API documentation](https://www.kernel.org/doc/html/latest/gpu/drm-uapi.html). - - -## Usage - -### Building DRM Lease manager and sample clients - -Enable the `agl-drm-lease` AGL feature when setting up your build environment -with aglsetup.sh. - -This will add the drm-lease-manager package to the image, and will add DRM -lease support to the following packages: - -* weston -* kmscube - -kmscube is not included in the image by default. To add the package to the -image, add the following to your local.conf - -``` -IMAGE_INSTALL_append = " kmscube" -``` - -### Starting the DRM lease manager - -The drm-lease-manager must be the only process to directly open the DRM device. -Shut down any running window systems (eg. weston or agl-compositor) and run: - -```shell - systemctl start drm-lease-manager -``` - -This will create a lease for each output connection on the platform. -The name of each lease will be in the form of `card0-` - (eg. `card0-LVDS-1` or `card0-HDMI-A-1`) - -**Note**: `drm-lease-manager` can be started on a different display controller (i.e. not `card0`) by modifying the command line in the systemd unit file. - -Run the help command for details. - -```shell - drm-lease-manager --help -``` - -### Running weston - -weston can be started on any available DRM lease by running with the -`--drm-lease=` option. - -```shell - weston --drm-lease=card0-HDMI-A-1 -``` - -### Running kmscube sample -With the `drm-lease-manager` running, `kmscube` can display on any available -lease by launching it with the `-L -D` options. - -```shell - kmscube -L -Dcard0-HDMI-A-1 -``` - -Multiple weston or kmscube instances (one per DRM lease) can be started at the same time. - -## Adding support to your application - -The DRM Lease Manager packages includes a client library (libdlmclient) to request access to the DRM leases it creates. The client library provides file descriptors that can be used as if they were created by directly opening the underlying DRM device. - -Clients that want _direct access_ to the DRM device can use this library to do so. Compositor (agl-compositor or weston) client applications do not need to use this interface. - - -To use the DRM leases, clients only need to replace their calls to -`drmOpen()` and `drmClose()` with the appropriate libdlmclient API calls. - -### libdlmclient API usage - -_Error handling has been omitted for brevity and clarity of examples._ - -#### Requesting a lease from the DRM Lease Manager - -```c - struct dlm_lease *lease = dlm_get_lease("card0-HDMI-A-1"); - int drm_device_fd = dlm_lease_fd(lease); -``` - -`drm_device_fd` can now be used to access the DRM device - -#### Releasing a lease - -```c - dlm_release_lease(lease); -``` - -**Note: `drm_device_fd` is not usable after calling `dlm_release_lease()`** - -## Runtime directory -A runtime directory under `/var` is used to keep the Unix Domain sockets that the drm-lease-manager and clients to communicate with each other. - -The default path is `/var/run/drm-lease-manager`, but can be changed by setting the `DLM_RUNTIME_PATH` environment variable. diff --git a/docs/5_Component_Documentation/5_application_framework.md b/docs/5_Component_Documentation/5_application_framework.md deleted file mode 100644 index 1af8796..0000000 --- a/docs/5_Component_Documentation/5_application_framework.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Application Framework ---- - -# AppFW - -FIXME. diff --git a/docs/5_Component_Documentation/6_pipewire_wireplumber.md b/docs/5_Component_Documentation/6_pipewire_wireplumber.md deleted file mode 100644 index e58b97d..0000000 --- a/docs/5_Component_Documentation/6_pipewire_wireplumber.md +++ /dev/null @@ -1,159 +0,0 @@ ---- -title: PipeWire / WirePlumber ---- - -# PipeWire / WirePlumber - -## Overview - -AGL uses the PipeWire daemon service to provide audio playback and capture capabilities. -PipeWire is accompanied by a secondary service, WirePlumber (also referred to as the -*session manager*), which provides policy management, device discovery, configuration and more. - -Applications can connect to the PipeWire service through its UNIX socket, by using either the -*libpipewire* or *libwireplumber* libraries as a front-end to that socket. - -Upstream documentation for these components can be found at the links below: - -- [PipeWire documentation](https://docs.pipewire.org/) - -- [WirePlumber documentation](https://pipewire.pages.freedesktop.org/wireplumber/) - -- [PipeWire Wiki](https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/home) - -## APIs - -### libpipewire - -The main entry point for applications to access the audio system is the API offered by -*libpipewire*. The functionality offered by *libpipewire* is vast and it is beyond the -scope of this document to describe it all. - -For playback and capture, applications should use *struct pw_stream* and its associated methods. -See [PipeWire: Tutorial - Part 4: Playing a tone](https://docs.pipewire.org/page_tutorial4.html) -for a starting point. - -### GStreamer (Recommended) - -For convenience, applications that use GStreamer can use the PipeWire GStreamer elements to -plug the functionality offered by *struct pw_stream* directly in the GStreamer pipeline. These -elements are called *pipewiresrc* and *pipewiresink* - -Example: - -```shell -> gst-launch-1.0 audiotestsrc ! pipewiresink -``` - -Through these elements, it is possible to specify the application role by setting it in the -*stream-properties* property of the element, as shown below: - -```shell -> gst-launch-1.0 audiotestsrc ! pipewiresink stream-properties="p,media.role=Multimedia"" -``` - -or, in the C API: - -```c -gst_util_set_object_arg (sink, "stream-properties", "p,media.role=Multimedia"); -``` - -Of course, it is also possible to use *alsasink* and *alsasrc* and route audio through the -virtual ALSA device that is mentioned below. This is also the default behavior of *playbin* -and similar auto-plugging elements, because the PipeWire GStreamer elements are not autoplugged -(this may change in a future version). - -### ALSA - -PipeWire offers a virtual ALSA device (called *pipewire*) that redirects audio to PipeWire -through an ALSA PCM plugin. This device is the default one, so unless you explicitly specify -a device in your ALSA client application, audio will go through PipeWire instead. - -Example: - -```shell -> aplay sound.wav # the default device is 'pipewire' -> aplay -D pipewire sound.wav -``` - -In order to specify the application role while using the ALSA compatibility device, pass the role -as a device parameter like this: - -```shell -> aplay -D pipewire:ROLE=Navigation turnleft.wav -``` - -### Audiomixer service - -See the separate [agl-service-audiomixer](https://git.automotivelinux.org/apps/agl-service-audiomixer/about/) documentation. - -### libwireplumber - -The WirePlumber library provides API that wraps libpipewire and makes it easier to work with -when you are writing control applications, such as a volume mixer. The audiomixer service is in -fact implemented using *libwireplumber*. - -WirePlumber also provides support for lua-based scripting. Standalone scripts, executed with the -*wpexec* tool, may be used as a means to rapidly make use of the API provided by *libwireplumber* - -## Tools - -* **wpctl**: allows inspecting the devices, choosing which source & sink are the default ones - and allows volume/mute adjustments to be made on the command line. Try `wpctl status` and - `wpctl help` to get started with it - -* **wpexec**: allows running wireplumber lua scripts standalone, which is useful to implement - custom scripts to interact with PipeWire - -* **pw-cli**: this is the main tool for interacting with pipewire directly - -* **pw-dump**: dumps all the objects in the pipewire graph to a big JSON. The output of this - tool is very useful to include in bug reports. It is also suitable for implementing scripts - that parse information with jq - -* **pw-dot** is a useful debug tool that dumps the objects in a dot graph for easy visualization - -* **pw-cat / pw-play / pw-record**: This is a set of tools similar to aplay/arecord, for simple - audio operations - -* **pw-top**: This is a performance measurement tool that shows realtime timing information - about the audio pipeline. Before running this tool, you will need to uncomment the loading - of "libpipewire-module-profiler" in /etc/pipewire/pipewire.conf and restart pipewire - -## Systemd Integration - -The PipeWire service, `pipewire.service`, is activated on demand, via systemd socket activation, -by `pipewire.socket`. The WirePlumber service, `wireplumber.service`, is bound to the pipewire -service and therefore started and stopped together with the PipeWire service. - -If you wish to manually stop or restart both services, you can do so by using *systemctl*, -operating on the *.socket* unit: - -```shell -> systemctl restart pipewire.socket -> systemctl stop pipewire.socket -``` - -## Debugging - -The PipeWire daemon can be configured to be more verbose by editing -**/etc/pipewire/pipewire.conf** and setting `log.level=n` (n=0-5) in section -`context.properties`. - -Similarly, the WirePlumber daemon can be configured to be more verbose by editing -**/etc/wireplumber/wireplumber.conf** and setting `log.level=n` (n=0-5) in section -`context.properties`. - -All messages will be available in the systemd journal, inspectable with journalctl. - -For applications, at runtime, `PIPEWIRE_DEBUG` can be set to a value between 0 and 5, -with 5 being the most verbose and 0 the least verbose. - -For applications that use *libwireplumber* the equivalent environment variable is -`WIREPLUMBER_DEBUG`, which also takes values between 0 and 5. - -The default debug level for the daemons is 2, while for applications it's 0 -(with few exceptions). - -More information is also available on -[WirePlumber's documentation on debug logging](https://pipewire.pages.freedesktop.org/wireplumber/daemon-logging.html) diff --git a/docs/5_Component_Documentation/7_ic-sound-manager.md b/docs/5_Component_Documentation/7_ic-sound-manager.md deleted file mode 100644 index 75e163e..0000000 --- a/docs/5_Component_Documentation/7_ic-sound-manager.md +++ /dev/null @@ -1,120 +0,0 @@ -# Instrument Cluster Sound Management - -## Introduction - -This document describes the design of the software setup which enables the integration -of AGL’s sound system with applications running in the Instrument Cluster domain. -This software setup is specific to the case where a single system is used to implement -both the Instrument Cluster and some other domain of the vehicle, typically the -In-Vehicle-Infotainment domain, using container technology to separate them. - -Applications running in the Instrument Cluster need a way to safely play important -sounds to alert the driver of conditions that need the driver’s attention. At the same -time, in a containerized environment that serves multiple vehicle domains, applications -running in other containers may be using the sound hardware to play less important sounds, -such as music, which conflicts with the IC’s need to play sound on the same hardware. - -The solution developed here, for safety reasons, relies on the operating system and the -hardware itself to allow the IC applications to stream sounds to the speakers using a -dedicated device handle, while applications from other domains are all routed through a -sound server that runs on the host container and operates on a different sound device handle. - -However, to achieve good inter-operation, there is need for additional software mechanisms -that will work in combination with this hardware-based solution. First of all, it is necessary -to have a mechanism that allows IC applications to pause all sounds that are being routed via -the sound server while there is an important IC sound playing and resume them afterwards. -This is so that other domain applications can be informed of this temporary pause and offer -the appropriate user experience. Secondly, it is desirable to have separation of duties -between the host and the other domain’s (non-IC) container. It should be the responsibility -of the other domain’s container to implement the sound system policy, so that the host does -not need to be aware of the exact applications that are running on this container. - -## Requirements - -- Single system shared between IC and at least one secondary domain (IVI, other ...) - -- The domains are separated using containers - -- All the containers, including the host, are running a variant of AGL - -- The host OS and the secondary domain container use PipeWire and WirePlumber - to implement the sound system - -- The sound hardware offers, on the Linux kernel driver side, a separate ALSA - device for sounds that belong to the IC and a separate ALSA device for other sounds - -## Architectural design - -![Architecture overview](images/ic-sound-manager/architecture.png) - -The core of the sound system consists of the PipeWire daemon, which is responsible for routing -audio between the kernel and applications running in the “Other Container”. - -The PipeWire session is orchestrated by a secondary daemon, WirePlumber. WirePlumber is -designed in such a way so that it can have multiple instances, for task separation. -One instance shall be running in the host container and it shall be responsible for -managing the devices that PipeWire handles as well as the security isolation between -different applications and different containers. At least one more instance shall be -running in the “Other Container” and be responsible for implementing policy mechanisms -related to the applications that are running in that container. - -Further WirePlumber instances are possible to run as well. For instance, it may be desirable -to have another “policy” instance in a third container that implements another vehicle system -and shares the main PipeWire daemon from the host. Additionally, the “Other Container” may -be running a separate WirePlumber instance to manage bluetooth audio devices, which shall be -the responsibility of that container instead of the host. - -To implement communication between the IC and the host, a third daemon is used: pipewire-ic-ipc. -This daemon listens on a UNIX domain socket for messages from the IC applications and offers -them the ability to pause or resume sounds that are being routed via PipeWire. - -Finally, IC applications are given a library (icipc library) that allows them to send messages -to pipewire-ic-ipc on the host. This library is minimal and has no external dependencies, -for safety reasons. - -For sound playback, IC applications are expected to use the ALSA API directly and communicate -with the dedicated ALSA device that is meant for IC sounds. Arbitration of this device between -different IC applications is out of scope for this document and it is assumed to be a solved -problem. - -### PipeWire-IC-IPC - -This component acts as the server-side component for the UNIX socket that is used for -communication between the IC applications and the host. It is implemented as a pipewire module, -therefore it needs the `/usr/bin/pipewire` process in order to be launched. Launching happens -with a special configuration file (`pipewire-ic-ipc.conf`) which instructs this PipeWire process -to be launched as a client (`core.daemon = false`) and to load only `module-ic-ipc` together -with `module-protocol-native`. The latter enables communication with the daemon instance of -PipeWire (`core.daemon = true`), which implements the sound server. - -![PipeWire-IC-IPC Processes](images/ic-sound-manager/pipewire-ic-ipc-processes.png) - -### icipc library - -The IC Application is given a library (‘libicipc’) that implements the client side of -pipewire-ic-ipc. This library allows sending two commands: - -- SUSPEND - - Asks WirePlumber (via PipeWire) to cork applications and mute the ALSA device used by PipeWire -- RESUME - - Reverts the effects of SUSPEND - -IC Applications are expected to send the SUSPEND command before starting playback of a sound -to their dedicated ALSA device. The RESUME command should be sent after playback of this IC -sound has finished. - -It should be noted that the RESUME command is also issued automatically when the IC application -disconnects from the pipewire-ic-ipc UNIX socket. - -If multiple IC application issue SUSPEND to the pipewire-ic-ipc server, then only the first -SUSPEND generates actions for WirePlumber. The rest are counted and the pipewire-ic-ipc -server expects an equal number of RESUME commands before generating resume actions for -WirePlumber. - -The implementation of the SUSPEND/RESUME mechanism uses PipeWire’s metadata to signal -WirePlumber. PipeWire-IC-IPC will look for the “default” metadata object in PipeWire’s list -of objects and will write the “suspend.playback” key with a value of “true” on id 0. -The metadata change is then notified to all clients. WirePlumber, being a client, gets -notified of this change and takes actions. All actions are defined in Lua scripts. - -![PipeWire-IC-IPC Calls](images/ic-sound-manager/pipewire-ic-ipc-calls.png) diff --git a/docs/5_Component_Documentation/images/agl-compositor/arch_diagram.png b/docs/5_Component_Documentation/images/agl-compositor/arch_diagram.png deleted file mode 100644 index 88a4381..0000000 Binary files a/docs/5_Component_Documentation/images/agl-compositor/arch_diagram.png and /dev/null differ diff --git a/docs/5_Component_Documentation/images/agl-compositor/drawing_shell.png b/docs/5_Component_Documentation/images/agl-compositor/drawing_shell.png deleted file mode 100644 index bcd0a98..0000000 Binary files a/docs/5_Component_Documentation/images/agl-compositor/drawing_shell.png and /dev/null differ diff --git a/docs/5_Component_Documentation/images/ic-sound-manager/architecture.png b/docs/5_Component_Documentation/images/ic-sound-manager/architecture.png deleted file mode 100644 index 3d0820f..0000000 Binary files a/docs/5_Component_Documentation/images/ic-sound-manager/architecture.png and /dev/null differ diff --git a/docs/5_Component_Documentation/images/ic-sound-manager/pipewire-ic-ipc-calls.png b/docs/5_Component_Documentation/images/ic-sound-manager/pipewire-ic-ipc-calls.png deleted file mode 100644 index 9003e60..0000000 Binary files a/docs/5_Component_Documentation/images/ic-sound-manager/pipewire-ic-ipc-calls.png and /dev/null differ diff --git a/docs/5_Component_Documentation/images/ic-sound-manager/pipewire-ic-ipc-processes.png b/docs/5_Component_Documentation/images/ic-sound-manager/pipewire-ic-ipc-processes.png deleted file mode 100644 index 494b760..0000000 Binary files a/docs/5_Component_Documentation/images/ic-sound-manager/pipewire-ic-ipc-processes.png and /dev/null differ diff --git a/docs/5_Component_Documentation/images/rba/Basic_syntax.png b/docs/5_Component_Documentation/images/rba/Basic_syntax.png deleted file mode 100644 index 6704abd..0000000 Binary files a/docs/5_Component_Documentation/images/rba/Basic_syntax.png and /dev/null differ diff --git a/docs/5_Component_Documentation/images/rba/model.png b/docs/5_Component_Documentation/images/rba/model.png deleted file mode 100644 index e43289e..0000000 Binary files a/docs/5_Component_Documentation/images/rba/model.png and /dev/null differ diff --git a/docs/6_Component_Documentation/1_AGL_components.md b/docs/6_Component_Documentation/1_AGL_components.md new file mode 100644 index 0000000..a251b05 --- /dev/null +++ b/docs/6_Component_Documentation/1_AGL_components.md @@ -0,0 +1,27 @@ +--- +title: AGL Components +--- + +## Components under development within AGL + +### Graphics + +- [The AGL compositor](1_agl-compositor.md) +- [Waltham receiver/transmitter configuration](2_waltham-receiver_waltham-transmitter.md) +- [DRM lease manager](4_drm-leasemanager.md) + + +### Sound + +- [Pipewire & Wireplumber](6_pipewire_wireplumber.md) +- [IC and Sound Manager](7_ic-sound-manager.md) + + +### Policies + +- [Rule based arbitrator](3_rba.md) + + +### Lifecycle management + +- [Application Framework](../3_Developer_Guides/1_Application_Framework/1_Introduction.md) diff --git a/docs/6_Component_Documentation/2_agl-compositor.md b/docs/6_Component_Documentation/2_agl-compositor.md new file mode 100644 index 0000000..437e6a7 --- /dev/null +++ b/docs/6_Component_Documentation/2_agl-compositor.md @@ -0,0 +1,498 @@ +--- +title: agl-compositor +--- + +# Wayland compositor + +When the AGL project was started, weston was chosen as the compositor, which is +the reference implementation of a Wayland compositor, while for window management +functionality it relied on *ivi-shell* (In-Vehicle Infotainment) together +with an extension, called [wayland-ivi-exension](https://github.com/GENIVI/wayland-ivi-extension). + +A demo platform image of AGL comes with a handful of demo applications, done +with the Qt, which abstracts the protocol communication between the client and +the compositor. Additional functionality was in place under the form of +library, to control and signal back to the compositor when applications were +started, among other things. + +Management of applications, starting, running and stopping them is done in AGL +with AppFW [Application Framework Management](../3_Developer_Guides/1_Application_Framework/1_Introduction.md), +which is an umbrella name to denote the suite of tools and daemons that handle +all of that. It is integrated with systemd and with the current security model. +Applications can use AppFW to hang off data, and to pass it down to +other services. Together with AppFW, applications could tell the compositor +which application to activate or to switch to. + + +## Simplifying the graphical stack + +Trimming down these abstractions, simplifying the way clients interact with the +compositor, and avoid using modules that aren't really maintained upstream were +the reasons behind looking at alternatives to ivi-shell. On the desktop, +[xdg-shell](https://gitlab.freedesktop.org/wayland/wayland-protocols/-/raw/master/stable/xdg-shell/xdg-shell.xml) +is currently de-facto protocol for handling all window management related +functionality. + +Wayland protocol has a window-like interface embedded into its protocol (called +wl_shell), but *xdg-shell* has long time ago deprecated it and instead +of adding it in the wayland protocol namespace, it was integrated +together with some other useful protocols, into +[wayland-protocols](https://gitlab.freedesktop.org/wayland/wayland-protocols) +project. The whole purpose of wayland-protocols is to enhance the Wayland +protocol with new functionality and bring new extensions entirely. Compositors +are free to implement, modify, enhance, and add new extensions to +wayland-protocols but they need to do so in consensus. + +Besides the core wayland protocol and extended functionality from +wayland-protocols, a compositor can provide and implement additional protocol +extensions (custom to that compositor). By using such private extensions we +align with the AGL project and its requirements, without compromising specific +functionality and allows to add or improve the current ones. With that in mind, +the approach was to create a new compositor, called +[agl-compositor](https://gerrit.automotivelinux.org/gerrit/admin/repos/src/agl-compositor) +and implement dedicated private extensions, rather than trying to modify weston +itself, which AGL project would have been required to keep and maintain for +itself, as a fork. + +## A compositor based on libweston + +The compositor used currently in AGL, just like weston, is built on top of +*libweston* and *libweston-desktop*. The latter, among other things, is required +as it provides the server side implementation of the xdg-shell protocol which +underlying toolkits (like Qt/Chromium project) makes use of to deliver +desktop-like functionality. The former is used to provide back-ends and +rendering support, effectively managing the HW, besides implementing the +wayland protocol. + +The high-level goal of [libweston](https://wayland.pages.freedesktop.org/weston/toc/libweston.html) is +to decouple the compositor from the shell implementation. + +Traditionally, clients were entirely separated from the window manager, the +desktop environment and the display server. In wayland all these are +conceptually under the same entity though they are implemented as different +(UNIX) processes, or as a different namespaces with front and back-end APIs, +exposed by libraries. The compositor and the shell driving the UI should be +seen as one and the same, and in practice, this happens on desktop +environments. For AGL, the shell client can be represented under different +forms, as well as the fact that the process management has another layer +baked-in to handle MAC (Mandatory Access Control) labels and use the +above-mentioned Application Framework. These are all tightly +integrated and therefore, the AGL compositor will not automatically start the +shell client, although there's code to handle that. + +## Specifying a shell client to be started by the compositor + +Nevertheless, one can modify the configuration file, add the shell client path, and the +compositor will attempt to start it. + +``` +[shell-client] +command=/path/to/your/client/shell +``` + + + +## Private extensions + +Compositors can define and implement custom extensions to further control +application behaviour. For AGL, we have two private extensions defined. +One targeted at defining surface roles commonly found in desktop environments +(like panels, and backgrounds), which a shell client would bind to, and one +targeted at regular application(s) that might require additional functionality: +being able to display/activate its own surface or other's application surface, +implement some kind of split screen management of windows, or +dialog/pop-ups that exhibit always-on-top property even if the active +surface has been changed. + +![Layers_And_Extensions](images/agl-compositor/drawing_shell.png) + +Clients can make use of these private extensions to define other kind of roles +for instance dialog/pop-ups or full-screen roles, and split windows vertically or +horizontally. It includes the ability to activate other applications, assuming +that the surfaces have been created, and the capability of delaying +presentation for the client shell. Doing so, all the information is displayed +at once, rather than waiting for the toolkit to map/show the surface. + +An application identification mechanism was required to be able to activate +other clients windows/surfaces. A string-based identifier name was chosen +which can be used by the client to set an application-based identifier using +the xdg-shell protocol. While there's nothing stopping the client to avoid +doing that, specifically, to avoid assigning an application identifier, +the compositor won't be able to find which surfaces matches to a particular +client, if one would want to activate/display it at some time in the future. + +### agl-shell + +Client shellls can make use of this protocol to define panels and background +roles for different surfaces. It includes to ability to activate other +applications, assuming that those are already running. Activation happens by +using using the app_id, respectively using set_app_id request as defined by the +xdg-shell protocol. Established client-side implementation of the xdg-shelll +protocol will have a function exposed which can be used to set an application +identifier. Further more, the compositor will not present/display anything to +the user as long the `ready()` is not requested. So, after creating the surfaces +assigning them panel and/or background roles, and they're fully loaded, +the client can then issue `ready()` request and the compositor will start +presenting. + +Please consult the [protocol file](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/agl-compositor.git;a=blob_plain;f=protocol/agl-shell.xml;hb=refs/heads/master) +as that is the authoritative way of getting the latest version. + +#### V2 updates + +Version 2 of the agl-shell protocol, while it is is not obligatory to be +supported by the shell client, it adds two new events: bound_ok and bound_fail +events. + +It has been observed that in some cases where we do not explicitly have a knob +in the toolkit to tell whether the application is a regular one (which doesn't +need to bind to the agl-shell protocol) or a one that needs to implement +agl-shell protocol might result in terminating the wayland connection. + +That happens because we can't have multiple clients bind to the agl-shell +protocol interface and was particularly visible when using regular +flutter applications with other shell clients (Qt homescreen, or WAM/chromum), +basically mashing together different kind of toolkits in the same image. Once +a client has already bound to the agl-shell protocol interface any other client +that attempts to do same will get its wayland connection severed and the +application will be terminated. + +These two events provide a race-free method in which the clients can tell if +they're in charge (of being the shell client) or their just regular +applications. Explicitly implementing this protocol if you have other means to +specify which type of application it is running wouldn't be required nor +necessary. But by using the protocol we can provide the same thing, +programmatically, without fearing that the wayland connection might be +severed, and implicitly taking down the application. + +#### V3 updates + +Version 3 of the agl-shell protocol adds 4 more events to signal out when the +application state was changed: started, activated, deactivated and terminated. + +Version 3 update was mostly prompted by an issue with start-up of applications +but also is part of the first steps to reduce and simplify a bit more +activation handling in the compositor. Specifically with this protocol update, +we can correctly orchestrate start-up and activation of applications. + +At the moment of adding this protocol update, the default compositor behaviour +is to display/activate applications as soon they're started, a feature which +we've called activate-by-default (and which is turned on by default). +But users can choose to disable that in such a way that activation is entirely +driven the shell client. + +Implicitly having this activate-by-default papered over various +issue when don't have that activation by default turned on. Supporting both +use-cases (activate-by-default, on and off) turned out to be cluster of +problems and regression over time. Not only that the amount of complexity in +the compositor is unwarranted and can simplified by telling the shell client +handle any window management interaction on its own. + +Further more, with this protocol update we also includes some events already +present in the agl-shell-desktop protocol like deactivate and terminate. + +### agl-shell-desktop + +This extension is targeted at keeping some of the functionally already +established in AGL as to a) allow applications display/activate other +surfaces/application window, and b) set further roles, specially dialog/window +pop-ups and split-type of surfaces. + +Clients can make use of this protocol to set further roles, like independently +positioned pop-up dialog windows, split type of surfaces or fullscreen ones. +Additional roles, and implicitly functionality can be added by extending the +protocol. These roles serve as hints for the compositor and should be used +before the actual surface creation takes place, such that the compositor can +take the necessary steps to satisfy those requirements. + +Please consult the [protocol file](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/agl-compositor.git;a=blob_plain;f=protocol/agl-shell-desktop.xml;hb=refs/heads/master) +as that is the authoritative way of getting the latest version. + +#### Additional surface roles in agl-shell-desktop + +Like mentioned earlier, the compositor is already making use of some (internal) +roles, and with this extension we add some further ones. These are: + +* split (there's vertical and a horizontal one) +* fullscreen +* dialog/pop-up + +Internally these are encoded with different values such that there's a +translation needed, between the protocol values and the internal ones. Besides +the roles, additional data can to be passed on, but only depending on the role. +It is highly recommend **to avoid** using the protocol to pass down information +between different applications using this communication channel. It is only +intended to help out with demo applications. Other sharing mechanism are +available in the AGL project that can satisfy those requirements. + +#### Receiving application state events from (other) applications + +agl-shell-desktop exposes two events which client can install handlers for, one +that signals when regular xdg application have been created, and one that +signals state changes (active/hidden) as well as destroyed/no longer present +surfaces. These events can be useful to add additional functionality if +needed. + +#### Activating (other) applications + +Both agl-shell and agl-shell-desktop have requests to activate other +application based on their xdg-shell app_id. In case the application is +present/running, it will attempt to make the surface backing that application +the current activate one, with each output having independently active +surfaces. + +## Explicit output + +The activation and setting surface roles requires passing a Wayland output +(wl_output). The output is the wayland interface representation of an output +and is **mandatory** to pass it down to the compositor when activating a surface. +Clients can retrieve it (the output) if they wish to place the surface on other +outputs by using the toolkits that expose the Wayland objects. A human-like +representation is provided by either the toolkit, or by using other extensions +implemented by the client, for instance [xdg-output](https://gitlab.freedesktop.org/wayland/wayland-protocols/-/raw/master/unstable/xdg-output/xdg-output-unstable-v1.xml) +is the one recommended way and provides a mapping between a human +representation of the output and the wayland one. + +One can also choose the output where the application can start, by configuring +directly the AGL compositor. Under the `[output]` section one can use +`agl-shell-app-id=appid` restart the AGL compositor unitd systemd service and +start the application. Currently this *only* applies to regular applications, the +client shell having to handle it in the code. + +## Available toolkits, application conversions and available eco-systems + +Users and OEM vendors alike have the possibility, depending on their use-cases, +to either use some kind of a toolkit (Qt/GTK) for writing application, +or use plain C and the wayland library to communicate with the compositor +directly, without any toolkit abstraction. + +Currently, the demo applications in AGL use the Qt platform with Chromium being +at this phase, a second-class citizen, being currently in the works of +achieving the same level of integration as QtWayland (the underlying library that +abstracts the Wayland interaction) has at this moment. The Qt platform has +long been favoured in embedded systems so it feels natural why AGL project +chose it over other alternatives. In the same time, as web applications are +for quite some time now permeating the application development scene, it also +felt natural to add support for a runtime that gives that option, which in AGL +was achieved with the help of the Chromium project. + +For normal applications, not needing the ability to activate or displaying +other's application surface, would basically mean that it would use what the +toolkit has to offer, simplifying the application handling even more. Under +Qt, the client shell can use QPA (Qt Platform Abstraction) to gain access to +Wayland primitives, and implicitly is being able use the private extensions. + +![Architecture Diagram](images/agl-compositor/arch_diagram.png) + +On the Chromium side of things, that happens indirectly, as Chromium doesn't +expose the Wayland primitives. Not only that, but on the Chromium platform, +there's another mid-layer component, called [WAM](https://github.com/webosose/wam) +(WebApplicationManager) with the purpose of handling web applications life-cycle. + +So, controlling and passing information from a web application, that resembles +that of a shell client, has to travel more than a few levels in the software +stack, until it reaches the lower layers in Chromium where the Wayland +communication and interaction takes place. Support for the private extension +was done at the Ozone interface abstraction, which Chromium projects uses now +to handle the display/graphical interaction with the lower stack levels. + +## Streaming buffers and receiving events to and from remote outputs + +Quite a common feature, in the infotainment market, is the ability to stream +out buffers/data to remote outputs. For instance, super-imposing the navigation +application, between the speedometer and tachometer, in the IC (Instrument +Cluster) of a car is such a scenario. Just like weston, the AGL compositor is +capable of loading up libweston modules and make use of them. And just like +weston, the AGL compositor loads up the remoting-plugin to achieve the same +thing. + +The remoting-plugin uses the DRM virtual output API from libweston together +with gstreamer pipeline to capture, using DMA buffers, the DRM output and to +stream it, remotely to another machine. They can be over the network, or +locally. + +Further more, to cope with situations where the output is just a +panel/display, without some kind of compositor driving it, the necessity of +handling input events is an important feature to have, giving the user to +possibility to manipulate the application/environment as he or she seems fit. +The compositor loads a plug-in that streams out the buffers to an output +remotely, with [another plug-in](2_waltham-receiver_waltham-transmitter.md) +handling the input events. The events, which are sent back from the display to +the compositor, are generated with the help of wayland-eque protocol that works +over the network, called [Waltham](https://github.com/waltham/waltham). + +Together, they provide proper means to achieve a seamless integration with +other display devices in the car cabin. + +## Policies and Role Base Arbitration + +The compositor contains an API useful for implementing user-defined policies. +It contains a policy engine, and installs by default an allow-all kind of +policy. The policy engine controls if the client using the private extensions +is permitted to perform those calls. Not only that, but with some policies, it +won't allow the client to bind to the interfaces in the first place. That +happens with the deny-all policy, which is able to retrieve the client's +SMACK label and compares it with the ones statically defined. + +In the works, there's a new policy model, called [Role Based +Arbitration](https://gerrit.automotivelinux.org/gerrit/admin/repos/staging/rba). +Internally, how it works, should be found at [RBA](3_rba.md). +While the other two policies are embedded into the compositor, the RBA policy +model is an off the-shell policy. Obviously, vendors and users can hook up +their own policies, just like RBA did. These all work towards satisfying +the driver distraction mitigation requirement for the AGL project, as to avoid +overwhelming the driver with too much information. + +Users wanting to create their own policy should create a specialized version +of the callbacks defined in `struct ivi_policy_api`. + +As there's no dynamic loading of policies you'll need to recompile the compositor +with that policy in mind, specifically like the following: + + $ meson -Dprefix=/path/to/install-compositor/ -Dpolicy-default=my_policy build_directory + +The default policy found in src/policy-default.c should more than sufficient to +get started on creating new ones. Users can either re-purpose the default +policy or create a new one entirely different, based on their needs. + +These are hooks in place by the policy engine control the creation, committing +and activation of surfaces (`ivi_policy_api::surface_create()`, +`ivi_policy_api::surface_commited()`, `ivi_policy_api::surface_activate()`), +among other situations. + +Users can customize the hooks by using some sort of database to retrieve the +application name to compare against, or incorporate some kind of policy rule +engine. Alternatively, one can use the deny-all policy engine which allows the +top panel applications to be used/displayed as permitted applications. + +### Reactive rules + +The policy engine is stateful, and allows the ability to inject back events, +such that it allows the user to add custom rules into a policy and, depending +on the event received by the policy engine, to execute a rule match for that +event. Further more, the framework allows adding new states and events and the +default implementation has code for handling events like showing or hiding the +application specified in the policy rule. The most common example to exemplify +this feature is the ability to show a custom application, like displaying the +rear view camera application, when the automobile has been put in reverse. + +For deadling with these kind of rules, `ivi_policy_api::policy_rule_allow_to_add()` +can be used to control if policy rules could be added or not. Finally, we have +`ivi_policy_api::policy_rule_try_event()` which is executed for each policy +rule added, by using the policy API `ivi_policy_add()` function. + +By default the policy framework it will add the 'show', and 'hide' events and +the 'start', 'stop' and 'reverse' states. An special type, assigned by default +is 'invalid'. A **state change** has to be propagated to the compositor, which can +happen by using `ivi_policy_state_change()` function, and which signals the +compositor the state change took place, in order to apply the policy rules, and +implicitly to call the event handler `ivi_policy_api::policy_rule_try_event()`. + +## Back-ends and specific options for agl-compositor + +The compositor has support for the following back-ends: + +* **DRM/KMS** - runs a stand-alone back-end, uses Direct Rendering Manager/Kernel + Modesetting and evdev, that is utilizes and runs on real or virtualized HW + (qemu/Vbox/etc). +* **Wayland** - runs as a Wayland application, nested in another Wayland compositor + instance +* **X11** - run as a x11 application, nested in a X11 display server instance + +### Building and running the compositor on different platforms + +The compositor can run on desktop machines as easily as it does on AGL +platform. It should infer, depending on the environment, if it is being +compiled with the AGL SDK, or with the host build system. Running would also +be inferred from the environment. + +The compositor has some additional configuration options like: + +* `--debug` - enables the screenshooter interface, useful if one would want to + take a screenshot using `agl-screenshooter` client. This might be seen as a + security risk to it only be enabled in the AGL platform if built with agl-devel + DISTRO FEATURES. + +Additional configuration ini options have been added to help with the CI +integration. Worth mentioning are: + +* `activate-by-default=[true]` - if the surface of the client should be + displayed when the application started. Present in the `[core]` section. + By default set to `true`. Setting it to `false` will not activate, + by default, the client's surface when started. +* `hide-cursor=[false]` - do not advertise pointer/cursor to clients. Present + in the `[core]` section. + +## Running with software rendering + +By default the compositor will attempt to use the GL-renderer, and implicitly +the GPU. One could instead use the CPU, by making use of the Pixman library. To +use it in the compositor append `--use-pixman` to the command line. This purely +software approach has the benefit that would not rely at all on any GL +implementatation or library. In constrast, even if the GL-renderer is used, +in some situations it won't be able to use the GPU supported implementation +and fallback to sofware based one, and for instance that might happen when +running in virtualized environments. + +Both approaches could end up not actually using the GPU, but the latter does +actually use the GL library and perform the operations in software, while the +former does not use any GL whatsover. All back-ends support disabling the +GL-render to make sure it does not interfere with the composing process. + +## Multiple output set-up and touch input devices + +There's no deterministic way in which the compositor enables the outputs and +depending on the input devices, specifically touch input devices, and the way +the connectors are wired, a touch input device might be associated with a +different output than the one intended. + +A consistent way, that survives a reboot, is to use +[udev rules](https://man7.org/linux/man-pages/man7/udev.7.html), which +libweston would be able to use such that a particular output is tied/associated +to a particular touch input device. + +For instance, assuming that you have a set-up consisting of 4 outputs, a 4 +touch input devices, when the outputs are being enabled the compositor +front-end will associate all 4 touch input device -- if they haven't been +previously being associated to a particular output, to the first enabled +output. + +In order to avoid that, and associate each touch input device to +their respective output an udev rule can be installed, for the default +seat (named `seat0`). + +Example of a udev rule: + +``` +SUBSYSTEM=="input", ATTRS{idVendor}=="222a", ATTRS{idProduct}=="004a", OWNER="display", ENV{ID_SEAT}="seat0", ENV{WL_OUTPUT}="HDMI-A-1" +SUBSYSTEM=="input", ATTRS{idVendor}=="222a", ATTRS{idProduct}=="004b", OWNER="display", ENV{ID_SEAT}="seat0", ENV{WL_OUTPUT}="HDMI-A-2" +SUBSYSTEM=="input", ATTRS{idVendor}=="222a", ATTRS{idProduct}=="004c", OWNER="display", ENV{ID_SEAT}="seat0", ENV{WL_OUTPUT}="HDMI-A-3" +SUBSYSTEM=="input", ATTRS{idVendor}=="222a", ATTRS{idProduct}=="004d", OWNER="display", ENV{ID_SEAT}="seat0", ENV{WL_OUTPUT}="HDMI-A-4" +``` + +Add the following under `/etc/udev/rules.d/91-output.rules` and reload udev +rules for these changes to take effect: + + $ udevadm control --reload-rules && udevadm trigger + +Note that in the above example, we use physical seat, named `seat0` which is +the default physical seat. You can verify that these changes have been applied by +checking the compositor logs (under `/run/platform/display/compositor.log` file) +You should be seeing `CONNECTOR-NO by udev` message like the following: + +``` +associating input device event0 with output HDMI-A-1 (HDMI-A-1 by udev) +``` + +vs + +``` +associating input device event0 with output HDMI-A-2 (none by udev) +``` + +where the rules are either incorrect or badly written. + +Retrieving device attributes could be done archaically using `lsusb` or `lspci` +or using `udevadm info -a /dev/input/event*` which can provide with a multitude +of attributes to use. In our above example we only relied `idVendor` and +`idProduct` but potentially other attributes might be used. diff --git a/docs/6_Component_Documentation/3_waltham-receiver_waltham-transmitter.md b/docs/6_Component_Documentation/3_waltham-receiver_waltham-transmitter.md new file mode 100644 index 0000000..b98de32 --- /dev/null +++ b/docs/6_Component_Documentation/3_waltham-receiver_waltham-transmitter.md @@ -0,0 +1,96 @@ +--- +title: Waltham receiver/transmitter +--- + +# Waltham + +[Waltham protocol](https://github.com/waltham/waltham) is a IPC library similar +to [Wayland](https://wayland.freedesktop.org), developed with networking in +mind. It operates over TCP sockets, while the wayland protocol only works +locally over a UNIX socket. It retains wayland-esque paradigm, making use of +XMLs to describe the protocol, and it follows an object-oriented design with an +asynchronous architecture. + +## Differences from Wayland to Waltham + +Some of the differences between Wayland and Waltham are: + +* Waltham uses TCP sockets for communication +* Waltham cannot send file descriptors +* Waltham API is minimal and symmetric between server and client sides +* Waltham does not provide an event loop implementation +* The registry implementation is left out of the library, only the interface is + provided +* No multi-threading support for sharing objects between threads + +## Waltham-transmitter and remoting plugin + +Surface sharing is not part of Waltham protocol, each system needs to implement +the most efficient way of passing by the buffers from one side to another. On +AGL, make use of remoting-plugin to enable surface sharing which uses GStreamer +as encoder/decoder. It uses libweston DRM virtual API to grab the buffers, and +then to stream them over the network. The gstreamer pipeline uses UDP while the +input events are communicated with Waltham protocol. The input part is handled +by *waltham-transmitter* plugin which provides an API to create remote +connections and push surfaces over the network and handles remote input. The +act of pushing surface is a misnomer, kept from the older, previous +implementation, and acts a notification mechanism from the transmitter side to +the remote side. + +## The receiver client + +waltham-receiver application is a wayland demo implementation which should be +running at the remote side. It is using Waltham protocol to obtain and process +remote input events which handled the transmitter side by the waltham-transmitter +plugin. It creates a similar gstreamer pipeline to process the incoming buffers +and draw and displaying them into a subsurface created by waylandsink. + +Contrary to expectations, the waltham receiver is the one that implements the +server side of the Waltham protocol and is capable of displaying the incoming +buffers but also process input events locally and forward them with the help of +the Waltham protocol back at the transmitter side, which in turn will update +the image contents and stream to the receiver, showing the changes caused by +that input. + + + ECU 1 ECU 2 + +---------------------------------------------+ +--------------------------------------+ + | +-----------------+ | | | + | | Application | | | +-----------+-----------+ | + | +-----------------+ | | | Gstreamer | | | + | ^ | Buffer ---------------> (Decode) | | | + | wayland | +-------------------/ | +-----------+ | | + | v | | (Ethernet) | | Waltham-receiver | | + | +----+---------------------+ | | --------------------> | | + | | | Transmitter plugin |<---------------------/ | +-----------------------+ | + | | | | | | Waltham-Protocol | ^ | + | | |---------------------| | | | wayland | | + | | | Remoting plugin |-------+ | | v | + | | | | | | +---------------------+ | + | | +---------------------+ | | | | | + | | | | | | compositor | | + | | compositor | | | | | | + | +------+-------------------+ | | +----------------+----+ | + | | | | | | + | v | | v | + | +------------+ | | +----------+ | + | | Display | | | | Display | | + | | | | | | | | + | +------------+ | | +----------+ | + +---------------------------------------------+ +--------------------------------------+ + +## Migrating/Placing applications on other outputs + +In order to start or place an application on the remoting-ouput output, we can +use `agl-shell-app-id` ini entry for that particular output. + + [transmitter-output] + name=transmitter-1 + mode=640x720@30 + host=192.168.20.99 + port=5005 + agl-shell-app-id= + +Alternatively, and programmatically, one can use the +[agl-shell-desktop](1_agl-compositor.md#private-extensions) protocol and inform +the compositor that it should migrate it to other, remote outputs. diff --git a/docs/6_Component_Documentation/4_rba.md b/docs/6_Component_Documentation/4_rba.md new file mode 100644 index 0000000..9661923 --- /dev/null +++ b/docs/6_Component_Documentation/4_rba.md @@ -0,0 +1,1207 @@ +--- +title: Rule Based Arbitrator (RBA) +--- + +# RBA + +Rule Based Arbitrator decides which of the content to display when a large number of contents to be displayed on the cockpit display device (CID, meter, HUD, etc.) occur simultaneously under a certain rule (arbitration). + +### 1. Overview + +#### 1.1 Purpose of this document + +This document describes the syntax of the Rule-based Arbitration Model. + +#### 1.2 Basic syntax + +The basic syntax of the Rule-based Arbitration Model is as follows. + +![Basic syntax](images/rba/Basic_syntax.png) + +Define the properties of the model element in {} after declaration of Model element keyword,　Model element ID. Each property depends on the element. The properties of the model element may also define other model elements. + +#### 1.3 Relationship between files and Model definitions + +The Rule-based Arbitration Model can be defined in multiple files. (The extension of the file will be ".rba") Firstly, define the Package model element in the file. + +Areas.rba +```shell +Package AreasPackage { + +} +``` +Content.rba +```shell +Package ContentsPackage { + +} +``` + +#### 1.4 Structure of Rule-based Arbitration Model + +The elements of the Rule-based Arbitration Model are as follows. Each inheritance relationship between elements is defined and expresses elements that can be described in PackagableElement. + +![model](images/rba/model.png) + +#### 1.5 Notation of Syntax Definition + +For Model element + +syntax: +```shell +Package [ID] { + description: [String] + [PackagableElement] +} +``` + +Description: + +| Syntax element | Description | +| :--- | :---- | +| description: 0..1 | Description | +| [PackagableElement] * | Child element Package,Display,Size,Constraint,PostConstraint,Scene,Event,Rule,Area,AreaSet,ViewContent,ViewContentSet| + +The multiplicity is expressed as follows: + +| Expression of multiplicity | Description | +| :--- | :--- | +| * | 0 or more | +| 1..* | 1 or more | +| 1 | 1 | +| 0..1 | 0 or 1 | + +Description of [] notation is as follows: + +| Syntax element | Description | +| :--- | :---- | +| [ID] | ID. A character string in which the first character is not a number. Only _ can be used for symbols, Space cannot be used. +| [String] | An arbitrary character string. specify it by enclosing with "". | +| [Number] | An integer that is greater than equal 0. | +| [expression] | An expression whose return value is a property type. | +| [] | Definition of other Model elements. Sometimes an abstract class is specified. | +| [ID of A] | Reference to other Model elements. A represents an element. | +| [X\|Y] | Indicates that you can describe X or Y. | + +### 2. Common + +#### 2.1 Package + +The Package element is the root element in the file. It has PackagableElement as a Child element and groups PackagableElements in arbitrary units. + +syntax: +```shell +Package [ID] { + description: [String] + [PackagableElement] +} +``` + +| Syntax element | Description | +| :--- | :---- | +| description: 0..1 | Description | +| [PackagableElement] * | Child element Package,Display,Size,Constraint,PostConstraint,Scene,Event,Rule,Area,AreaSet,ViewContent,ViewContentSet| + +Description example: +```shell +Package SamplePackage { + description: "This is a sample Packege" + Area SampleArea { + arbitrationPolicy: DEFAULT + sizeReference: SampleSize1 + visibility: NONE_VALUE + zorder: 3 + } + ViewContent SampleContent { + allocatable: [SampleArea1] + State NORMAL { + priority: STANDARD_VALUE + } + } +} +``` + +#### 2.2 Size + +Size is the size of Area and ViewContent. + +Syntax: + +```shell +Size [ID] { + description: [String] + width: [Number] + height: [Number] +} +``` + +| Syntax element | Description | +| :--- | :---- | +| description: 0..1 | Description of Size element | +| width: 1 | width | +| height: 1 | height | + +Description example: +```shell +Size ScreenSize { + description: " Screen size" + width: 200 + height: 200 +} +``` + +#### 2.3 Project + +The Project element is an element that can be defined only once in one project. +Like The Package element, it can be defined directly under the file. + +Syntax: +```shell +Project { + version: [String] +} +``` + +| Syntax element | Description | +| :--- | :---- | +|version: 1| Version of the Project| + +Description example: +```shell +Project { + version: "version 1.0" +} +``` + + +### 3. Area + +Area is a frame to display the ViewContent on the screen. Only one ViewContent is allocated to one Area at most. Since Arbitration is executed for each Area, the Arbitration Policy is defined. + +Syntax: + +```shell +Area [ID] { + description: [String] + arbitrationPolicy: [DEFAULT | FIRST_COME_FIRST | LAST_COME_FIRST | PRIORITY_FIRST_COME_FIRST | PRIORITY_LAST_COME_FIRST] + [[Size]| sizeReference:[ID of Size]] + [visibility|priority]:[Number|Expression] + zorder:[Number|Expression] +} +``` + +| Syntax element | Description | +| :--- | :---- | +| description: 0..1 | Description | +| arbitrationPolicy: 0..1 | Arbitration Policy for Area. Refer to "Types of Arbitration Policy" for the policies which can be specified. If not specified, consider it as "DEFAULT". +| [Size\|sizeReference:] 1..* | Size: Size definition.| +|| sizeReference: Reference to Size definition.| +|| ※One or more definitions of either Size or sizeReference are needed. Multiple definitions should be defined consecutively.| +| [visibility\|priority]: 1 | Value of Area. Describe the relative value for other Areas as an expression or set a numerical value.| +|| The following predefined value can be set as a String. NONE_VALUE, STANDARD_VALUE, MIN_VALUE, MAX_VALUE See " Value / Z order definition" for details. | +| zorder: 1 | Z order of Area. Describe the relative Z order for other Areas as an expression or set a numerical value. The following predefined value can be set as a String. | +||NONE_VALUE, STANDARD_VALUE, MIN_VALUE, MAX_VALUE See " Value / Z order definition" for details. | + + + +Types of Arbitration Policy + +| Arbitration Policy | Description | +| :--- | :---- | +| DEFAULT | Same as Priority and First Come First Arbitration. If the Arbitration Policy is not specified, it will be this type.| +| FIRST_COME_FIRST | First Come First Arbitration. Give priority to the request which occurred first. | +| LAST_COME_FIRST | Last Come First Arbitration. Give priority to the request which occurred later. | +| PRIORITY_FIRST_COME_FIRST | Priority and First Come First Arbitration. It follows the priority set to the Content. If the priority is the same, give priority to the request which occurred first. | +| PRIORITY_LAST_COME_FIRST | Priority and Last Come First Arbitration. It follows the priority set to the Content. If the priority is the same, give priority to the request which occurred later.| + +Description example: +```shell +Area SampleArea { + description: "This is a sample Area." + arbitrationPolicy: DEFAULT + Size Default { + width: 200 + height: 150 + } + sizeReference: SampleSize1 + visibility: NONE_VALUE + zorder: 3 +} +``` + +### 4. Value / Z order definition + +Values (visibility or priority) of area is the order of arbitrating of the area. The higher is arbitrated first. You can describe only one of the visibility or priority. +For the Z order (zorder), the higher one will be on the front of the screen. You can define values absolutely by number or define relatively to other areas by expressions. You can use comparison operators (> and <), equality operator (=) and That-of operator for the expressions. + +- Description example of value : +Visibility of SampleArea2 is 10, zorder is 5. +```shell +Area SampleArea2 { + visibility: 10 + zorder: 5 +} +``` +- Description example of comparison operator: +Priority of SampleArea1 is greater than SampleArea2. Zorder of SampleArea1 is less than SampleArea3. +```shell +Area SampleArea1 { + priority: > That-of SampleArea1 + zorder: < That-of SampleArea3 +} +``` +- Description example of range: +Visibility of SampleArea1 is greater than 1 and less than SampleArea2. Zorder of SampleArea1 is greater than SampleArea3 and less than SampleArea4. +```shell +Area SampleArea1 { + visibility: (> 1 AND < That-of SampleArea2) + zorder: (> That-of SampleArea3 AND < That-of SampleArea4) +} +``` + +- Description example of equality operator: +```shell +Area SampleArea1 { + visibility: = That-of SampleArea2 + zorder: = That-of SampleArea3 + That-of SampleArea2 +} +``` + +- Equality operator can be omitted. +```shell +Area SampleArea1 { + visibility: That-of SampleArea2 + zorder: That-of SampleArea3 + That-of SampleArea2 +} +``` + +### 5. ViewContent definition + +#### 5.1 ViewContent + +ViewContent is an object to be displayed in the Area. ViewContent has multiple states. When ViewContent is allocated to an Area, active state of theViewContent is displayed. Define the Area which can display ViewContent to the ViewContent. You can define several Areas. + +Syntax: +```shell +ViewContent [ID] { + description: [String] + allocatable: [ [ID of Area] | [ID of Set] ] + [ViewContentState] + [[Size]|sizeReference: [ID of Size]] + loserType: [GOOD_LOSER | DO_NOT_GIVEUP_UNTIL_WIN | NEVER_GIVEUP] +} +``` + +|Syntax element | Description| +| :--- | :---- | +|description: 0..1 | Description| +|allocatable: 0..* | Displayable Area. Specify the ID of displayable Areas or Sets with comma-separated.If don’t specify allocatable, should specify allocatable in the ViewContentSet that includes this ViewContent. | +| [ViewContentState] 1..* |Define the State of ViewContent.| +|[Size\|sizeReference:] 1..*|Size: Size definition| +||sizeReference: Reference to Size definition.| +||※One or more definitions of either Size or sizeReference are needed. Multiple definitions should be defined consecutively.| +|loserType: 0..1| Action on lost. Specify whether to cancel a request, if ViewContent is not displayed after arbitration. See "Types of Action on lost" for details. If not defined, consider it as "NEVER_GIVEUP".| + +Types of Action on lost + +|loserType | Description| +| :--- | :---- | +|GOOD_LOSER |When losing arbitration, cancel a request.| +|DO_NOT_GIVEUP_UNTIL_WIN |When the state is changed visible to invisible , cancel a request.| +|NEVER_GIVEUP|Keep a request.| + +Description example: +```shell +ViewContent Power { +description: " Warning from power management" + allocatable: [ + MessageArea, HUDMessageArea + ] + State Warning { + priority: > That-of Power.Attention + } + State Attention { + priority: > That-of TEL.Incoming + } +Size Default { +description: "Default size" +width: 200 +height: 200 +} + sizeReference: InterruptMessageSize + loserType: GOOD_LOSER +} +``` +#### 5.2 State(ViewContent) + +State is the state of the ViewContent. + +Syntax: +```shell +State [ID] { + description: [String] + [priority|value]: [Number|Expression] +} +``` + +|Syntax element | Description| +| :--- | :---- | +|description: 0..1 | Description +|[priority\|value]: 1 | Priority of ViewContent. | +||Describe the relative value for other State under ViewContent as an expression, or set a numerical value. | +||The following predefined value can be set as a String.NONE_VALUE, STANDARD_VALUE, MIN_VALUE, MAX_VALUE See "Priority definition"for details. | + +Description example: +```shell +State Warning { + description: "Display warning message" +priority: > That-of Attention +} +State Attention { + description: " Display attention message " +priority: > That-of TEL.Incoming +} +``` +### 6. Priority definition + +Define the priority of Content to the State under ViewContent or SoundContent (hereinafter, Content). The priority is used when the area / zone arbitration policy is "Priority and First Come First Arbitration" or "Priority and Last Come First Arbitration", the higher one is allocated first. Values can be defined absolutely by number or relative to other areas by expressions. You can describe only one of the visibility or priority. You can use comparison operators (> and <), equality operator (=) and That-of operator for the expressions. + +- Description example of value: +Priority of Warning is 10. +```shell +State Warning { + description: " Display warning message " +priority: 10 +} +``` +- Description example of comparison operator: +Value of Warning is greater than Attention. +
Value of Attention is greater than State Incoming of TEL of other Content. +
Value of Notice is less than Attention. +
※When referring to the State of another Content, refer to the Content ID and State ID by connecting with “.”. +```shell +State Warning { + value: > That-of Attention +} + +State Attention { + value: > That-of TEL.Incoming +} + +State Notice { + value: < That-of Attention +} +``` + +- Description example of range: Priority of Attention is greater than Incoming of TEL and less than Warning. +
※When referring to the State of another Content, refer to the Content ID and State ID by connecting with “.”. +```shell +State Attention { + priority: (> That-of TEL.Incoming AND < That-of Warning) +} +``` + +- Description example of equality operator:Value of Attention is equal to State Incoming of TEL of other Content. +```shell +State Attention { + priority: = That-of TEL.Incoming +} +``` +- Equality operator can be omitted. +```shell +State Attention { + priority: That-of TEL.Incoming +} +``` + +### 7. Screen layout definition + +#### 7.1. Display + +Display represents one screen. When defined more than one, it will be Multi-screen layout. +The Display defines the set of Areas to be allocated on the screen. + +Syntax: +```shell +Display [ID] { + description: [String] + [CompositeArea] + [[Size]|sizeReference:[ID of Size]] +} +``` + +|Syntax element | Description| +| :--- | :---- | +| description: 0..1 | Description| +|[CompositeArea] 1 | Component of the screen| +|[Size\|sizeReference:] 1 | Size: Size definition| +|| sizeReference: Reference to Size definition| +|| ※One or more definitions of either Size or sizeReference are needed. | + +Description example: +```shell +Display METER { + description:"Meter display definition" + Size FULLSCREEN { + width: 500 + height: 400 + } + CompositeArea METER_Root { + layout: FixedPositionLayout { + PositionContainer { + x: 100 + y: 100 + basePoint: LEFT_TOP + areaReference: SpeedMeterArea + } + } + } +} +``` + +#### 7.2. CompositeArea + +CompositeArea specifies an Area that becomes a component of Display. + +Syntax: +```shell +CompositeArea [ID] { + description: [String] + layout: [FixedPositionLayout] +} +``` + +|Syntax element | Description| +| :--- | :---- | +|description: 0..1 | Description | +|layout: [FixedPositionLayout] 1| Layout type of Area| + +Description example: +```shell +CompositeArea METER_Root { + description:" Definition of Area’s layout method" + layout: FixedPositionLayout { + PositionContainer { + x: 100 + y: 100 + basePoint: LEFT_TOP + areaReference: SpeedMeterArea + } + } +} +``` + +#### 7.3. FixedPositionLayout + +FixedPositionLayout declares that areas are laid out with fixed values. The specific position define by PositionContainer. + +Syntax: +```shell +FixedPositionLayout { + [PositionContainer] +} +``` + +|Syntax element | Description| +| :--- | :---- | +|[PositionContainer] 1..*| Position information.| + +```shell +FixedPositionLayout { + PositionContainer { + x: 100 + y: 100 + basePoint: LEFT_TOP + areaReference: SpeedMeterArea + } +} +``` +#### 7.4. PositionContainer + +PositionContainer specifies the display position of the Area. + +syntax: +```shell +PositionContainer { + x: [Number] + y: [Number] + basePoint: [Value] + areaReference: [ID of Area] + [Offset] +} +``` + +|Syntax element | Description| +| :--- | :---- | +|x: 1 |x position| +|y: 1 |y position| +|basePoint: 1 | Defined x, y position. The following predefined value can be set.| +|| CENTER_BOTTOM (Define x, y as the lower center position)| +|| CENTER_MIDDLE(Define x, y as center position)| +|| CENTER_TOP (Define x, y as the upper center position)| +||LEFT_BOTTOM (Define x, y as the lower left position)| +||LEFT_MIDDLE (Define x, y as the left center position)| +||LEFT_TOP (Define x, y as the upper left position)| +||RIGHT_BOTTOM (Define x, y as the lower right position)| +||RIGHT_MIDDLE (Define x, y as right center position)| +||RIGHT_TOP (Define x, y as the upper right position)| +|areaReference: 1| Area to be placed in Display. Specify ID of the Area.| +|[Offset] 0..*| Display position offset of AreaSpecify the position of the Area for each size.| + + +Description example: +```shell +FixedPositionLayout { + PositionContainer { + x: 100 + y: 100 + basePoint: LEFT_TOP + areaReference: SpeedMeterArea + Offset { x:-50 y:20 sizeReference: SpeedMeterArea } + } +} +``` +#### 7.5. Offset + +Offset is the offset position for each size. + +Syntax: +```shell +Offset { + description: [String] + x: [Number] + y: [Number] + sizeReference: [ID of Size] +} +``` + +|Syntax element | Description| +| :--- | :---- | +|description: 0..1| Description| +|x: 1| Offset from x position of PositionContainer.| +|y: 1| Offset from y position of PositionContainer.| +|sizeReference: 1| Size to apply the offset. Specify ID of Size.| +||※ This Size must be specified in Area.| + +Description example: +```shell +Offset { +description:"Offset" + x: 100 + y: -50 + sizeReference: SpeedMeterSize +} +``` + +### 8. Constraint defination + +Constraints can be defined according to the state of the Area/Zone and the state of the ViewContent/SoundContent. The syntax can be used for Constraints is shown below. + +- State reference of Area: + +|Name | Notation |Meaning| +| :--- | :---- | :---- | +|IsDisplayed | .isDisplayed()| The Area is displayed. (At this time, the ViewContent is necessarily allocated to the Area) True if the Area is displayed.| +|DisplayingContent| .displayingContent()| ViewContent which is displayed in the Area. When the Area is hidden or ViewContent is not allocated, it is not evaluated. +|AllocatedContent| .allocatedContent()| ViewContent which is allocated to the Area. Even if the Area is hidden after allocation, it is possible to refer to the allocated ViewContent.| +|IsHidden| .isHidden() |The Area is hidden. Regardless of whether the ViewContent is allocated to the Area or not,true if the Area is hidden.| +|ContentValue| .contentValue()| The value of the ViewContentState allocated to the Area. If ViewContent is not allocated to the Area, it is not evaluated.| +|ContentsList| .contentsList()| A set of ViewContent which is allocatable to the Area.| +|activeContents| .activeContents() |The set of active content amang the ViewContent which is allocatable to the Area| + +- State reference of ViewContent: + +|Name | Notation |Meaning| +| :--- | :---- | :---- | +|IsActive| .isActive()| True if there is a Content request of ViewContent.| +|IsVisible| .isVisible()| The ViewContent is displayed. True if the ViewContent is allocated to any Area.| +|StateValue |.stateValue() |Priority/value that is defined in active state of the ViewContent. When the ViewContent has no active state, it does not evaluate.| +|HasComeEarlierThan| .hasComeEarlierThan()| True if the ViewContentA’s request has come earlier than the ViewContentB’s. When the either ViewContent has been not requested, it does not evaluate.| +|HasComeLaterThan| .hasComeLaterThan() |True if the ViewContentA’s request has come later than the ViewContentB’s. When the either ViewContent has been not requested, it does not evaluate.| +|Allocatables| .allocatables()| A set of Areas where the ViewContent can be displayed.| + +- Scene reference: + +|Name | Notation |Meaning| +| :--- | :---- | :---- | +|IsOn| .isOn()| True if the Scene is valid.| +|Get| ..get()| Get scene property value.| + +- Stereotyope: + +|Name | Notation |Meaning| +| :--- | :---- | :---- | +|isTypeOf| .isTypeOf(“”)| Whether or not “” is used in the | +|||It can be applied to the following models Area,ViewContent| + +- Operator: + +|Name | Notation |Meaning| +| :--- | :---- | :---- | +|AND| AND | True if all Bool expressions are true.| +|OR| OR |True if any Bool expression is true.| +|Negation| ! | True if Bool expression is false.| +|Implication| -> | A -> B is equivalent to ((A AND B) OR !A).| +|Equal sign (Comparison of values)| = | True if the values shown on the left-hand side and the right-hand side are identical.The type of left-hand side and the right-hand side expressions must match.| +|Equal sign (Comparison of objects) | == | True if the values shown on the left-hand side and the right-hand side are identical.The type of left-hand side and the right-hand side expressions must match.| +|Comparison (greater than) | \> |True if the Number on the left-hand side is greater than the Number on the right-hand side.| +|Comparison (greater than)| \>= |True if the Number on the left-hand side is greater than equal to the Number on the right-hand side.| +|Comparison (less than)| < | True if the Number on the left-hand side is less than the Number on the right-hand side.| +|Comparison (less than)| <= | True if the Number on the left-hand side is less than the equal to Number on the right-hand side.| + +- Quantization symbol: + +|Name | Notation |Meaning| +| :--- | :---- | :---- | +|∀(For All) |For-All{ \| } | contains the ViewContentSet or the SoundContentSet, the AreaSet, the ZoneSet, and the One-time Set. True if is true for all set element .| +|∃(Exists)| Exists< Set\>{ \| } | contains the ViewContentSet or the SoundContentSet, the AreaSet, the ZoneSet, and the One-time Set. True if < Set\> has one or more elements that satisfy .| + +- Built-in defined Expression: + +|Name | Notation |Meaning| +| :--- | :---- | :---- | +|All Area| ALL_AREAS| A set of all the Areas defined in the Model.| +|All ViewContent| ALL_VIEWCONTENTS| A set of all the ViewContents defined in the Model.| +|IF-THEN-ELSE Syntax| IF ()THEN ELSE | The type of the expression must be identical, for the THEN clause, if the Bool expression is true, for THEN and ELSE clause ,if the Bool expression is false.| +|Let　Expression| let = | Evaluate 　as variable , which can then be referenced in subsequent expressions| +|||Can only be used inside the expression. For-All, Exists, Max, Min, Select| +|Pre-arbitration value specifier| (pre) | Refere to the state before arbitration of Area, ViewContent, Property.| + +**The syntax precedence and associativity are shown below:** + +|Priority| Name| Notation| Connectivity| +| :--- | :---- | :---- | :---- | +|1 |Parentheses| () |-| +|2| ∃(Exists)| Exists{ \| }|-| +|| ∀(For All)| For-All{ \| }| -| +|| IF-THEN-ELSE Syntax| IF () THEN ELSE | -| +||SetOf operator| { , }| -| +|| Pre-arbitration value specifier| (pre)| -| +|3|Predicate connector |.| Left| +|4 |Negation| ! | Right| +|5| Comparison (less than)| < | Left| +|| Comparison (greater than)| \> |Left| +|| Comparison (less than)| <= | Left| +|| Comparison (greater than)| \>= | Left| +|6| Equal sign (Comparison of values)| = | Left| +|| Equal sign (Comparison of objects)| == | Left| +|7| AND| AND |Left| +|8 |OR| OR | Left| +|9 |Implication| -\> | Left| + + +#### 8.1 Constraint + +Constraint describes constraint expressions. There are two types of constraint expressions Runtime constraints and Offline constraints. A Runtime constraint is a constraint expression that should be be true at the time of arbitration and controls the behavior of arbitration. An Offline constraint is a constraint expression that should be satisfied after arbitration and tests the arbitration result. + +Syntax: +```shell +Constraint [ID] { + description: [String] + runtime: [true|false] + [expression] +} +``` + +|Syntax element |Description| +| :--- | :---- | +|description: 0..1| Description| +|runtime: 1 |true: Runtime constraint| +||Arbitrate each Area / Zone to be true this constraint.| +||false: Offline constraint| +||Verify that this constraint is true after all Area arbitration.| +|[expression] 1| Constraint expression| + +Description example + +- AND/ OR/ Negation +
In the constraint expression, it is possible to express logical AND, logical OR, negation, which is a general logical operator, with AND, OR, and !. By using () you can also use in combination. + +Example: Content1 is displayed or Content2 and Content3 are not displayed at the same time. +```shell +Constraint SampleConstraint1 { +runtime: true +Content1.isVisible() OR !(Content2.isVisible() AND Content3.isVisible()) +} +``` +Example: SampleContent1 is displayed or SampleContent2 is not displayed. +```shell +Constraint SampleConstraint1 { + description: "Sample Constraint Expression" + runtime: true + SampleContent1.isVisible() OR !SampleContent2.isVisible() +} +``` + +- Implication + +Implications are false only if the left-hand side is true and the right-hand side is false, otherwise it is true. + +Example: SampleContent4 is displayed if there is a request of SampleContent4. +```shell +Constraint SampleConstraint3 { + runtime: true + SampleContent4.isActive() -> SampleContent4.isVisible() +} +``` + +Example: If SampleArea1 displays SampleContent3, SampleArea2 does not display SampleContent3. +```shell +Constraint SampleConstraint2 { + runtime: true + (SampleArea1.displayingContent() == SampleContent3) +-> !(SampleArea2.displayingContent() == SampleContent3) +} +``` + +Example: If the value of the content displayed on SampleArea1 is higher than the value of the content displayed in SampleArea2, hide SampleArea2. +```shell +Constraint SampleConstraint2 { + runtime: true + (SampleArea1.contentValue() > SampleArea2.contentValue()) +-> SampleArea2.isHidden()) +} +``` + +Example: If the value of property1 of the information received from other RBAModel (Project) is 1, Content10 is not displayed. +```shell +Constraint SampleConstraint { + (SampleScene1.isOn() AND SampleScene1.property1.get() = 1) + -> ! Content10.isVisible() +} +``` + +- For-All + +For-All targets a set, and it is true if all element of the set satisfies a lambda expression ({element name declaration | element condition}). +For the set, you can specify a defined set or an One-time set. (Refer to “Group definition” for more informations.) +
Example: If SampleContent1 is displayed, all Areas of AreaGroup1 is not displayed. +
It is assumed that "AreaGroup1" is defined as AreaSet. + +```shell +Constraint SampleConstraint { + runtime: true + SampleContent1.isVisible() -> +For-All AreaGroup1 { x | x.isHidden() } +} +``` + +- Exists + +Exists targets a set, and it is true if even one element of the set satisfies a Lambda expression ({element name declaration | element condition}). +
For the set, you can specify a defined set or an One-time set. (Refer to “Group definition” for more informations.) +
Example: If any Content of ContentGroup1 is displayed, all Areas of AreaGroup1 is not displayed. +
It is assumed that "ContentGroup1" is defined as ContentSet. +
It is assumed that "AreaGroup1" is defined as AreaSet. +```shell +Constraint SampleConstraint { + runtime: true + Exists ContentGroup1{ x | x.isVisible() } -> +For-All AreaGroup1 { x | x.isHidden() } +} +``` + +- IF-THEN-ELSE +Example: If the scene is SampleScene1, SampleContent4 is displayed, otherwise SampleContent4 is not displayed. + +```shell +Constraint SampleConstraint4 { + runtime: true + IF(SampleScene1.isOn()) + THEN + SampleContent4.isVisible() + ELSE + !SampleContent4.isVisible() +} +``` + +- (pre) +Example: If SampleContent 1 is displayed (before arbitration), SampleContent 2 is not displayed. +```shell +Constraint SampleConstraint { + runtime: true +(pre)SampleContent1.isVisible() -> !SampleContent2.isVisible() +} +``` + +- HasComeEarlierThan/HasComeLaterThan +Example: If request SampleContent 1 has come earlier then SampleContent 2, SampleContent 2 does not displayed. +```shell +Constraint SampleConstraint { + runtime: true +SampleContent1.hasComeEarlierThan(SampleContent2) -> !SampleContent2.isVisible() +} +``` +Below constraint behave as same as above. +```shell +Constraint SampleConstraint { + runtime: true +SampleContent2.hasComeLaterThan(SampleContent1) -> !SampleContent2.isVisible() +} +``` + +#### 8.2 Syntax sugar + +This syntax sugar simplifies the constraint expressions and improves their readability. You can use them like the existing constraint expressions. +Below are the syntax sugars that can be used. + +- Inequality（!=） +
It means that the left side value and the right side value are not equal. You can use this to compare objects. +True if the left side value and the right side value are not equal. +The types of expressions on the left and the right sides must match. + +|Type| Operator| +| :--- | :---- | +|Notation| != | +|ECE*| !( == )| + +*ECE: Equivalent constraint expression + +Description example: The ViewContent allocated to AreaA is not Content1. + +||| +| :--- | :---- | +|Notation| AreaA.allocatedContent() != Content1| +|ECE| !( AreaA.allocatedContent() == Content1)| + +- Allocation of Area/Zone +
It indicates that ViewContent/SoundContent is allocated to the Area/Zone. +True if theViewConten/SoundContentt is allocated to the Area/Zone. + +|Type| State reference of ViewContent| +| :--- | :---- | +|Notation| .isAllocatedTo()| +|ECE| .allocatedContent() == | + +Description example: The Content1 is allocated to the AreaA. + +||| +| :--- | :---- | +|Notation| Content1.isAllocatedTo(AreaA)| +|ECE| AreaA.allocatedContent() == Content1| + +- Allocation changing of Area/Zone +
It indicates a changing of the ViewContent’s/SoundContent’s allocated to the Area/Zone. +True if the changing happens. + +|Type |State reference of Area| +| :--- | :---- | +|Notation| .isChanged()| +|ECE| !((pre).allocatedContent() == .allocatedContent())| + +Description example: The ViewContent allocated to AreaA has changed. + +||| +| :--- | :---- | +|Notation| AreaA.isChanged()| +|ECE| !((pre)AreaA.allocatedContent() == AreaA.allocatedContent())| + +- Changing of a content allocated to Area/Zone +
It indicates whether a ViewContent/SoundContent allocated to the Area/Zone has changed to the specified ViewContent/SoundContent.True if the changing happens + +|Type |State reference of Area| +| :--- | :---- | +|Notation| .isTranslatedTo()| +|ECE| !((pre).allocatedContent() == ) AND (.allocatedContent() == )| + +Description example: A ViewContent allocated to the AreaA has changed to Content1. + +||| +| :--- | :---- | +|Notation| AreaA.isTranslatedTo(Content1)| +|ECE |!((pre)AreaA.allocatedContent() == Content1) AND (AreaA.allocatedContent() == Content1)| + +- Displaying in the Area +
It indicates whether the ViewContent displayed or not in the Area. +True if the ViewContent is displayed in the Area. + +|Type| State reference of ViewContent| +| :--- | :---- | +|Notation| .isDisplayedOn()| +|ECE| .isDisplayed() AND (.displayingContent() == )| + +Description example: The Content1 is displayed in the AreaA. + +||| +| :--- | :---- | +|Notation| Content1.isDisplayedOn(AreaA)| +|ECE| AreaA.isDisplayed() AND (AreaA.displayingContent() == Content1)| + +- Display changing of the Area +
It indicates whether the display of the Area changes or not. +True if the change happens. + +|Type |State reference of Area| +| :--- | :---- | +|Notation| .isChangedDisplay()| +|ECE |!((pre).displayingContent() == .displayingContent()) OR ((pre).isDisplayed() AND !.isDisplayed()) OR (!(pre).isDisplayed() AND .isDisplayed())| + +Description example: The display of the AreaA has changed. + +||| +| :--- | :---- | +|Notation |AreaA.isChangedDisplay()| +|ECE |!((pre)AreaA.displayingContent() == AreaA.displayingContent()) OR((pre)AreaA.isDisplayed() AND !AreaA.isDisplayed()) OR(!(pre)AreaA.isDisplayed() AND AreaA.isDisplayed())| + +- Changing of the displayed ViewContent to the specified ViewContent +
It indicates whether the ViewContent displayed in the Area has changed to anther specified ViewContent. +True if the change happens. + +|Type |State reference of Area| +| :--- | :---- | +|Notation| .isTranslatedViewTo()| +|ECE |(.isDisplayed()) AND (.displayingContent() == ) AND (!((pre).displayingContent() == ) OR !(pre) .isDisplayed())| + +Description example: A ViewContent displayed in the AreaA has changed to another Content1. + +||| +| :--- | :---- | +|Notation| AreaA.isTranslatedViewTo(Content1)| +|ECE| (AreaA.isDisplayed()) AND (AreaA.displayingContent() == Content1) AND (!((pre)AreaA.displayingContent() == Content1) OR !(pre)AreaA.isDisplayed())| + +- Hide a lower priority Area +
Compare the two Areas and hide the Area displaying a ViewContent with lower priority. + +|Type| State reference of Area| +| :--- | :---- | +|Notation| HideLowerPriority(, )| +|ECE| ((.contentValue() < .contentValue() -\> .isHidden()) AND (.contentValue() \> .contentValue() -\> .isHidden()))| + +Description example: AreaA and AreaB are compared to hide the Area which displays a ViewContent with lower priority. + +||| +| :--- | :---- | +|Notation| HideLowerPriority(AreaA, AreaB)| +|ECE| ((AreaA.contentValue() < AreaB.contentValue() -\> AreaA.isHidden()) AND (AreaA.contentValue() \> AreaB.contentValue() -\> AreaB.isHidden()))| + +### 9. Group definition + +#### 9.1 AreaSet + +When dealing with multiple Areas in the Constraint expression, in order to describe it simply, you can define multiple Areas together in one group. + +Syntax: +```shell +AreaSet [ID] { + description: [String] + target: [ [ID of Area] ] +} +``` + +|Syntax element | Description| +| :--- | :---- | +|description: | 0..1 Description| +|target: 0..* | Areas or AreaSets which compose the group. Specify the ID of the Area or the AreaSet with comma-separated.| + +Description example: +```shell +AreaSet MainScreen { + description: "Area constituting the main screen" + target: [SampleArea, SampleArea1, OtherAreaSet] +} +``` +#### 9.2 ViewContentSet + +When dealing with multiple ViewContents in the Constraint expression, in order to describe it simply, you can define multiple ViewContents together in one group. + +Syntax: +```shell +ViewContentSet [ID] { + description: [String] + allocatable: [ [ID of Area] ] + target: [ [ID of ViewContent] ] +} +``` + +|Syntax element | Description| +| :--- | :---- | +|description: | 0..1 Description| +|allocatable: 0..*| Displayable Areas or AreaSets.Specify the ID of the Areas or the AreaSets with comma-separated.| +|target: 0..*| ViewContents or ViewContentSets which compose the group. Specify the ID of the ViewContents or ViewContentSets with comma-separated.| + +Description example: +```shell +ViewContentSet InterruptContent{ + allocatable: [ + MessageArea, HUDMessageArea, InterruptAreaGroup + ] + target: [ + TEL,Power, ViewContentGroup + ] +} +``` + +#### 9.3 One-time Set + +Specify an set in the For-All or the Exists constraint, you can define the One-time set. + +Syntax: +```shell +{ [ID] } +``` + +|Syntax element | Description| +| :--- | :---- | +|[ID] 1..* |Element of the set. Specify the IDs of elements with comma-separated. +||The type of elements should be same.| +||At this time, Area and AreaSet regard it as the same type.( ViewContent and ViewContentSet are treat similarly.) + +- Description example: Define the One-time set as AreaSet. +```shell +Constraint SampleConstraint { + runtime: true + SampleContent1.isVisible() -> +For-All {Area1, Area2, Area3} { x | x.isHidden() } +} +``` + +- Description example: Define the One-time set as ViewContentSet. +```shell +Constraint SampleConstraint { + runtime: true + Exists {ViewContent1, ViewContentSet1} { x | x.isActive() -> x.isVisible() } +} +``` +### 10. Scene definition +#### 10.1 Scene +Scene comprehensively expresses the state at the time including the system, and it is used to switch the status of Area/Zone, View/Sound Content by Scene. You can also define the Global scene and share the results of arbitration among multiple RBA Models (Projects). + +Syntax: +```shell +Scene [ID] { + description: [String] + global: [true|false] + [Property] +} +``` + +|Syntax element | Description| +| :--- | :---- | +|description: 0..1| Description| +|global: 0..1| true: Global Scene for sharing arbitration results with other RBA Models (Projects).| +||false: Local Scene.| +||If not defined, consider it as "false".| +|[Property] 0..*| Information for sharing arbitration results with other RBA models (Projects).| +||Can define only if global is true.| + +Description example: +```shell +Scene AutoDrivingScene { + description: "In auto driving mode" +} + +Scene DisplayEventNotification { + global: true + int OverallPriority: 6 + int RiskSeverity: 3 + int RiskMargin: 1 +} +``` +#### 10.2 Property + +Property is arbitrary properties which is defined in the Scene. + +Syntax: +```shell +int [String]: [Number] +``` + +|Syntax element | Description| +| :--- | :---- | +|[String] 1 |Arbitrary Property name| +|[Number] 1 |Default value of Property. Positive integer can be specified.| + +Description example: +```shell +int RiskSeverity: 3 +``` + +### 11. Stereotype + +Syntax: +```shell +StereoType<[Target Model Name]> [ID] ([valiable]) @BEGIN@ +description: [String] + [Propaties of Element] +@END@ +``` + +|Syntax element | Description| +| :--- | :---- | +|description: 0..1| Description| +|[Target Model Name] 1| Identify the applicable model by describing the model element keywords| +||It can be applied to the Area, ViewContent models| +|[valiable] 0..*| Describe an arbitrary variable as the parameter to be replaced, which will be set in the property of the model element specified in [Target Model Name].If there are multiple variables, separate them with commas.| +|[Properties of Element] 1..*| Describe the properties of the model element specified in [Target Model Name].In the property, the value to be replaced is written in @{[variable]} .| +||The variables must match the variables described in ().| + +Description example: +```shell +Stereotype display_warnning (name,allocatable,priority) @BEGIN@ + description: “@{name}” + allocatable: [@{allocatable}] + Size WarnSize { + width: 300 + height: 100 + } + State NORMAL { piority: @{priority} } + +@END@ +``` + +### 12. Tag + +Syntax: +```shell +<<[Stereotype ID]>> | <<[Stereotype ID]>>{“[String]”} +``` + +|Syntax element | Description| +| :--- | :---- | +|[ID of Stereotype] 0..*| Can be assigned to Area, ViewContent| +||If StereoType is defined, then the child elements and attributes defined there will be expanded as child elements and attributes of this object| +||Multiple definitions can be made for a single model. To define more than one, define them consecutively.| +|[String] 0..* |Argument value| +||If there is no argument, it can be omitted| + +Description example: +```shell +ViewContent Warning_1 { + <>{ “Warning_01”,”Area1”,“1” } +} + +ViewContent Warning_2 { + <>{ “Warning_02”,”Area2”,”2” } +} + +Stereotype display_warnning (name,allocatable,priority) @BEGIN@ + description: “@{name}” + allocatable: [@{allocatable}] + Size WarnSize { + width: 300 + height: 100 + } + State NORMAL { piority: @{priority} } +@END@ +``` + +## Generate .json from .rba file +Download [prebuilt package](https://git.automotivelinux.org/staging/rba-tool/tree/tool_bin) + +- If some errors occur, RBAModel.json is not generated (exit code 1). +```` +java -cp ./ -jar JSONGenerator.jar "[path to model directory]" "[path to output directory]" +```` + +Example: + +- RBAModel.json file is generated in directory same as JSONGenerator.jar +```` +java -cp ./ -jar JSONGenerator.jar "./RBAModel.rba" +```` + +- RBAModel.json file is generated in ~/ directory +```` +java -cp ./ -jar JSONGenerator.jar "./RBAModel.rba" "~/" +```` +Note: For the reference .rba file is given under the path [prebuilt package/sample_model](https://git.automotivelinux.org/staging/rba-tool/tree/tool_bin/sample_model) diff --git a/docs/6_Component_Documentation/5_drm-leasemanager.md b/docs/6_Component_Documentation/5_drm-leasemanager.md new file mode 100644 index 0000000..3b7b2e9 --- /dev/null +++ b/docs/6_Component_Documentation/5_drm-leasemanager.md @@ -0,0 +1,108 @@ +--- +title: DRM lease manager +--- + +# DRM Lease Manager + +## Overview + +The DRM Lease Manager is used in AGL to allocate display controller outputs to different processes. Each process has direct access to its allocated output via the kernel DRM interface, and is prevented from accessing any other outputs managed by the display controller. + +The display controller partitioning is made possible by using the kernel DRM Lease feature. For more information on the DRM lease functionality, please see the Linux kernel [DRM userspace API documentation](https://www.kernel.org/doc/html/latest/gpu/drm-uapi.html). + + +## Usage + +### Building DRM Lease manager and sample clients + +Enable the `agl-drm-lease` AGL feature when setting up your build environment +with aglsetup.sh. + +This will add the drm-lease-manager package to the image, and will add DRM +lease support to the following packages: + +* weston +* kmscube + +kmscube is not included in the image by default. To add the package to the +image, add the following to your local.conf + +``` +IMAGE_INSTALL_append = " kmscube" +``` + +### Starting the DRM lease manager + +The drm-lease-manager must be the only process to directly open the DRM device. +Shut down any running window systems (eg. weston or agl-compositor) and run: + +```shell + systemctl start drm-lease-manager +``` + +This will create a lease for each output connection on the platform. +The name of each lease will be in the form of `card0-` + (eg. `card0-LVDS-1` or `card0-HDMI-A-1`) + +**Note**: `drm-lease-manager` can be started on a different display controller (i.e. not `card0`) by modifying the command line in the systemd unit file. + +Run the help command for details. + +```shell + drm-lease-manager --help +``` + +### Running weston + +weston can be started on any available DRM lease by running with the +`--drm-lease=` option. + +```shell + weston --drm-lease=card0-HDMI-A-1 +``` + +### Running kmscube sample +With the `drm-lease-manager` running, `kmscube` can display on any available +lease by launching it with the `-L -D` options. + +```shell + kmscube -L -Dcard0-HDMI-A-1 +``` + +Multiple weston or kmscube instances (one per DRM lease) can be started at the same time. + +## Adding support to your application + +The DRM Lease Manager packages includes a client library (libdlmclient) to request access to the DRM leases it creates. The client library provides file descriptors that can be used as if they were created by directly opening the underlying DRM device. + +Clients that want _direct access_ to the DRM device can use this library to do so. Compositor (agl-compositor or weston) client applications do not need to use this interface. + + +To use the DRM leases, clients only need to replace their calls to +`drmOpen()` and `drmClose()` with the appropriate libdlmclient API calls. + +### libdlmclient API usage + +_Error handling has been omitted for brevity and clarity of examples._ + +#### Requesting a lease from the DRM Lease Manager + +```c + struct dlm_lease *lease = dlm_get_lease("card0-HDMI-A-1"); + int drm_device_fd = dlm_lease_fd(lease); +``` + +`drm_device_fd` can now be used to access the DRM device + +#### Releasing a lease + +```c + dlm_release_lease(lease); +``` + +**Note: `drm_device_fd` is not usable after calling `dlm_release_lease()`** + +## Runtime directory +A runtime directory under `/var` is used to keep the Unix Domain sockets that the drm-lease-manager and clients to communicate with each other. + +The default path is `/var/run/drm-lease-manager`, but can be changed by setting the `DLM_RUNTIME_PATH` environment variable. diff --git a/docs/6_Component_Documentation/6_application_framework.md b/docs/6_Component_Documentation/6_application_framework.md new file mode 100644 index 0000000..1af8796 --- /dev/null +++ b/docs/6_Component_Documentation/6_application_framework.md @@ -0,0 +1,7 @@ +--- +title: Application Framework +--- + +# AppFW + +FIXME. diff --git a/docs/6_Component_Documentation/7_pipewire_wireplumber.md b/docs/6_Component_Documentation/7_pipewire_wireplumber.md new file mode 100644 index 0000000..e58b97d --- /dev/null +++ b/docs/6_Component_Documentation/7_pipewire_wireplumber.md @@ -0,0 +1,159 @@ +--- +title: PipeWire / WirePlumber +--- + +# PipeWire / WirePlumber + +## Overview + +AGL uses the PipeWire daemon service to provide audio playback and capture capabilities. +PipeWire is accompanied by a secondary service, WirePlumber (also referred to as the +*session manager*), which provides policy management, device discovery, configuration and more. + +Applications can connect to the PipeWire service through its UNIX socket, by using either the +*libpipewire* or *libwireplumber* libraries as a front-end to that socket. + +Upstream documentation for these components can be found at the links below: + +- [PipeWire documentation](https://docs.pipewire.org/) + +- [WirePlumber documentation](https://pipewire.pages.freedesktop.org/wireplumber/) + +- [PipeWire Wiki](https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/home) + +## APIs + +### libpipewire + +The main entry point for applications to access the audio system is the API offered by +*libpipewire*. The functionality offered by *libpipewire* is vast and it is beyond the +scope of this document to describe it all. + +For playback and capture, applications should use *struct pw_stream* and its associated methods. +See [PipeWire: Tutorial - Part 4: Playing a tone](https://docs.pipewire.org/page_tutorial4.html) +for a starting point. + +### GStreamer (Recommended) + +For convenience, applications that use GStreamer can use the PipeWire GStreamer elements to +plug the functionality offered by *struct pw_stream* directly in the GStreamer pipeline. These +elements are called *pipewiresrc* and *pipewiresink* + +Example: + +```shell +> gst-launch-1.0 audiotestsrc ! pipewiresink +``` + +Through these elements, it is possible to specify the application role by setting it in the +*stream-properties* property of the element, as shown below: + +```shell +> gst-launch-1.0 audiotestsrc ! pipewiresink stream-properties="p,media.role=Multimedia"" +``` + +or, in the C API: + +```c +gst_util_set_object_arg (sink, "stream-properties", "p,media.role=Multimedia"); +``` + +Of course, it is also possible to use *alsasink* and *alsasrc* and route audio through the +virtual ALSA device that is mentioned below. This is also the default behavior of *playbin* +and similar auto-plugging elements, because the PipeWire GStreamer elements are not autoplugged +(this may change in a future version). + +### ALSA + +PipeWire offers a virtual ALSA device (called *pipewire*) that redirects audio to PipeWire +through an ALSA PCM plugin. This device is the default one, so unless you explicitly specify +a device in your ALSA client application, audio will go through PipeWire instead. + +Example: + +```shell +> aplay sound.wav # the default device is 'pipewire' +> aplay -D pipewire sound.wav +``` + +In order to specify the application role while using the ALSA compatibility device, pass the role +as a device parameter like this: + +```shell +> aplay -D pipewire:ROLE=Navigation turnleft.wav +``` + +### Audiomixer service + +See the separate [agl-service-audiomixer](https://git.automotivelinux.org/apps/agl-service-audiomixer/about/) documentation. + +### libwireplumber + +The WirePlumber library provides API that wraps libpipewire and makes it easier to work with +when you are writing control applications, such as a volume mixer. The audiomixer service is in +fact implemented using *libwireplumber*. + +WirePlumber also provides support for lua-based scripting. Standalone scripts, executed with the +*wpexec* tool, may be used as a means to rapidly make use of the API provided by *libwireplumber* + +## Tools + +* **wpctl**: allows inspecting the devices, choosing which source & sink are the default ones + and allows volume/mute adjustments to be made on the command line. Try `wpctl status` and + `wpctl help` to get started with it + +* **wpexec**: allows running wireplumber lua scripts standalone, which is useful to implement + custom scripts to interact with PipeWire + +* **pw-cli**: this is the main tool for interacting with pipewire directly + +* **pw-dump**: dumps all the objects in the pipewire graph to a big JSON. The output of this + tool is very useful to include in bug reports. It is also suitable for implementing scripts + that parse information with jq + +* **pw-dot** is a useful debug tool that dumps the objects in a dot graph for easy visualization + +* **pw-cat / pw-play / pw-record**: This is a set of tools similar to aplay/arecord, for simple + audio operations + +* **pw-top**: This is a performance measurement tool that shows realtime timing information + about the audio pipeline. Before running this tool, you will need to uncomment the loading + of "libpipewire-module-profiler" in /etc/pipewire/pipewire.conf and restart pipewire + +## Systemd Integration + +The PipeWire service, `pipewire.service`, is activated on demand, via systemd socket activation, +by `pipewire.socket`. The WirePlumber service, `wireplumber.service`, is bound to the pipewire +service and therefore started and stopped together with the PipeWire service. + +If you wish to manually stop or restart both services, you can do so by using *systemctl*, +operating on the *.socket* unit: + +```shell +> systemctl restart pipewire.socket +> systemctl stop pipewire.socket +``` + +## Debugging + +The PipeWire daemon can be configured to be more verbose by editing +**/etc/pipewire/pipewire.conf** and setting `log.level=n` (n=0-5) in section +`context.properties`. + +Similarly, the WirePlumber daemon can be configured to be more verbose by editing +**/etc/wireplumber/wireplumber.conf** and setting `log.level=n` (n=0-5) in section +`context.properties`. + +All messages will be available in the systemd journal, inspectable with journalctl. + +For applications, at runtime, `PIPEWIRE_DEBUG` can be set to a value between 0 and 5, +with 5 being the most verbose and 0 the least verbose. + +For applications that use *libwireplumber* the equivalent environment variable is +`WIREPLUMBER_DEBUG`, which also takes values between 0 and 5. + +The default debug level for the daemons is 2, while for applications it's 0 +(with few exceptions). + +More information is also available on +[WirePlumber's documentation on debug logging](https://pipewire.pages.freedesktop.org/wireplumber/daemon-logging.html) diff --git a/docs/6_Component_Documentation/8_ic-sound-manager.md b/docs/6_Component_Documentation/8_ic-sound-manager.md new file mode 100644 index 0000000..75e163e --- /dev/null +++ b/docs/6_Component_Documentation/8_ic-sound-manager.md @@ -0,0 +1,120 @@ +# Instrument Cluster Sound Management + +## Introduction + +This document describes the design of the software setup which enables the integration +of AGL’s sound system with applications running in the Instrument Cluster domain. +This software setup is specific to the case where a single system is used to implement +both the Instrument Cluster and some other domain of the vehicle, typically the +In-Vehicle-Infotainment domain, using container technology to separate them. + +Applications running in the Instrument Cluster need a way to safely play important +sounds to alert the driver of conditions that need the driver’s attention. At the same +time, in a containerized environment that serves multiple vehicle domains, applications +running in other containers may be using the sound hardware to play less important sounds, +such as music, which conflicts with the IC’s need to play sound on the same hardware. + +The solution developed here, for safety reasons, relies on the operating system and the +hardware itself to allow the IC applications to stream sounds to the speakers using a +dedicated device handle, while applications from other domains are all routed through a +sound server that runs on the host container and operates on a different sound device handle. + +However, to achieve good inter-operation, there is need for additional software mechanisms +that will work in combination with this hardware-based solution. First of all, it is necessary +to have a mechanism that allows IC applications to pause all sounds that are being routed via +the sound server while there is an important IC sound playing and resume them afterwards. +This is so that other domain applications can be informed of this temporary pause and offer +the appropriate user experience. Secondly, it is desirable to have separation of duties +between the host and the other domain’s (non-IC) container. It should be the responsibility +of the other domain’s container to implement the sound system policy, so that the host does +not need to be aware of the exact applications that are running on this container. + +## Requirements + +- Single system shared between IC and at least one secondary domain (IVI, other ...) + +- The domains are separated using containers + +- All the containers, including the host, are running a variant of AGL + +- The host OS and the secondary domain container use PipeWire and WirePlumber + to implement the sound system + +- The sound hardware offers, on the Linux kernel driver side, a separate ALSA + device for sounds that belong to the IC and a separate ALSA device for other sounds + +## Architectural design + +![Architecture overview](images/ic-sound-manager/architecture.png) + +The core of the sound system consists of the PipeWire daemon, which is responsible for routing +audio between the kernel and applications running in the “Other Container”. + +The PipeWire session is orchestrated by a secondary daemon, WirePlumber. WirePlumber is +designed in such a way so that it can have multiple instances, for task separation. +One instance shall be running in the host container and it shall be responsible for +managing the devices that PipeWire handles as well as the security isolation between +different applications and different containers. At least one more instance shall be +running in the “Other Container” and be responsible for implementing policy mechanisms +related to the applications that are running in that container. + +Further WirePlumber instances are possible to run as well. For instance, it may be desirable +to have another “policy” instance in a third container that implements another vehicle system +and shares the main PipeWire daemon from the host. Additionally, the “Other Container” may +be running a separate WirePlumber instance to manage bluetooth audio devices, which shall be +the responsibility of that container instead of the host. + +To implement communication between the IC and the host, a third daemon is used: pipewire-ic-ipc. +This daemon listens on a UNIX domain socket for messages from the IC applications and offers +them the ability to pause or resume sounds that are being routed via PipeWire. + +Finally, IC applications are given a library (icipc library) that allows them to send messages +to pipewire-ic-ipc on the host. This library is minimal and has no external dependencies, +for safety reasons. + +For sound playback, IC applications are expected to use the ALSA API directly and communicate +with the dedicated ALSA device that is meant for IC sounds. Arbitration of this device between +different IC applications is out of scope for this document and it is assumed to be a solved +problem. + +### PipeWire-IC-IPC + +This component acts as the server-side component for the UNIX socket that is used for +communication between the IC applications and the host. It is implemented as a pipewire module, +therefore it needs the `/usr/bin/pipewire` process in order to be launched. Launching happens +with a special configuration file (`pipewire-ic-ipc.conf`) which instructs this PipeWire process +to be launched as a client (`core.daemon = false`) and to load only `module-ic-ipc` together +with `module-protocol-native`. The latter enables communication with the daemon instance of +PipeWire (`core.daemon = true`), which implements the sound server. + +![PipeWire-IC-IPC Processes](images/ic-sound-manager/pipewire-ic-ipc-processes.png) + +### icipc library + +The IC Application is given a library (‘libicipc’) that implements the client side of +pipewire-ic-ipc. This library allows sending two commands: + +- SUSPEND + - Asks WirePlumber (via PipeWire) to cork applications and mute the ALSA device used by PipeWire +- RESUME + - Reverts the effects of SUSPEND + +IC Applications are expected to send the SUSPEND command before starting playback of a sound +to their dedicated ALSA device. The RESUME command should be sent after playback of this IC +sound has finished. + +It should be noted that the RESUME command is also issued automatically when the IC application +disconnects from the pipewire-ic-ipc UNIX socket. + +If multiple IC application issue SUSPEND to the pipewire-ic-ipc server, then only the first +SUSPEND generates actions for WirePlumber. The rest are counted and the pipewire-ic-ipc +server expects an equal number of RESUME commands before generating resume actions for +WirePlumber. + +The implementation of the SUSPEND/RESUME mechanism uses PipeWire’s metadata to signal +WirePlumber. PipeWire-IC-IPC will look for the “default” metadata object in PipeWire’s list +of objects and will write the “suspend.playback” key with a value of “true” on id 0. +The metadata change is then notified to all clients. WirePlumber, being a client, gets +notified of this change and takes actions. All actions are defined in Lua scripts. + +![PipeWire-IC-IPC Calls](images/ic-sound-manager/pipewire-ic-ipc-calls.png) diff --git a/docs/6_Component_Documentation/images/agl-compositor/arch_diagram.png b/docs/6_Component_Documentation/images/agl-compositor/arch_diagram.png new file mode 100644 index 0000000..88a4381 Binary files /dev/null and b/docs/6_Component_Documentation/images/agl-compositor/arch_diagram.png differ diff --git a/docs/6_Component_Documentation/images/agl-compositor/drawing_shell.png b/docs/6_Component_Documentation/images/agl-compositor/drawing_shell.png new file mode 100644 index 0000000..bcd0a98 Binary files /dev/null and b/docs/6_Component_Documentation/images/agl-compositor/drawing_shell.png differ diff --git a/docs/6_Component_Documentation/images/ic-sound-manager/architecture.png b/docs/6_Component_Documentation/images/ic-sound-manager/architecture.png new file mode 100644 index 0000000..3d0820f Binary files /dev/null and b/docs/6_Component_Documentation/images/ic-sound-manager/architecture.png differ diff --git a/docs/6_Component_Documentation/images/ic-sound-manager/pipewire-ic-ipc-calls.png b/docs/6_Component_Documentation/images/ic-sound-manager/pipewire-ic-ipc-calls.png new file mode 100644 index 0000000..9003e60 Binary files /dev/null and b/docs/6_Component_Documentation/images/ic-sound-manager/pipewire-ic-ipc-calls.png differ diff --git a/docs/6_Component_Documentation/images/ic-sound-manager/pipewire-ic-ipc-processes.png b/docs/6_Component_Documentation/images/ic-sound-manager/pipewire-ic-ipc-processes.png new file mode 100644 index 0000000..494b760 Binary files /dev/null and b/docs/6_Component_Documentation/images/ic-sound-manager/pipewire-ic-ipc-processes.png differ diff --git a/docs/6_Component_Documentation/images/rba/Basic_syntax.png b/docs/6_Component_Documentation/images/rba/Basic_syntax.png new file mode 100644 index 0000000..6704abd Binary files /dev/null and b/docs/6_Component_Documentation/images/rba/Basic_syntax.png differ diff --git a/docs/6_Component_Documentation/images/rba/model.png b/docs/6_Component_Documentation/images/rba/model.png new file mode 100644 index 0000000..e43289e Binary files /dev/null and b/docs/6_Component_Documentation/images/rba/model.png differ diff --git a/docs/6_How_To_Contribute/1_Getting_Linux_Foundation_account.md b/docs/6_How_To_Contribute/1_Getting_Linux_Foundation_account.md deleted file mode 100644 index f2b2cb7..0000000 --- a/docs/6_How_To_Contribute/1_Getting_Linux_Foundation_account.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: Getting Linux Foundation account ---- - -In order to participate in the development of the Automotive Grade Linux -project, you will need a Linux Foundation account. You will need to use -your LF ID to access to all the AGL community development tools, -including [Gerrit](http://gerrit.automotivelinux.org/), -[Jira](https://jira.automotivelinux.org/) and the -[Wiki](https://wiki.automotivelinux.org/) (for editing, only). - -**NOTE:** Further information about Contributing to the AGL Distro -available at [AGL wiki](https://wiki.automotivelinux.org/agl-distro/contributing). - -## Creating Linux Foundation ID - - 1. Go to the [Linux Foundation ID website](https://identity.linuxfoundation.org/). - - 2. Select the option `I need to create a Linux Foundation ID`, and fill - out the form that appears. (It is advised to authenticate through email - instead of logging through Facebook/Google/Github.) - - 3. Wait a few minutes, then look for an email message with the subject - line: `Validate your Linux Foundation ID email`. - - 4. Open the received URL to validate your email address. - - 5. Verify that your browser displays the message ``You have - successfully validated your e-mail address``. - - 6. Access [Gerrit](http://gerrit.automotivelinux.org/) by selecting - ``Sign In``, and use your new Linux Foundation account ID to sign in. - -## Configuring Gerrit to Use SSH - -Gerrit uses SSH to interact with your Git client. If you already have an SSH -key pair, you can skip the part of this section that explains how to generate one. - -What follows explains how to generate an SSH key pair in a Linux environment --- -follow the equivalent steps on your OS. - -First, create an SSH key pair with the command: -**Note:** This guide recommends using ed25519 keys because it has been found that this type works well across all operating systems. - - ```sh - $ ssh-keygen -t ed25519 -C "your_name@example.com" - ``` - -**Note:** When you’re prompted to “Enter a file in which to save the key” press Enter. This accepts the default location. Next, it will ask you for a password to protect the private key as -it generates a unique key. Please keep this password private, and DO NOT -enter a blank password. - -The generated SSH key pair can be found in the files ``~/.ssh/id_ed25519`` and -``~/.ssh/id_ed25519.pub``. - -Next, add the private key in the ``id_ed25519`` file to your key ring, e.g.: - - ```sh - $ ssh-add ~/.ssh/id_ed25519 - ``` - -Finally, add the public key of the generated key pair to the Gerrit -server, with the following steps: - -1. Go to [Gerrit](http://gerrit.automotivelinux.org/). - -2. Click on your account name in the upper right corner. - -3. From the pop-up menu, select ``Settings``. - -4. On the left side menu, click on ``SSH Public Keys``. - -5. Paste the contents of your public key ``~/.ssh/id_ed25519.pub`` and click - ``Add key``. - -**Note:** The ``id_ed25519.pub`` file can be opened with any text editor or you can run the command ``cat ~/.ssh/id_ed25519.pub`` in your terminal and copy output. Ensure that all the contents of the file are selected, copied and pasted into the ``Add SSH key`` window in Gerrit. - -**Note:** The SSH key generation instructions operate on the assumption -that you are using the default naming. It is possible to generate -multiple SSH keys and to name the resulting files differently. See the -[ssh-keygen](https://en.wikipedia.org/wiki/Ssh-keygen) documentation for -details on how to do that. Once you have generated non-default keys, you -need to configure SSH to use the correct key for Gerrit. In that case, -you need to create a ``~/.ssh/config`` file with command ``touch ~/.ssh/config`` and add details in config file. - -``` -host gerrit.automotivelinux.org - HostName gerrit.automotivelinux.org - IdentityFile ~/.ssh/id_ed25519 - User - Port 29418 -``` - -`` is your Linux Foundation ID(username) and the value of IdentityFile is the -name of the public key file you generated. - -**Warning:** Potential Security Risk! Do not copy your private key -``~/.ssh/id_ed25519``. Use only the public ``~/.ssh/id_ed25519.pub``. diff --git a/docs/6_How_To_Contribute/2_Using_Jira_for_current_work_items.md b/docs/6_How_To_Contribute/2_Using_Jira_for_current_work_items.md deleted file mode 100644 index 49b443d..0000000 --- a/docs/6_How_To_Contribute/2_Using_Jira_for_current_work_items.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Using Jira for current work items ---- - -This document has been created to give further insight into the work in progress -towards the Automotive Grade Linux architecture based on the community roadmap. -The requirements for the roadmap are being tracked in -[Jira](https://jira.automotivelinux.org/). - -On this page you will see all the public (and restricted) boards that have been -created. For example the **Board Name** *CI and Automated Test Expert Group*: - -![Jira boards](images/jira-2.png) - -When you click on *CI and Automated Test Expert Group* under **Board name** you -will be directed to a page that contains the following columns: - -![Jira boards](images/jira-3.png) - -The meanings to these columns are as follows: - -- **NOT STARTED** – list of items slated for the current sprint (sprints are - defined in 2 week iterations), but are not currently in progress -- **IN PROGRESS** – items currently being worked by someone in the community. -- **DONE** – items merged and complete in the sprint. - -If there is an item you are interested in working on, want more information or -have questions, or if there is an item that you feel needs to be in higher -priority, please add comments directly to the Jira item. All feedback and help -is very much appreciated. \ No newline at end of file diff --git a/docs/6_How_To_Contribute/3_Working_with_Gerrit.md b/docs/6_How_To_Contribute/3_Working_with_Gerrit.md deleted file mode 100644 index ccd9133..0000000 --- a/docs/6_How_To_Contribute/3_Working_with_Gerrit.md +++ /dev/null @@ -1,153 +0,0 @@ ---- -title: Working with Gerrit ---- - -Follow these instructions to collaborate on AGL through the Gerrit review -system. - -Please be sure that you are subscribed to the [mailing -list](https://lists.automotivelinux.org/g/agl-dev-community) and of course, you -can reach out on IRC at the #automotive channel on irc.libera.chat - -Gerrit assigns the following roles to users: - -- **Submitters**: May submit changes for consideration, review other code - changes, and make recommendations for acceptance or rejection by voting +1 or - -1, respectively. -- **Maintainers**: May approve or reject changes based upon feedback from - reviewers voting +2 or -2, respectively. - -## Getting deeper into Gerrit - -A comprehensive walk-through of Gerrit is beyond the scope of this document. -There are plenty of resources available on the Internet. A good summary can be -found [here](https://www.mediawiki.org/wiki/Gerrit/Tutorial) and [Basic Gerrit -Walkthrough for GitHub -Users](https://gerrit-review.googlesource.com/Documentation/intro-gerrit-walkthrough-github.html). - -## Working with a local clone of the repository - -To work on something, whether a new feature or a bugfix: - -1. Open the Gerrit [repo - page](https://gerrit.automotivelinux.org/gerrit/admin/repos/). - -2. Select the repository you wish to work on. - -3. Open a terminal window and clone the project locally using the ``Clone with - git hook`` URL. Be sure that ``ssh`` is also selected, as this will make - authentication much simpler. For example, for `documentation` repository: - - ```sh - $ git clone "ssh://@gerrit.automotivelinux.org:29418/AGL/documentation" && scp -p -P - 29418 @gerrit.automotivelinux.org:hooks/commit-msg "documentation/.git/hooks/" - ``` - -4. Setup `user` and `email` for git config - - ```sh - $ cd documentation - $ git.config --global user.name "Your Full Name" - $ git config --global user.email "your@email.com" - ``` - - **NOTE:** To only configure for a particular repository : - - ```sh - $ cd documentation - $ git.config user.name "Your Full Name" - $ git config user.email "your@email.com" - ``` - -5. Create a descriptively-named branch off of your cloned repository - - ```sh - $ git checkout -b issue-nname - ``` - -## Using git review - -There's a **very** useful tool for working with Gerrit called -[git-review](https://www.mediawiki.org/wiki/Gerrit/git-review). This -command-line tool can automate most of the ensuing sections for you. Ofcourse, -reading the information below is also highly recommended so that you understand -what's going on behind the scenes. - -```sh -# for first time use only -$ git review -s -``` -If `.gitreview` is missing, add the following section to ``.git/config``, and -replace ```` with your LFID id. - -```sh -[remote "gerrit"] - url = ssh://@gerrit.automotivelinux.org:29418/AGL/documentation.git - fetch = +refs/heads/*:refs/remotes/gerrit/* -``` - -Then submit your change with ``git review``. - -```sh -$ cd documentation -$ git review -``` - -When you update your patch, you can commit with ``git commit --amend``, and then -repeat the ``git review`` command. - -## Typical Review Workflow - - - New Fresh Change - - ```sh - $ cd documentation # Working Repository - $ git remote -v update # Updating wrt remote - $ git checkout -b mytopicbranch origin/master # Creating new branch - ### CODE the CHANGES - $ git add  # Track the changed files - $ git commit -s # Signed Commit Message - $ git review # Submit Changes to review - ``` - - - Updating existing Gerrit Review - - ```sh - $ cd documentation # Working Repository - $ git review -d 25678 # Download review, 25678 is change number - ### CODE the CHANGES - $ git add  # Track the changed files - $ git commit -s # Signed Commit Message - $ git review # Submit Changes to review - $ git checkout master # Return to master branch - ``` - -## Reviewing Using Gerrit - -- **Add**: This button allows the change submitter to manually add names of - people who should review a change; start typing a name and the system will - auto-complete based on the list of people registered and with access to the - system. They will be notified by email that you are requesting their input. - -- **Abandon**: This button is available to the submitter only; it allows a - committer to abandon a change and remove it from the merge queue. - -- **Change-ID**: This ID is generated by Gerrit (or system). It becomes useful - when the review process determines that your commit(s) have to be amended. - You may submit a new version; and if the same Change-ID header (and value) - are present, Gerrit will remember it and present it as another version of the - same change. - -- **Status**: Currently, the example change is in review status, as indicated - by “Needs Verified” in the upper-left corner. The list of Reviewers will all - emit their opinion, voting +1 if they agree to the merge, -1 if they - disagree. Gerrit users with a Maintainer role can agree to the merge or - refuse it by voting +2 or -2 respectively. - -Notifications are sent to the email address in your commit message's -Signed-off-by line. Visit your [Gerrit -dashboard](https://gerrit.automotivelinux.org/gerrit/dashboard/self), to check -the progress of your requests. - -The history tab in Gerrit will show you the in-line comments and the author of -the review. diff --git a/docs/6_How_To_Contribute/4_Submitting_Changes.md b/docs/6_How_To_Contribute/4_Submitting_Changes.md deleted file mode 100644 index d226450..0000000 --- a/docs/6_How_To_Contribute/4_Submitting_Changes.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Submitting Changes ---- - -Carefully review the following before submitting a change. These guidelines -apply to developers that are new to open source, as well as to experienced open -source developers. - -## Change Requirements - - -This section contains guidelines for submitting code changes for review. For -more information on how to submit a change using Gerrit, please see [Working -with Gerrit](./3_Working_with_Gerrit.md). - -Changes are submitted as Git commits. Each commit must contain: - -- a short and descriptive subject line that is 72 characters or fewer, followed - by a blank line. -- a change description with your logic or reasoning for the changes, followed - by a blank line -- a Signed-off-by line, followed by a colon (Signed-off-by:) -- a Change-Id identifier line, followed by a colon (Change-Id:). Gerrit won't - accept patches without this identifier. - -A commit with the above details is considered well-formed. [This -page](https://chris.beams.io/posts/git-commit/) is a very useful for the same. - -All changes and topics sent to Gerrit must be well-formed. Informationally, -``commit messages`` must include: - -- **what** the change does, -- **why** you chose that approach, and -- **how** you know it works -- for example, which tests you ran. - -For example: One commit fixes whitespace issues, another renames a function and -a third one changes the code's functionality. An example commit file is -illustrated below in detail: - -```sh - -A short description of your change with no period at the end - -You can add more details here in several paragraphs, but please keep each line -width less than 80 characters. A bug fix should include the issue number. - -Bug-AGL: [SPEC-] -Change-Id: IF7b6ac513b2eca5f2bab9728ebd8b7e504d3cebe1 -Signed-off-by: Your Name -``` - -Include the issue ID in the one line description of your commit message for -readability. Gerrit will link issue IDs automatically to the corresponding entry -in Jira. - -Each commit must also contain the following line at the bottom of the commit -message: - -```sh -Signed-off-by: Your Name -``` - -The name in the Signed-off-by line and your email must match the change -authorship information. Make sure your :file:``.git/config`` is set up -correctly. Always submit the full set of changes via Gerrit. - -When a change is included in the set to enable other changes, but it will not be -part of the final set, please let the reviewers know this. diff --git a/docs/6_How_To_Contribute/5_Reviewing_Changes.md b/docs/6_How_To_Contribute/5_Reviewing_Changes.md deleted file mode 100644 index e9d6758..0000000 --- a/docs/6_How_To_Contribute/5_Reviewing_Changes.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: Reviewing Changes ---- - -1. Click on a link for incoming or outgoing review. - -2. The details of the change and its current status are loaded: - - ![review](images/review.png) - - - **Status:** Displays the current status of the change. - - - **Reply:** Click on this button after reviewing to add a final review - message and a score, -1, 0 or +1. - - - **Patch Sets:** If multiple revisions of a patch exist, this button - enables navigation among revisions to see the changes. By default, the - most recent revision is presented. - - - **Download:** This button brings up another window with multiple - options to download or checkout the current changeset. The button on - the right copies the line to your clipboard. You can easily paste it - into your git interface to work with the patch as you prefer. - - Underneath the commit information, the files that have been changed by - this patch are displayed. - -3. Click on a filename to review it. Select the code base to differentiate - against. The default is ``Base`` and it will generally be what is needed. - -4. The review page presents the changes made to the file. At the top of the - review, the presentation shows some general navigation options. Navigate - through the patch set using the arrows on the top right corner. It is - possible to go to the previous or next file in the set or to return to the - main change screen. Click on the yellow sticky pad to add comments to the - whole file. - - The focus of the page is on the comparison window. The changes made are - presented in green on the right versus the base version on the left. - Double click to highlight the text within the actual change to provide - feedback on a specific section of the code. Press *c* once the code is - highlighted to add comments to that section. - -5. After adding the comment, it is saved as a *Draft*. - -6. Once you have reviewed all files and provided feedback, click the *green up - arrow* at the top right to return to the main change page. Click the - ``Reply`` button, write some final comments, and submit your score for the - patch set. Click ``Post`` to submit the review of each reviewed file, as well - as your final comment and score. Gerrit sends an email to the - change-submitter and all listed reviewers. Finally, it logs the review for - future reference. All individual comments are saved as *Draft* until the - ``Post`` button is clicked. - - diff --git a/docs/6_How_To_Contribute/6_Gerrit_Recommended_Practices.md b/docs/6_How_To_Contribute/6_Gerrit_Recommended_Practices.md deleted file mode 100644 index 671c685..0000000 --- a/docs/6_How_To_Contribute/6_Gerrit_Recommended_Practices.md +++ /dev/null @@ -1,263 +0,0 @@ ---- -title: Gerrit Recommended Practices ---- - -This document presents some best practices to help you use Gerrit more -effectively. The intent is to show how content can be submitted easily. Use the -recommended practices to reduce your troubleshooting time and improve -participation in the community. - -## Commit Messages - -Gerrit follows the Git commit message format. Ensure the headers are at the -bottom and don't contain blank lines between one another. The following example -shows the format and content expected in a commit message: - -Brief (no more than 50 chars) one line description. - -Elaborate summary of the changes made referencing why (motivation), what was -changed and how it was tested. Note also any changes to documentation made to -remain consistent with the code changes, wrapping text at 72 chars/line. - -```sh -Bug-AGL: SPEC- - -Change-Id: LONGHEXHASH -Signed-off-by: Your Name your.email\@example.org -``` - -The Gerrit server provides a precommit hook to autogenerate the Change-Id which -is one time use. - -**Recommended reading:** [How to Write a Git Commit -Message](http://chris.beams.io/posts/git-commit/). - -## Avoid Pushing Untested Work to a Gerrit Server - -To avoid pushing untested work to Gerrit. - -Check your work at least three times before pushing your change to Gerrit. Be -mindful of what information you are publishing. - -## Keeping Track of Changes - -- Set Gerrit to send you emails: - -- Gerrit will add you to the email distribution list for a change if a - developer adds you as a reviewer, or if you comment on a specific Patch Set. - -- Opening a change in Gerrit's review interface is a quick way to follow that - change. - -- Watch projects in the Gerrit projects section at ``Gerrit``, select at least - *New Changes, New Patch Sets, All Comments* and *Submitted Changes*. - -Always track the projects you are working on; also see the feedback/comments -[mailing list](https://lists.automotivelinux.org/g/agl-dev-community) to learn -and help others ramp up. - -## Topic branches - -Topic branches are temporary branches that you push to commit a set of -logically-grouped dependent commits: - -To push changes from ``REMOTE/master`` tree to Gerrit for being reviewed as a -topic in **TopicName** use the following command as an example: - -```sh -$ git push REMOTE HEAD:refs/for/master/TopicName -``` - -The topic will show up in the review ``UI`` and in the ``Open Changes List``. -Topic branches will disappear from the master tree when its content is merged. - -## Finding Available Topics - -```sh -$ ssh -p 29418 @gerrit.automotivelinux.org gerrit query \ status:open branch:master| grep topic: | sort -u -``` - -- [gerrit.automotivelinux.org](https://gerrit.automotivelinux.org) is the - current URL where the project is hosted. -- *status* : Indicates the topic's current status: open , merged, abandoned, - draft, merge conflict. -- *project* : Refers to the current name of the project, in this case fabric. -- *branch* : The topic is searched at this branch. -- *topic* : The name of an specific topic, leave it blank to include them all. -- *sort* : Sorts the found topics, in this case by update (-u). - -## Downloading or Checking Out a Change - -In the review UI, on the top right corner, the **Download** link provides a list -of commands and hyperlinks to checkout or download diffs or files. - -We recommend the use of the *git review* plugin. The steps to install git review -are beyond the scope of this document. Refer to the [git review -documentation](https://wiki.openstack.org/wiki/Documentation/HowTo/FirstTimers) -for the installation process. - -To check out a specific change using Git, the following command usually works: - -```sh -$ git review -d CHANGEID -``` - -If you don't have Git-review installed, the following commands will do the same -thing: - -```sh -$ git fetch REMOTE refs/changes/NN/CHANGEIDNN/VERSION \ && git checkout FETCH_HEAD -``` - -For example, for the 4th version of change 2464, NN is the first two digits -(24): - -```sh -$ git fetch REMOTE refs/changes/24/2464/4 \ && git checkout FETCH_HEAD -``` - -## Using Sandbox Branches - -You can create your own branches to develop features. The branches are pushed to -the ``refs/heads/sandbox/USERNAME/BRANCHNAME`` location. - -These commands ensure the branch is created in Gerrit's server. - -```sh -$ git checkout -b sandbox/USERNAME/BRANCHNAME -$ git push --set-upstream REMOTE HEAD:refs/heads/sandbox/USERNAME/BRANCHNAME -``` - -Usually, the process to create content is: - -- develop the code, -- break the information into small commits, -- submit changes, -- apply feedback, -- rebase. - -The next command pushes forcibly without review: - -```sh -$ git push REMOTE sandbox/USERNAME/BRANCHNAME -``` - -You can also push forcibly with review: - -```sh -$ git push REMOTE HEAD:ref/for/sandbox/USERNAME/BRANCHNAME -``` - -## Updating the Version of a Change - -During the review process, you might be asked to update your change. It is -possible to submit multiple versions of the same change. Each version of the -change is called a patch set. - -Always maintain the **Change-Id** that was assigned. For example, there is a -list of commits, **c0...c7**, which were submitted as a topic branch: - -```sh - -$ git log REMOTE/master..master - - c0 - ... - c7 - -$ git push REMOTE HEAD:refs/for/master/SOMETOPIC -``` - -After you get reviewers' feedback, there are changes in **c3** and **c4** that -must be fixed. If the fix requires rebasing, rebasing changes the commit Ids, -see the [rebasing](http://git-scm.com/book/en/v2/Git-Branching-Rebasing) section -for more information. However, you must keep the same Change-Id and push the -changes again: - -```sh -$ git push REMOTE HEAD:refs/for/master/SOMETOPIC -``` - -This new push creates a patches revision, your local history is then cleared. -However you can still access the history of your changes in Gerrit on the -``review UI`` section, for each change. - -It is also permitted to add more commits when pushing new versions. - -### Rebasing - -Rebasing is usually the last step before pushing changes to Gerrit; this allows -you to make the necessary *Change-Ids*. The *Change-Ids* must be kept the same. - -- **squash:** mixes two or more commits into a single one. -- **reword:** changes the commit message. -- **edit:** changes the commit content. -- **reorder:** allows you to interchange the order of the commits. -- **rebase:** stacks the commits on top of the master. - -## Rebasing During a Pull - -Before pushing a rebase to your master, ensure that the history has a -consecutive order. - -For example, your ``REMOTE/master`` has the list of commits from **a0** to -**a4**; Then, your changes **c0...c7** are on top of **a4**; thus: - -```sh -$ git log --oneline REMOTE/master..master - - a0 - a1 - a2 - a3 - a4 - c0 - c1 - ... - c7 -``` - -If ``REMOTE/master`` receives commits **a5**, **a6** and **a7**. Pull with a -rebase as follows: - -```sh -$ git pull --rebase REMOTE master -``` - -This pulls **a5-a7** and re-apply **c0-c7** on top of them: - -```sh -$ git log --oneline REMOTE/master..master -a0 -... -a7 -c0 -c1 -... -c7 -``` - -## Getting Better Logs from Git - -Use these commands to change the configuration of Git in order to produce better -logs: - -```sh -$ git config log.abbrevCommit true -``` - -The command above sets the log to abbreviate the commits' hash. - -```sh -$ git config log.abbrev 5 -``` - -The command above sets the abbreviation length to the last 5 characters of the -hash. - -```sh -$ git config format.pretty oneline -``` - -The command above avoids the insertion of an unnecessary line before the Author -line. diff --git a/docs/6_How_To_Contribute/7_General_Guidelines.md b/docs/6_How_To_Contribute/7_General_Guidelines.md deleted file mode 100644 index 66092de..0000000 --- a/docs/6_How_To_Contribute/7_General_Guidelines.md +++ /dev/null @@ -1,163 +0,0 @@ ---- -title: General Guidelines ---- - -## Getting help - -If you are looking for something to work on, or need some expert assistance in -debugging a problem or working out a fix to an issue, our community is always -eager to help. We hang out on various [developer -meetings](https://www.automotivelinux.org/developer-meetings/), IRC (#automotive -on irc.libera.chat) and the [mailing -lists](https://lists.automotivelinux.org/g/agl-dev-community). We will be glad -to help. The only silly question is the one you don't ask. Questions are in fact -a great way to help improve the project as they highlight where our -documentation could be clearer. - -## Reporting bugs - -If you are a user and you have found a bug, please submit an issue using -[JIRA](https://jira.automotivelinux.org/). Before you create a new JIRA issue, -please try to search the existing items to be sure no one else has previously -reported it. If it has been previously reported, then you might add a comment -that you also are interested in seeing the defect fixed. - -If it has not been previously reported, create a new JIRA. Please try to provide -sufficient information for someone else to reproduce the issue. One of the -project's maintainers should respond to your issue within 24 hours. If not, -please bump the issue with a comment and request that it be reviewed. - -## Submitting your fix - -If you just submitted a JIRA for a bug you've discovered, and would like to -provide a fix, we would welcome that gladly! Please assign the JIRA issue to -yourself, then you can submit a change request (CR). - -**NOTE:** If you need help with submitting your first CR, we have created a -brief [tutorial](./4_Submitting_Changes.md) for you. - -## Fixing issues and working stories - -Review the [open issue list](https://jira.automotivelinux.org/issues/?filter=-5) -and find something that interests you. It is wise to start with something -relatively straight forward and achievable, and that no one is already assigned. -If no one is assigned, then assign the issue to yourself. Please be considerate -and rescind the assignment if you cannot finish in a reasonable time, or add a -comment saying that you are still actively working the issue if you need a -little more time. - -## Reviewing submitted Change Requests (CRs) - -Another way to contribute and learn about Automotive Grade Linux is to help the -maintainers with the review of the CRs that are open. Indeed maintainers have -the difficult role of having to review all the CRs that are being submitted and -evaluate whether they should be merged or not. You can review the code and/or -documentation changes, test the changes, and tell the submitters and maintainers -what you think. Once your review and/or test is complete just reply to the CR -with your findings, by adding comments and/or voting. A comment saying something -like "I tried it on system X and it works" or possibly "I got an error on system -X: xxx " will help the maintainers in their evaluation. As a result, maintainers -will be able to process CRs faster and everybody will gain from it. - -Just browse through the [open CRs on -Gerrit](https://gerrit.automotivelinux.org/gerrit/q/status:open) to get started. - -## Making Feature/Enhancement Proposals - -Review [JIRA](https://jira.automotivelinux.org/) to be sure that there isn't -already an open (or recently closed) proposal for the same function. If there -isn't, to make a proposal we recommend that you open a JIRA Epic, Story or -Improvement, whichever seems to best fit the circumstance and link or inline a -"one pager" of the proposal that states what the feature would do and, if -possible, how it might be implemented. It would help also to make a case for why -the feature should be added, such as identifying specific use case(s) for which -the feature is needed and a case for what the benefit would be should the -feature be implemented. Once the JIRA issue is created, and the "one pager" -either attached, inlined in the description field, or a link to a publicly -accessible document is added to the description, send an introductory email to -the [agl-dev community](mailto:agl-dev-community@lists.automotivelinux.org) -mailing list linking the JIRA issue, and soliciting feedback. - -Discussion of the proposed feature should be conducted in the JIRA issue itself, -so that we have a consistent pattern within our community as to where to find -design discussion. - -Getting the support of three or more of the AGL maintainers for the new feature -will greatly enhance the probability that the feature's related CRs will be -merged. - -## What makes a good change request? - -- One change at a time. Not five, not three, not ten. One and only one. Why? - Because it limits the blast area of the change. If we have a regression, it - is much easier to identify the culprit commit than if we have some composite - change that impacts more of the code. - -- Include a link to the JIRA story for the change. Why? Because a) we want to - track our velocity to better judge what we think we can deliver and when and - b) because we can justify the change more effectively. In many cases, there - should be some discussion around a proposed change and we want to link back - to that from the change itself. - -- Include unit and integration tests (or changes to existing tests) with every - change. This does not mean just happy path testing, either. It also means - negative testing of any defensive code that it correctly catches input - errors. When you write code, you are responsible to test it and provide the - tests that demonstrate that your change does what it claims. Why? Because - without this we have no clue whether our current code base actually works. - -- Minimize the lines of code per CR. Why? If you send a 1,000 or 2,000 LOC - change, how long do you think it takes to review all of that code? Keep your - changes to < 200-300 LOC, if possible. If you have a larger change, decompose - it into multiple independent changess. If you are adding a bunch of new - functions to fulfill the requirements of a new capability, add them - separately with their tests, and then write the code that uses them to - deliver the capability. Of course, there are always exceptions. If you add a - small change and then add 300 LOC of tests, you will be forgiven;-) If you - need to make a change that has broad impact or a bunch of generated code - (protobufs, etc.). Again, there can be exceptions. - - **NOTE:** Large change requests, e.g. those with more than 300 LOC are - more likely than not going to receive a -2, and you'll be asked to - refactor the change to conform with this guidance. - -- Do not stack change requests (e.g. submit a CR from the same local branch as - your previous CR) unless they are related. This will minimize merge conflicts - and allow changes to be merged more quickly. If you stack requests your - subsequent requests may be held up because of review comments in the - preceding requests. - -- Write a meaningful commit message. Include a meaningful 50 (or less) - character title, followed by a blank line, followed by a more comprehensive - description of the change. Each change MUST include the JIRA identifier - corresponding to the change (e.g. [SPEC-1234]). This can be in the title but - should also be in the body of the commit message. See the [complete - requirements](./4_Submitting_Changes.md) for an acceptable change request. - - **NOTE:** That Gerrit will automatically create a hyperlink to the JIRA item. - - ```sh - Bug-AGL: [SPEC-] .... - - Fix [SPEC-] .... - ``` - -Finally, be responsive. Don't let a change request fester with review comments -such that it gets to a point that it requires a rebase. It only further delays -getting it merged and adds more work for you - to remediate the merge conflicts. - -## Legal stuff - -We have tried to make it as easy as possible to make contributions. This applies -to how we handle the legal aspects of contribution. - -We simply ask that when submitting a patch for review, the developer must -include a sign-off statement in the commit message. This is done to ensure that -the author of the change adhere to follow [**DCO**](https://developercertificate.org/). - -```sh -Signed-off-by: John Doe -``` - -You can include this automatically when you commit a change to your local git -repository using ``git commit -s``. diff --git a/docs/6_How_To_Contribute/8_Adding_Documentation.md b/docs/6_How_To_Contribute/8_Adding_Documentation.md deleted file mode 100644 index 7797ab5..0000000 --- a/docs/6_How_To_Contribute/8_Adding_Documentation.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -title: Adding Documentation ---- - -The [documentation gerrit -repository](https://gerrit.automotivelinux.org/gerrit/admin/repos/AGL/documentation) -contains AGL documentation website template and content, rendering is visible at -[https://automotivegradelinux.readthedocs.io/en/latest/](https://automotivegradelinux.readthedocs.io/en/latest/). -The documentation site is hosted on -[readthedocs](https://readthedocs.org/projects/automotivegradelinux/) and -corresponding builds are mentioned -[here](https://readthedocs.org/projects/automotivegradelinux/builds/). - -## Download Repository - - -Clone with commit-msg hook : - -```sh -$ git clone "ssh://@gerrit.automotivelinux.org:29418/AGL/documentation" && scp -p -P 29418 @gerrit.automotivelinux.org:hooks/commit-msg "documentation/.git/hooks/" -``` - -## Building a local site - -1. Change into the directory - - ```sh - $ cd documentation - ``` - -2. Install MkDocs and rtd-dropdown theme - - ```sh - $ sudo pip install -r requirements.txt - ``` - -3. Serve locally (defaultly rendered at [127.0.0.1:8000/](127.0.0.1:8000/)): - - ```sh - $ sudo mkdocs serve - ``` - -Process to **add new or edit existing** markdown files to AGL documentation: - -## Directory Structure - -Find existing or add new markdowns in the following directory structure. - -```sh -documentation -├── docs -│   ├── 0_Getting_Started -│   │   ├── 1_Quickstart -│   │   └── 2_Building_AGL_Image -| ├── ..... -| | -| ├──_ -| | ├──_ -| | | ├──_.md -| | | ├── ..... -``` - -## Markdown Formatting - - 1. Add following at the start of each markdown : - - ```sh - --- - title: - --- - ``` - - 2. Internal Linking : - - ```sh - [](../_/_/_.md) - ``` - -## Test Hyperlinks - -[LinkChecker](https://wummel.github.io/linkchecker/) is a tool that allows to -check all the hyperlinks in the site. - -For testing hyperlinks as soon as the local site is running, do: - -```sh -$ linkchecker http://localhost:8000 -``` - -The ```linkchecker``` output will display the broken link and there location in -the site. - - -## Submitting changes - -1. Install Git Review - - ```sh - #recent version of git-review  (>=1.28.0 is required) - $ sudo pip3 install git-review  - ``` - -2. Write commit message (**Note:** Please follow [submitting changes](./4_Submitting_Changes.md) guideline to write your commit message.) - - ```sh - # track all the new changes - $ git add . - - # Write the commit message - $ git commit --signoff - ``` - -3. Push changes for review to Gerrit - - ```sh - # first time only - $ git review -s - - # then to push use - $ git review - ``` diff --git a/docs/6_How_To_Contribute/9_Contribution_Checklist.md b/docs/6_How_To_Contribute/9_Contribution_Checklist.md deleted file mode 100644 index 7d86ada..0000000 --- a/docs/6_How_To_Contribute/9_Contribution_Checklist.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Contribution Checklist ---- - -**Open Source Code Contribution Checklist** - -## General -- [ ] Does the component have a name ? (Pick one fitting the purpose and the project.) -- [ ] Is a separate git repo required for the component ? -- [ ] Does the component have a README.md containing all basic information about it ? - - [ ] Description. - - [ ] Dependencies. - - [ ] Build instructions. - - [ ] Installation instructions. - - [ ] Usage instructions. - - [ ] Example invocations. -- [ ] Does the component have a CONTRIBUTIONS.md file? (Containing all necessary information on how to contribute, e.g. pointing to project website? ) - -## License - - [ ] Is the license an OSI approved open source software license? - - [ ] Are all files under an OSI approved open source license? - - [ ] Does the component have a LICENSE (or COPYING) file detailing the license of the code? - - [ ] Do the source code files have the license mentioned in the header? - - [ ] Do the source code files have an SPDX tag? (Note: An SPDX tag can be used in a file header instead of the license note) - - [ ] Are there files with other licenses in their header? - - [ ] If so, LICENSE should be the for the majority of the files and LICENSE.xyz for the exceptions. - -## docs/ - - [ ] Are there docs/ folder for the component ? - - [ ] e.g. Are all APIs described inclusive description, usage and example invocations ? - - [ ] e.g. Are all cmdline tools or options described in the documentation ? - - [ ] e.g. Is the program flow described ? - - [ ] Contain Changelog.md ? (Keep track of major changes in the changelog.) - -## tests/ - - [ ] Must have tests available. - - [ ] Must have simple invocation scripts available. - - [ ] Must have instructions for CI available. - - [ ] Must contribute CI test definitions. - -## Git repository - - [ ] Must have: a .gitreview file. - - [ ] Option: Can have a .gitignore file. - - [ ] Option: Can have a .editorconfig file. - - [ ] All code needs to build against master. - - [ ] Is a backport to a release branch required ? - - [ ] Code contributions submitted need to have a Sign-off-by! (Follow [**DCO**](https://developercertificate.org/).) - -## Yocto/OE - - [ ] Recipes need to follow the guidelines of : [**new-recipe-writing-a-new-recipe**](https://www.yoctoproject.org/docs/latest/mega-manual/mega-manual.html#new-recipe-writing-a-new-recipe). - - [ ] Recipes follow the [**bitbake style guide**](https://www.openembedded.org/wiki/Styleguide). - - [ ] Your 'meta-*' layer needs to pass the yocto-check-layer tool. - -## Gerrit Reviews -**All gerrit reviews need to be addressed. All issues are to be discussed with the experts.** - - - [ ] Issues are to be discussed in the EG first. - - [ ] Consent needs to be reached. - - [ ] Gerrit commits need two upvotes (not from authors!) to be merged. - - [ ] Uploads should be 'ready for review' or marked 'WIP'. \ No newline at end of file diff --git a/docs/6_How_To_Contribute/A_How_to_setup_your_own_AGL_LAVA_Lab.md b/docs/6_How_To_Contribute/A_How_to_setup_your_own_AGL_LAVA_Lab.md deleted file mode 100644 index f445b8c..0000000 --- a/docs/6_How_To_Contribute/A_How_to_setup_your_own_AGL_LAVA_Lab.md +++ /dev/null @@ -1,211 +0,0 @@ - -## Prerequisites ## - -As well as the packages docker, docker-compose and pyyaml mentioned in the top - -level README, you will need the following: - - - -1) The following ports are forwarded to docker and therefore need to be kept free - -on the host machine: - -- 69/UDP: proxyfied to the slave for TFTP - -- 80: proxyfied to the slave for TODO (transfer overlay) - -- 5500: proxyfied to the slave for Notification - -- 55950-56000: proxyfied to the slave for NBD - -2) You will need a remote power switch to remotely power the DUTs on and off. - -3) You need to have an account with lava.automotivelinux.org. Please contact the - -agl-dev-community mailing list if you would like an account, and include that you would - -like to create your own lab in the email so that the relevant user permissions - -can be set. - - - -## Steps to create your own LAVA lab ## - - - -1) Clone AGL lava-docker image: - -``` - -git clone https://git.automotivelinux.org/AGL/lava-docker.git - -cd lava-docker - -``` - - - -2) On the LAVA master web GUI, create a new API token: - -https://lava.automotivelinux.org/api/tokens/ - - - -3) Connect all the DUTs' serial to usb and ethernet connections to the host. - - -4) Edit the boards.yaml file: - -- Copy the API token you created in step 2 in the place of . - -- Add details of each board connected to the lab. See the top level README for - -instructions. You will need the following: - -- any custom options you require in the kernel args - -- uart idvendor, idproduct, devpath - -- power on, off and reset commads for the power switch - - - -To get the uart idvendor and idproduct, unplug and re-plugin the USB cable of the - -device in question and then find the details in the latest output of: - -``` - -sudo dmesg | grep idvendor - -``` - - - -To get the uart devpath, run the command: - -``` - -udevadm info -a -n /dev/ttyUSB1 |grep devpath | head -n1 - -``` - - - -NOTE: Make sure you have at least one "board" included. (It is easiest to keep - -qemu). - - - -5) Run the automated setup script: - -``` - -./start.sh slave - -``` - - - -7) Check the web GUI to see if the lab has successfully connected to the LAVA - -master: https://lava.automotivelinux.org/scheduler/allworkers. If it isn't, run the - -following command for debugging: - -``` - -docker-exec -it cat /var/log/lava-dispatcher/lava-slave.log - -``` - -To identify the container name run the following to list the running containers: - -``` - -docker ps - -``` - - - -LAVA logs can be found in `/var/log/lava-dispatcher/`. - - - -8) Helper scripts - -There are a few helper scripts to automate starting/stopping the lab. - -``` - -./start.sh slave - -./restart.sh slave - -./stop.sh slave - -``` - - - -## Adding new device-type templates ## - - - -Not all device types are supported by default. Templates for new devices will - -need to be added to the LAVA master. Please submit new templates to the agl-dev-community - -mailing list. - - - -Before you submit any new device-type templates, please verify that they work. - -You can verify that they work in LAVA by carrying out the following instructions: - -1) Install lavacli on Debian Stretch or Ubuntu 18.04 and later (if you don't - -have a compatible OS, please see https://lava.automotivelinux.org/api/help/ for an - -alternative way to use the API) - -2) Create your lavacli config file - -``` - -touch ~/.config/lavacli.yaml - -``` - -3) Configure this file to look like the following (note: use the first token - -created in https://lava.automotivelinux.org/api/tokens/) - -``` - -default: - -uri: https://lava.automotivelinux.org/RPC2 - -username: - -token: - -``` - -4) Add your device template to the master - -``` - -lavacli device-types template set .yaml - -``` - -NOTE: make sure your device-type templates always follow the following naming scheme: - -```.yaml``` diff --git a/docs/6_How_To_Contribute/images/jira-1.png b/docs/6_How_To_Contribute/images/jira-1.png deleted file mode 100644 index 4a39bfb..0000000 Binary files a/docs/6_How_To_Contribute/images/jira-1.png and /dev/null differ diff --git a/docs/6_How_To_Contribute/images/jira-2.png b/docs/6_How_To_Contribute/images/jira-2.png deleted file mode 100644 index c1cdb21..0000000 Binary files a/docs/6_How_To_Contribute/images/jira-2.png and /dev/null differ diff --git a/docs/6_How_To_Contribute/images/jira-3.png b/docs/6_How_To_Contribute/images/jira-3.png deleted file mode 100644 index b1bec2e..0000000 Binary files a/docs/6_How_To_Contribute/images/jira-3.png and /dev/null differ diff --git a/docs/6_How_To_Contribute/images/review.png b/docs/6_How_To_Contribute/images/review.png deleted file mode 100644 index 805166a..0000000 Binary files a/docs/6_How_To_Contribute/images/review.png and /dev/null differ diff --git a/docs/7_How_To_Contribute/1_Getting_Linux_Foundation_account.md b/docs/7_How_To_Contribute/1_Getting_Linux_Foundation_account.md new file mode 100644 index 0000000..f2b2cb7 --- /dev/null +++ b/docs/7_How_To_Contribute/1_Getting_Linux_Foundation_account.md @@ -0,0 +1,98 @@ +--- +title: Getting Linux Foundation account +--- + +In order to participate in the development of the Automotive Grade Linux +project, you will need a Linux Foundation account. You will need to use +your LF ID to access to all the AGL community development tools, +including [Gerrit](http://gerrit.automotivelinux.org/), +[Jira](https://jira.automotivelinux.org/) and the +[Wiki](https://wiki.automotivelinux.org/) (for editing, only). + +**NOTE:** Further information about Contributing to the AGL Distro +available at [AGL wiki](https://wiki.automotivelinux.org/agl-distro/contributing). + +## Creating Linux Foundation ID + + 1. Go to the [Linux Foundation ID website](https://identity.linuxfoundation.org/). + + 2. Select the option `I need to create a Linux Foundation ID`, and fill + out the form that appears. (It is advised to authenticate through email + instead of logging through Facebook/Google/Github.) + + 3. Wait a few minutes, then look for an email message with the subject + line: `Validate your Linux Foundation ID email`. + + 4. Open the received URL to validate your email address. + + 5. Verify that your browser displays the message ``You have + successfully validated your e-mail address``. + + 6. Access [Gerrit](http://gerrit.automotivelinux.org/) by selecting + ``Sign In``, and use your new Linux Foundation account ID to sign in. + +## Configuring Gerrit to Use SSH + +Gerrit uses SSH to interact with your Git client. If you already have an SSH +key pair, you can skip the part of this section that explains how to generate one. + +What follows explains how to generate an SSH key pair in a Linux environment --- +follow the equivalent steps on your OS. + +First, create an SSH key pair with the command: +**Note:** This guide recommends using ed25519 keys because it has been found that this type works well across all operating systems. + + ```sh + $ ssh-keygen -t ed25519 -C "your_name@example.com" + ``` + +**Note:** When you’re prompted to “Enter a file in which to save the key” press Enter. This accepts the default location. Next, it will ask you for a password to protect the private key as +it generates a unique key. Please keep this password private, and DO NOT +enter a blank password. + +The generated SSH key pair can be found in the files ``~/.ssh/id_ed25519`` and +``~/.ssh/id_ed25519.pub``. + +Next, add the private key in the ``id_ed25519`` file to your key ring, e.g.: + + ```sh + $ ssh-add ~/.ssh/id_ed25519 + ``` + +Finally, add the public key of the generated key pair to the Gerrit +server, with the following steps: + +1. Go to [Gerrit](http://gerrit.automotivelinux.org/). + +2. Click on your account name in the upper right corner. + +3. From the pop-up menu, select ``Settings``. + +4. On the left side menu, click on ``SSH Public Keys``. + +5. Paste the contents of your public key ``~/.ssh/id_ed25519.pub`` and click + ``Add key``. + +**Note:** The ``id_ed25519.pub`` file can be opened with any text editor or you can run the command ``cat ~/.ssh/id_ed25519.pub`` in your terminal and copy output. Ensure that all the contents of the file are selected, copied and pasted into the ``Add SSH key`` window in Gerrit. + +**Note:** The SSH key generation instructions operate on the assumption +that you are using the default naming. It is possible to generate +multiple SSH keys and to name the resulting files differently. See the +[ssh-keygen](https://en.wikipedia.org/wiki/Ssh-keygen) documentation for +details on how to do that. Once you have generated non-default keys, you +need to configure SSH to use the correct key for Gerrit. In that case, +you need to create a ``~/.ssh/config`` file with command ``touch ~/.ssh/config`` and add details in config file. + +``` +host gerrit.automotivelinux.org + HostName gerrit.automotivelinux.org + IdentityFile ~/.ssh/id_ed25519 + User + Port 29418 +``` + +`` is your Linux Foundation ID(username) and the value of IdentityFile is the +name of the public key file you generated. + +**Warning:** Potential Security Risk! Do not copy your private key +``~/.ssh/id_ed25519``. Use only the public ``~/.ssh/id_ed25519.pub``. diff --git a/docs/7_How_To_Contribute/2_Using_Jira_for_current_work_items.md b/docs/7_How_To_Contribute/2_Using_Jira_for_current_work_items.md new file mode 100644 index 0000000..49b443d --- /dev/null +++ b/docs/7_How_To_Contribute/2_Using_Jira_for_current_work_items.md @@ -0,0 +1,30 @@ +--- +title: Using Jira for current work items +--- + +This document has been created to give further insight into the work in progress +towards the Automotive Grade Linux architecture based on the community roadmap. +The requirements for the roadmap are being tracked in +[Jira](https://jira.automotivelinux.org/). + +On this page you will see all the public (and restricted) boards that have been +created. For example the **Board Name** *CI and Automated Test Expert Group*: + +![Jira boards](images/jira-2.png) + +When you click on *CI and Automated Test Expert Group* under **Board name** you +will be directed to a page that contains the following columns: + +![Jira boards](images/jira-3.png) + +The meanings to these columns are as follows: + +- **NOT STARTED** – list of items slated for the current sprint (sprints are + defined in 2 week iterations), but are not currently in progress +- **IN PROGRESS** – items currently being worked by someone in the community. +- **DONE** – items merged and complete in the sprint. + +If there is an item you are interested in working on, want more information or +have questions, or if there is an item that you feel needs to be in higher +priority, please add comments directly to the Jira item. All feedback and help +is very much appreciated. \ No newline at end of file diff --git a/docs/7_How_To_Contribute/3_Working_with_Gerrit.md b/docs/7_How_To_Contribute/3_Working_with_Gerrit.md new file mode 100644 index 0000000..ccd9133 --- /dev/null +++ b/docs/7_How_To_Contribute/3_Working_with_Gerrit.md @@ -0,0 +1,153 @@ +--- +title: Working with Gerrit +--- + +Follow these instructions to collaborate on AGL through the Gerrit review +system. + +Please be sure that you are subscribed to the [mailing +list](https://lists.automotivelinux.org/g/agl-dev-community) and of course, you +can reach out on IRC at the #automotive channel on irc.libera.chat + +Gerrit assigns the following roles to users: + +- **Submitters**: May submit changes for consideration, review other code + changes, and make recommendations for acceptance or rejection by voting +1 or + -1, respectively. +- **Maintainers**: May approve or reject changes based upon feedback from + reviewers voting +2 or -2, respectively. + +## Getting deeper into Gerrit + +A comprehensive walk-through of Gerrit is beyond the scope of this document. +There are plenty of resources available on the Internet. A good summary can be +found [here](https://www.mediawiki.org/wiki/Gerrit/Tutorial) and [Basic Gerrit +Walkthrough for GitHub +Users](https://gerrit-review.googlesource.com/Documentation/intro-gerrit-walkthrough-github.html). + +## Working with a local clone of the repository + +To work on something, whether a new feature or a bugfix: + +1. Open the Gerrit [repo + page](https://gerrit.automotivelinux.org/gerrit/admin/repos/). + +2. Select the repository you wish to work on. + +3. Open a terminal window and clone the project locally using the ``Clone with + git hook`` URL. Be sure that ``ssh`` is also selected, as this will make + authentication much simpler. For example, for `documentation` repository: + + ```sh + $ git clone "ssh://@gerrit.automotivelinux.org:29418/AGL/documentation" && scp -p -P + 29418 @gerrit.automotivelinux.org:hooks/commit-msg "documentation/.git/hooks/" + ``` + +4. Setup `user` and `email` for git config + + ```sh + $ cd documentation + $ git.config --global user.name "Your Full Name" + $ git config --global user.email "your@email.com" + ``` + + **NOTE:** To only configure for a particular repository : + + ```sh + $ cd documentation + $ git.config user.name "Your Full Name" + $ git config user.email "your@email.com" + ``` + +5. Create a descriptively-named branch off of your cloned repository + + ```sh + $ git checkout -b issue-nname + ``` + +## Using git review + +There's a **very** useful tool for working with Gerrit called +[git-review](https://www.mediawiki.org/wiki/Gerrit/git-review). This +command-line tool can automate most of the ensuing sections for you. Ofcourse, +reading the information below is also highly recommended so that you understand +what's going on behind the scenes. + +```sh +# for first time use only +$ git review -s +``` +If `.gitreview` is missing, add the following section to ``.git/config``, and +replace ```` with your LFID id. + +```sh +[remote "gerrit"] + url = ssh://@gerrit.automotivelinux.org:29418/AGL/documentation.git + fetch = +refs/heads/*:refs/remotes/gerrit/* +``` + +Then submit your change with ``git review``. + +```sh +$ cd documentation +$ git review +``` + +When you update your patch, you can commit with ``git commit --amend``, and then +repeat the ``git review`` command. + +## Typical Review Workflow + + - New Fresh Change + + ```sh + $ cd documentation # Working Repository + $ git remote -v update # Updating wrt remote + $ git checkout -b mytopicbranch origin/master # Creating new branch + ### CODE the CHANGES + $ git add  # Track the changed files + $ git commit -s # Signed Commit Message + $ git review # Submit Changes to review + ``` + + - Updating existing Gerrit Review + + ```sh + $ cd documentation # Working Repository + $ git review -d 25678 # Download review, 25678 is change number + ### CODE the CHANGES + $ git add  # Track the changed files + $ git commit -s # Signed Commit Message + $ git review # Submit Changes to review + $ git checkout master # Return to master branch + ``` + +## Reviewing Using Gerrit + +- **Add**: This button allows the change submitter to manually add names of + people who should review a change; start typing a name and the system will + auto-complete based on the list of people registered and with access to the + system. They will be notified by email that you are requesting their input. + +- **Abandon**: This button is available to the submitter only; it allows a + committer to abandon a change and remove it from the merge queue. + +- **Change-ID**: This ID is generated by Gerrit (or system). It becomes useful + when the review process determines that your commit(s) have to be amended. + You may submit a new version; and if the same Change-ID header (and value) + are present, Gerrit will remember it and present it as another version of the + same change. + +- **Status**: Currently, the example change is in review status, as indicated + by “Needs Verified” in the upper-left corner. The list of Reviewers will all + emit their opinion, voting +1 if they agree to the merge, -1 if they + disagree. Gerrit users with a Maintainer role can agree to the merge or + refuse it by voting +2 or -2 respectively. + +Notifications are sent to the email address in your commit message's +Signed-off-by line. Visit your [Gerrit +dashboard](https://gerrit.automotivelinux.org/gerrit/dashboard/self), to check +the progress of your requests. + +The history tab in Gerrit will show you the in-line comments and the author of +the review. diff --git a/docs/7_How_To_Contribute/4_Submitting_Changes.md b/docs/7_How_To_Contribute/4_Submitting_Changes.md new file mode 100644 index 0000000..d226450 --- /dev/null +++ b/docs/7_How_To_Contribute/4_Submitting_Changes.md @@ -0,0 +1,68 @@ +--- +title: Submitting Changes +--- + +Carefully review the following before submitting a change. These guidelines +apply to developers that are new to open source, as well as to experienced open +source developers. + +## Change Requirements + + +This section contains guidelines for submitting code changes for review. For +more information on how to submit a change using Gerrit, please see [Working +with Gerrit](./3_Working_with_Gerrit.md). + +Changes are submitted as Git commits. Each commit must contain: + +- a short and descriptive subject line that is 72 characters or fewer, followed + by a blank line. +- a change description with your logic or reasoning for the changes, followed + by a blank line +- a Signed-off-by line, followed by a colon (Signed-off-by:) +- a Change-Id identifier line, followed by a colon (Change-Id:). Gerrit won't + accept patches without this identifier. + +A commit with the above details is considered well-formed. [This +page](https://chris.beams.io/posts/git-commit/) is a very useful for the same. + +All changes and topics sent to Gerrit must be well-formed. Informationally, +``commit messages`` must include: + +- **what** the change does, +- **why** you chose that approach, and +- **how** you know it works -- for example, which tests you ran. + +For example: One commit fixes whitespace issues, another renames a function and +a third one changes the code's functionality. An example commit file is +illustrated below in detail: + +```sh + +A short description of your change with no period at the end + +You can add more details here in several paragraphs, but please keep each line +width less than 80 characters. A bug fix should include the issue number. + +Bug-AGL: [SPEC-] +Change-Id: IF7b6ac513b2eca5f2bab9728ebd8b7e504d3cebe1 +Signed-off-by: Your Name +``` + +Include the issue ID in the one line description of your commit message for +readability. Gerrit will link issue IDs automatically to the corresponding entry +in Jira. + +Each commit must also contain the following line at the bottom of the commit +message: + +```sh +Signed-off-by: Your Name +``` + +The name in the Signed-off-by line and your email must match the change +authorship information. Make sure your :file:``.git/config`` is set up +correctly. Always submit the full set of changes via Gerrit. + +When a change is included in the set to enable other changes, but it will not be +part of the final set, please let the reviewers know this. diff --git a/docs/7_How_To_Contribute/5_Reviewing_Changes.md b/docs/7_How_To_Contribute/5_Reviewing_Changes.md new file mode 100644 index 0000000..e9d6758 --- /dev/null +++ b/docs/7_How_To_Contribute/5_Reviewing_Changes.md @@ -0,0 +1,55 @@ +--- +title: Reviewing Changes +--- + +1. Click on a link for incoming or outgoing review. + +2. The details of the change and its current status are loaded: + + ![review](images/review.png) + + - **Status:** Displays the current status of the change. + + - **Reply:** Click on this button after reviewing to add a final review + message and a score, -1, 0 or +1. + + - **Patch Sets:** If multiple revisions of a patch exist, this button + enables navigation among revisions to see the changes. By default, the + most recent revision is presented. + + - **Download:** This button brings up another window with multiple + options to download or checkout the current changeset. The button on + the right copies the line to your clipboard. You can easily paste it + into your git interface to work with the patch as you prefer. + + Underneath the commit information, the files that have been changed by + this patch are displayed. + +3. Click on a filename to review it. Select the code base to differentiate + against. The default is ``Base`` and it will generally be what is needed. + +4. The review page presents the changes made to the file. At the top of the + review, the presentation shows some general navigation options. Navigate + through the patch set using the arrows on the top right corner. It is + possible to go to the previous or next file in the set or to return to the + main change screen. Click on the yellow sticky pad to add comments to the + whole file. + + The focus of the page is on the comparison window. The changes made are + presented in green on the right versus the base version on the left. + Double click to highlight the text within the actual change to provide + feedback on a specific section of the code. Press *c* once the code is + highlighted to add comments to that section. + +5. After adding the comment, it is saved as a *Draft*. + +6. Once you have reviewed all files and provided feedback, click the *green up + arrow* at the top right to return to the main change page. Click the + ``Reply`` button, write some final comments, and submit your score for the + patch set. Click ``Post`` to submit the review of each reviewed file, as well + as your final comment and score. Gerrit sends an email to the + change-submitter and all listed reviewers. Finally, it logs the review for + future reference. All individual comments are saved as *Draft* until the + ``Post`` button is clicked. + + diff --git a/docs/7_How_To_Contribute/6_Gerrit_Recommended_Practices.md b/docs/7_How_To_Contribute/6_Gerrit_Recommended_Practices.md new file mode 100644 index 0000000..671c685 --- /dev/null +++ b/docs/7_How_To_Contribute/6_Gerrit_Recommended_Practices.md @@ -0,0 +1,263 @@ +--- +title: Gerrit Recommended Practices +--- + +This document presents some best practices to help you use Gerrit more +effectively. The intent is to show how content can be submitted easily. Use the +recommended practices to reduce your troubleshooting time and improve +participation in the community. + +## Commit Messages + +Gerrit follows the Git commit message format. Ensure the headers are at the +bottom and don't contain blank lines between one another. The following example +shows the format and content expected in a commit message: + +Brief (no more than 50 chars) one line description. + +Elaborate summary of the changes made referencing why (motivation), what was +changed and how it was tested. Note also any changes to documentation made to +remain consistent with the code changes, wrapping text at 72 chars/line. + +```sh +Bug-AGL: SPEC- + +Change-Id: LONGHEXHASH +Signed-off-by: Your Name your.email\@example.org +``` + +The Gerrit server provides a precommit hook to autogenerate the Change-Id which +is one time use. + +**Recommended reading:** [How to Write a Git Commit +Message](http://chris.beams.io/posts/git-commit/). + +## Avoid Pushing Untested Work to a Gerrit Server + +To avoid pushing untested work to Gerrit. + +Check your work at least three times before pushing your change to Gerrit. Be +mindful of what information you are publishing. + +## Keeping Track of Changes + +- Set Gerrit to send you emails: + +- Gerrit will add you to the email distribution list for a change if a + developer adds you as a reviewer, or if you comment on a specific Patch Set. + +- Opening a change in Gerrit's review interface is a quick way to follow that + change. + +- Watch projects in the Gerrit projects section at ``Gerrit``, select at least + *New Changes, New Patch Sets, All Comments* and *Submitted Changes*. + +Always track the projects you are working on; also see the feedback/comments +[mailing list](https://lists.automotivelinux.org/g/agl-dev-community) to learn +and help others ramp up. + +## Topic branches + +Topic branches are temporary branches that you push to commit a set of +logically-grouped dependent commits: + +To push changes from ``REMOTE/master`` tree to Gerrit for being reviewed as a +topic in **TopicName** use the following command as an example: + +```sh +$ git push REMOTE HEAD:refs/for/master/TopicName +``` + +The topic will show up in the review ``UI`` and in the ``Open Changes List``. +Topic branches will disappear from the master tree when its content is merged. + +## Finding Available Topics + +```sh +$ ssh -p 29418 @gerrit.automotivelinux.org gerrit query \ status:open branch:master| grep topic: | sort -u +``` + +- [gerrit.automotivelinux.org](https://gerrit.automotivelinux.org) is the + current URL where the project is hosted. +- *status* : Indicates the topic's current status: open , merged, abandoned, + draft, merge conflict. +- *project* : Refers to the current name of the project, in this case fabric. +- *branch* : The topic is searched at this branch. +- *topic* : The name of an specific topic, leave it blank to include them all. +- *sort* : Sorts the found topics, in this case by update (-u). + +## Downloading or Checking Out a Change + +In the review UI, on the top right corner, the **Download** link provides a list +of commands and hyperlinks to checkout or download diffs or files. + +We recommend the use of the *git review* plugin. The steps to install git review +are beyond the scope of this document. Refer to the [git review +documentation](https://wiki.openstack.org/wiki/Documentation/HowTo/FirstTimers) +for the installation process. + +To check out a specific change using Git, the following command usually works: + +```sh +$ git review -d CHANGEID +``` + +If you don't have Git-review installed, the following commands will do the same +thing: + +```sh +$ git fetch REMOTE refs/changes/NN/CHANGEIDNN/VERSION \ && git checkout FETCH_HEAD +``` + +For example, for the 4th version of change 2464, NN is the first two digits +(24): + +```sh +$ git fetch REMOTE refs/changes/24/2464/4 \ && git checkout FETCH_HEAD +``` + +## Using Sandbox Branches + +You can create your own branches to develop features. The branches are pushed to +the ``refs/heads/sandbox/USERNAME/BRANCHNAME`` location. + +These commands ensure the branch is created in Gerrit's server. + +```sh +$ git checkout -b sandbox/USERNAME/BRANCHNAME +$ git push --set-upstream REMOTE HEAD:refs/heads/sandbox/USERNAME/BRANCHNAME +``` + +Usually, the process to create content is: + +- develop the code, +- break the information into small commits, +- submit changes, +- apply feedback, +- rebase. + +The next command pushes forcibly without review: + +```sh +$ git push REMOTE sandbox/USERNAME/BRANCHNAME +``` + +You can also push forcibly with review: + +```sh +$ git push REMOTE HEAD:ref/for/sandbox/USERNAME/BRANCHNAME +``` + +## Updating the Version of a Change + +During the review process, you might be asked to update your change. It is +possible to submit multiple versions of the same change. Each version of the +change is called a patch set. + +Always maintain the **Change-Id** that was assigned. For example, there is a +list of commits, **c0...c7**, which were submitted as a topic branch: + +```sh + +$ git log REMOTE/master..master + + c0 + ... + c7 + +$ git push REMOTE HEAD:refs/for/master/SOMETOPIC +``` + +After you get reviewers' feedback, there are changes in **c3** and **c4** that +must be fixed. If the fix requires rebasing, rebasing changes the commit Ids, +see the [rebasing](http://git-scm.com/book/en/v2/Git-Branching-Rebasing) section +for more information. However, you must keep the same Change-Id and push the +changes again: + +```sh +$ git push REMOTE HEAD:refs/for/master/SOMETOPIC +``` + +This new push creates a patches revision, your local history is then cleared. +However you can still access the history of your changes in Gerrit on the +``review UI`` section, for each change. + +It is also permitted to add more commits when pushing new versions. + +### Rebasing + +Rebasing is usually the last step before pushing changes to Gerrit; this allows +you to make the necessary *Change-Ids*. The *Change-Ids* must be kept the same. + +- **squash:** mixes two or more commits into a single one. +- **reword:** changes the commit message. +- **edit:** changes the commit content. +- **reorder:** allows you to interchange the order of the commits. +- **rebase:** stacks the commits on top of the master. + +## Rebasing During a Pull + +Before pushing a rebase to your master, ensure that the history has a +consecutive order. + +For example, your ``REMOTE/master`` has the list of commits from **a0** to +**a4**; Then, your changes **c0...c7** are on top of **a4**; thus: + +```sh +$ git log --oneline REMOTE/master..master + + a0 + a1 + a2 + a3 + a4 + c0 + c1 + ... + c7 +``` + +If ``REMOTE/master`` receives commits **a5**, **a6** and **a7**. Pull with a +rebase as follows: + +```sh +$ git pull --rebase REMOTE master +``` + +This pulls **a5-a7** and re-apply **c0-c7** on top of them: + +```sh +$ git log --oneline REMOTE/master..master +a0 +... +a7 +c0 +c1 +... +c7 +``` + +## Getting Better Logs from Git + +Use these commands to change the configuration of Git in order to produce better +logs: + +```sh +$ git config log.abbrevCommit true +``` + +The command above sets the log to abbreviate the commits' hash. + +```sh +$ git config log.abbrev 5 +``` + +The command above sets the abbreviation length to the last 5 characters of the +hash. + +```sh +$ git config format.pretty oneline +``` + +The command above avoids the insertion of an unnecessary line before the Author +line. diff --git a/docs/7_How_To_Contribute/7_General_Guidelines.md b/docs/7_How_To_Contribute/7_General_Guidelines.md new file mode 100644 index 0000000..66092de --- /dev/null +++ b/docs/7_How_To_Contribute/7_General_Guidelines.md @@ -0,0 +1,163 @@ +--- +title: General Guidelines +--- + +## Getting help + +If you are looking for something to work on, or need some expert assistance in +debugging a problem or working out a fix to an issue, our community is always +eager to help. We hang out on various [developer +meetings](https://www.automotivelinux.org/developer-meetings/), IRC (#automotive +on irc.libera.chat) and the [mailing +lists](https://lists.automotivelinux.org/g/agl-dev-community). We will be glad +to help. The only silly question is the one you don't ask. Questions are in fact +a great way to help improve the project as they highlight where our +documentation could be clearer. + +## Reporting bugs + +If you are a user and you have found a bug, please submit an issue using +[JIRA](https://jira.automotivelinux.org/). Before you create a new JIRA issue, +please try to search the existing items to be sure no one else has previously +reported it. If it has been previously reported, then you might add a comment +that you also are interested in seeing the defect fixed. + +If it has not been previously reported, create a new JIRA. Please try to provide +sufficient information for someone else to reproduce the issue. One of the +project's maintainers should respond to your issue within 24 hours. If not, +please bump the issue with a comment and request that it be reviewed. + +## Submitting your fix + +If you just submitted a JIRA for a bug you've discovered, and would like to +provide a fix, we would welcome that gladly! Please assign the JIRA issue to +yourself, then you can submit a change request (CR). + +**NOTE:** If you need help with submitting your first CR, we have created a +brief [tutorial](./4_Submitting_Changes.md) for you. + +## Fixing issues and working stories + +Review the [open issue list](https://jira.automotivelinux.org/issues/?filter=-5) +and find something that interests you. It is wise to start with something +relatively straight forward and achievable, and that no one is already assigned. +If no one is assigned, then assign the issue to yourself. Please be considerate +and rescind the assignment if you cannot finish in a reasonable time, or add a +comment saying that you are still actively working the issue if you need a +little more time. + +## Reviewing submitted Change Requests (CRs) + +Another way to contribute and learn about Automotive Grade Linux is to help the +maintainers with the review of the CRs that are open. Indeed maintainers have +the difficult role of having to review all the CRs that are being submitted and +evaluate whether they should be merged or not. You can review the code and/or +documentation changes, test the changes, and tell the submitters and maintainers +what you think. Once your review and/or test is complete just reply to the CR +with your findings, by adding comments and/or voting. A comment saying something +like "I tried it on system X and it works" or possibly "I got an error on system +X: xxx " will help the maintainers in their evaluation. As a result, maintainers +will be able to process CRs faster and everybody will gain from it. + +Just browse through the [open CRs on +Gerrit](https://gerrit.automotivelinux.org/gerrit/q/status:open) to get started. + +## Making Feature/Enhancement Proposals + +Review [JIRA](https://jira.automotivelinux.org/) to be sure that there isn't +already an open (or recently closed) proposal for the same function. If there +isn't, to make a proposal we recommend that you open a JIRA Epic, Story or +Improvement, whichever seems to best fit the circumstance and link or inline a +"one pager" of the proposal that states what the feature would do and, if +possible, how it might be implemented. It would help also to make a case for why +the feature should be added, such as identifying specific use case(s) for which +the feature is needed and a case for what the benefit would be should the +feature be implemented. Once the JIRA issue is created, and the "one pager" +either attached, inlined in the description field, or a link to a publicly +accessible document is added to the description, send an introductory email to +the [agl-dev community](mailto:agl-dev-community@lists.automotivelinux.org) +mailing list linking the JIRA issue, and soliciting feedback. + +Discussion of the proposed feature should be conducted in the JIRA issue itself, +so that we have a consistent pattern within our community as to where to find +design discussion. + +Getting the support of three or more of the AGL maintainers for the new feature +will greatly enhance the probability that the feature's related CRs will be +merged. + +## What makes a good change request? + +- One change at a time. Not five, not three, not ten. One and only one. Why? + Because it limits the blast area of the change. If we have a regression, it + is much easier to identify the culprit commit than if we have some composite + change that impacts more of the code. + +- Include a link to the JIRA story for the change. Why? Because a) we want to + track our velocity to better judge what we think we can deliver and when and + b) because we can justify the change more effectively. In many cases, there + should be some discussion around a proposed change and we want to link back + to that from the change itself. + +- Include unit and integration tests (or changes to existing tests) with every + change. This does not mean just happy path testing, either. It also means + negative testing of any defensive code that it correctly catches input + errors. When you write code, you are responsible to test it and provide the + tests that demonstrate that your change does what it claims. Why? Because + without this we have no clue whether our current code base actually works. + +- Minimize the lines of code per CR. Why? If you send a 1,000 or 2,000 LOC + change, how long do you think it takes to review all of that code? Keep your + changes to < 200-300 LOC, if possible. If you have a larger change, decompose + it into multiple independent changess. If you are adding a bunch of new + functions to fulfill the requirements of a new capability, add them + separately with their tests, and then write the code that uses them to + deliver the capability. Of course, there are always exceptions. If you add a + small change and then add 300 LOC of tests, you will be forgiven;-) If you + need to make a change that has broad impact or a bunch of generated code + (protobufs, etc.). Again, there can be exceptions. + + **NOTE:** Large change requests, e.g. those with more than 300 LOC are + more likely than not going to receive a -2, and you'll be asked to + refactor the change to conform with this guidance. + +- Do not stack change requests (e.g. submit a CR from the same local branch as + your previous CR) unless they are related. This will minimize merge conflicts + and allow changes to be merged more quickly. If you stack requests your + subsequent requests may be held up because of review comments in the + preceding requests. + +- Write a meaningful commit message. Include a meaningful 50 (or less) + character title, followed by a blank line, followed by a more comprehensive + description of the change. Each change MUST include the JIRA identifier + corresponding to the change (e.g. [SPEC-1234]). This can be in the title but + should also be in the body of the commit message. See the [complete + requirements](./4_Submitting_Changes.md) for an acceptable change request. + + **NOTE:** That Gerrit will automatically create a hyperlink to the JIRA item. + + ```sh + Bug-AGL: [SPEC-] .... + + Fix [SPEC-] .... + ``` + +Finally, be responsive. Don't let a change request fester with review comments +such that it gets to a point that it requires a rebase. It only further delays +getting it merged and adds more work for you - to remediate the merge conflicts. + +## Legal stuff + +We have tried to make it as easy as possible to make contributions. This applies +to how we handle the legal aspects of contribution. + +We simply ask that when submitting a patch for review, the developer must +include a sign-off statement in the commit message. This is done to ensure that +the author of the change adhere to follow [**DCO**](https://developercertificate.org/). + +```sh +Signed-off-by: John Doe +``` + +You can include this automatically when you commit a change to your local git +repository using ``git commit -s``. diff --git a/docs/7_How_To_Contribute/8_Adding_Documentation.md b/docs/7_How_To_Contribute/8_Adding_Documentation.md new file mode 100644 index 0000000..7797ab5 --- /dev/null +++ b/docs/7_How_To_Contribute/8_Adding_Documentation.md @@ -0,0 +1,121 @@ +--- +title: Adding Documentation +--- + +The [documentation gerrit +repository](https://gerrit.automotivelinux.org/gerrit/admin/repos/AGL/documentation) +contains AGL documentation website template and content, rendering is visible at +[https://automotivegradelinux.readthedocs.io/en/latest/](https://automotivegradelinux.readthedocs.io/en/latest/). +The documentation site is hosted on +[readthedocs](https://readthedocs.org/projects/automotivegradelinux/) and +corresponding builds are mentioned +[here](https://readthedocs.org/projects/automotivegradelinux/builds/). + +## Download Repository + + +Clone with commit-msg hook : + +```sh +$ git clone "ssh://@gerrit.automotivelinux.org:29418/AGL/documentation" && scp -p -P 29418 @gerrit.automotivelinux.org:hooks/commit-msg "documentation/.git/hooks/" +``` + +## Building a local site + +1. Change into the directory + + ```sh + $ cd documentation + ``` + +2. Install MkDocs and rtd-dropdown theme + + ```sh + $ sudo pip install -r requirements.txt + ``` + +3. Serve locally (defaultly rendered at [127.0.0.1:8000/](127.0.0.1:8000/)): + + ```sh + $ sudo mkdocs serve + ``` + +Process to **add new or edit existing** markdown files to AGL documentation: + +## Directory Structure + +Find existing or add new markdowns in the following directory structure. + +```sh +documentation +├── docs +│   ├── 0_Getting_Started +│   │   ├── 1_Quickstart +│   │   └── 2_Building_AGL_Image +| ├── ..... +| | +| ├──_ +| | ├──_ +| | | ├──_.md +| | | ├── ..... +``` + +## Markdown Formatting + + 1. Add following at the start of each markdown : + + ```sh + --- + title: + --- + ``` + + 2. Internal Linking : + + ```sh + [](../_/_/_.md) + ``` + +## Test Hyperlinks + +[LinkChecker](https://wummel.github.io/linkchecker/) is a tool that allows to +check all the hyperlinks in the site. + +For testing hyperlinks as soon as the local site is running, do: + +```sh +$ linkchecker http://localhost:8000 +``` + +The ```linkchecker``` output will display the broken link and there location in +the site. + + +## Submitting changes + +1. Install Git Review + + ```sh + #recent version of git-review  (>=1.28.0 is required) + $ sudo pip3 install git-review  + ``` + +2. Write commit message (**Note:** Please follow [submitting changes](./4_Submitting_Changes.md) guideline to write your commit message.) + + ```sh + # track all the new changes + $ git add . + + # Write the commit message + $ git commit --signoff + ``` + +3. Push changes for review to Gerrit + + ```sh + # first time only + $ git review -s + + # then to push use + $ git review + ``` diff --git a/docs/7_How_To_Contribute/9_Contribution_Checklist.md b/docs/7_How_To_Contribute/9_Contribution_Checklist.md new file mode 100644 index 0000000..7d86ada --- /dev/null +++ b/docs/7_How_To_Contribute/9_Contribution_Checklist.md @@ -0,0 +1,60 @@ +--- +title: Contribution Checklist +--- + +**Open Source Code Contribution Checklist** + +## General +- [ ] Does the component have a name ? (Pick one fitting the purpose and the project.) +- [ ] Is a separate git repo required for the component ? +- [ ] Does the component have a README.md containing all basic information about it ? + - [ ] Description. + - [ ] Dependencies. + - [ ] Build instructions. + - [ ] Installation instructions. + - [ ] Usage instructions. + - [ ] Example invocations. +- [ ] Does the component have a CONTRIBUTIONS.md file? (Containing all necessary information on how to contribute, e.g. pointing to project website? ) + +## License + - [ ] Is the license an OSI approved open source software license? + - [ ] Are all files under an OSI approved open source license? + - [ ] Does the component have a LICENSE (or COPYING) file detailing the license of the code? + - [ ] Do the source code files have the license mentioned in the header? + - [ ] Do the source code files have an SPDX tag? (Note: An SPDX tag can be used in a file header instead of the license note) + - [ ] Are there files with other licenses in their header? + - [ ] If so, LICENSE should be the for the majority of the files and LICENSE.xyz for the exceptions. + +## docs/ + - [ ] Are there docs/ folder for the component ? + - [ ] e.g. Are all APIs described inclusive description, usage and example invocations ? + - [ ] e.g. Are all cmdline tools or options described in the documentation ? + - [ ] e.g. Is the program flow described ? + - [ ] Contain Changelog.md ? (Keep track of major changes in the changelog.) + +## tests/ + - [ ] Must have tests available. + - [ ] Must have simple invocation scripts available. + - [ ] Must have instructions for CI available. + - [ ] Must contribute CI test definitions. + +## Git repository + - [ ] Must have: a .gitreview file. + - [ ] Option: Can have a .gitignore file. + - [ ] Option: Can have a .editorconfig file. + - [ ] All code needs to build against master. + - [ ] Is a backport to a release branch required ? + - [ ] Code contributions submitted need to have a Sign-off-by! (Follow [**DCO**](https://developercertificate.org/).) + +## Yocto/OE + - [ ] Recipes need to follow the guidelines of : [**new-recipe-writing-a-new-recipe**](https://www.yoctoproject.org/docs/latest/mega-manual/mega-manual.html#new-recipe-writing-a-new-recipe). + - [ ] Recipes follow the [**bitbake style guide**](https://www.openembedded.org/wiki/Styleguide). + - [ ] Your 'meta-*' layer needs to pass the yocto-check-layer tool. + +## Gerrit Reviews +**All gerrit reviews need to be addressed. All issues are to be discussed with the experts.** + + - [ ] Issues are to be discussed in the EG first. + - [ ] Consent needs to be reached. + - [ ] Gerrit commits need two upvotes (not from authors!) to be merged. + - [ ] Uploads should be 'ready for review' or marked 'WIP'. \ No newline at end of file diff --git a/docs/7_How_To_Contribute/A_How_to_setup_your_own_AGL_LAVA_Lab.md b/docs/7_How_To_Contribute/A_How_to_setup_your_own_AGL_LAVA_Lab.md new file mode 100644 index 0000000..f445b8c --- /dev/null +++ b/docs/7_How_To_Contribute/A_How_to_setup_your_own_AGL_LAVA_Lab.md @@ -0,0 +1,211 @@ + +## Prerequisites ## + +As well as the packages docker, docker-compose and pyyaml mentioned in the top + +level README, you will need the following: + + + +1) The following ports are forwarded to docker and therefore need to be kept free + +on the host machine: + +- 69/UDP: proxyfied to the slave for TFTP + +- 80: proxyfied to the slave for TODO (transfer overlay) + +- 5500: proxyfied to the slave for Notification + +- 55950-56000: proxyfied to the slave for NBD + +2) You will need a remote power switch to remotely power the DUTs on and off. + +3) You need to have an account with lava.automotivelinux.org. Please contact the + +agl-dev-community mailing list if you would like an account, and include that you would + +like to create your own lab in the email so that the relevant user permissions + +can be set. + + + +## Steps to create your own LAVA lab ## + + + +1) Clone AGL lava-docker image: + +``` + +git clone https://git.automotivelinux.org/AGL/lava-docker.git + +cd lava-docker + +``` + + + +2) On the LAVA master web GUI, create a new API token: + +https://lava.automotivelinux.org/api/tokens/ + + + +3) Connect all the DUTs' serial to usb and ethernet connections to the host. + + +4) Edit the boards.yaml file: + +- Copy the API token you created in step 2 in the place of . + +- Add details of each board connected to the lab. See the top level README for + +instructions. You will need the following: + +- any custom options you require in the kernel args + +- uart idvendor, idproduct, devpath + +- power on, off and reset commads for the power switch + + + +To get the uart idvendor and idproduct, unplug and re-plugin the USB cable of the + +device in question and then find the details in the latest output of: + +``` + +sudo dmesg | grep idvendor + +``` + + + +To get the uart devpath, run the command: + +``` + +udevadm info -a -n /dev/ttyUSB1 |grep devpath | head -n1 + +``` + + + +NOTE: Make sure you have at least one "board" included. (It is easiest to keep + +qemu). + + + +5) Run the automated setup script: + +``` + +./start.sh slave + +``` + + + +7) Check the web GUI to see if the lab has successfully connected to the LAVA + +master: https://lava.automotivelinux.org/scheduler/allworkers. If it isn't, run the + +following command for debugging: + +``` + +docker-exec -it cat /var/log/lava-dispatcher/lava-slave.log + +``` + +To identify the container name run the following to list the running containers: + +``` + +docker ps + +``` + + + +LAVA logs can be found in `/var/log/lava-dispatcher/`. + + + +8) Helper scripts + +There are a few helper scripts to automate starting/stopping the lab. + +``` + +./start.sh slave + +./restart.sh slave + +./stop.sh slave + +``` + + + +## Adding new device-type templates ## + + + +Not all device types are supported by default. Templates for new devices will + +need to be added to the LAVA master. Please submit new templates to the agl-dev-community + +mailing list. + + + +Before you submit any new device-type templates, please verify that they work. + +You can verify that they work in LAVA by carrying out the following instructions: + +1) Install lavacli on Debian Stretch or Ubuntu 18.04 and later (if you don't + +have a compatible OS, please see https://lava.automotivelinux.org/api/help/ for an + +alternative way to use the API) + +2) Create your lavacli config file + +``` + +touch ~/.config/lavacli.yaml + +``` + +3) Configure this file to look like the following (note: use the first token + +created in https://lava.automotivelinux.org/api/tokens/) + +``` + +default: + +uri: https://lava.automotivelinux.org/RPC2 + +username: + +token: + +``` + +4) Add your device template to the master + +``` + +lavacli device-types template set .yaml + +``` + +NOTE: make sure your device-type templates always follow the following naming scheme: + +```.yaml``` diff --git a/docs/7_How_To_Contribute/images/jira-1.png b/docs/7_How_To_Contribute/images/jira-1.png new file mode 100644 index 0000000..4a39bfb Binary files /dev/null and b/docs/7_How_To_Contribute/images/jira-1.png differ diff --git a/docs/7_How_To_Contribute/images/jira-2.png b/docs/7_How_To_Contribute/images/jira-2.png new file mode 100644 index 0000000..c1cdb21 Binary files /dev/null and b/docs/7_How_To_Contribute/images/jira-2.png differ diff --git a/docs/7_How_To_Contribute/images/jira-3.png b/docs/7_How_To_Contribute/images/jira-3.png new file mode 100644 index 0000000..b1bec2e Binary files /dev/null and b/docs/7_How_To_Contribute/images/jira-3.png differ diff --git a/docs/7_How_To_Contribute/images/review.png b/docs/7_How_To_Contribute/images/review.png new file mode 100644 index 0000000..805166a Binary files /dev/null and b/docs/7_How_To_Contribute/images/review.png differ -- cgit 1.2.3-korg