diff --git a/cobalt/site/docs/development/setup-android.md b/cobalt/site/docs/development/setup-android.md index 518404b85b46..b8f0cc84068c 100644 --- a/cobalt/site/docs/development/setup-android.md +++ b/cobalt/site/docs/development/setup-android.md @@ -27,32 +27,32 @@ return and complete the following steps. git checkout tags/24.lts.40 ``` -1. Enter the top-level of the Cobalt directory +2. Enter the top-level of the Cobalt directory ```sh cd $COBALT_SRC ``` -1. Download the Starboard toolchain and Android SDK +3. Download the Starboard toolchain and Android SDK ```sh ./starboard/tools/download_clang.sh ./starboard/android/shared/download_sdk.sh ``` -1. Install additional Linux packages +4. Install additional Linux packages ```sh sudo apt install binutils-arm-linux-gnueabi libgles2-mesa-dev mesa-common-dev ``` -1. Make sure Android debug keystore is setup +5. Make sure Android debug keystore is setup ```sh keytool -genkey -v -keystore ~/.android/debug.keystore -storepass android -alias androiddebugkey -keypass android -keyalg RSA -keysize 2048 -validity 10000 ``` -1. Enable python3 virtual environment +6. Enable python3 virtual environment ```sh python3 -m venv ~/.virtualenvs/cobalt_dev @@ -69,11 +69,12 @@ return and complete the following steps. - Build type, ex: gold, qa - Starboard API version, ex: 15 - An example to create directory for evergreen-arm-softfp with build_type=qa and sb_api_version=15 + ```sh gn gen out/evergreen-arm-softfp_qa --args="target_platform=\"evergreen-arm-softfp\" use_asan=false target_cpu=\"arm\" build_type=\"qa\" sb_api_version=15" ``` -1. Select Google-prebuilt Cobalt binaries from [GitHub](https://github.com/youtube/cobalt/releases) +2. Select Google-prebuilt Cobalt binaries from [GitHub](https://github.com/youtube/cobalt/releases) - Choose the correct evergreen version based on the target device specification @@ -91,7 +92,7 @@ return and complete the following steps. - `QA version`: cobalt_evergreen_5.1.2_arm-softfp_sbversion-16_qa_compressed_20240629001855.crx - Right click the file and copy file URL -1. Download and unzip the file +3. Download and unzip the file ```sh export LOCAL_CRX_DIR=/tmp/cobalt_dl @@ -107,7 +108,7 @@ return and complete the following steps. unzip $LOCAL_CRX_DIR/cobalt_prebuilt.crx -d $LOCAL_CRX_DIR/cobalt_prebuilt ``` -1. Copy the files to the appropriate directories for building +4. Copy the files to the appropriate directories for building ```sh cd $COBALT_SRC @@ -130,19 +131,19 @@ return and complete the following steps. To enable Evergreen-lite, you may either pass in command line flag `--evergreen_lite` or set the `cobalt.EVERGREEN_LITE` property to be `true` in the AndroidManifest.xml -1. Build Crashpad handler first +2. Build Crashpad handler first ```sh ninja -C out/android-arm_qa native_target/crashpad_handler ``` -1. Build loader_app APK +3. Build loader_app APK ```sh ninja -C out/android-arm_qa loader_app_install ``` -1. Check the output apk file. The output file is available at +4. Check the output apk file. The output file is available at ```sh out/android-arm_qa/loader_app.apk @@ -152,11 +153,11 @@ return and complete the following steps. ### Configure your device to be in developer mode -1. From `Settings`, in the `System` row, select `About` -1. Scroll down to and click on `Android TV OS build` several times until a toast appears with - the message, "You are now a developer" -1. In the newly added "Developer options" settings menu, make sure `USB` - debugging is enabled +1. From `Settings`, in the `System` row, select `About` +2. Scroll down to and click on `Android TV OS build` several times until a + toast appears with the message, "You are now a developer" +3. In the newly added "Developer options" settings menu, make sure `USB` + debugging is enabled **NOTE:** This instruction is based on Chromecast (Google TV). If you do not find the same setting, please check similar setting under **System, About and Build**. @@ -164,7 +165,7 @@ return and complete the following steps. 1. Connect your workstation with the Android device via USB -1. Check device is connected +2. Check device is connected ```sh adb devices @@ -175,53 +176,53 @@ return and complete the following steps. ### Install the Evergreen loader APK on the device -``` +```sh adb install out/android-arm_qa/loader_app.apk ``` ### Launch the APK -1. Start the application with +1. Start the application with - ```sh - adb shell am start dev.cobalt.coat/dev.cobalt.app.MainActivity - ``` + ```sh + adb shell am start dev.cobalt.coat/dev.cobalt.app.MainActivity + ``` -1. For command line parameters use the `--esa` flag to specify the "args" array - as comma-separated values (with characters backslash-escaped as needed to - make it through both the shell on your workstation and the shell on the - device), e.g.: +2. For command line parameters use the `--esa` flag to specify the "args" array + as comma-separated values (with characters backslash-escaped as needed to + make it through both the shell on your workstation and the shell on the + device), e.g.: - ```sh - adb shell am start --esa args --flag_arg,--value_arg=something dev.cobalt.coat - ``` + ```sh + adb shell am start --esa args --flag_arg,--value_arg=something dev.cobalt.coat + ``` -1. For Evergreen-lite, two ways to launch it depending on how you enable it - - Via command line flag +3. For Evergreen-lite, two ways to launch it depending on how you enable it + - Via command line flag - ```sh - adb shell "am start --esa args '--evergreen_lite=true' dev.cobalt.coat" - ``` + ```sh + adb shell "am start --esa args '--evergreen_lite=true' dev.cobalt.coat" + ``` - - Via AndroidManifest.xml - ```sh - adb shell "am start dev.cobalt.coat" - ``` + - Via AndroidManifest.xml -1. To monitor log output, watch logcat in another shell with a filter for - starboard messages + ```sh + adb shell "am start dev.cobalt.coat" + ``` - ```sh - adb logcat -s starboard:* - ``` +4. To monitor log output, watch logcat in another shell with a filter for + starboard messages -1. To kill any existing running application process (even if it's no longer the - active app) use + ```sh + adb logcat -s starboard:* + ``` - ```sh - adb shell am force-stop dev.cobalt.coat - ``` +5. To kill any existing running application process (even if it's no longer the + active app) use + ```sh + adb shell am force-stop dev.cobalt.coat + ``` ## Running Tests @@ -232,19 +233,20 @@ run that on a device, it needs to be packaged into another loader APK. ### Build nplb library Similar to loader_app, create the directory with arguments that meet the target device specification. Here is an example: + 1. Generate evergreen folder ```sh gn gen out/evergreen-arm-softfp_devel --args="target_platform=\"evergreen-arm-softfp\" target_cpu=\"arm\" use_asan=false build_type=\"devel\" sb_api_version=15" ``` -1. Build nplb library +2. Build nplb library ```sh ninja -C out/evergreen-arm-softfp_devel nplb_install ``` -1. Generate apk output folder +3. Generate apk output folder ```sh gn gen out/android-arm_devel --args="target_platform=\"android-arm\" target_cpu=\"arm\" target_os=\"android\" sb_is_evergreen_compatible=true build_type=\"devel\" sb_api_version=15" @@ -258,13 +260,13 @@ Similar to loader_app, create the directory with arguments that meet the target ninja -C out/android-arm_devel nplb_evergreen_loader_install ``` -1. Check the output apk file. The output file is available at +2. Check the output apk file. The output file is available at ```sh out/android-arm_devel/nplb_evergreen_loader.apk ``` -1. To run the nplb test, execute following command +3. To run the nplb test, execute following command ```sh # install the apk @@ -274,7 +276,7 @@ Similar to loader_app, create the directory with arguments that meet the target adb shell "am start --esa args '--evergreen_library=app/cobalt/lib/libnplb.so,--evergreen_content=app/cobalt/content' dev.cobalt.coat" ``` -1. Generate test result with XML format +4. Generate test result with XML format Due to access permission constrains on AOSP, the xml file should be created by `adb shell` first, before nplb apk writing test result in it. @@ -301,13 +303,13 @@ Similar to loader_app, create the directory with arguments that meet the target ninja -C out/android-arm_devel nplb_evergreen_compat_tests_install ``` -1. Check the output apk file. The output file is available at +2. Check the output apk file. The output file is available at ```sh out/android-arm_devel/nplb_evergreen_compat_tests.apk ``` -1. To run the nplb compat test, execute following command +3. To run the nplb compat test, execute following command ```sh # install the apk @@ -344,31 +346,31 @@ they can still build the library locally. Ex: ## Removing the Cobalt Android Environment -1. Unset ANDROID_HOME and or ANDROID_NDK_HOME in your shell and in .bashrc +1. Unset ANDROID_HOME and or ANDROID_NDK_HOME in your shell and in .bashrc -1. Delete the SDK +2. Delete the SDK - ```sh - rm -rf ~/starboard-toolchains/AndroidSdk - ``` + ```sh + rm -rf ~/starboard-toolchains/AndroidSdk + ``` -1. Delete NDK toolchains +3. Delete NDK toolchains - ```sh - rm -rf ~/starboard-toolchains/android* - ``` + ```sh + rm -rf ~/starboard-toolchains/android* + ``` -1. Delete cached Android files +4. Delete cached Android files - ```sh - rm -rf ~/.android - ``` + ```sh + rm -rf ~/.android + ``` **NOTE:** Removing this directory will remove all signing keys even for different projects, so only delete this if you truly want to remove the entire Cobalt and Android Studio environment. -1. Uninstall APK from device +5. Uninstall APK from device ```sh adb uninstall dev.cobalt.coat diff --git a/starboard/doc/evergreen/cobalt_evergreen_lite.md b/starboard/doc/evergreen/cobalt_evergreen_lite.md index 3c92fa9bcab2..9227eec4e233 100644 --- a/starboard/doc/evergreen/cobalt_evergreen_lite.md +++ b/starboard/doc/evergreen/cobalt_evergreen_lite.md @@ -10,21 +10,18 @@ Updater feature used in Evergreen Full. Evergreen Lite relies on separating the Starboard (platform) and Cobalt (core) components of a Cobalt implementation into the following discrete components: -![Evergreen Lite Overvew](resources/evergreen_lite_overview.png) +![Evergreen Lite Overview](resources/evergreen_lite_overview.png) ## Components Google-built (on Google toolchain) - * Cobalt Core - * Pre-built shared library available for all supported architectures + * Prebuilt shared library available for all supported architectures * Cobalt Updater - disabled Partner-built (on Partner toolchain) - - * Starboard * Platform-specific implementation * Contains system dependencies (e.g. libpthread.so, libEGL.so) @@ -38,38 +35,38 @@ Partner-built (on Partner toolchain) With this new Cobalt Evergreen platform architecture, less engineering effort is necessary for a full Cobalt integration/deployment. -**The idea here is you should only need to implement Starboard one time (as -long as the Starboard API version is supported by Cobalt), and any Cobalt -Core-level binary updates are provided by Google with pre-built -configurations/symbols via our open-source releases -([GitHub](https://github.com/youtube/cobalt/releases))**. These pre-built -Cobalt Core Evergreen binaries should be a direct replacement to update Cobalt -without any engineering work required. As Cobalt Core binaries are pre-built, -they should only require platform testing. NOTE that certain new Cobalt -features may require Starboard changes, so if you want to take advantage of -some of these new features, Starboard changes may be necessary. +**The idea here is you should only need to implement Starboard one time (as long +as the Starboard API version is supported by Cobalt), and any Cobalt Core-level +binary updates are provided by Google with prebuilt configurations/symbols via +our open-source releases +([GitHub](https://github.com/youtube/cobalt/releases))**. These prebuilt Cobalt +Core Evergreen binaries should be a direct replacement to update Cobalt without +any engineering work required. As Cobalt Core binaries are prebuilt, they should +only require platform testing. NOTE that certain new Cobalt features may require +Starboard changes, so if you want to take advantage of some of these new +features, Starboard changes may be necessary. ### Benefits compared to non-Evergreen -* Less engineering work/accelerated timeline for Cobalt -integration/deployment as Google builds Cobalt core code and partners only need -to build and maintain the Starboard layer +* Less engineering work and accelerated timeline for Cobalt + integration/deployment as Google builds Cobalt core code and partners only + need to build and maintain the Starboard layer * Performance enhancements as the Cobalt core is built with modern toolchain * Crash reports are uploaded to Google backend and monitored by Google, so -they can be acted on and addressed more quickly + they can be acted on and addressed more quickly ### New in Evergreen Lite compared to non-Evergreen -* New `loader_app` and `crashpad_handler` components required to be built -on platform toolchains +* New `loader_app` and `crashpad_handler` components required to be built on + platform toolchains * No Cobalt Core customization is allowed because the vanilla Cobalt Core -binary is provided by Google. + binary is provided by Google. ### Differences compared to Evergreen Full * The Google-control cloud-based automatic updates are disabled. Instead, -Cobalt provides the update binary to partners, and partners control the release -process + Cobalt provides the update binary to partners, and partners control the + release process * No extra storage required comparing to the existing software requirements ## How is Evergreen different from porting Cobalt previously? @@ -79,21 +76,22 @@ Same as the [Evergreen full doc](cobalt_evergreen_overview.md). ## Building Cobalt Evergreen Components `kSbSystemPathStorageDirectory` is not required to implement. Set both -`sb_evergreen_compatible` and `sb_evergreen_compatible_lite` to `1`s in the `gyp` -platform config. The remaining is the same as the Evergreen full doc. +`sb_evergreen_compatible` and `sb_evergreen_compatible_lite` to `1`s in the +`gn` platform config. The remaining is the same as the [Evergreen Full +doc](cobalt_evergreen_overview.md). ## How does the update work with Evergreen Lite? -Cobalt will release the Cobalt Core binary to partners for each Cobalt LTS -major and minor release, and partners decide whether to update their devices -with the latest Cobalt Core code via firmware OTA update. To update, partners -only need to put the new Cobalt Core binary at the system image location under +Cobalt will release the Cobalt Core binary to partners for each Cobalt LTS major +and minor release, and partners decide whether to update their devices with the +latest Cobalt Core code via firmware OTA update. To update, partners only need +to put the new Cobalt Core binary at the system image location under `/app/cobalt`. More about the system image slot is explained below. ## Platform Requirements -Cobalt Evergreen currently supports the following +Cobalt Evergreen supports the following Target Architectures: @@ -107,8 +105,7 @@ Supported Javascript Engines ## Building and Running Tests -Same as the Evergreen Full doc - -[cobalt_evergreen_overview.md](cobalt_evergreen_overview.md). +Same as the [Evergreen Full doc](cobalt_evergreen_overview.md). ## System Design @@ -120,16 +117,15 @@ Download server. ### Cobalt Evergreen Interfaces -Same as the Evergreen Full doc - -[cobalt_evergreen_overview.md](cobalt_evergreen_overview.md). +Same as the [Evergreen Full doc](cobalt_evergreen_overview.md). ### System Image Slot -Evergreen Lite will have only one system image slot. This is stored in the -directory specified by `kSbSystemPathContentDirectory` under the -`app/cobalt` subdirectory. +Evergreen Lite will have only one system image slot. This is stored in the +directory specified by `kSbSystemPathContentDirectory` under the `app/cobalt` +subdirectory. -``` +```none . ├── content <--(kSbSystemPathContentDirectory) │ └── fonts <--(kSbSystemPathFontDirectory, `standard` or `limit` configuration) @@ -156,18 +152,19 @@ Same as the Evergreen Full doc - Launch Cobalt with the loader app binary with the `evergreen_lite` flag +```sh +./loader_app --evergreen_lite ``` -$ ./loader_app --evergreen_lite -``` + ## FAQ -### What’s the path from Evergreen Lite to Evergreen Full? +### What's the path from Evergreen Lite to Evergreen Full? * Provision storage for the installation slots to contain downloaded update -binaries - `kSbSystemPathStorageDirectory `and configure the slots as instructed -in the Evergreen full doc -* Configure icu table under `kSbSystemPathStorageDirectory` to be shared - among slots + binaries - `kSbSystemPathStorageDirectory `and configure the slots as + instructed in the Evergreen full doc +* Configure icu table under `kSbSystemPathStorageDirectory` to be shared among + slots * Set `sb_evergreen_compatible_lite` to 0 * Implement the handling of pending updates * Rebuild and rerun `nplb_evergreen_compat_tests` diff --git a/starboard/doc/evergreen/cobalt_evergreen_overview.md b/starboard/doc/evergreen/cobalt_evergreen_overview.md index 6f6f786a84a9..3c06088e088a 100644 --- a/starboard/doc/evergreen/cobalt_evergreen_overview.md +++ b/starboard/doc/evergreen/cobalt_evergreen_overview.md @@ -10,14 +10,15 @@ updates without the need for supplemental Cobalt integration work on device platforms. There are two configurations available: -* Evergreen-Lite - * Please read this document for general Evergreen details then see - Evergreen-Lite specific configuration details in - [cobalt_evergreen_lite.md](cobalt_evergreen_lite.md) + * Evergreen Full - * Please continue reading below documentation for configuration details +* Evergreen Lite + +Please read this document for general Evergreen details first. Then read +[Evergreen-Lite](cobalt_evergreen_lite.md) for its specific configuration. -![Cobalt Evergreen Configurations](resources/cobalt_evergreen_configurations.png) +![Cobalt Evergreen +Configurations](resources/cobalt_evergreen_configurations.png) For a bit of background context, as the number of Cobalt devices in the field increases there is a growing proliferation of version fragmentation. Many of @@ -33,10 +34,10 @@ a Cobalt implementation into the following discrete components: **Google-built** (on Google toolchain) * Cobalt Core - * Pre-built shared library available for all supported architectures + * Prebuilt shared library available for all supported architectures * Cobalt Updater * Part of Cobalt Core and used to query servers to check for and download - updated Cobalt Core + updated Cobalt Core **Partner-built** (on Partner toolchain) @@ -46,7 +47,7 @@ a Cobalt implementation into the following discrete components: * Cobalt Loader (Loader App) * Selects the appropriate Cobalt core for usage * An ELF loader is used to load the Cobalt core and resolves symbols with - Starboard APIs when Cobalt starts up in Evergreen mode + Starboard APIs when Cobalt starts up in Evergreen mode With this new Cobalt platform architecture, less engineering effort is necessary for a full Cobalt integration/deployment. The idea here is you should only need @@ -73,7 +74,7 @@ Starboard changes may be necessary. * New `loader_app` and `crashpad_handler` components required to be built on platform toolchains * Additional testing/verification required to ensure new Cobalt releases work - properly + properly ## How is Evergreen different from porting Cobalt previously? @@ -116,7 +117,7 @@ that it sets `is_starboard = false` and `is_native_target_build = true`. For example: -``` +```none gcc_toolchain("target") { ... } @@ -140,8 +141,8 @@ Evergreen: * `kSbSystemPathStorageDirectory` * Dedicated location for storing Cobalt Evergreen-related binaries * This path must be writable and have at least 64MB of reserved space for - Evergreen updates. Please see the “Platforms Requirements” section below - for more details. + Evergreen updates. Please see the "Platforms Requirements" section below for + more details. * `kSbMemoryMapProtectExec` * Ensures mapped memory can be executed * Set `kSbCanMapExecutableMemory` to `true` @@ -164,9 +165,9 @@ out to us for guidance. As mentioned, the Google-maintained Evergreen toolchain is used to build Cobalt core (`libcobalt.so`). For example: -``` -$ gn gen out/evergreen-arm-softfp_qa --args="target_platform=\"evergreen-arm-softfp\" build_type=\"qa\" target_cpu=\"arm\" target_os=\"linux\" sb_api_version=15" -$ ninja -C out/evergreen-arm-softfp_qa cobalt_install +```sh +gn gen out/evergreen-arm-softfp_qa --args="target_platform=\"evergreen-arm-softfp\" build_type=\"qa\" target_cpu=\"arm\" target_os=\"linux\" sb_api_version=15" +ninja -C out/evergreen-arm-softfp_qa cobalt_install ``` This produces a `libcobalt.so` shared library, and a compressed `libcobalt.lz4` @@ -175,16 +176,15 @@ copy, targeted for a specific architecture, ABI, and Starboard version. Note: `sb_api_version` defaults to the latest supported Starboard version in the current branch. - -The partner port of Starboard is built with the partner’s "target" toolchain and +The partner port of Starboard is built with the partner's "target" toolchain and is linked into the `loader_app`, which knows how to dynamically load `libcobalt.lz4`. And the `crashpad_handler` binary is built with the partner's "native_target" toolchain. For example: -``` -$ gn gen out/_qa --args='target_platform="" build_type="qa" sb_api_version=15' -$ ninja -C out/_qa loader_app -$ ninja -C out/_qa native_target/crashpad_handler +```sh +gn gen out/_qa --args='target_platform="" build_type="qa" sb_api_version=15' +ninja -C out/_qa loader_app +ninja -C out/_qa native_target/crashpad_handler ``` Note that when building `crashpad_handler`, a special prefix is used to have @@ -197,17 +197,17 @@ of the CSS which can cause layout behavior to cause components to overlap and give users a poor user experience. A fix for this is identified and pushed to Cobalt open source ready for integration and deployment on devices. -#### Without Cobalt Evergreen: +#### Without Cobalt Evergreen Though a fix for this was made available in the latest Cobalt open source, affected devices in the field are not getting updated (e.g. due to engineering resources, timing, device end-of-life), users continue to have a poor experience and have negative sentiment against a device. In parallel, the web app team determines a workaround for this particular situation, but the workaround is -obtuse and causes app bloat and technical debt from on-going maintenance of +obtuse and causes app bloat and technical debt from ongoing maintenance of workarounds for various Cobalt versions. -#### With Cobalt Evergreen: +#### With Cobalt Evergreen The Cobalt team can work with you to guide validation and deployment of a shared Cobalt library to all affected devices much more quickly without all the @@ -264,7 +264,7 @@ These paths should be *relative to the content of the elf_loader_sandbox*. For example, if we wanted to run the NPLB set of tests and had the following directory tree, -``` +```none .../elf_loader_sandbox .../content/app/nplb/lib/libnplb.so .../content/app/nplb/content @@ -272,7 +272,7 @@ directory tree, we would use the following command to run NPLB: -``` +```sh .../elf_loader_sandbox --evergreen_library=app/nplb/lib/libnplb.so --evergreen_content=app/nplb/content ``` @@ -301,41 +301,51 @@ instructions available [here](cobalt_evergreen_reference_port_raspi2.md). ### Verifying Crashpad Uploads -1. Build the `crashpad_database_util` target and deploy it onto the device. -``` -$ gn gen out/_qa --args='target_platform="" build_type="qa"' -$ ninja -C out/_qa native_target/crashpad_database_util -``` -2. Remove the existing state for crashpad as it throttles uploads to 1 per hour: -``` -$ rm -rf /crashpad_database/ +1. Build the `crashpad_database_util` target and deploy it onto the device. -``` -3. Launch Cobalt. -4. Trigger crash by sending `abort` signal to the `loader_app` process: -``` -$ kill -6 -``` -5. Verify the crash was uploaded through running `crashpad_database_util` on the device -pointing it to the cache directory, where the crash data is stored. + ```sh + gn gen out/_qa --args='target_platform="" build_type="qa"' + ninja -C out/_qa native_target/crashpad_database_util + ``` -``` -$ crashpad_database_util -d /crashpad_database/ --show-completed-reports --show-all-report-info -``` +2. Remove the existing state for crashpad as it throttles uploads to 1 per + hour: -``` -8c3af145-30a0-43c7-a3a5-0952dea230e4: - Path: cobalt/cache/crashpad_database/completed/8c3af145-30a0-43c7-a3a5-0952dea230e4.dmp - Remote ID: c9b14b489a895093 - Creation time: 2021-06-01 17:01:19 HDT - Uploaded: true - Last upload attempt time: 2021-06-01 17:01:19 HDT - Upload attempts: 1 -``` + ```sh + rm -rf /crashpad_database/ + ``` + +3. Launch Cobalt. -In this example the minidump was successfully uploaded because we see `Uploaded: true`. +4. Trigger crash by sending `abort` signal to the `loader_app` process: -Reference for [crashpad_database_util](https://chromium.googlesource.com/crashpad/crashpad/+/refs/heads/main/tools/crashpad_database_util.md) + ```sh + kill -6 + ``` + +5. Verify the crash was uploaded through running `crashpad_database_util` on + the device pointing it to the cache directory, where the crash data is + stored. + + ```sh + crashpad_database_util -d /crashpad_database/ --show-completed-reports --show-all-report-info + ``` + + ```none + 8c3af145-30a0-43c7-a3a5-0952dea230e4: + Path: cobalt/cache/crashpad_database/completed/8c3af145-30a0-43c7-a3a5-0952dea230e4.dmp + Remote ID: c9b14b489a895093 + Creation time: 2021-06-01 17:01:19 HDT + Uploaded: true + Last upload attempt time: 2021-06-01 17:01:19 HDT + Upload attempts: 1 + ``` + +In this example the minidump was successfully uploaded because we see `Uploaded: +true`. + +Reference for +[crashpad_database_util](https://chromium.googlesource.com/crashpad/crashpad/+/refs/heads/main/tools/crashpad_database_util.md) ## System Design @@ -345,11 +355,11 @@ Components](resources/cobalt_evergreen_overview_components.png) The above diagram is a high-level overview of the components in the Cobalt Evergreen architecture. -* **Partner-built** represents components the Partner is responsible for - implementing and building. +* **Partner-built** represents components the Partner is responsible for + implementing and building. -* **Cobalt-built** represents components the Cobalt team is responsible for - implementing and building. +* **Cobalt-built** represents components the Cobalt team is responsible for + implementing and building. ### Cobalt Evergreen Components @@ -430,14 +440,16 @@ slots(i.e. known locations on disk), and are used to significantly improve the resilience and reliability of Cobalt updates. All slot configurations assume the following: -* 1 System Image Installation Slot (read-only) -* 2+ Additional Installation Slot(s) (writable) + +* 1 System Image Installation Slot (read-only) +* 2+ Additional Installation Slot(s) (writable) The number of installation slots available will be determined by the platform owner. **3 slots is the default configuration for Evergreen**. There can be `N` installation slots configured with the only limitation being available storage. #### Slot Configuration + NOTE: 3-slots is the DEFAULT configuration. The number of installation slots is directly controlled using @@ -458,7 +470,7 @@ For example, on the Raspberry Pi the `kSbSystemPathStorageDirectory` directory is `/home/pi/.cobalt_storage`, and the paths to all existing installation slots will be as follows: -``` +```none /home/pi//app/cobalt (system image installation SLOT_0) (read-only) /home/pi/.cobalt_storage/installation_1 (SLOT_1) /home/pi/.cobalt_storage/installation_2 (SLOT_2) @@ -470,6 +482,7 @@ Where the most recent update is stored will alternate between the available writable slots. In the above example, this would be `SLOT_1`...`SLOT_N`. #### Understanding Slot Structure + Slots are used to manage Cobalt Evergreen binaries with associated app metadata to select the appropriate Cobalt Evergreen binaries. @@ -478,7 +491,7 @@ See the below structures for an example 3-slot configuration. Structure for `kSbSystemPathContentDirectory` used for the read-only System Image required for all slot configurations: -``` +```none . ├── content <--(kSbSystemPathContentDirectory) │ └── fonts <--(kSbSystemPathFontDirectory, `standard` or `limit` configuration, to be explained below) @@ -498,7 +511,7 @@ Image required for all slot configurations: Structure for `kSbSystemPathStorageDirectory` used for future Cobalt Evergreen updates in an example 3-slot configuration: -``` +```none ├── .cobalt_storage <--(kSbSystemPathStorageDirectory) ├── cobalt_updater │ └── prefs_.json @@ -514,16 +527,19 @@ updates in an example 3-slot configuration: │ └── manifest.json <-- (Evergreen version information of Cobalt Core under SLOT_2) ├── installation_store_.pb ``` -Note that after the Cobalt binary is loaded by the loader_app, `kSbSystemPathContentDirectory` points to the -content directory of the running binary, as stated in Starboard Module Reference of system.h. + +Note that after the Cobalt binary is loaded by the loader_app, +`kSbSystemPathContentDirectory` points to the content directory of the running +binary, as stated in Starboard Module Reference of system.h. #### App metadata + Each Cobalt Evergreen application has a set of unique metadata to track slot selection. The following set of files are unique per application via a -differentiating identifier, which is a Base64 hash appended to the +differentiating `` identifier, which is a Base64 hash appended to the filename. -``` +```none /installation_store_.pb /cobalt_updater/prefs_.json ``` @@ -531,8 +547,8 @@ filename. You should NOT change any of these files and they are highlighted here just for reference. - ### Fonts + The system font directory `kSbSystemPathFontDirectory` should be configured to point to either the system fonts on the device or the Cobalt `standard` (23MB) or the Cobalt `limited` (3.1MB) font packages. An easy way to use the Cobalt @@ -540,71 +556,78 @@ fonts is to set `kSbSystemPathFontDirectory` to point to `kSbSystemPathContentDirectory/fonts` and configure `cobalt_font_package` to `standard` or `limited` in your port. -Cobalt Evergreen (built by Google), will by default use the `empty` font -package to minimize storage requirements. A separate -`cobalt_font_package` variable is set to `empty` in the Evergreen platform. +Cobalt Evergreen (built by Google), will by default use the `empty` font package +to minimize storage requirements. A separate `cobalt_font_package` variable is +set to `empty` in the Evergreen platform. On Raspberry Pi the Cobalt fonts are configured the following way: `empty` set of fonts under: -``` + +```none /app/starboard/content/fonts ``` `standard` or `limited` set of fonts under: -``` + +```none /fonts ``` ### Handling Pending Updates + Pending updates will be picked up on the next application start, which means that on platforms that support suspending the platform should check `loader_app::IsPendingRestart` and call `SbSystemRequestStop` instead of - suspending if there is a pending restart. +suspending if there is a pending restart. -Please see -[`suspend_signals.cc`](../../shared/signal/suspend_signals.cc) -for an example. +Please see [`suspend_signals.cc`](../../shared/signal/suspend_signals.cc) for an +example. ### Cleaning up after uninstall + When the application is uninstalled the updates should be cleanup by calling the -application with the `--reset_evergreen_update` flag. This would remove all files -under `kSbSystemPathStorageDirectory` and exit the app. +application with the `--reset_evergreen_update` flag. This would remove all +files under `kSbSystemPathStorageDirectory` and exit the app. -``` +```sh loader_app --reset_evergreen_update ``` ### Multi-App Support + Evergreen can support multiple apps that share a Cobalt binary. This is a very common way to save space and keep all your Cobalt apps using the latest version of Cobalt. We understand that there are situations where updates are only needed for certain apps, so we have provided a way where Cobalt Updater and loader_app -behavior can be easily configured on a per-app basis with simple command-line flags. +behavior can be easily configured on a per-app basis with simple command-line +flags. The configurable options for Cobalt Updater configuration are: -* `--evergreen_lite` *Use the System Image version of Cobalt under Slot_0 and turn - off the updater for the specified application.* -Each app’s Cobalt Updater will perform an independent, regular check for new +* `--evergreen_lite` *Use the System Image version of Cobalt under Slot_0 and + turn off the updater for the specified application.* + +Each app's Cobalt Updater will perform an independent, regular check for new Cobalt Evergreen updates. Note that all apps will share the same set of slots, -but each app will maintain metadata about which slots are “good” (working) or -“bad” (error detected) and use the appropriate slot. Sharing slots allows +but each app will maintain metadata about which slots are "good" (working) or +"bad" (error detected) and use the appropriate slot. Sharing slots allows Evergreen to download Cobalt updates a single time and be able to use it across all Evergreen-enabled apps. To illustrate, a simple example: -* Cobalt v5 - latest Cobalt Evergreen version +* Cobalt v5 - latest Cobalt Evergreen version #### BEFORE COBALT UPDATE -``` + +```none [APP_1] (currently using SLOT_1, using Cobalt v4) [APP_2] (currently using SLOT_0, using Cobalt v3) [APP_3] (currently using SLOT_0, using Cobalt v3) ``` -Now remember, apps could share the same Cobalt binary. Let’s say `APP_1` has +Now remember, apps could share the same Cobalt binary. Let's say `APP_1` has detected an update available and downloads the latest update (Cobalt v5) into SLOT_2. The next time `APP_2` runs, it may detect Cobalt v5 as well. It would then simply do a `request_roll_forward` operation to switch to SLOT_2 and does @@ -613,10 +636,11 @@ existing slot. In this case, `APP_1` and `APP_2` are now using the same Cobalt binaries in SLOT_2. If `APP_3` has not been launched, not run through a regular Cobalt Updater -check, or launched with the `--evergreen_lite` flag, -it stays with its current configuration. +check, or launched with the `--evergreen_lite` flag, it stays with its current +configuration. #### AFTER COBALT UPDATE + ``` [APP_1] (currently using SLOT_2, using Cobalt v5) [APP_2] (currently using SLOT_2, using Cobalt v5) @@ -626,10 +650,9 @@ it stays with its current configuration. Now that we have gone through an example scenario, we can cover some examples of how to configure Cobalt Updater behavior and `loader_app` configuration. - Some example configurations include: -``` +```none # All Cobalt-based apps get Evergreen Updates [APP_1] (Cobalt Updater ENABLED) [APP_2] (Cobalt Updater ENABLED) @@ -639,7 +662,6 @@ loader_app --url="" loader_app --url="" loader_app --url="" - # APP_1 gets Evergreen Updates, APP_2 uses an alternate splash screen, APP_3 uses # the system image and disables the updater [APP_1] (Cobalt Updater ENABLED) @@ -650,7 +672,6 @@ loader_app --url="" loader_app --url="" --fallback_splash_screen_url="//app_2_splash_screen.html" loader_app --url="" --evergreen_lite - # APP_3 is a local app, wants Cobalt Updater disabled and stays on the system image, and uses an alternate content # directory (This configuration is common for System UI apps. APP_3 in this example.) [APP_1] (Cobalt Updater ENABLED) @@ -662,12 +683,12 @@ loader_app --url="" loader_app --csp_mode=disable --allow_http --url="file:////index.html" --content="//content" --evergreen_lite ``` -Please see -[`loader_app_switches.cc`](../../loader_app/loader_app.cc) -for full list of available command-line flags. +Please see [`loader_app_switches.cc`](../../loader_app/loader_app.cc) for full +list of available command-line flags. ### Platform Security +{# disableFinding(LINK_DOCS) #}LintDevSiteLinter_md As Cobalt binary packages ([CRX format](https://docs.google.com/document/d/1pAVB4y5EBhqufLshWMcvbQ5velk0yMGl5ynqiorTCG4/edit#heading=h.ke61kmpkapku)) are downloaded from the Google Downloads server, the verification of the Cobalt @@ -739,5 +760,5 @@ platform-specific behavior. Much of the optimization work remains in the Starboard layer and configuration so you should still expect good performance using Cobalt Evergreen. That being -said, the Cobalt Evergreen configuration allows you to customize Cobalt features -and settings as before. +said, the Cobalt Evergreen configuration lets you customize Cobalt features and +settings as before.