Crate devicemapper

Low-level devicemapper configuration of the running kernel.

Overview

Linux’s devicemapper allows the creation of block devices whose storage is mapped to other block devices in useful ways, either by changing the location of its data blocks, or performing some operation on the data itself. This is a low-level facility that is used by higher-level volume managers such as LVM2. Uses may include:

• Dividing a large block device into smaller logical volumes (dm-linear)
• Combining several separate block devices into a single block device with better performance and/or redundancy (dm-raid)
• Encrypting a block device (dm-crypt)
• Performing Copy-on-Write (COW) allocation of a volume’s blocks enabling fast volume cloning and snapshots (dm-thin)
• Configuring a smaller, faster block device to act as a cache for a larger, slower one (dm-cache)
• Verifying the contents of a read-only volume (dm-verity)

Usage

Before they can be used, DM devices must be created using DM::device_create(), have a mapping table loaded using DM::table_load(), and then activated with DM::device_suspend(). (This function is used for both suspending and activating a device.) Once activated, they can be used as a regular block device, including having other DM devices map to them.

Devices have “active” and “inactive” mapping tables. See function descriptions for which table they affect.

Polling for Events

Since DM minor version 37, first available in Linux kernel 4.14, the file descriptor associated with a DM context may be polled for events generated by DM devices.

The fd will indicate POLLIN if any events have occurred on any DM devices since the fd was opened, or since DM::arm_poll() was called. Therefore, in order to determine which DM devices have generated an event, the following usage is required:

1. Create a DM.
2. Call DM::list_devices() and track the event_nrs for any DM devices of interest.
3. poll() on the DM’s file descriptor, obtained by calling DM::file().as_raw_fd().
4. If the fd indicates activity, first clear the event by calling DM::arm_poll(). This must be done before event processing to ensure events are not missed.
5. Process events. Call DM::list_devices() again, and compare event_nr returned by the more recent call with event_nr values from the earlier call. If event_nr differs, an event has occurred on that specific device. Handle the event(s). Update the list of last-seen event_nrs.
6. Optionally loop and re-invoke poll() on the fd to wait for more events.

Modules

IEC

International Electrotechnical Commission Units Standards

errors

Definition for low level error class for core methods !

Structs

Bytes

A type for bytes

CacheDev

DM Cache device

CacheDevPerformance

Cache dev performance data

CacheDevTargetTable

A target table for a cache device.

CacheDevUsage

Cache usage

CacheDevWorkingStatus

Status values of a cache device when it is working

CacheTargetParams

Struct representing params for a cache target

DM

Context needed for communicating with devicemapper.

DataBlocks

A type for data blocks

Device

A struct containing the device’s major and minor numbers

DeviceInfo

Contains information about the device.

DmFlags

Flags used by devicemapper.

DmName

The borrowed version of the DM identifier.

DmNameBuf

The owned version of the DM identifier.

DmOptions

Encapsulates options for device mapper calls

DmUdevFlags

Flags used by devicemapper, see: https://sourceware.org/git/?p=lvm2.git;a=blob;f=libdm/libdevmapper.h#l3627 for complete information about the meaning of the flags.

DmUuid

The borrowed version of the DM identifier.

DmUuidBuf

The owned version of the DM identifier.

FlakeyTargetParams

Target params for flakey target

LinearDev

A DM construct of combined Segments

LinearDevTargetTable

A target table for a linear device. Such a table allows flakey targets as well as linear targets.

LinearTargetParams

Struct representing params for a linear target

MetaBlocks

A type for meta blocks

Sectors

A type for sectors

TargetLine

One line of a device mapper table.

TargetType

The borrowed version of the DM identifier.

TargetTypeBuf

The owned version of the DM identifier.

ThinDev

DM construct for a thin block device

ThinDevId

A thindev id is a 24 bit number, i.e., its bit width is not a power of 2.

ThinDevTargetTable

A target table for a thin device.

ThinDevWorkingStatus

Status values for a thin device that is working

ThinPoolDev

DM construct to contain thin provisioned devices

ThinPoolDevTargetTable

A target table for a thin pool device.

ThinPoolTargetParams

Struct representing params for a thin pool target

ThinPoolUsage

Contains values indicating the thinpool’s used vs total allocations for metadata and data blocks.

ThinPoolWorkingStatus

Status of a working thin pool, i.e, one that does not have status Fail

ThinTargetParams

Struct representing params for a thin target

Enums

CacheDevStatus

Return type of CacheDev::status()

DevId

Used as a parameter for functions that take either a Device name or a Device UUID.

DmError

Super error type, with constructors distinguishing outer errors from core errors.

ErrorEnum

A very simple breakdown of outer layer errors.

LinearDevTargetParams

Target params for linear dev. These are either flakey or linear.

ThinPoolNoSpacePolicy

Policy if no space on device

ThinPoolStatus

Top-level thinpool status that indicates if it is working or failed.

ThinPoolStatusSummary

Indicates if a working thinpool is working optimally, or is experiencing a non-fatal error condition.

ThinStatus

Thin device status.

Constants

MAX_CACHE_BLOCK_SIZE

The maximum size recommended in the docs for a cache block.

MIN_CACHE_BLOCK_SIZE

The minimum size recommended in the docs for a cache block.

SECTOR_SIZE

disk sector size in bytes

Traits

DmDevice

A trait capturing some shared properties of DM devices.

TargetParams

The trait for properties of the params string of TargetType

TargetTable

Manages a target’s table

Functions

device_exists

Check if a device of the given name exists.

devnode_to_devno

Get a device number from a device node. Return None if the device is not a block device; devicemapper is not interested in other sorts of devices. Return None if the device appears not to exist.

message

Send a message that expects no reply to target device.

Type Aliases

DmResult

return result for DM functions