include/topology.h File Reference

libtopology - a library for discovering Linux system topology More...

Go to the source code of this file.

Defines
#define	topology_for_each_device_of_type(ctx, dev, type)
Typedefs
typedef unsigned long	topo_context_t
typedef unsigned long	topo_procent_t
typedef unsigned long	topo_device_t
typedef enum topology_level	topo_level_t
Enumerations
enum	topology_level {   TOPOLOGY_THREAD = 1, TOPOLOGY_CORE, TOPOLOGY_PACKAGE, TOPOLOGY_NODE,   TOPOLOGY_SYSTEM }
Functions
int	topology_init_context (topo_context_t *ctx, topo_procent_t *system)
void	topology_free_context (topo_context_t ctx)
size_t	topology_sizeof_cpumask (topo_context_t ctx)
topo_procent_t	topology_traverse (topo_procent_t start, topo_procent_t iter, topo_level_t to_level)
void	topology_procent_cpumask (topo_procent_t ent, cpu_set_t *dest)
topo_device_t	topology_find_device_by_type (topo_context_t ctx, topo_device_t prev, const char *type)
void	topology_device_cpumask (topo_device_t dev, cpu_set_t *dest)
const char *	topology_device_get_attribute (topo_device_t dev, const char *name)

---

Detailed Description

libtopology - a library for discovering Linux system topology

The libtopology API allows one to formulate scheduling and NUMA policies in terms that are abstract and portable.

---

Define Documentation

#define topology_for_each_device_of_type	(	ctx,
		dev,
		type		)

Value:

for ((dev) = topology_find_device_by_type((ctx), (topo_device_t)0, (type)); \
             (dev) != 0;                                                            \
             (dev) = topology_find_device_by_type((ctx), (dev), (type)))

topology_for_each_device_of_type() - Iterate over all devices matching type

Parameters:

	ctx	- Topology context in use
	dev	- struct topo_device * iterator
	type	- type string, e.g. "cache"

The order in which devices are returned is unspecified.

---

Function Documentation

int topology_init_context	(	topo_context_t *	ctx,
		topo_procent_t *	system
	)

topology_init_context() - Allocate a topology context

Parameters:

	ctx	- address of topo_context_t
	system	- address of system topo_procent_t

Returns:

0 on success, non-zero on failure.

On success ctx will contain a valid handle for a topology context which can be used with other topology APIs. If the system pointer is non-NULL, on success it contains a handle corresponding to the top-level system object, from which all other topo_procent_t objects in the system (nodes, packages, cores, and threads) can be reached.

On failure the contents of ctx and system are unspecified.

void topology_free_context

(

topo_context_t

ctx

)

topology_free_context() - Release a topology context

Parameters:

ctx

- context to release

Releases the resources associated with a valid topology context provided by topology_init_context(). After a call to topology_free_context(), ctx is considered invalid and must not be passed to other topology APIs. This function should be called only after all other operations on this context or its derived objects have completed. In other words, topology_free_context() should not be called until the user is done making libtopology calls.

size_t topology_sizeof_cpumask

(

topo_context_t

ctx

)

topology_sizeof_cpumask() - get the size of cpumasks used by libtopology

Parameters:

ctx

- a valid context returned from topology_init_context()

Returns:

The size in bytes of cpumask objects used by libtopology for this context.

During context initialization, libtopology may dynamically determine the size of the cpumask data structure (a bitfield representing a set of logical CPU ids), which is used to indicate the set of logical CPUs with which an object is associated. The value returned by this function is the size which must be used to allocate cpu_set_t objects which are passed to the libtopology API (e.g. topology_device_cpumask()).

See also:

topology_device_cpumask

topology_procent_cpumask

topo_procent_t topology_traverse	(	topo_procent_t	start,
		topo_procent_t	iter,
		topo_level_t	to_level
	)

topology_traverse() - traverse from one processor entity to others

Parameters:

	start	- starting point in procent hierarchy
	iter	- value returned from previous call to topology_traverse(), or 0
	to_level	- the topology_level value which returned objects must match

Returns:

The next topo_procent_t object at the level specified, relative to start and iter.

This function can be used to interrogate the topo_procent_t hierarchy. The iter argument is consulted when traversing an object's constituents or "children", i.e. when to_level is less than the starting point's level.

void topology_procent_cpumask	(	topo_procent_t	ent,
		cpu_set_t *	dest
	)

topology_procent_cpumask() - copy a topo_procent_t's cpumask

Parameters:

	ent	- topo_procent_t to query
	dest	- pointer to cpu_set_t allocated by the caller

Copies ent's cpumask to the cpumask buffer provided by the caller. The size of the cpumask buffer must be equal to the size returned by topology_sizeof_cpumask().

See also:

topology_sizeof_cpumask

topo_device_t topology_find_device_by_type	(	topo_context_t	ctx,
		topo_device_t	prev,
		const char *	type
	)

topology_find_device_by_type() - Iterate from one device to the next of the given type

Parameters:

	ctx	- Topology context in use
	prev	- 0, or a topo_device_t returned by a previous call to topology_find_device_by_type()
	type	- type string, e.g. "cache"

Returns:

The next device matching the given type

This interface is useful primarily in combination with topology_for_each_device_of_type() to iterate over a the devices matching the given type. The order in which devices are returned is unspecified.

See also:

topology_for_each_device_of_type

void topology_device_cpumask	(	topo_device_t	dev,
		cpu_set_t *	dest
	)

topology_device_cpumask() - copy a topo_device_t's cpumask

Parameters:

	dev	- topo_device_t to query
	dest	- pointer to cpu_set_t allocated by the caller

Copies the given device's cpumask to the cpumask buffer provided by the caller. The size of the cpumask buffer must be equal to the size returned by topology_sizeof_cpumask().

See also:

topology_sizeof_cpumask

const char* topology_device_get_attribute	(	topo_device_t	dev,
		const char *	name
	)

topology_device_get_attribute - query the properties of a device

Parameters:

	dev	- topo_device *
	name	- string identifying the attribute

Returns:

The value of the attribute for the given device.

If the device has no attribute matching the given name, returns NULL. The pointer returned refers to memory allocated by libtopology; if the user intends to use this value after releasing the context associated with dev, a copy should be made.