CPU topology configuration of Test Agents

Overview

// typedefs

typedef struct tapi_cpu_index_t tapi_cpu_index_t;
typedef struct tapi_cpu_prop_t tapi_cpu_prop_t;

// structs

struct tapi_cpu_index_t;
struct tapi_cpu_prop_t;

// global functions

te_errno tapi_cfg_cpu_grab_by_id(const char* ta, const tapi_cpu_index_t* cpu_id);
te_errno tapi_cfg_cpu_release_by_id(const char* ta, const tapi_cpu_index_t* cpu_id);
te_errno tapi_cfg_cpu_grab_by_prop(const char* ta, const tapi_cpu_prop_t* prop, tapi_cpu_index_t* cpu_id);
te_errno tapi_cfg_get_cpu_cores(const char* ta, size_t* size, tapi_cpu_index_t** indices);
te_errno tapi_cfg_get_all_threads(const char* ta, size_t* size, tapi_cpu_index_t** indices);
te_errno tapi_cfg_cpu_get_nodes(const char* ta, size_t* n_nodes, tapi_cpu_index_t** nodes);
te_errno tapi_cfg_cpu_grab_multiple_with_id(const char* ta, const tapi_cpu_prop_t* prop, const tapi_cpu_index_t* topology, unsigned int n_cpus, tapi_cpu_index_t* cpu_ids);
te_errno tapi_cfg_cpu_grab_multiple_on_single_node(const char* ta, const tapi_cpu_prop_t* prop, unsigned int n_cpus, tapi_cpu_index_t* cpu_ids);
te_errno tapi_cfg_cpu_calculate_numjobs(const char* ta, const char* expr, unsigned int* n_jobs);

// macros

#define TAPI_CFG_CPU_NCORES_FACTOR
#define TAPI_CFG_CPU_NPROC_FACTOR
#define TAPI_CPU_ID_UNSPEC

Detailed Documentation

Typedefs

typedef struct tapi_cpu_index_t tapi_cpu_index_t

Identifier of a logical CPU (CPU thread)

typedef struct tapi_cpu_prop_t tapi_cpu_prop_t

CPU properties that can be requested when looking for a CPU

Global Functions

te_errno tapi_cfg_cpu_grab_by_id(const char* ta, const tapi_cpu_index_t* cpu_id)

Grab a CPU on a test agent with requested index

Parameters:

ta	Test Agent
cpu_id	CPU index

Returns:

Status code.

te_errno tapi_cfg_cpu_release_by_id(const char* ta, const tapi_cpu_index_t* cpu_id)

Release a CPU on a test agent with requested index

Parameters:

ta	Test Agent
cpu_id	CPU index

Returns:

Status code.

te_errno tapi_cfg_cpu_grab_by_prop(const char* ta, const tapi_cpu_prop_t* prop, tapi_cpu_index_t* cpu_id)

Grab a CPU on a test agent with requested properties (if specified) as a resource and retrieve its index.

Parameters:

ta	Test Agent
prop	CPU properties. May be NULL to grab any available CPU
cpu_id	Index of grabbed CPU

Returns:

Status code.

te_errno tapi_cfg_get_cpu_cores(const char* ta, size_t* size, tapi_cpu_index_t** indices)

Get number of CPU cores on a test agent.

Parameters:

ta	Test Agent name.
size	Number of CPU cores (size of indices).
indices	CPU core indices (might be NULL).

Returns:

Status code.

te_errno tapi_cfg_get_all_threads(const char* ta, size_t* size, tapi_cpu_index_t** indices)

Get all available CPU threads indices on a test agents.

Parameters:

ta	Test Agent
size	Number of CPU threads (size of indices)
indices	CPU thread indices (might be NULL)

te_errno tapi_cfg_cpu_get_nodes(const char* ta, size_t* n_nodes, tapi_cpu_index_t** nodes)

Get all available CPU NUMA nodes indices on a test agent.

Parameters:

ta	Test Agent
n_nodes	Number of NUMA nodes (size of nodes)
nodes	CPU NUMA indices (may be NULL)

te_errno tapi_cfg_cpu_grab_multiple_with_id(const char* ta, const tapi_cpu_prop_t* prop, const tapi_cpu_index_t* topology, unsigned int n_cpus, tapi_cpu_index_t* cpu_ids)

Grab multiple CPUs on a test agent with requested properties (if specified) and requested CPU topology (if specified) as a resource and retrieve their indices.

Parameters:

ta	Test Agent
prop	CPU properties. May be NULL to ignore CPU properties
topology	CPU topology. Only CPUs with specified node/package/core/thread ID will be grabbed. May be NULL to ignore the restriction
n_cpus	Number of CPUs to grab
cpu_ids	Indices of grabbed CPUs

te_errno tapi_cfg_cpu_grab_multiple_on_single_node(const char* ta, const tapi_cpu_prop_t* prop, unsigned int n_cpus, tapi_cpu_index_t* cpu_ids)

Wrapper of tapi_cfg_cpu_grab_multiple_with_id() which grabs CPUs on a single NUMA node.

te_errno tapi_cfg_cpu_calculate_numjobs(const char* ta, const char* expr, unsigned int* n_jobs)

Calculate number of jobs depending on number of CPU cores or threads.

The syntax of the expression string:

COUNT | (FACTOR? ("nproc" | "ncores") ("/" DIVISOR)? (("+" | "-") DISP)?
         ("<" MAX)? (">" MIN)?)`

where COUNT - exact number of jobs, FACTOR - multiplier for nproc or ncores, nproc - number of CPU threads, ncores - number of CPU cores, DIVISOR - divisor for nproc or ncores, DISP - displacement from the calculated number, MAX - upper bound for jobs number, MIN - lower bound for jobs number.

Examples:

Expression	nproc	ncores	Result

In case of division, the value is truncated towards zero. If the resulting value is less than 1, it is set to 1.

Parameters:

ta	Test Agent.
expr	Expression for calculating the number of jobs.
n_jobs	Calculated number of jobs.

Returns:

Status code.

Macros

#define TAPI_CFG_CPU_NCORES_FACTOR

Factor to calculate number of jobs depending on CPU cores number.

#define TAPI_CFG_CPU_NPROC_FACTOR

Factor to calculate number of jobs depending on CPU threads number.

#define TAPI_CPU_ID_UNSPEC

Unspecified CPU index used in tapi_cpu_index_t