From 5e727649c99bbc81d136b7282e3e21f9245cecf2 Mon Sep 17 00:00:00 2001 From: Edward Cragg Date: Thu, 24 Sep 2015 15:09:16 +0100 Subject: Rawdisk partitioning v2: Add documentation Change-Id: Icf965499380522d8f80cc07f17678179dedeee1a --- extensions/pyfdisk.README | 144 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 144 insertions(+) create mode 100644 extensions/pyfdisk.README (limited to 'extensions/pyfdisk.README') 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 + + >>> 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 -- cgit v1.2.1