1
0
mirror of git://sourceware.org/git/lvm2.git synced 2024-10-05 12:19:48 +03:00
lvm2/libdm/libdevmapper.h

3775 lines
133 KiB
C
Raw Permalink Normal View History

/*
2004-03-30 23:08:57 +04:00
* Copyright (C) 2001-2004 Sistina Software, Inc. All rights reserved.
* Copyright (C) 2004-2017 Red Hat, Inc. All rights reserved.
2015-08-05 07:21:58 +03:00
* Copyright (C) 2006 Rackable Systems All rights reserved.
*
2004-03-30 23:08:57 +04:00
* This file is part of the device-mapper userspace tools.
*
* This copyrighted material is made available to anyone wishing to use,
* modify, copy, or redistribute it subject to the terms and conditions
* of the GNU Lesser General Public License v.2.1.
*
* You should have received a copy of the GNU Lesser General Public License
* along with this program; if not, write to the Free Software Foundation,
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
*/
#ifndef LIB_DEVICE_MAPPER_H
#define LIB_DEVICE_MAPPER_H
#include <inttypes.h>
2006-08-21 16:52:39 +04:00
#include <stdarg.h>
#include <sys/types.h>
#include <sys/stat.h>
#ifdef __linux__
# include <linux/types.h>
#endif
2005-10-17 02:57:20 +04:00
#include <limits.h>
#include <string.h>
#include <stdlib.h>
#include <stdio.h>
#include <stddef.h> /* offsetof */
2005-10-17 02:57:20 +04:00
#ifndef __GNUC__
# define __typeof__ typeof
#endif
/* Macros to make string defines */
#define DM_TO_STRING_EXP(A) #A
#define DM_TO_STRING(A) DM_TO_STRING_EXP(A)
#define DM_ARRAY_SIZE(a) (sizeof(a) / sizeof((a)[0]))
#ifdef __cplusplus
extern "C" {
#endif
2005-11-09 17:10:50 +03:00
/*****************************************************************
* The first section of this file provides direct access to the
* individual device-mapper ioctls. Since it is quite laborious to
* build the ioctl arguments for the device-mapper, people are
* encouraged to use this library.
2005-11-09 17:10:50 +03:00
****************************************************************/
/*
* The library user may wish to register their own
* logging function. By default errors go to stderr.
* Use dm_log_with_errno_init(NULL) to restore the default log fn.
* Error messages may have a non-zero errno.
* Debug messages may have a non-zero class.
* Aborts on internal error when env DM_ABORT_ON_INTERNAL_ERRORS is 1
*/
typedef void (*dm_log_with_errno_fn) (int level, const char *file, int line,
int dm_errno_or_class, const char *f, ...)
__attribute__ ((format(printf, 5, 6)));
void dm_log_with_errno_init(dm_log_with_errno_fn fn);
void dm_log_init_verbose(int level);
/*
* Original version of this function.
* dm_errno is set to 0.
*
* Deprecated: Use the _with_errno_ versions above instead.
*/
typedef void (*dm_log_fn) (int level, const char *file, int line,
const char *f, ...)
__attribute__ ((format(printf, 4, 5)));
void dm_log_init(dm_log_fn fn);
/*
* For backward-compatibility, indicate that dm_log_init() was used
* to set a non-default value of dm_log().
*/
int dm_log_is_non_default(void);
/*
* Number of devices currently in suspended state (via the library).
*/
int dm_get_suspended_counter(void);
enum {
DM_DEVICE_CREATE,
DM_DEVICE_RELOAD,
DM_DEVICE_REMOVE,
DM_DEVICE_REMOVE_ALL,
DM_DEVICE_SUSPEND,
DM_DEVICE_RESUME,
DM_DEVICE_INFO,
DM_DEVICE_DEPS,
DM_DEVICE_RENAME,
DM_DEVICE_VERSION,
DM_DEVICE_STATUS,
DM_DEVICE_TABLE,
2003-07-02 01:20:58 +04:00
DM_DEVICE_WAITEVENT,
DM_DEVICE_LIST,
2003-11-13 16:14:28 +03:00
DM_DEVICE_CLEAR,
DM_DEVICE_MKNODES,
2004-06-09 00:34:40 +04:00
DM_DEVICE_LIST_VERSIONS,
DM_DEVICE_TARGET_MSG,
DM_DEVICE_SET_GEOMETRY,
DM_DEVICE_ARM_POLL,
DM_DEVICE_GET_TARGET_VERSION
};
/*
* You will need to build a struct dm_task for
* each ioctl command you want to execute.
*/
struct dm_pool;
struct dm_task;
struct dm_timestamp;
struct dm_task *dm_task_create(int type);
void dm_task_destroy(struct dm_task *dmt);
int dm_task_set_name(struct dm_task *dmt, const char *name);
int dm_task_set_uuid(struct dm_task *dmt, const char *uuid);
/*
* Retrieve attributes after an info.
*/
struct dm_info {
int exists;
int suspended;
2003-07-02 01:20:58 +04:00
int live_table;
int inactive_table;
int32_t open_count;
2003-04-29 15:34:23 +04:00
uint32_t event_nr;
uint32_t major;
uint32_t minor; /* minor device number */
int read_only; /* 0:read-write; 1:read-only */
int32_t target_count;
int deferred_remove;
int internal_suspend;
};
struct dm_deps {
uint32_t count;
uint32_t filler;
uint64_t device[];
};
2003-07-02 01:20:58 +04:00
struct dm_names {
uint64_t dev;
uint32_t next; /* Offset to next struct from start of this struct */
char name[];
2003-07-02 01:20:58 +04:00
};
struct dm_versions {
uint32_t next; /* Offset to next struct from start of this struct */
uint32_t version[3];
char name[];
};
int dm_get_library_version(char *version, size_t size);
int dm_task_get_driver_version(struct dm_task *dmt, char *version, size_t size);
int dm_task_get_info(struct dm_task *dmt, struct dm_info *dmi);
/*
* This function returns dm device's UUID based on the value
* of the mangling mode set during preceding dm_task_run call:
2012-10-15 17:40:37 +04:00
* - unmangled UUID for DM_STRING_MANGLING_{AUTO, HEX},
* - UUID without any changes for DM_STRING_MANGLING_NONE.
*
2012-10-15 17:40:37 +04:00
* To get mangled or unmangled form of the UUID directly, use
* dm_task_get_uuid_mangled or dm_task_get_uuid_unmangled function.
*/
const char *dm_task_get_uuid(const struct dm_task *dmt);
struct dm_deps *dm_task_get_deps(struct dm_task *dmt);
struct dm_versions *dm_task_get_versions(struct dm_task *dmt);
const char *dm_task_get_message_response(struct dm_task *dmt);
/*
* These functions return device-mapper names based on the value
* of the mangling mode set during preceding dm_task_run call:
* - unmangled name for DM_STRING_MANGLING_{AUTO, HEX},
* - name without any changes for DM_STRING_MANGLING_NONE.
*
* To get mangled or unmangled form of the name directly, use
* dm_task_get_name_mangled or dm_task_get_name_unmangled function.
*/
const char *dm_task_get_name(const struct dm_task *dmt);
struct dm_names *dm_task_get_names(struct dm_task *dmt);
int dm_task_set_ro(struct dm_task *dmt);
int dm_task_set_newname(struct dm_task *dmt, const char *newname);
int dm_task_set_newuuid(struct dm_task *dmt, const char *newuuid);
int dm_task_set_minor(struct dm_task *dmt, int minor);
2003-04-02 23:03:00 +04:00
int dm_task_set_major(struct dm_task *dmt, int major);
int dm_task_set_major_minor(struct dm_task *dmt, int major, int minor, int allow_default_major_fallback);
int dm_task_set_uid(struct dm_task *dmt, uid_t uid);
int dm_task_set_gid(struct dm_task *dmt, gid_t gid);
int dm_task_set_mode(struct dm_task *dmt, mode_t mode);
/* See also description for DM_UDEV_DISABLE_LIBRARY_FALLBACK flag! */
int dm_task_set_cookie(struct dm_task *dmt, uint32_t *cookie, uint16_t flags);
2003-04-29 15:34:23 +04:00
int dm_task_set_event_nr(struct dm_task *dmt, uint32_t event_nr);
int dm_task_set_geometry(struct dm_task *dmt, const char *cylinders, const char *heads, const char *sectors, const char *start);
2004-06-09 00:34:40 +04:00
int dm_task_set_message(struct dm_task *dmt, const char *message);
int dm_task_set_sector(struct dm_task *dmt, uint64_t sector);
int dm_task_no_flush(struct dm_task *dmt);
int dm_task_no_open_count(struct dm_task *dmt);
int dm_task_skip_lockfs(struct dm_task *dmt);
int dm_task_query_inactive_table(struct dm_task *dmt);
int dm_task_suppress_identical_reload(struct dm_task *dmt);
int dm_task_secure_data(struct dm_task *dmt);
int dm_task_retry_remove(struct dm_task *dmt);
int dm_task_deferred_remove(struct dm_task *dmt);
int dm_task_ima_measurement(struct dm_task *dmt);
/*
* Record timestamp immediately after the ioctl returns.
*/
int dm_task_set_record_timestamp(struct dm_task *dmt);
struct dm_timestamp *dm_task_get_ioctl_timestamp(struct dm_task *dmt);
/*
* Enable checks for common mistakes such as issuing ioctls in an unsafe order.
*/
int dm_task_enable_checks(struct dm_task *dmt);
typedef enum dm_add_node_e {
DM_ADD_NODE_ON_RESUME, /* add /dev/mapper node with dmsetup resume */
DM_ADD_NODE_ON_CREATE /* add /dev/mapper node with dmsetup create */
} dm_add_node_t;
int dm_task_set_add_node(struct dm_task *dmt, dm_add_node_t add_node);
/*
* Control read_ahead.
*/
#define DM_READ_AHEAD_AUTO UINT32_MAX /* Use kernel default readahead */
#define DM_READ_AHEAD_NONE 0 /* Disable readahead */
#define DM_READ_AHEAD_MINIMUM_FLAG 0x1 /* Value supplied is minimum */
2007-12-05 19:28:19 +03:00
/*
* Read ahead is set with DM_DEVICE_CREATE with a table or DM_DEVICE_RESUME.
*/
int dm_task_set_read_ahead(struct dm_task *dmt, uint32_t read_ahead,
uint32_t read_ahead_flags);
2007-11-30 17:59:57 +03:00
uint32_t dm_task_get_read_ahead(const struct dm_task *dmt,
uint32_t *read_ahead);
/*
* Use these to prepare for a create or reload.
*/
int dm_task_add_target(struct dm_task *dmt,
uint64_t start,
uint64_t size, const char *ttype, const char *params);
2003-07-02 01:20:58 +04:00
/*
* Format major/minor numbers correctly for input to driver.
2003-07-02 01:20:58 +04:00
*/
#define DM_FORMAT_DEV_BUFSIZE 13 /* Minimum bufsize to handle worst case. */
2003-07-02 01:20:58 +04:00
int dm_format_dev(char *buf, int bufsize, uint32_t dev_major, uint32_t dev_minor);
/* Use this to retrieve target information returned from a STATUS call */
void *dm_get_next_target(struct dm_task *dmt,
void *next, uint64_t *start, uint64_t *length,
char **target_type, char **params);
/*
* Following dm_get_status_* functions will allocate appropriate status structure
* from passed mempool together with the necessary character arrays.
* Destroying the mempool will release all associated allocation.
*/
/* Parse params from STATUS call for mirror target */
typedef enum dm_status_mirror_health_e {
DM_STATUS_MIRROR_ALIVE = 'A',/* No failures */
DM_STATUS_MIRROR_FLUSH_FAILED = 'F',/* Mirror out-of-sync */
DM_STATUS_MIRROR_WRITE_FAILED = 'D',/* Mirror out-of-sync */
DM_STATUS_MIRROR_SYNC_FAILED = 'S',/* Mirror out-of-sync */
DM_STATUS_MIRROR_READ_FAILED = 'R',/* Mirror data unaffected */
DM_STATUS_MIRROR_UNCLASSIFIED = 'U' /* Bug */
} dm_status_mirror_health_t;
struct dm_status_mirror {
uint64_t total_regions;
uint64_t insync_regions;
uint32_t dev_count; /* # of devs[] elements (<= 8) */
struct dm_dev_leg_health_s {
dm_status_mirror_health_t health;
uint32_t major;
uint32_t minor;
} *devs; /* array with individual legs */
const char *log_type; /* core, disk,.... */
uint32_t log_count; /* # of logs[] elements */
struct dm_dev_log_health_s {
dm_status_mirror_health_t health;
uint32_t major;
uint32_t minor;
} *logs; /* array with individual logs */
};
int dm_get_status_mirror(struct dm_pool *mem, const char *params,
struct dm_status_mirror **status);
/* Parse params from STATUS call for raid target */
struct dm_status_raid {
uint64_t reserved;
uint64_t total_regions; /* sectors */
uint64_t insync_regions; /* sectors */
uint64_t mismatch_count;
uint32_t dev_count;
char *raid_type;
/* A - alive, a - alive not in-sync, D - dead/failed */
char *dev_health;
/* idle, frozen, resync, recover, check, repair */
char *sync_action;
lvconvert: add infrastructure for RaidLV reshaping support In order to support striped raid5/6/10 LV reshaping (change of LV type, stripesize or number of legs), this patch introduces infrastructure prerequisites to be used by raid_manip.c extensions in followup patches. This base is needed for allocation of out-of-place reshape space required by the MD raid personalities to avoid writing over data in-place when reading off the current RAID layout or number of legs and writing out the new layout or to a different number of legs (i.e. restripe) Changes: - add members reshape_len to 'struct lv_segment' to store out-of-place reshape length per component rimage - add member data_copies to struct lv_segment to support more than 2 raid10 data copies - make alloc_lv_segment() aware of both reshape_len and data_copies - adjust all alloc_lv_segment() callers to the new API - add functions to retrieve the current data offset (needed for out-of-place reshaping space allocation) and the devices count from the kernel - make libdm deptree code aware of reshape_len - add LV flags for disk add/remove reshaping - support import/export of the new 'struct lv_segment' members - enhance lv_extend/_lv_reduce to cope with reshape_len - add seg_is_*/segtype_is_* macros related to reshaping - add target version check for reshaping - grow rebuilds/writemostly bitmaps to 246 bit to support kernel maximal - enhance libdm deptree code to support data_offset (out-of-place reshaping) and delta_disk (legs add/remove reshaping) target arguments Related: rhbz834579 Related: rhbz1191935 Related: rhbz1191978
2017-02-24 02:50:00 +03:00
uint64_t data_offset; /* RAID out-of-place reshaping */
};
int dm_get_status_raid(struct dm_pool *mem, const char *params,
struct dm_status_raid **status);
/* Parse params from STATUS call for cache target */
struct dm_status_cache {
uint64_t version; /* zero for now */
uint32_t metadata_block_size; /* in 512B sectors */
uint32_t block_size; /* AKA 'chunk_size' */
uint64_t metadata_used_blocks;
uint64_t metadata_total_blocks;
uint64_t used_blocks;
uint64_t dirty_blocks;
uint64_t total_blocks;
uint64_t read_hits;
uint64_t read_misses;
uint64_t write_hits;
uint64_t write_misses;
uint64_t demotions;
uint64_t promotions;
uint64_t feature_flags; /* DM_CACHE_FEATURE_? */
int core_argc;
char **core_argv;
char *policy_name;
int policy_argc;
char **policy_argv;
unsigned error : 1; /* detected error (switches to fail soon) */
unsigned fail : 1; /* all I/O fails */
unsigned needs_check : 1; /* metadata needs check */
unsigned read_only : 1; /* metadata may not be changed */
uint32_t reserved : 28;
};
int dm_get_status_cache(struct dm_pool *mem, const char *params,
struct dm_status_cache **status);
/*
* Parse params from STATUS call for snapshot target
*
* Snapshot target's format:
* <= 1.7.0: <used_sectors>/<total_sectors>
* >= 1.8.0: <used_sectors>/<total_sectors> <metadata_sectors>
*/
struct dm_status_snapshot {
uint64_t used_sectors; /* in 512b units */
uint64_t total_sectors;
uint64_t metadata_sectors;
unsigned has_metadata_sectors : 1; /* set when metadata_sectors is present */
unsigned invalid : 1; /* set when snapshot is invalidated */
unsigned merge_failed : 1; /* set when snapshot merge failed */
unsigned overflow : 1; /* set when snapshot overflows */
};
int dm_get_status_snapshot(struct dm_pool *mem, const char *params,
struct dm_status_snapshot **status);
/* Parse params from STATUS call for thin_pool target */
typedef enum dm_thin_discards_e {
DM_THIN_DISCARDS_IGNORE,
DM_THIN_DISCARDS_NO_PASSDOWN,
DM_THIN_DISCARDS_PASSDOWN
} dm_thin_discards_t;
struct dm_status_thin_pool {
uint64_t transaction_id;
uint64_t used_metadata_blocks;
uint64_t total_metadata_blocks;
uint64_t used_data_blocks;
uint64_t total_data_blocks;
uint64_t held_metadata_root;
uint32_t read_only; /* metadata may not be changed */
dm_thin_discards_t discards;
uint32_t fail : 1; /* all I/O fails */
uint32_t error_if_no_space : 1; /* otherwise queue_if_no_space */
uint32_t out_of_data_space : 1; /* metadata may be changed, but data may not be allocated (no rw) */
uint32_t needs_check : 1; /* metadata needs check */
uint32_t error : 1; /* detected error (switches to fail soon) */
uint32_t reserved : 27;
};
int dm_get_status_thin_pool(struct dm_pool *mem, const char *params,
struct dm_status_thin_pool **status);
/* Parse params from STATUS call for thin target */
struct dm_status_thin {
uint64_t mapped_sectors;
uint64_t highest_mapped_sector;
uint32_t fail : 1; /* Thin volume fails I/O */
uint32_t reserved : 31;
};
int dm_get_status_thin(struct dm_pool *mem, const char *params,
struct dm_status_thin **status);
/*
* device-mapper statistics support
*/
/*
* Statistics handle.
*
* Operations on dm_stats objects include managing statistics regions
* and obtaining and manipulating current counter values from the
* kernel. Methods are provided to return basic count values and to
* derive time-based metrics when a suitable interval estimate is
* provided.
*
* Internally the dm_stats handle contains a pointer to a table of one
* or more dm_stats_region objects representing the regions registered
* with the dm_stats_create_region() method. These in turn point to a
* table of one or more dm_stats_counters objects containing the
* counter sets for each defined area within the region:
*
* dm_stats->dm_stats_region[nr_regions]->dm_stats_counters[nr_areas]
*
* This structure is private to the library and may change in future
* versions: all users should make use of the public interface and treat
* the dm_stats type as an opaque handle.
*
* Regions and counter sets are stored in order of increasing region_id.
* Depending on region specifications and the sequence of create and
* delete operations this may not correspond to increasing sector
* number: users of the library should not assume that this is the case
* unless region creation is deliberately managed to ensure this (by
* always creating regions in strict order of ascending sector address).
*
* Regions may also overlap so the same sector range may be included in
* more than one region or area: applications should be prepared to deal
* with this or manage regions such that it does not occur.
*/
struct dm_stats;
libdm: add latency histogram support Add support for creating, parsing, and reporting dm-stats latency histograms on kernels that support precise_timestamps. Histograms are specified as a series of time values that give the boundaries of the bins into which I/O counts accumulate (with implicit lower and upper bounds on the first and last bins). A new type, struct dm_histogram, is introduced to represent histogram values and bin boundaries. The boundary values may be given as either a string of values (with optional unit suffixes) or as a zero terminated array of uint64_t values expressing boundary times in nanoseconds. A new bounds argument is added to dm_stats_create_region() which accepts a pointer to a struct dm_histogram initialised with bounds values. Histogram data associated with a region is parsed during a call to dm_stats_populate() and used to build a table of histogram values that are pointed to from the containing area's counter set. The histogram for a specified area may then be obtained and interogated for values and properties. This relies on kernel support to provide the boundary values in a @stats_list response: this will be present in 4.3 and 4.2-stable. A check for a minimum driver version of 4.33.0 is implemented to ensure that this is present (4.32.0 has the necessary precise_timestamps and histogram features but is unable to report these via @stats_list). Access methods are provided to retrieve histogram values and bounds as well as simple string representations of the counts and bin boundaries. Methods are also available to return the total count for a histogram and the relative value (as a dm_percent_t) of a specified bin.
2015-08-19 22:39:10 +03:00
/*
* Histogram handle.
*
* A histogram object represents the latency histogram values and bin
* boundaries of the histogram associated with a particular area.
*
* Operations on the handle allow the number of bins, bin boundaries,
* counts and relative proportions to be obtained as well as the
* conversion of a histogram or its bounds to a compact string
* representation.
*/
struct dm_histogram;
/*
* Allocate a dm_stats handle to use for subsequent device-mapper
* statistics operations. A program_id may be specified and will be
* used by default for subsequent operations on this handle.
*
* If program_id is NULL or the empty string a program_id will be
* automatically set to the value contained in /proc/self/comm.
*/
struct dm_stats *dm_stats_create(const char *program_id);
/*
* Bind a dm_stats handle to the specified device major and minor
* values. Any previous binding is cleared and any preexisting counter
* data contained in the handle is released.
*/
int dm_stats_bind_devno(struct dm_stats *dms, int major, int minor);
/*
* Bind a dm_stats handle to the specified device name.
* Any previous binding is cleared and any preexisting counter
* data contained in the handle is released.
*/
int dm_stats_bind_name(struct dm_stats *dms, const char *name);
/*
* Bind a dm_stats handle to the specified device UUID.
* Any previous binding is cleared and any preexisting counter
* data contained in the handle is released.
*/
int dm_stats_bind_uuid(struct dm_stats *dms, const char *uuid);
/*
* Bind a dm_stats handle to the device backing the file referenced
* by the specified file descriptor.
*
* File descriptor fd must reference a regular file, open for reading,
* in a local file system, backed by a device-mapper device, that
* supports the FIEMAP ioctl, and that returns data describing the
* physical location of extents.
*/
int dm_stats_bind_from_fd(struct dm_stats *dms, int fd);
/*
* Test whether the running kernel supports the precise_timestamps
* feature. Presence of this feature also implies histogram support.
* The library will check this call internally and fails any attempt
* to use nanosecond counters or histograms on kernels that fail to
* meet this check.
*/
int dm_message_supports_precise_timestamps(void);
/*
* Precise timestamps and histogram support.
*
libdm: add latency histogram support Add support for creating, parsing, and reporting dm-stats latency histograms on kernels that support precise_timestamps. Histograms are specified as a series of time values that give the boundaries of the bins into which I/O counts accumulate (with implicit lower and upper bounds on the first and last bins). A new type, struct dm_histogram, is introduced to represent histogram values and bin boundaries. The boundary values may be given as either a string of values (with optional unit suffixes) or as a zero terminated array of uint64_t values expressing boundary times in nanoseconds. A new bounds argument is added to dm_stats_create_region() which accepts a pointer to a struct dm_histogram initialised with bounds values. Histogram data associated with a region is parsed during a call to dm_stats_populate() and used to build a table of histogram values that are pointed to from the containing area's counter set. The histogram for a specified area may then be obtained and interogated for values and properties. This relies on kernel support to provide the boundary values in a @stats_list response: this will be present in 4.3 and 4.2-stable. A check for a minimum driver version of 4.33.0 is implemented to ensure that this is present (4.32.0 has the necessary precise_timestamps and histogram features but is unable to report these via @stats_list). Access methods are provided to retrieve histogram values and bounds as well as simple string representations of the counts and bin boundaries. Methods are also available to return the total count for a histogram and the relative value (as a dm_percent_t) of a specified bin.
2015-08-19 22:39:10 +03:00
* Test for the presence of precise_timestamps and histogram support.
*/
int dm_stats_driver_supports_precise(void);
libdm: add latency histogram support Add support for creating, parsing, and reporting dm-stats latency histograms on kernels that support precise_timestamps. Histograms are specified as a series of time values that give the boundaries of the bins into which I/O counts accumulate (with implicit lower and upper bounds on the first and last bins). A new type, struct dm_histogram, is introduced to represent histogram values and bin boundaries. The boundary values may be given as either a string of values (with optional unit suffixes) or as a zero terminated array of uint64_t values expressing boundary times in nanoseconds. A new bounds argument is added to dm_stats_create_region() which accepts a pointer to a struct dm_histogram initialised with bounds values. Histogram data associated with a region is parsed during a call to dm_stats_populate() and used to build a table of histogram values that are pointed to from the containing area's counter set. The histogram for a specified area may then be obtained and interogated for values and properties. This relies on kernel support to provide the boundary values in a @stats_list response: this will be present in 4.3 and 4.2-stable. A check for a minimum driver version of 4.33.0 is implemented to ensure that this is present (4.32.0 has the necessary precise_timestamps and histogram features but is unable to report these via @stats_list). Access methods are provided to retrieve histogram values and bounds as well as simple string representations of the counts and bin boundaries. Methods are also available to return the total count for a histogram and the relative value (as a dm_percent_t) of a specified bin.
2015-08-19 22:39:10 +03:00
int dm_stats_driver_supports_histogram(void);
/*
* Returns 1 if the specified region has the precise_timestamps feature
* enabled (i.e. produces nanosecond-precision counter values) or 0 for
* a region using the default millisecond precision.
*/
int dm_stats_get_region_precise_timestamps(const struct dm_stats *dms,
uint64_t region_id);
/*
* Returns 1 if the region at the current cursor location has the
* precise_timestamps feature enabled (i.e. produces
* nanosecond-precision counter values) or 0 for a region using the
* default millisecond precision.
*/
int dm_stats_get_current_region_precise_timestamps(const struct dm_stats *dms);
#define DM_STATS_ALL_PROGRAMS ""
/*
* Parse the response from a @stats_list message. dm_stats_list will
* allocate the necessary dm_stats and dm_stats region structures from
* the embedded dm_pool. No counter data will be obtained (the counters
* members of dm_stats_region objects are set to NULL).
*
* A program_id may optionally be supplied; if the argument is non-NULL
* only regions with a matching program_id value will be considered. If
* the argument is NULL then the default program_id associated with the
* dm_stats handle will be used. Passing the special value
* DM_STATS_ALL_PROGRAMS will cause all regions to be queried
* regardless of region program_id.
*/
int dm_stats_list(struct dm_stats *dms, const char *program_id);
#define DM_STATS_REGIONS_ALL UINT64_MAX
/*
* Populate a dm_stats object with statistics for one or more regions of
* the specified device.
*
* A program_id may optionally be supplied; if the argument is non-NULL
* only regions with a matching program_id value will be considered. If
* the argument is NULL then the default program_id associated with the
* dm_stats handle will be used. Passing the special value
* DM_STATS_ALL_PROGRAMS will cause all regions to be queried
* regardless of region program_id.
*
* Passing the special value DM_STATS_REGIONS_ALL as the region_id
* argument will attempt to retrieve all regions selected by the
* program_id argument.
*
* If region_id is used to request a single region_id to be populated
* the program_id is ignored.
*/
int dm_stats_populate(struct dm_stats *dms, const char *program_id,
uint64_t region_id);
/*
* Create a new statistics region on the device bound to dms.
*
* start and len specify the region start and length in 512b sectors.
* Passing zero for both start and len will create a region spanning
* the entire device.
*
* Step determines how to subdivide the region into discrete counter
* sets: a positive value specifies the size of areas into which the
* region should be split while a negative value will split the region
* into a number of areas equal to the absolute value of step:
*
* - a region with one area spanning the entire device:
*
* dm_stats_create_region(dms, 0, 0, -1, p, a);
*
* - a region with areas of 1MiB:
*
* dm_stats_create_region(dms, 0, 0, 1 << 11, p, a);
*
* - one 1MiB region starting at 1024 sectors with two areas:
*
* dm_stats_create_region(dms, 1024, 1 << 11, -2, p, a);
*
* If precise is non-zero attempt to create a region with nanosecond
* precision counters using the kernel precise_timestamps feature.
*
libdm: add latency histogram support Add support for creating, parsing, and reporting dm-stats latency histograms on kernels that support precise_timestamps. Histograms are specified as a series of time values that give the boundaries of the bins into which I/O counts accumulate (with implicit lower and upper bounds on the first and last bins). A new type, struct dm_histogram, is introduced to represent histogram values and bin boundaries. The boundary values may be given as either a string of values (with optional unit suffixes) or as a zero terminated array of uint64_t values expressing boundary times in nanoseconds. A new bounds argument is added to dm_stats_create_region() which accepts a pointer to a struct dm_histogram initialised with bounds values. Histogram data associated with a region is parsed during a call to dm_stats_populate() and used to build a table of histogram values that are pointed to from the containing area's counter set. The histogram for a specified area may then be obtained and interogated for values and properties. This relies on kernel support to provide the boundary values in a @stats_list response: this will be present in 4.3 and 4.2-stable. A check for a minimum driver version of 4.33.0 is implemented to ensure that this is present (4.32.0 has the necessary precise_timestamps and histogram features but is unable to report these via @stats_list). Access methods are provided to retrieve histogram values and bounds as well as simple string representations of the counts and bin boundaries. Methods are also available to return the total count for a histogram and the relative value (as a dm_percent_t) of a specified bin.
2015-08-19 22:39:10 +03:00
* precise - A flag to request nanosecond precision counters
* to be used for this region.
*
* histogram_bounds - specify the boundaries of a latency histogram to
* be tracked for the region. The values are expressed as an array of
* uint64_t terminated with a zero. Values must be in order of ascending
* magnitude and specify the upper bounds of successive histogram bins
* in nanoseconds (with an implicit lower bound of zero on the first bin
* and an implicit upper bound of infinity on the final bin). For
* example:
*
* uint64_t bounds_ary[] = { 1000, 2000, 3000, 0 };
*
* Specifies a histogram with four bins: 0-1000ns, 1000-2000ns,
* 2000-3000ns and >3000ns.
*
* The smallest latency value that can be tracked for a region not using
* precise_timestamps is 1ms: attempting to create a region with
* histogram boundaries < 1ms will cause the precise_timestamps feature
* to be enabled for that region automatically if it was not requested
* explicitly.
*
* program_id is an optional string argument that identifies the
* program creating the region. If program_id is NULL or the empty
* string the default program_id stored in the handle will be used.
*
* user_data is an optional string argument that is added to the
* content of the aux_data field stored with the statistics region by
* the kernel.
*
* The library may also use this space internally, for example, to
* store a group descriptor or other metadata: in this case the
* library will strip any internal data fields from the value before
* it is returned via a call to dm_stats_get_region_aux_data().
*
* The user data stored is not accessed by the library or kernel and
* may be used to store an arbitrary data word (embedded whitespace is
* not permitted).
*
* An application using both the library and direct access to the
* @stats_list device-mapper message may see the internal values stored
* in this field by the library. In such cases any string up to and
* including the first '#' in the field must be treated as an opaque
* value and preserved across any external modification of aux_data