imagefile

Documentation

Overview

Package imagefile contains code to create a file with the following content:

	.-----------.----------.---------------.
	| 0 - 512 B | 4 - 8 Kb |  2M - ...     |
	|-----------+----------+---------------+
	|   MBR #1  |   DAX    |  FS           |
	'-----------'----------'---------------'
	      |         |      ^
	      |         '-data-'
	      |                |
	      '--fs-partition--'

                    ^          ^
          daxHeaderOffset      |
                           HeaderSize

MBR: Master boot record. DAX: Metadata required by the NVDIMM driver to enable DAX in the guest (struct nd_pfn_sb). FS: partition that contains a filesystem.

The MBR is useful for working with the image file:

• the `file` utility uses it to determine what the file contains
• when binding the entire file to /dev/loop0, /dev/loop0p1 will be the file system (beware that partprobe /dev/loop0 might be needed); alternatively one could bind the file system directly by specifying an offset

When such a file is created on a dax-capable filesystem, then it can be used as backing store for a [QEMU nvdimm device](https://github.com/qemu/qemu/blob/master/docs/nvdimm.txt) such that the guest kernel provides a /dev/pmem0 (the FS partition above) which can be mounted with -odax. For full dax semantic, the QEMU device configuration must use the 'pmem' and 'share' flags.

Index

• Constants
• func Create(filename string, size Bytes, fs FsType) error
• type Bytes
• type FsType

Constants

const (
	MiB = Bytes(1024 * 1024)
	KiB = Bytes(1024)

	// Alignment of partitions relative to the start of the block device, i.e. the MBR.
	// For DAX huge pages this has to be 2MB, see https://nvdimm.wiki.kernel.org/2mib_fs_dax
	DaxAlignment = 2 * MiB

	// Start of the file system.
	// Chosen so that we have enough space before it for MBR #1 and the DAX metadata.
	HeaderSize = DaxAlignment

	// Block size used for the filesystem. ext4 only supports dax with 4KiB blocks.
	BlockSize = 4 * KiB

	// /dev/pmem0 will have some fake disk geometry attached to it.
	// We have to make the final device size a multiple of the fake
	// head * track... even if the actual filesystem is smaller.
	DiskAlignment = DaxAlignment * 512
)

Functions

func Create

func Create(filename string, size Bytes, fs FsType) error

Create writes a complete image file of a certain total size. The size must be a multiple of DaxAlignment. The resulting partition then is size - HeaderSize large.

Depending on the filesystem, additional constraints apply for the size of that partition. A multiple of BlockSize should be safe.

The resulting file will have "size" bytes in use. If bytes is zero, then the image file will be made as large as possible.

The result will be sparse, i.e. empty parts are not actually written yet, but they will be allocated, so there is no risk later on that attempting to write fails due to lack of space.

Types

type Bytes

type Bytes int64

type FsType

type FsType string

const (
	Ext4 FsType = "ext4"
	Xfs  FsType = "xfs"
)