Data Structures
struct	arr_int

struct	arr_int_pos

struct	conf_pver_enumerate_st

struct	conf_pver_base_walk_st

struct	m0_conf_pver_info

Macros
#define	M0_TRACE_SUBSYSTEM M0_TRACE_SUBSYS_CONF

#define	CONF_PVER_VECTOR_LOG(owner, fid, vector)

Enumerations
enum	{ MAX_FAILURES_NOT_REACHED, MAX_FAILURES_REACHED, MAX_FAILURES_EXCEEDED }

enum	{ CONF_PVER_FID_MASK = 0x003fffffffffffffULL }

enum	m0_conf_pver_state { M0_CPS_HEALTHY, M0_CPS_DEGRADED, M0_CPS_CRITICAL, M0_CPS_DAMAGED, M0_CPS_NR }

Functions
static int	conf_pver_formulate (const struct m0_conf_pver fpver, struct m0_conf_pver *out)

static int	conf_pver_formulaic_base (const struct m0_conf_pver fpver, struct m0_conf_pver *out)

static int	conf_pver_objvs_count (struct m0_conf_pver base, uint32_t out)

static int	conf_pver_virtual_create (const struct m0_fid fid, struct m0_conf_pver base, const uint32_t allowance, struct arr_int failed, struct m0_conf_pver **out)

static int	conf_pver_failures_cid (struct m0_conf_pver base, uint64_t out)

static void	conf_pver_subtree_delete (struct m0_conf_obj *obj)

static int	conf_pver_recd_build (struct m0_conf_obj obj, void args)

static int	conf_pver_formulaic_find_locked (uint32_t fpver_id, const struct m0_conf_root root, const struct m0_conf_pver *out)

static int	conf_pver_base_recd_update (const struct m0_conf_pool *pool)

static int	conf_pver_find_locked (const struct m0_conf_pool pool, const struct m0_fid pver_to_skip, struct m0_conf_pver **out)

static int	conf_pver_find_by_fid_locked (const struct m0_fid fid, const struct m0_conf_root root, struct m0_conf_pver **out)

M0_INTERNAL int	m0_conf_pver_find (const struct m0_conf_pool pool, const struct m0_fid pver_to_skip, struct m0_conf_pver **out)

M0_INTERNAL int	m0_conf_pver_find_by_fid (const struct m0_fid fid, const struct m0_conf_root root, struct m0_conf_pver **out)

M0_INTERNAL int	m0_conf_pver_formulaic_find (uint32_t fpver_id, const struct m0_conf_root root, const struct m0_conf_pver *out)

M0_INTERNAL int	m0_conf_pver_formulaic_from_virtual (const struct m0_conf_pver virtual, const struct m0_conf_root root, const struct m0_conf_pver **out)

M0_INTERNAL bool	m0_conf_pver_is_clean (const struct m0_conf_pver *pver)

M0_INTERNAL struct m0_fid	m0_conf_pver_fid (enum m0_conf_pver_kind kind, uint64_t container, uint64_t key)

M0_INTERNAL int	m0_conf_pver_fid_read (const struct m0_fid fid, enum m0_conf_pver_kind kind, uint64_t container, uint64_t key)

static struct m0_fid	conf_objv_virtual_fid (struct m0_conf_cache *cache)

M0_INTERNAL unsigned	m0_conf_pver_level (const struct m0_conf_obj *obj)

static int	conf_pver_enumerate_w (struct m0_conf_obj obj, void args)

static void	conf_pver_enumerate (struct m0_conf_pver *pver)

static int	conf_objv_failed_fill (struct m0_conf_obj obj, void args)

static int	conf_pver_base_obj_check (struct m0_conf_obj obj, struct conf_pver_base_walk_st st)

static int	conf_pver_base_w (struct m0_conf_obj obj, void args)

static int	conf_pver_tolerance_adjust (struct m0_conf_pver *pver)

static int	tolerance_failure_cmp (struct m0_conf_pver pv, const uint32_t srecd)

