devicemapper/
lib.rs

1// This Source Code Form is subject to the terms of the Mozilla Public
2// License, v. 2.0. If a copy of the MPL was not distributed with this
3// file, You can obtain one at http://mozilla.org/MPL/2.0/.
4
5//! Low-level devicemapper configuration of the running kernel.
6//!
7//! # Overview
8//!
9//! Linux's devicemapper allows the creation of block devices whose
10//! storage is mapped to other block devices in useful ways, either by
11//! changing the location of its data blocks, or performing some
12//! operation on the data itself. This is a low-level facility that is
13//! used by higher-level volume managers such as LVM2. Uses may
14//! include:
15//!
16//! * Dividing a large block device into smaller logical volumes (dm-linear)
17//! * Combining several separate block devices into a single block
18//!   device with better performance and/or redundancy (dm-raid)
19//! * Encrypting a block device (dm-crypt)
20//! * Performing Copy-on-Write (COW) allocation of a volume's blocks
21//!   enabling fast volume cloning and snapshots (dm-thin)
22//! * Configuring a smaller, faster block device to act as a cache for a
23//!   larger, slower one (dm-cache)
24//! * Verifying the contents of a read-only volume (dm-verity)
25//!
26//! # Usage
27//!
28//! Before they can be used, DM devices must be created using
29//! `DM::device_create()`, have a mapping table loaded using
30//! `DM::table_load()`, and then activated with
31//! `DM::device_suspend()`. (This function is used for both suspending
32//! and activating a device.) Once activated, they can be used as a
33//! regular block device, including having other DM devices map to
34//! them.
35//!
36//! Devices have "active" and "inactive" mapping tables. See function
37//! descriptions for which table they affect.
38//!
39//! # Polling for Events
40//!
41//! Since DM minor version 37, first available in Linux kernel 4.14, the file
42//! descriptor associated with a `DM` context may be polled for events generated by
43//! DM devices.
44//!
45//! The fd will indicate POLLIN if any events have occurred on any DM devices
46//! since the fd was opened, or since `DM::arm_poll()` was called. Therefore,
47//! in order to determine which DM devices have generated an event, the
48//! following usage is required:
49//!
50//! 1. Create a `DM`.
51//! 2. Call `DM::list_devices()` and track the `event_nr`s for any DM devices
52//!    of interest.
53//! 3. `poll()` on the `DM`'s file descriptor, obtained by calling
54//!    `DM::file().as_raw_fd()`.
55//! 4. If the fd indicates activity, first clear the event by calling
56//!    `DM::arm_poll()`.  This must be done before event processing to ensure
57//!    events are not missed.
58//! 5. Process events. Call `DM::list_devices()` again, and compare `event_nr`
59//!    returned by the more recent call with `event_nr` values from the earlier
60//!    call.  If `event_nr` differs, an event has occurred on that specific
61//!    device. Handle the event(s). Update the list of last-seen `event_nr`s.
62//! 6. Optionally loop and re-invoke `poll()` on the fd to wait for more
63//!    events.
64
65#![allow(clippy::doc_markdown)]
66#![warn(missing_docs)]
67
68#[macro_use]
69extern crate bitflags;
70#[macro_use]
71extern crate nix;
72#[macro_use]
73extern crate log;
74
75/// Range macros
76#[macro_use]
77mod range_macros;
78/// ID macros
79#[macro_use]
80mod id_macros;
81/// shared constants
82mod consts;
83/// core functionality
84mod core;
85/// Macros shared by device mapper devices.
86#[macro_use]
87mod shared_macros;
88/// cachedev
89mod cachedev;
90/// functions to create continuous linear space given device segments
91mod lineardev;
92/// return results container
93mod result;
94/// functionality shared between devices
95mod shared;
96/// allocate a device from a pool
97mod thindev;
98/// the id the pool uses to track its devices
99mod thindevid;
100/// thinpooldev is shared space for  other thin provisioned devices to use
101mod thinpooldev;
102/// representation of units used by the outer layers
103mod units;
104
105#[cfg(test)]
106mod testing;
107
108/// More useful test output for match cases
109#[cfg(test)]
110#[macro_use]
111extern crate assert_matches;
112
113pub use crate::{
114    cachedev::{
115        CacheDev, CacheDevPerformance, CacheDevStatus, CacheDevTargetTable, CacheDevUsage,
116        CacheDevWorkingStatus, CacheTargetParams, MAX_CACHE_BLOCK_SIZE, MIN_CACHE_BLOCK_SIZE,
117    },
118    consts::IEC,
119    core::{
120        devnode_to_devno, errors, DevId, Device, DeviceInfo, DmFlags, DmName, DmNameBuf, DmOptions,
121        DmUdevFlags, DmUuid, DmUuidBuf, DM,
122    },
123    lineardev::{
124        FlakeyFeatureArg, FlakeyTargetParams, LinearDev, LinearDevTargetParams,
125        LinearDevTargetTable, LinearTargetParams,
126    },
127    result::{DmError, DmResult, ErrorEnum},
128    shared::{
129        device_exists, message, DmDevice, TargetLine, TargetParams, TargetTable, TargetType,
130        TargetTypeBuf,
131    },
132    thindev::{ThinDev, ThinDevTargetTable, ThinDevWorkingStatus, ThinStatus, ThinTargetParams},
133    thindevid::ThinDevId,
134    thinpooldev::{
135        ThinPoolDev, ThinPoolDevTargetTable, ThinPoolNoSpacePolicy, ThinPoolStatus,
136        ThinPoolStatusSummary, ThinPoolTargetParams, ThinPoolUsage, ThinPoolWorkingStatus,
137    },
138    units::{Bytes, DataBlocks, MetaBlocks, Sectors, SECTOR_SIZE},
139};
devicemapper/lib.rs

devicemapper/
lib.rs
