summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorEdward Cragg <edward.cragg@codethink.co.uk>2015-09-24 15:09:16 +0100
committerPedro Alvarez <pedro.alvarez@codethink.co.uk>2015-10-24 14:44:00 +0100
commitd9aeb29a199aa4f869c335e9923065554a1bb350 (patch)
tree44740b01023eb946f53b59d67e5f298134837bb6
parent025e1444551457b2fc3d9a048402e6bdfd6da7e5 (diff)
downloaddefinitions-d9aeb29a199aa4f869c335e9923065554a1bb350.tar.gz
Rawdisk partitioning v2: Add documentation
Change-Id: Icf965499380522d8f80cc07f17678179dedeee1a
-rw-r--r--extensions/pyfdisk.README144
-rw-r--r--extensions/rawdisk.write.help45
2 files changed, 189 insertions, 0 deletions
diff --git a/extensions/pyfdisk.README b/extensions/pyfdisk.README
new file mode 100644
index 00000000..8b3b941b
--- /dev/null
+++ b/extensions/pyfdisk.README
@@ -0,0 +1,144 @@
+Introduction
+============
+
+The pyfdisk.py module provides a basic Python wrapper around command-line
+fdisk from util-linux, and some assorted related functions for querying
+information from real disks or disk images.
+
+
+YAML partition specification
+============================
+
+A YAML file may be loaded, using the function load_yaml(). This can contain
+all the information needed to create a Device object which can then be
+committed to disk.
+
+The format of this file is as follows:
+
+ start_offset: 2048
+ partition_table_format: gpt
+ partitions:
+ - description: boot
+ size: 1M
+ fdisk_type: 0x0B
+ filesystem: vfat
+ boot: yes
+ mountpoint: /boot
+ - description: rootfs
+ number: 3
+ size: 10G
+ filesystem: btrfs
+ fdisk_type: 0x83
+ mountpoint: /
+ - description: src
+ size: fill
+ filesystem: ext4
+ fdisk_type: 0x81
+ mountpoint: /src
+
+There are a couple of global attributes:
+
+* 'start_offset': specifies the start sector of the first partition on the
+ device (default: 2048)
+
+* 'partition_table_format': specifies the partition table format to be used
+ when creating the partition table. Possible format
+ strings are 'gpt', 'dos', or 'mbr' ('dos' and
+ 'mbr' are interchangeable). (default: gpt)
+
+Following this, up to 4 (for MBR) or 128 (for GPT) partitions can be
+specified, in the list, 'partitions'. For partitions, 'size', 'fdisk_type' and
+'filesystem' are required.
+
+* 'size' is the size in bytes, or 'fill', which will expand the partition to
+ fill any unused space. Multiple partitions with 'size: fill' will share the
+ free space on the device. Human readable formatting can be used: K, M, G, T,
+ for integer multiples (calculated as powers of 2^n)
+
+* 'fdisk_type' is the fdisk partition type, specified as a hexadecimal value
+ (default: 0x81)
+
+* 'filesystem' specifies a filesystem to be created on the partition. It can
+ be a filesystem with associated any mkfs.* tool, or 'none' for an
+ unformatted partition.
+
+Optional partition attributes include:
+
+* 'number' is optional, and can be used to override the numbering of
+ partitions, if it is desired to have partition numbering that differs from
+ the physical order of the partitions on the disk.
+ - For all un-numbered partitions, the physical order of partitions on the
+ device is determined by the order in which they appear in the
+ specification.
+ - For any partitions without a specified number, partition numbering is
+ handled automatically. In the example above, /boot is 1, /src is 2,
+ and / is 3, even though the physical order differs.
+
+* 'boot' sets the partition's bootable flag (currently only for MBR partition
+ tables)
+
+* 'mountpoint' specifies a mountpoint of a partition. One partition must
+ have a '/' mountpoint to contain the rootfs, otherwise this is optional.
+ Files present in the rootfs under the mount point for a given partition will
+ be copied to the created partition.
+
+load_yaml() produces a Device object, populated with any partitions contained
+in the specification.
+
+
+Objects
+=======
+
+Partition - An object containing properties of a partition
+
+Device - An object holding information about a physical device, and the
+ overall properties of the partitioning scheme. It contains a
+ PartitionList holding the partitions on the device.
+
+PartitionList - An object which holds a list of partitions on the disk. New
+ partitions can be added to the list at any time. When the list
+ is queried, properties of partitions which depend on the
+ properties of the other partitions in the list, for example
+ the size of a fill partition, or numbering, are recalculated,
+ and an updated copy of a Partition object is returned.
+
+Extent - An object which helps encapsulate sector dimensions for partitions
+ and devices.
+
+
+Quick start
+===========
+
+ >>> dev = pyfdisk.Device('test.img', 'fill')
+ >>> print dev
+ <Device: location=test.img, size=16777216, partitions: 0>
+ >>> part = pyfdisk.Partition(size='1M', fdisk_type=0x81, filesystem='ext4', mountpoint='/test1')
+ >>> part2 = pyfdisk.Partition(size='fill', filesystem='btrfs', mountpoint='/test2')
+ >>> dev.add_partition(part)
+ >>> dev.add_partition(part2)
+ >>> print dev.partitionlist
+ Partition
+ size: 14663168
+ fdisk type: 0x81
+ filesystem: btrfs
+ start: 4096
+ end: 32734
+ number: 2
+ mountpoint: /test2
+ Partition
+ size: 1048576
+ fdisk type: 0x81
+ filesystem: ext4
+ start: 2048
+ end: 4095
+ number: 1
+ mountpoint: /test1
+ >>> dev.commit()
+ Creating GPT partition table on test.img
+
+ $ fdisk -l test.img
+ Disk test.img: 16 MiB, 16777216 bytes, 32768 sectors
+ ...
+ Device Start End Sectors Size Type
+ test.img1 2048 4095 2048 1M Linux filesystem
+ test.img2 4096 32734 28639 14M Linux filesystem
diff --git a/extensions/rawdisk.write.help b/extensions/rawdisk.write.help
index 52ed73fb..72e285b7 100644
--- a/extensions/rawdisk.write.help
+++ b/extensions/rawdisk.write.help
@@ -78,5 +78,50 @@ help: |
(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)