int	m0_conf_pver_status (struct m0_fid fid, struct m0_confc confc, struct m0_conf_pver_info *out_info)

static int	conf_obj_mark_deleted (struct m0_conf_obj obj, void args M0_UNUSED)

Detailed Description

There are 3 kinds of m0_conf_pver objects: actual, formulaic, virtual. Of those only actual and formulaic pvers are 1) linked to the DAG of conf objects, 2) specified in configuration strings (conf.xc files), and 3) exist in memory of confd service.

When HA state of a device[1] changes, flset_hw_obj_failure_cb() updates recd[2] vectors of the actual pvers, whose objvs refer to this device.

[1] Here "device" is m0_conf_{rack,enclosure,controller,disk}, i.e., an object which m0_conf_objv::cv_real may refer to.

[2] "recd" is acronym of "racks, enclosures, controllers, disks".

The attributes of an actual pver:

pvs_recd[]: number of failed (i.e., non-M0_NC_ONLINE) devices at each level of this pver's subtree;
pvs_sitevs;
pvs_attr;
pvs_tolerance[]: this attribute is used by failure domains code (fd/fd.c) and is opaque for conf code.

Formulaic pvers are "leaves" of conf DAG — they do not have a subtree of objvs growing from them. The attributes of a formulaic pver are:

pvf_id: cluster-unique identifier;
pvf_base: reference to the actual pver, the subtree of which is used to create/restore virtual pver subtree;
pvf_allowance[]: number of non-M0_NC_ONLINE objects at each level of base pver subtree.

When configuration consumer needs a pool version, it calls m0_conf_pver_find(), passing m0_conf_pool as an argument. The function searches for a "clean" pver among m0_conf_pool::pl_pvers — the one for which m0_conf_pver_is_clean() returns true.

An actual pver is clean iff all its objvs refer to M0_NC_ONLINE objects.

A formulaic pver is clean iff the number of failed devices at level L of the base pver's subtree is equal to L-th element of the allowance vector, where L = 0..M0_CONF_PVER_LVL_DRIVES.

Clean actual pver is returned (by m0_conf_pver_find()) to user as is. Clean formulaic pver is used to find or create virtual pver; see conf_pver_formulate().

Virtual pver resembles actual pver in that it also has a subtree of objvs growing from it. Differences:

virtual pver is not linked to the DAG of conf objects (i.e., its m0_conf_obj::co_parent is NULL);
virtual pver and its children (m0_conf_dirs and m0_conf_objvs) exist in local conf cache only. They are never transferred over network, are not represented in conf strings, do not exist in confd's conf cache.

Fid of virtual pver contains all the information necessary to restore virtual pver subtree (e.g., in case of node restart). m0_conf_pver_find_by_fid() finds or re-creates virtual pool version by its fid.

To generate or parse m0_conf_pver fid, use m0_conf_pver_fid() and m0_conf_pver_fid_read(), correspondingly.

Design Assumptions

m0_conf_pver_find() assumes that all conf objects of the subtree, originating at ‘pool’ argument, exist in the conf cache and are M0_CS_READY.

m0_conf_pver_find_by_fid() assumes M0_CS_READY-ness of all conf objects, whose type is not m0_conf_{node,process,service,sdev}.

References

See also: doc/formulaic-pvers.org

Macro Definition Documentation

◆ CONF_PVER_VECTOR_LOG

#define CONF_PVER_VECTOR_LOG	(	owner,
		fid,
		vector
	)

Value:

M0_LOG(M0_DEBUG, owner"="FID_F" "#vector"=[%u %u %u %u %u]", fid, \
               vector[M0_CONF_PVER_LVL_SITES],                         \
               vector[M0_CONF_PVER_LVL_RACKS],                         \
               vector[M0_CONF_PVER_LVL_ENCLS],                         \
               vector[M0_CONF_PVER_LVL_CTRLS],                         \
               vector[M0_CONF_PVER_LVL_DRIVES])

Definition at line 41 of file pvers.c.

◆ M0_TRACE_SUBSYSTEM

#define M0_TRACE_SUBSYSTEM M0_TRACE_SUBSYS_CONF

