:orphan: .. index:: pair: group; CPU topology configuration of Test Agents .. _doxid-group__tapi__conf__cpu: CPU topology configuration of Test Agents ========================================= .. toctree:: :hidden: struct_tapi_cpu_index_t.rst struct_tapi_cpu_prop_t.rst Overview ~~~~~~~~ .. ref-code-block:: cpp :class: doxyrest-overview-code-block // typedefs typedef struct :ref:`tapi_cpu_index_t` :ref:`tapi_cpu_index_t`; typedef struct :ref:`tapi_cpu_prop_t` :ref:`tapi_cpu_prop_t`; // structs struct :ref:`tapi_cpu_index_t`; struct :ref:`tapi_cpu_prop_t`; // global functions :ref:`te_errno` :ref:`tapi_cfg_cpu_grab_by_id`(const char* ta, const :ref:`tapi_cpu_index_t`* cpu_id); :ref:`te_errno` :ref:`tapi_cfg_cpu_release_by_id`(const char* ta, const :ref:`tapi_cpu_index_t`* cpu_id); :ref:`te_errno` :ref:`tapi_cfg_cpu_grab_by_prop`(const char* ta, const :ref:`tapi_cpu_prop_t`* prop, :ref:`tapi_cpu_index_t`* cpu_id); :ref:`te_errno` :ref:`tapi_cfg_get_cpu_cores`(const char* ta, size_t* size, :ref:`tapi_cpu_index_t`** indices); :ref:`te_errno` :ref:`tapi_cfg_get_all_threads`(const char* ta, size_t* size, :ref:`tapi_cpu_index_t`** indices); :ref:`te_errno` :ref:`tapi_cfg_cpu_get_nodes`(const char* ta, size_t* n_nodes, :ref:`tapi_cpu_index_t`** nodes); :ref:`te_errno` :ref:`tapi_cfg_cpu_grab_multiple_with_id`(const char* ta, const :ref:`tapi_cpu_prop_t`* prop, const :ref:`tapi_cpu_index_t`* topology, unsigned int n_cpus, :ref:`tapi_cpu_index_t`* cpu_ids); :ref:`te_errno` :ref:`tapi_cfg_cpu_grab_multiple_on_single_node`(const char* ta, const :ref:`tapi_cpu_prop_t`* prop, unsigned int n_cpus, :ref:`tapi_cpu_index_t`* cpu_ids); :ref:`te_errno` :ref:`tapi_cfg_cpu_calculate_numjobs`(const char* ta, const char* expr, unsigned int* n_jobs); // macros #define :ref:`TAPI_CFG_CPU_NCORES_FACTOR` #define :ref:`TAPI_CFG_CPU_NPROC_FACTOR` #define :ref:`TAPI_CPU_ID_UNSPEC` .. _details-group__tapi__conf__cpu: Detailed Documentation ~~~~~~~~~~~~~~~~~~~~~~ Typedefs -------- .. index:: pair: typedef; tapi_cpu_index_t .. _doxid-group__tapi__conf__cpu_1gae717b521e623bbcd9ff5f8764f3a0475: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef struct :ref:`tapi_cpu_index_t` tapi_cpu_index_t Identifier of a logical CPU (CPU thread) .. index:: pair: typedef; tapi_cpu_prop_t .. _doxid-group__tapi__conf__cpu_1ga2f2763398272e1b82381a6b994e34d66: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef struct :ref:`tapi_cpu_prop_t` tapi_cpu_prop_t CPU properties that can be requested when looking for a CPU Global Functions ---------------- .. index:: pair: function; tapi_cfg_cpu_grab_by_id .. _doxid-group__tapi__conf__cpu_1ga3f1810ec04ff3eabfcf7a67a26d0ca36: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_cfg_cpu_grab_by_id(const char* ta, const :ref:`tapi_cpu_index_t`* cpu_id) Grab a CPU on a test agent with requested index .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - ta - Test Agent * - cpu_id - CPU index .. rubric:: Returns: Status code. .. index:: pair: function; tapi_cfg_cpu_release_by_id .. _doxid-group__tapi__conf__cpu_1ga4570dcd2e8c5c7108bcadc25ef0cc128: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_cfg_cpu_release_by_id(const char* ta, const :ref:`tapi_cpu_index_t`* cpu_id) Release a CPU on a test agent with requested index .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - ta - Test Agent * - cpu_id - CPU index .. rubric:: Returns: Status code. .. index:: pair: function; tapi_cfg_cpu_grab_by_prop .. _doxid-group__tapi__conf__cpu_1gaf29066a2fdc0b3244c1c64fe7e46f94b: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_cfg_cpu_grab_by_prop(const char* ta, const :ref:`tapi_cpu_prop_t`* prop, :ref:`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. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - ta - Test Agent * - prop - CPU properties. May be ``NULL`` to grab any available CPU * - cpu_id - Index of grabbed CPU .. rubric:: Returns: Status code. .. index:: pair: function; tapi_cfg_get_cpu_cores .. _doxid-group__tapi__conf__cpu_1ga0c8fc365f6232e2adc0837a95853bb37: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_cfg_get_cpu_cores(const char* ta, size_t* size, :ref:`tapi_cpu_index_t`** indices) Get number of CPU cores on a test agent. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - ta - Test Agent name. * - size - Number of CPU cores (size of ``indices``). * - indices - CPU core indices (might be ``NULL``). .. rubric:: Returns: Status code. .. index:: pair: function; tapi_cfg_get_all_threads .. _doxid-group__tapi__conf__cpu_1ga953331503eae482fb7998634062726de: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_cfg_get_all_threads(const char* ta, size_t* size, :ref:`tapi_cpu_index_t`** indices) Get all available CPU threads indices on a test agents. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - ta - Test Agent * - size - Number of CPU threads (size of ``indices``) * - indices - CPU thread indices (might be ``NULL``) .. index:: pair: function; tapi_cfg_cpu_get_nodes .. _doxid-group__tapi__conf__cpu_1gae4710a99004d858b4775c96a338d696c: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_cfg_cpu_get_nodes(const char* ta, size_t* n_nodes, :ref:`tapi_cpu_index_t`** nodes) Get all available CPU NUMA nodes indices on a test agent. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - ta - Test Agent * - n_nodes - Number of NUMA nodes (size of ``nodes``) * - nodes - CPU NUMA indices (may be ``NULL``) .. index:: pair: function; tapi_cfg_cpu_grab_multiple_with_id .. _doxid-group__tapi__conf__cpu_1ga19acf46d6f77aacd89d9f56bb700ad43: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_cfg_cpu_grab_multiple_with_id(const char* ta, const :ref:`tapi_cpu_prop_t`* prop, const :ref:`tapi_cpu_index_t`* topology, unsigned int n_cpus, :ref:`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. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - 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 .. index:: pair: function; tapi_cfg_cpu_grab_multiple_on_single_node .. _doxid-group__tapi__conf__cpu_1ga2114b0fe07a19659799741a853ec3f4b: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`te_errno` tapi_cfg_cpu_grab_multiple_on_single_node(const char* ta, const :ref:`tapi_cpu_prop_t`* prop, unsigned int n_cpus, :ref:`tapi_cpu_index_t`* cpu_ids) Wrapper of :ref:`tapi_cfg_cpu_grab_multiple_with_id() ` which grabs CPUs on a single NUMA node. .. index:: pair: function; tapi_cfg_cpu_calculate_numjobs .. _doxid-group__tapi__conf__cpu_1ga0bf32e3f78092dd5bc945fda2484c4c8: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`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: .. ref-code-block:: cpp 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 ========== ===== ====== ====== 2 8 8 2 6 6 4 4 3 32 16 1 4 ========== ===== ====== ====== In case of division, the value is truncated towards zero. If the resulting value is less than ``1``, it is set to ``1``. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - ta - Test Agent. * - expr - Expression for calculating the number of jobs. * - n_jobs - Calculated number of jobs. .. rubric:: Returns: Status code. Macros ------ .. index:: pair: define; TAPI_CFG_CPU_NCORES_FACTOR .. _doxid-group__tapi__conf__cpu_1ga25d4da244bf80dc831a7247d5b294368: .. ref-code-block:: cpp :class: doxyrest-title-code-block #define TAPI_CFG_CPU_NCORES_FACTOR Factor to calculate number of jobs depending on CPU cores number. .. index:: pair: define; TAPI_CFG_CPU_NPROC_FACTOR .. _doxid-group__tapi__conf__cpu_1gafa39267016c42729165bf0137ae1f043: .. ref-code-block:: cpp :class: doxyrest-title-code-block #define TAPI_CFG_CPU_NPROC_FACTOR Factor to calculate number of jobs depending on CPU threads number. .. index:: pair: define; TAPI_CPU_ID_UNSPEC .. _doxid-group__tapi__conf__cpu_1ga7d35a94c270ee41ea93923959244ffe9: .. ref-code-block:: cpp :class: doxyrest-title-code-block #define TAPI_CPU_ID_UNSPEC Unspecified CPU index used in :ref:`tapi_cpu_index_t `