1 files changed, 127 insertions, 0 deletions
diff --git a/extensions/rawdisk.write.help b/extensions/rawdisk.write.help
new file mode 100644
index 00000000..72e285b7
--- /dev/null
+++ b/extensions/rawdisk.write.help
@@ -0,0 +1,127 @@
+# Copyright (C) 2014, 2015 Codethink Limited
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; version 2 of the License.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, see <http://www.gnu.org/licenses/>.
+
+help: |
+
+    Write a system produced by Morph to a physical disk, or to a file that can
+    be used as a virtual disk. The target will be formatted as a single Btrfs
+    partition, with the system image written to a subvolume in /systems, and
+    other subvolumes created for /home, /opt, /root, /srv and /var.
+
+    When written to a physical drive, the drive can be used as the boot device
+    for a 'real' machine.
+
+    When written to a file, the file can be used independently of `morph` to
+    create virtual machines with KVM / libvirt, OpenStack or, after converting
+    it to VDI format, VirtualBox.
+
+    `morph deploy` will fail if the file specified by `location` already
+    exists.
+
+    If used in `morph upgrade`, the rootfs produced by 'morph build' is added
+    to the existing raw disk image or device as an additional btrfs sub-volume.
+    `morph upgrade` will fail if the file specified by `location` does not
+    exist, or is not a Baserock raw disk image. (Most users are unlikely to
+    need or use this functionality: it is useful mainly for developers working
+    on the Baserock tools.)
+
+    Parameters:
+
+    * location: the pathname of the disk image to be created/upgraded, or the
+      path to the physical device.
+
+    * VERSION_LABEL=label - should contain only alpha-numeric
+      characters and the '-' (hyphen) character. Mandatory if being used with
+      `morph update`
+
+    * INITRAMFS_PATH=path: the location of an initramfs for the bootloader to
+      tell Linux to use, rather than booting the rootfs directly.
+
+    * DTB_PATH=path: **(MANDATORY)** for systems that require a device tree
+      binary - Give the full path (without a leading /) to the location of the
+      DTB in the built system image . The deployment will fail if `path` does
+      not exist.
+
+    * BOOTLOADER_INSTALL=value: the bootloader to be installed
+      **(MANDATORY)** for non-x86 systems
+
+        allowed values =
+        - 'extlinux' (default) - the extlinux bootloader will
+           be installed
+        - 'none' - no bootloader will be installed by `morph deploy`. A
+           bootloader must be installed manually. This value must be used when
+           deploying non-x86 systems such as ARM.
+
+    * BOOTLOADER_CONFIG_FORMAT=value: the bootloader format to be used.
+      If not specified for x86-32 and x86-64 systems, 'extlinux' will be used
+
+        allowed values =
+        - 'extlinux'
+
+    * KERNEL_ARGS=args: optional additional kernel command-line parameters to
+      be appended to the default set. The default set is:
+
+        'rw init=/sbin/init rootfstype=btrfs \
+          rootflags=subvol=systems/default/run \
+          root=[name or UUID of root filesystem]'
+
+        (See https://www.kernel.org/doc/Documentation/kernel-parameters.txt)
+
+    * PARTITION_FILE=path: path to a YAML partition specification to use for
+      producing partitioned disks or devices. The default specification is
+      'partitioning/default' in definitions, which specifies a device with a
+      single partition. This may serve as an example of the format of this
+      file, or check the pyfdisk.py documentation in pyfdisk.README.
+
+        In addition to the features available in pyfdisk.py, using this
+        extension, a list of 'raw_files' items can be added at the partition
+        level, or the top level of the partition specification. This specifies
+        files to be written directly to the target device or image using `dd`
+
+            start_offset: 2048
+            partition_table_format: mbr
+            partitions:
+            - description: boot
+              filesystem: none
+              ...
+              raw_files:
+              - file: boot/uboot.img
+            raw_files:
+            - file: boot/uboot-env.img
+              offset_bytes: 512
+            - file: boot/preloader.bin
+              skip_bytes: 128
+              count_bytes: 16K
+
+        * Files are written consecutively in the order they are listed, and
+          sourced from the unpacked root filesystem image
+        * Files can be given a specific offset with 'offset_sectors' or
+          'offset_bytes'
+        * With 'raw_files' specified inside a partition, 'offset_sectors' or
+          'offset_bytes' is counted from the start of that partition,
+          otherwise from the start of the device.
+        * For files without an explicit offset, the next file is written
+          starting with the next free byte following the previous file
+        * Providing an offset is optional for all files
+        * Specifying 'skip_bytes' will set the 'skip=' option for dd, skipping
+          a number of bytes at the start of the input file
+        * Specifying 'count_bytes' sets the 'count=' option for dd
+        * For properties which take an input in bytes, a human-readable
+          multiplier can be used, e.g. K, M, G (integer multiplicands only)
+
+    * USE_PARTITIONING=boolean (default: no) Use this flag to enable
+      partitioning functions.
+
+    (See `morph help deploy` for details of how to pass parameters to write
+    extensions)