Definition at line 28 of file pvers.c.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Enumerator
MAX_FAILURES_NOT_REACHED
MAX_FAILURES_REACHED
MAX_FAILURES_EXCEEDED

Definition at line 49 of file pvers.c.

◆ anonymous enum

anonymous enum

Enumerator
CONF_PVER_FID_MASK

Definition at line 306 of file pvers.c.

◆ m0_conf_pver_state

enum m0_conf_pver_state

State is determined by counting the number of failures in the cluster.

Enumerator
M0_CPS_HEALTHY
M0_CPS_DEGRADED
M0_CPS_CRITICAL
M0_CPS_DAMAGED
M0_CPS_NR

Definition at line 113 of file pvers.h.

Function Documentation

◆ conf_obj_mark_deleted()

static int conf_obj_mark_deleted	(	struct m0_conf_obj *	obj,
		void *args	M0_UNUSED
	)

static

Definition at line 902 of file pvers.c.

Here is the caller graph for this function:

◆ conf_objv_failed_fill()

static int conf_objv_failed_fill	(	struct m0_conf_obj *	obj,
		void *	args
	)

static

Definition at line 537 of file pvers.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ conf_objv_virtual_fid()

static struct m0_fid conf_objv_virtual_fid ( struct m0_conf_cache * cache )

static

Generates new fid for a m0_conf_objv of virtual pver subtree.

Definition at line 377 of file pvers.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ conf_pver_base_obj_check()

static int conf_pver_base_obj_check	(	struct m0_conf_obj *	obj,
		struct conf_pver_base_walk_st *	st
	)

static

Checks if ‘obj’ should be copied to the virtual pver subtree.

Return values

0	Current objv should be copied to the virtual pver subtree.
M0_CW_SKIP_SUBTREE	Current objv and its children should be excluded.
M0_CW_CONTINUE	Current object is not an objv.
-Exxx	Error.

Definition at line 612 of file pvers.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ conf_pver_base_recd_update()

static int conf_pver_base_recd_update ( const struct m0_conf_pool * pool )

static

Definition at line 108 of file pvers.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ conf_pver_base_w()

static int conf_pver_base_w	(	struct m0_conf_obj *	obj,
		void *	args
	)

static

This function is called for every object in base pver subtree.

Definition at line 645 of file pvers.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ conf_pver_enumerate()

static void conf_pver_enumerate ( struct m0_conf_pver * pver )

static

Sets m0_conf_objv::cv_ix for pver's objvs.

Definition at line 481 of file pvers.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ conf_pver_enumerate_w()

static int conf_pver_enumerate_w	(	struct m0_conf_obj *	obj,
		void *	args
	)

static

Definition at line 450 of file pvers.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ conf_pver_failures_cid()

static int conf_pver_failures_cid	(	struct m0_conf_pver *	base,
		uint64_t *	out
	)

static

Computes index of combination of failed devices in the ordered sequence of pver's devices.

Definition at line 559 of file pvers.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ conf_pver_find_by_fid_locked()

static int conf_pver_find_by_fid_locked	(	const struct m0_fid *	fid,
		const struct m0_conf_root *	root,
		struct m0_conf_pver **	out
	)

static

Definition at line 160 of file pvers.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ conf_pver_find_locked()

static int conf_pver_find_locked	(	const struct m0_conf_pool *	pool,
		const struct m0_fid *	pver_to_skip,
		struct m0_conf_pver **	out
	)

static

Definition at line 126 of file pvers.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ conf_pver_formulaic_base()

static int conf_pver_formulaic_base	(	const struct m0_conf_pver *	fpver,
		struct m0_conf_pver **	out
	)

static

Tries to find base pver of given formulaic pver in the conf cache.

Definition at line 262 of file pvers.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ conf_pver_formulaic_find_locked()

static int conf_pver_formulaic_find_locked	(	uint32_t	fpver_id,
		const struct m0_conf_root *	root,
		const struct m0_conf_pver **	out
	)

static

Definition at line 80 of file pvers.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ conf_pver_formulate()

