mobile-nixos · May 14, 2020 · May 14, 2020 · May 14, 2020 · May 14, 2020 · May 14, 2020
diff --git a/devices/families/README.adoc b/devices/families/README.adoc
@@ -0,0 +1,3 @@
+= Device families
+
+_See the documentation in <<../../doc/in-depth/devices.adoc#,Notes about devices>>._
diff --git a/devices/qemu-x86_64/default.nix b/devices/qemu-x86_64/default.nix
@@ -64,7 +64,7 @@ in
     ram = 1024 * 2;
   };
 
-  mobile.system.type = "kernel-initrd";
+  mobile.system.type = "qemu-startscript";
   mobile.boot.stage-1 = {
     kernel = {
       modular = true;

diff --git a/doc/_support/styles/asciidoc.less b/doc/_support/styles/asciidoc.less
@@ -32,8 +32,68 @@
 
 .imageblock {
 	margin-bottom: 1em;
+	#screen-xs-max({
+		img {
+			display: block;
+			margin: auto;
+		}
+	});
+	#screen-sm-min({
+		&.right {
+			float: right;
+			padding-left: @gutter;
+		}
+		&.left {
+			float: left;
+			padding-right: @gutter;
+		}
+	});
+}
+
+.image-halfwidth {
+	img {
+		#screen-sm-min({
+			max-width: 50vw;
+		});
+	}
+}
+
+// Use when the image is *intended* to be scaled regardless of text.
+// If you want the text inside an svg image to stay as big as 
+.image-scalable {
+	&.image-halfwidth {
+		#screen-sm-min({
+			width: 50%;
+		});
+		img {
+			max-width: 100%;
+			width: 50vw;
+		}
+	}
+	#screen-xs-max({
+		&, &.image-halfwidth {
+			img {
+				max-width: 100%;
+				width: 100vw;
+			}
+		}
+	});
 }
 
 table.stretch {
 	width: 100%;
 }
+
+.clear-floats {
+	clear: both;
+}
+
+#footnotes {
+	&:before {
+		display: block;
+		content: "";
+		width: 30%;
+		border-top: 1px solid #666;
+		margin-bottom: @gutter/2;
+	}
+}
diff --git a/doc/_support/styles/layout.less b/doc/_support/styles/layout.less
@@ -65,6 +65,7 @@ body.index {
 	}
 }
 
+body > #footnotes,
 body > #content {
 	overflow: auto;
 	background-color: #fff;

