Merge pull request #320 from samueldr-wip/feature/android-flashable-zip

android: Add flashable zip output

devices/asus-flo/default.nix

@@ -19,6 +19,7 @@
     kernel.package = pkgs.callPackage ./kernel { };
   };
 
+  mobile.system.android.device_name = "flo";
   mobile.system.android.bootimg = {
     flash = {
       offset_base = "0x80200000";

devices/asus-x018d/default.nix

@@ -20,6 +20,7 @@
     kernel.package = pkgs.callPackage ./kernel { };
   };
 
+  mobile.system.android.device_name = "ww_x018";
   mobile.system.android = {
     bootimg.flash = {
       offset_base = "0x40078000";

devices/asus-z00t/default.nix

@@ -24,6 +24,7 @@
 
   mobile.device.firmware = pkgs.callPackage ./firmware {};
 
+  mobile.system.android.device_name = "Z00T";
   mobile.system.android.bootimg = {
     flash = {
       offset_base = "0x10000000";

devices/google-marlin/default.nix

@@ -21,6 +21,7 @@
 
   mobile.device.firmware = pkgs.callPackage ./firmware {};
 
+  mobile.system.android.device_name = "marlin";
   mobile.system.android = {
     # This device has an A/B partition scheme
     ab_partitions = true;

devices/google-walleye/default.nix

@@ -19,6 +19,7 @@
     kernel.package = pkgs.callPackage ./kernel { };
   };
 
+  mobile.system.android.device_name = "walleye";
   mobile.system.android = {
     # This device has an A/B partition scheme
     ab_partitions = true;

devices/motorola-addison/default.nix

@@ -21,6 +21,7 @@
 
   mobile.device.firmware = pkgs.callPackage ./firmware {};
 
+  mobile.system.android.device_name = "addison";
   mobile.system.android.bootimg = {
     flash = {
       offset_base = "0x80000000";

devices/motorola-surfna/default.nix

@@ -19,6 +19,7 @@
     kernel.package = pkgs.callPackage ./kernel { };
   };
 
+  mobile.system.android.device_name = "surfna";
   mobile.system.android = {
     # This device adds skip_initramfs to cmdline for normal boots
     boot_as_recovery = true;

devices/oneplus-oneplus3/README.adoc

@@ -10,8 +10,11 @@ Using `fastboot` to burn system.img to the userdata partition will fail.
 It seems like it flashes successfully like other devices do, but the flashed
 image will not boot.
 
-The current workaround is to `fastboot boot` TWRP and use `dd` through `adb` to
-flash the image.
+The current workaround is to use the flashable zip for the system image, or for
+the full device install.
+
+Alternatively, `fastboot boot` TWRP and use `dd` through `adb` to flash the
+image.
 
 ```
  $ cat .../.system.img | adb shell dd of=/dev/block/by-name/userdata bs=8m

devices/oneplus-oneplus3/default.nix

@@ -21,6 +21,7 @@
 
   mobile.device.firmware = pkgs.callPackage ./firmware {};
 
+  mobile.system.android.device_name = "OnePlus3";
   mobile.system.android.bootimg = {
     flash = {
       offset_base = "0x80000000";

devices/razer-cheryl2/default.nix

@@ -19,6 +19,10 @@
     kernel.package = pkgs.callPackage ./kernel { };
   };
 
+  # cheryl2 is "ro.build.product";
+  # Different models of the Razer Phone 2 have different ro.product.device.
+  # It is unknown how supporting `bolt` or `linus` would actually differ.
+  mobile.system.android.device_name = "aura";
   mobile.system.android = {
     # This device has an A/B partition scheme.
     ab_partitions = true;

devices/samsung-a5y17lte/default.nix

@@ -21,6 +21,7 @@
 
   mobile.device.firmware = pkgs.callPackage ./firmware {};
 
+  mobile.system.android.device_name = "a5y17lte";
   mobile.system.android = {
     bootimg.flash = {
       offset_base = "0x10000000";

devices/sony-pioneer/default.nix

@@ -19,6 +19,7 @@
     kernel.package = pkgs.callPackage ./kernel { };
   };
 
+  mobile.system.android.device_name = "pioneer";
   mobile.system.android = {
     ab_partitions = true;
 

devices/xiaomi-begonia/default.nix

@@ -22,6 +22,7 @@
     kernel.package = pkgs.callPackage ./kernel { };
   };
 
+  mobile.system.android.device_name = "begonia";
   mobile.system.android = {
     # This device adds skip_initramfs to cmdline for normal boots
     boot_as_recovery = true;

devices/xiaomi-lavender/default.nix

@@ -22,6 +22,7 @@
     kernel.package = pkgs.callPackage ./kernel { };
   };
 
+  mobile.system.android.device_name = "lavender";
   mobile.system.android = {
     # This device adds skip_initramfs to cmdline for normal boots
     boot_as_recovery = true;

devices/xiaomi-tissot/default.nix

@@ -25,6 +25,7 @@
     idProduct = "d001";
   };
 
+  mobile.system.android.device_name = "tissot";
   mobile.system.android = {
     bootimg.flash = {
       offset_base = "0x80000000";

examples/demo/configuration.nix

@@ -255,5 +255,11 @@ in
         videoDrivers = [ "modesetting" ];
       };
     })
+
+    {
+      # Force userdata for the target partition. It is assumed it will not
+      # fit in the `system` partition.
+      mobile.system.android.system_partition_destination = "userdata";
+    }
   ];
 }

modules/system-types/android/default.nix

@@ -30,8 +30,7 @@ let
   # either of fastboot or the outputs.
   # This is because this output should have no refs. A simple tarball of this
   # output should be usable even on systems without Nix.
-  # TODO: Embed device-specific fastboot instructions as `echo` in the script.
-  android-device = pkgs.runCommandNoCC "android-device-${device.name}" {} ''
+  android-fastboot-images = pkgs.runCommandNoCC "android-fastboot-images-${device.name}" {} ''
     mkdir -p $out
     cp -v ${rootfs}/${rootfs.filename} $out/system.img
     cp -v ${android-bootimg} $out/boot.img
@@ -42,6 +41,12 @@ let
     #!/usr/bin/env bash
     dir="$(cd "$(dirname "''${BASH_SOURCE[0]}")"; echo "$PWD")"
     PS4=" $ "
+    ${if has_recovery_partition then ''
+    echo "NOTE: This script flashes the boot and recovery partitions only."
+    '' else ''
+    echo "NOTE: This script flashes the boot partition only."
+    ''}
+    (
     set -x
     ${if flashingMethod == "fastboot" then ''
       fastboot flash ${optionalString ab_partitions "--slot=all"} boot "$dir"/boot.img
@@ -55,17 +60,29 @@ let
         --RECOVERY "$dir"/recovery.img
       ''}
     ''
-    else builtins.throw "No flashing method for ${flashingMethod}"}
+    else builtins.throw "No flashing method for ${flashingMethod}"})
+    echo ""
+    echo "Flashing completed."
+    echo "The system image needs to be flashed manually to the ${config.mobile.system.android.system_partition_destination} partition."
     EOF
     chmod +x $out/flash-critical.sh
   '';
 
+  # The output name `android-device` does not describe well what it is.
+  # This is kept for some backwards compatibility (6 months)
+  # Change to a throw by or after September 2021.
+  android-device = builtins.trace "The output `android-device` has been renamed to: `android-systems-image`." android-fastboot-images;
+
   mkBootimgOption = name: lib.mkOption {
     type = types.str;
     internal = true;
   };
 in
 {
+  imports = [
+    ./flashable-zip.nix
+  ];
+
   options = {
     mobile.system.android = {
       ab_partitions = lib.mkOption {
@@ -82,13 +99,37 @@ in
         internal = true;
       };
 
+      device_name = lib.mkOption {
+        type = types.nullOr types.str;
+        description = "Value of `ro.product.device` or `ro.build.product`. Used to compare against in flashable zips.";
+        default = null;
+        internal = true;
+      };
+
+      flashingMethod = lib.mkOption {
+        type = types.enum [
+          "fastboot" # Default, using `fastboot`
+          "odin"     # Mainly Samsung, using `heimdall`
+        ];
+        description = "Configures which flashing method is used by the device.";
+        default = "fastboot";
+        internal = true;
+      };
+
       has_recovery_partition = lib.mkOption {
         type = types.bool;
         description = "Configures whether the device uses a distinct recovery partition";
         default = !config.mobile.system.android.boot_as_recovery;
         internal = true;
       };
 
+      system_partition_destination = lib.mkOption {
+        type = types.str;
+        description = "Partition label on which to install the system image. E.g. change to `userdata` when it does not fit in the system partition.";
+        default = "system";
+        internal = true;
+      };
+
       bootimg = {
         name = lib.mkOption {
           type = types.str;
@@ -113,16 +154,6 @@ in
           "pagesize"
         ] mkBootimgOption;
       };
-
-      flashingMethod = lib.mkOption {
-        type = types.enum [
-          "fastboot" # Default, using `fastboot`
-          "odin"     # Mainly Samsung, using `heimdall`
-        ];
-        description = "Configures which flashing method is used by the device.";
-        default = "fastboot";
-        internal = true;
-      };
     };
   };
 
@@ -131,8 +162,13 @@ in
 
     (lib.mkIf enabled {
       system.build = {
-        default = android-device;
-        inherit android-bootimg android-recovery android-device;
+        default = android-fastboot-images;
+        inherit
+          android-device
+          android-bootimg
+          android-recovery
+          android-fastboot-images
+        ;
       };
 
       mobile.HAL.boot.rebootModes = [

modules/system-types/android/device-notes.fastboot.adoc.erb

@@ -1,23 +1,62 @@
-== Building
+== Building and installing
 
-This will build the default output for your _<%= info["fullName"] %>_.
+There are multiple installation methods for your _<%= info["fullName"] %>_.
+They all rely on flashing one or more partitions on your device.
 
- $ nix-build --argstr device <%= info["identifier"] %> -A build.default
+[WARNING]
+====
+*All installation methods can lead to data loss.*
 
-== Installation
+Flashing a partition *will erase everything on the partition*. Additionally,
+the common backups methods, e.g. TWRP, will *not* backup the `userdata`
+partition, which may be the installation target.
+
+Make backups.
+====
+
+=== Using Fastboot
+
+This will produce a folder with a flashing script, and the partition images for
+your _<%= info["fullName"] %>_.
+
+ $ nix-build --argstr device <%= info["identifier"] %> -A build.android-fastboot-images
+
+Alternatively, you can build a specific partition image:
+
+ $ nix-build --argstr device <%= info["identifier"] %> -A build.android-bootimg
+ $ nix-build --argstr device <%= info["identifier"] %> -A build.rootfs
 
 The device will need to be booted in its bootloader, or `fastboot`, mode.
-The boot image can be installed using the following command, assuming it was
-built using the previous command.
+
+The boot images can be installed using the following command, assuming the
+`android-fastboot-images` output was used.
 
  $ result/flash-critical.sh
 
 If you have a system image (`system.img`) built, you can use `fastboot` to
 flash it to the device. Note that it might be too big to fit over the `system`
 partition. In such case, it can be flashed on the `userdata` partition.
 
-WARNING: *This will erase everything on the partition*. Additionally, the
-common backups methods, e.g. TWRP, will *not* backup the `userdata` partition.
-
  $ fastboot flash userdata system.img
 
+=== Using a flashable zip
+
+An alternative installation method is to use a flashable zip. The flashable zip
+can be built for your _<%= info["fullName"] %>_ using one of the following
+commands:
+
+ $ nix-build --argstr device <%= info["identifier"] %>-A build.android-flashable-bootimg
+ $ nix-build --argstr device <%= info["identifier"] %>-A build.android-flashable-system
+ $ nix-build --argstr device <%= info["identifier"] %>-A build.android-flashable-zip
+
+The first two will flash only a specific partition. The last one contains the
+partitions of the two previous one.
+
+The zip can either be copied to the device and selected in a compatible
+Android recovery, or sent to the device through `adb sideload`.
+
+ $ adb sideload /nix/store/eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee-flashable-<%= info["identifier"] %>-boot.zip
+
+By default it will flash to the `system` partition. Some configurations may
+change this to flash to the `userdata` partition. In that case, *no warning is
+given before flashing*.