static int conf_pver_formulate	(	const struct m0_conf_pver *	fpver,
		struct m0_conf_pver **	out
	)

static

Finds or creates virtual pool version, described by a formulaic one.

Definition at line 419 of file pvers.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ conf_pver_objvs_count()

static int conf_pver_objvs_count	(	struct m0_conf_pver *	base,
		uint32_t *	out
	)

static

Definition at line 492 of file pvers.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ conf_pver_recd_build()

static int conf_pver_recd_build	(	struct m0_conf_obj *	obj,
		void *	args
	)

static

Definition at line 519 of file pvers.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ conf_pver_subtree_delete()

static void conf_pver_subtree_delete ( struct m0_conf_obj * obj )

static

Definition at line 909 of file pvers.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ conf_pver_tolerance_adjust()

static int conf_pver_tolerance_adjust ( struct m0_conf_pver * pver )

static

Adjusts the tolerance vector of a virtual pool version to make it consistent with the underlying subtree.

Definition at line 696 of file pvers.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ conf_pver_virtual_create()

static int conf_pver_virtual_create	(	const struct m0_fid *	fid,
		struct m0_conf_pver *	base,
		const uint32_t *	allowance,
		struct arr_int *	failed,
		struct m0_conf_pver **	out
	)

static

Creates virtual pool version: copies subtree of base pool version, excluding objvs that correspond to failed devices.

Parameters

fid	Virtual pver fid.
base	Base pool version.
allowance	Allowance vector of the formulaic pver.
failed	[optional] Indices of failed devices in the base pver subtree.
out	Result.

If ‘failed’ is not provided, objvs are excluded according to m0_conf_obj::co_ha_state of objects they refer to.

Definition at line 725 of file pvers.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ m0_conf_pver_fid()

M0_INTERNAL struct m0_fid m0_conf_pver_fid	(	enum m0_conf_pver_kind	kind,
		uint64_t	container,
		uint64_t	key
	)

Returns m0_conf_pver fid.