diff --git a/doc/default.nix b/doc/default.nix
@@ -73,6 +73,8 @@ stdenv.mkDerivation {
       --output-dir="$out"
 
     rsync --prune-empty-dirs --verbose --archive \
+      --exclude="*.src.svg" \
+      --include="*.svg" \
       --include="*.jpeg" \
       --include="*.png" \
       --include="*/" --exclude="*" . $out/

diff --git a/doc/in-depth/devices-taxonomy.src.svg b/doc/in-depth/devices-taxonomy.src.svg
diff --git a/doc/in-depth/devices-taxonomy.svg b/doc/in-depth/devices-taxonomy.svg
diff --git a/doc/in-depth/devices.adoc b/doc/in-depth/devices.adoc
@@ -0,0 +1,158 @@
+= Notes about devices
+include::_support/common.inc[]
+:fn-soc: footnote:[link:https://en.wikipedia.org/wiki/System_on_a_chip[System on a Chip]]
+
+[.right.image-halfwidth]
+image::devices-taxonomy.svg[Devices taxonomy; System and Platform terms points to an optional Family term, which points to a Device term]
+
+This document describes the terms used to describe a *device* within Mobile
+NixOS.
+
+The terms are:
+
+* Device
+* (Family)
+* Platform
+* System
+
+[.clear-floats]
+== Definitions
+
+=== What is a _system_?
+
+A *system* describes the common peculiarities that are shared across the
+different _devices_ and _platforms_. Options may be present to describe
+systemic differences or evolutionary changes in those systems' design.
+
+Generally, a system describes the most basic requirements to boot devices,
+without caring for details that are _platform_-specific or _device_-specific.
+
+When talking about a _system_, they are commonly referred as _$system-based_.
+For example, `asus-z00t` is an *android-based* system. Its `system.type` is
+`android`.
+
+Examples of sytems:
+
+* android-based (most devices shipping with Android)
+* depthcharge-based (most devices shipping with ChromeOS)
+* u-boot-based (a wide range, but mostly "hackable" hardware)
+
+
+=== What is a _platform_?
+
+A *platform* describes the common features of a _SoC_{fn-soc} disregarding the
+_system_ it is used with. It is entirely expected that a single _platform_ is
+used with a variety of _systems_.
+
+The _platform_ should set as few global options as possible, the most likely,
+and lone, option set should be the _system_ used (e.g. `aarch64-linux`). A
+_platform_ will also toggle _quirks_ on and off, which are deficiencies
+that must be worked around specific to the _platform_.
+
+Lastly, as an implementation detail, it is preferred to keep the platforms _as
+precisely as possible_, making a distinct platform even if it is technically
+the same as another one (e.g. _Rockchip RK3399_ ⇆ _Rockchip OP-1_). This allows
+better differentiation if, in the end, there is a tiny difference.
+
+The names used should be the _technical_ names, as best as possible. This is
+why the _Qualcomm Snapdragon 615_ is named _Qualcomm MSM8939_.
+
+Examples of platforms:
+
+* Allwinner A64
+* Qualcomm MSM8939
+* Qualcomm SDM660
+* Rockchip OP-1
+
+
+=== What is a _device_?
+
+A *device* is a _somewhat specific_ description of a model of an _appliance_ or
+a _machine_. Generally speaking, when a single build boots on two different
+_SKUs_ without differentiation, they are the same _device_.
+
+The `oneplus-oneplus3` and `oneplus-oneplus3t` is a single _device_.
+Conversely, the `google-taimen` and `google-walleye` are _distinct devices_
+requiring a different kernel build (or software handling via kernel modules).
+The actual line where devices stop being devices and start becoming families is
+undefined, and undefinable. Though following _the same kernel build boots them_
+is likely a good differentiator.
+
+When describing a device, a device is made by or for an _OEM_ (e.g. ASUS,
+Google), has a _name_ (e.g. Zenfone 2 Laser, Pixel 2), and generally has a
+_codename_ (e.g. z00t, walleye). When talking about a device, it's better to
+use the _$oem-$codename_ pair (e.g. `asus-z00t`), as it describes the exact
+device more appropriately. Some OEMs re-use device names (e.g. Moto G).
+Additionally, those codenames are generally used to talk about the devices
+with Android ROM development, it ends up being useful to find resources about
+the device.
+
+Examples of devices:
+
+* ASUS Zenfone 2 Laser (`asus-z00t`)
+* Google Pixel 2 (`google-walleye`)
+
+
+=== What are _families_?
+
+First of all, *families* are optional. Most devices will directly be
+implemented without a family in sight.
+
+A family is best described as an _incomplete device_. Most of the device's
+properties will be defined by the family, and only the last details will be
+described by the device.
+
+Following from the previous example, `google-walleye` and `google-taimen` are
+different _devices_ of the same _family_. They both are made by the same OEM,
+and share most configuration. The main differences here are the display size,
+and the kernel build used.
+
+Examples of families:
+
+* `google-wahoo`, the Pixel 2 (`taimen` and `walleye`)
+
+
+== Implementation
+
+=== Do I need to implement a system type?
+
+Probably not. You only need to implement a system type when your device has a
+different boot chain not supported already.
+
+If you do end up needing to implement a system type, they are under the
+`modules/system-types` directory.
+
+
+=== How do I implement a platform?
+
+First, you need to know whether you need to add a platform or not. All distinct
+SoCs need their own option, see `modules/hardware-$manufacturer.nix`.
+
+Look at existing platforms implemented, and copy the one that matches yours the
+best. It is likely you only need to add an option to enable the platform, an
+option for the system type, and enable the relevant quirks.
+
+
+=== How do I implement a device?
+
+See the <<porting-guide.adoc#,Porting Guide>>.
+
+
+=== How do I implement a family?
+
+The easiest way is to implement two devices of your family, copy-paste and all,
+and only after refactor the common parts out.
+
+Families are found under the `devices/families` directory, one directory per
+family. They should mirror the implementation of a device, but be incomplete,
+expected to be completed by their devices.
+
+
+== Implementation details
+
+=== Families
+
+Families are not a module, like systems and platforms, as they would incur
+additional cost during the evaluation for not much gain. Seen in another way,
+families are an implementation detail of a device, and not an intrinsic part of
+the architecture of the Mobile NixOS project.
diff --git a/doc/in-depth/index.adoc b/doc/in-depth/index.adoc
@@ -11,6 +11,10 @@ Index of in-depth topics.
 
 * <<stage-1.adoc#,Stage-1>>
 
+== Project Organization
+
+* <<devices.adoc#,Devices>>
+
 == Android-Based Devices
 
 * <<android/partitions.adoc#,Partitions>>
diff --git a/modules/module-list.nix b/modules/module-list.nix
@@ -29,6 +29,7 @@
   ./mobile-device.nix
   ./nixpkgs.nix
   ./quirks/qualcomm/default.nix
+  ./rootfs.nix
   ./system-target.nix
   ./system-types.nix
 ]
diff --git a/systems/rootfs.nix → modules/rootfs.nix b/systems/rootfs.nix → modules/rootfs.nix
@@ -1,4 +1,5 @@
-# This builds a rootfs image (ext4) from the current configuration.
+# This provides `build.rootfs`, which is the rootfs image (ext4) built from
+# the current configuration.
 { config, lib, pkgs, ... }:
 
 let

diff --git a/modules/system-types.nix b/modules/system-types.nix
@@ -11,9 +11,8 @@ let
 in
 {
   imports = [
-    ../systems/rootfs.nix
     ./system-types/depthcharge
-    ./system-types/kernel-initrd
+    ./system-types/qemu-startscript
     ./system-types/android
     ./system-types/u-boot
   ];

diff --git a/systems/bootimg.nix → modules/system-types/android/bootimg.nix b/systems/bootimg.nix → modules/system-types/android/bootimg.nix
diff --git a/modules/system-types/android/default.nix b/modules/system-types/android/default.nix
@@ -39,13 +39,13 @@ let
 
   inherit (config.system.build) rootfs;
 
-  android-recovery = pkgs.callPackage ../../../systems/bootimg.nix {
+  android-recovery = pkgs.callPackage ./bootimg.nix {
     inherit device_config;
     initrd = recovery.system.build.initrd;
     name = "recovery.img";
   };
 
-  android-bootimg = pkgs.callPackage ../../../systems/bootimg.nix {
+  android-bootimg = pkgs.callPackage ./bootimg.nix {
     inherit device_config;
     initrd = config.system.build.initrd;
   };

diff --git a/modules/system-types/depthcharge/default.nix b/modules/system-types/depthcharge/default.nix
@@ -4,7 +4,7 @@ let
   device_config = config.mobile.device;
   enabled = config.mobile.system.type == "depthcharge";
 
-  build = pkgs.callPackage ../../../systems/depthcharge {
+  build = pkgs.callPackage ./depthcharge-build.nix {
     inherit device_config;
     initrd = config.system.build.initrd;
     system = config.system.build.rootfs;

diff --git a/systems/depthcharge/default.nix → ...m-types/depthcharge/depthcharge-build.nix b/systems/depthcharge/default.nix → ...m-types/depthcharge/depthcharge-build.nix
diff --git a/...es/system-types/kernel-initrd/default.nix → ...system-types/qemu-startscript/default.nix b/...es/system-types/kernel-initrd/default.nix → ...system-types/qemu-startscript/default.nix
@@ -5,17 +5,17 @@ let
   device_name = device_config.name;
   hardware_config = config.mobile.hardware;
   rootfs = config.system.build.rootfs;
-  enabled = config.mobile.system.type == "kernel-initrd";
+  enabled = config.mobile.system.type == "qemu-startscript";
 
-  kernel-initrd = pkgs.callPackage ../../../systems/kernel-initrd.nix {
+  qemu-startscript = pkgs.callPackage ./qemu-startscript-build.nix {
     inherit device_config hardware_config;
     initrd = config.system.build.initrd;
   };
 
   system = pkgs.linkFarm "${device_config.name}-build" [
     {
-      name = "kernel-initrd";
-      path = "kernel-initrd";
+      name = "qemu-startscript";
+      path = "qemu-startscript";
     }
     {
       name = "system";
@@ -28,7 +28,7 @@ let
 in
   {
     config = lib.mkMerge [
-      { mobile.system.types = [ "kernel-initrd" ]; }
+      { mobile.system.types = [ "qemu-startscript" ]; }
 
       (lib.mkIf enabled {
         system.build = rec {
@@ -45,10 +45,10 @@ in
 
             qemu-system-x86_64 \
               -enable-kvm \
-              -kernel "${kernel-initrd}/kernel" \
-              -initrd "${kernel-initrd}/initrd" \
-              -append "$(cat "${kernel-initrd}/cmdline.txt")" \
-              -m      "$(cat "${kernel-initrd}/ram.txt")M" \
+              -kernel "${qemu-startscript}/kernel" \
+              -initrd "${qemu-startscript}/initrd" \
+              -append "$(cat "${qemu-startscript}/cmdline.txt")" \
+              -m      "$(cat "${qemu-startscript}/ram.txt")M" \
               -serial "mon:stdio" \
               -drive  "file=fs.img,format=raw" \
               -device VGA,edid=on,xres=${xres},yres=${yres} \

diff --git a/systems/kernel-initrd.nix → ...mu-startscript/qemu-startscript-build.nix b/systems/kernel-initrd.nix → ...mu-startscript/qemu-startscript-build.nix
@@ -16,7 +16,7 @@ let
   cmdline = device_info.kernel_cmdline;
 in
 stdenv.mkDerivation {
-  name = "mobile-nixos_${device_name}-kernel-initrd";
+  name = "mobile-nixos_${device_name}-qemu-startscript";
 
   src = builtins.filterSource (path: type: false) ./.;
   unpackPhase = "true";
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		= Device families

		_See the documentation in <<../../doc/in-depth/devices.adoc#,Notes about devices>>._