Interpretation of ‘container’ and ‘key’ arguments in case of virtual pver (kind = M0_CONF_PVER_VIRTUAL): container = formulaic pver id; key = failure cid (the index of combination of failed devices in the ordered sequence of pver's devices).

Definition at line 309 of file pvers.c.

Here is the caller graph for this function:

◆ m0_conf_pver_fid_read()

M0_INTERNAL int m0_conf_pver_fid_read	(	const struct m0_fid *	fid,
		enum m0_conf_pver_kind *	kind,
		uint64_t *	container,
		uint64_t *	key
	)

Parses pver fid.

Gets ‘kind’, ‘container’, ‘key’ components. Any of the output pointers may be NULL.

See also: m0_conf_pver_fid() for the meaning of ‘container’ and ‘key’ in case of virtual pver.

Definition at line 352 of file pvers.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ m0_conf_pver_find()

M0_INTERNAL int m0_conf_pver_find	(	const struct m0_conf_pool *	pool,
		const struct m0_fid *	pver_to_skip,
		struct m0_conf_pver **	out
	)

Returns a pool version with online elements only.

If no such pool version exists, m0_conf_pver_find() will create virtual pool version subtree.

Definition at line 207 of file pvers.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ m0_conf_pver_find_by_fid()

M0_INTERNAL int m0_conf_pver_find_by_fid	(	const struct m0_fid *	fid,
		const struct m0_conf_root *	root,
		struct m0_conf_pver **	out
	)

Finds or creates (restores) a pool version by its fid.

Precondition: m0_conf_fid_type(fid) == &M0_CONF_PVER_TYPE

Note: m0_conf_pver_find_by_fid() does not pin ‘out’ object (i.e., it does not increment m0_conf_obj::co_nrefs). XXX Isn't this a bug?

Definition at line 219 of file pvers.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ m0_conf_pver_formulaic_find()

M0_INTERNAL int m0_conf_pver_formulaic_find	(	uint32_t	fpver_id,
		const struct m0_conf_root *	root,
		const struct m0_conf_pver **	out
	)

Finds formulaic pver by its m0_conf_pver_formulaic::pvf_id attribute.

Definition at line 231 of file pvers.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ m0_conf_pver_formulaic_from_virtual()

M0_INTERNAL int m0_conf_pver_formulaic_from_virtual	(	const struct m0_conf_pver *	virtual,
		const struct m0_conf_root *	root,
		const struct m0_conf_pver **	out
	)

Finds formulaic pool version which ‘virtual’ was "formulated" from.

Definition at line 244 of file pvers.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ m0_conf_pver_is_clean()

M0_INTERNAL bool m0_conf_pver_is_clean ( const struct m0_conf_pver * pver )

Returns true iff pver consists of online elements only or can be used to generate such a pver.

Precondition: pver is not virtual

Definition at line 281 of file pvers.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ m0_conf_pver_level()

M0_INTERNAL unsigned m0_conf_pver_level ( const struct m0_conf_obj * obj )

Which level of m0_conf_pver_subtree does given object correspond to?

Precondition: Type of ‘obj’ is one of m0_conf_{rack,enclosure,controller,disk}, or m0_conf_objv.

Postcondition: M0_CONF_PVER_LVL_RACKS <= retval && retval < M0_CONF_PVER_HEIGHT

Definition at line 394 of file pvers.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ m0_conf_pver_status()

int m0_conf_pver_status	(	struct m0_fid *	fid,
		struct m0_confc *	confc,
		struct m0_conf_pver_info *	out_info
	)

Returns the status of the pool version according to number of failed srecd objects in the pool version.

Parameters

fid	fid of the pool version whose status is queried.
out_info	out parameter which will contain status along with some pdclust attributes of pool version.
confc	configuration client for accessing the conf root.

Precondition: fid != NULL; confc != NULL

Returns: rc of the function.

HEALTHY: if no failures in pver. DEGRADED: if less than K failures in pver and failures at any level has not reached maximum supported failures. CRITICAL: if we have K failures or any level has reached maximum supported failures. DAMAGED: if we have more than K failures or any level has exceeded maximum supported failures.

Definition at line 837 of file pvers.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ tolerance_failure_cmp()

static int tolerance_failure_cmp	(	struct m0_conf_pver *	pv,
		const uint32_t *	srecd
	)

static

Check if failures at any level has reached or exceeded max allowed failures.

Definition at line 816 of file pvers.c.

Here is the caller graph for this function:

Data Structures

Macros

Enumerations

Functions

Detailed Description

Design Assumptions

References

Macro Definition Documentation

◆ CONF_PVER_VECTOR_LOG

◆ M0_TRACE_SUBSYSTEM

Enumeration Type Documentation

◆ anonymous enum

◆ anonymous enum

◆ m0_conf_pver_state

Function Documentation

◆ conf_obj_mark_deleted()

◆ conf_objv_failed_fill()

◆ conf_objv_virtual_fid()

◆ conf_pver_base_obj_check()

◆ conf_pver_base_recd_update()

◆ conf_pver_base_w()

◆ conf_pver_enumerate()

◆ conf_pver_enumerate_w()

◆ conf_pver_failures_cid()

◆ conf_pver_find_by_fid_locked()

◆ conf_pver_find_locked()

◆ conf_pver_formulaic_base()

◆ conf_pver_formulaic_find_locked()

◆ conf_pver_formulate()

◆ conf_pver_objvs_count()

◆ conf_pver_recd_build()

◆ conf_pver_subtree_delete()

◆ conf_pver_tolerance_adjust()

◆ conf_pver_virtual_create()

◆ m0_conf_pver_fid()

◆ m0_conf_pver_fid_read()

◆ m0_conf_pver_find()

◆ m0_conf_pver_find_by_fid()

◆ m0_conf_pver_formulaic_find()

◆ m0_conf_pver_formulaic_from_virtual()

◆ m0_conf_pver_is_clean()

◆ m0_conf_pver_level()

◆ m0_conf_pver_status()

◆ tolerance_failure_cmp()