geopm_topo_c(3) -- query platform component topology

SYNOPSIS

#include <geopm_topo.h>

Link with -lgeopm (MPI) or -lgeopmpolicy (non-MPI)

  • int geopm_topo_num_domain(: int _domaintype);

  • int geopm_topo_domain_idx(: int _domaintype,
    int _cpuidx);

  • int geopm_topo_num_domain_nested(: int _innerdomain,
    int _outerdomain);

  • int geopm_topo_domain_nested(: int _innerdomain,
    int _outerdomain,
    int _outeridx,
    size_t _num_domainnested,
    int *`_domain*nested*`);``

  • int geopm_topo_domain_name(: int _domaintype,
    size_t _domain_namemax,
    char *`_domain*name*`);``

  • int geopm_topo_domain_type(: const char *`_domain*name*`);``

  • int geopm_topo_create_cache(: void);

DOMAIN TYPES

The geopm_domain_e enum defines a set of values that correspond to hardware components on the system:

  • GEOPM_DOMAIN_INVALID = -1: Indicates an invalid domain.

  • GEOPM_DOMAIN_BOARD = 0: All components on a user allocated compute node. There is only a single board per compute node, and every other domain is contained with the board domain.

  • GEOPM_DOMAIN_PACKAGE = 1: A collection of all the hardware present on a single processor package installed on a distinct socket of a motherboard.

  • GEOPM_DOMAIN_CORE = 2: Physical core, i.e. a group of associated hyper-threads

  • GEOPM_DOMAIN_CPU = 3: Linux logical CPU. In practice, there is one logical CPU per hyperthread visible to the operating system.

  • GEOPM_DOMAIN_MEMORY = 4: Standard off-package DIMM (DRAM or NAND).

  • GEOPM_DOMAIN_PACKAGE_INTEGRATED_MEMORY = 5: On-package memory (MCDRAM).

  • GEOPM_DOMAIN_NIC = 6: Peripheral network interface controller not on the processor package.

  • GEOPM_DOMAIN_PACKAGE_INTEGRATED_NIC = 7: Network interface controller on the processor package.

  • GEOPM_DOMAIN_GPU = 8: Peripheral GPU card not on the processor package.

  • GEOPM_DOMAIN_PACKAGE_INTEGRATED_GPU = 9: GPU unit on the package (e.g on-package graphics).

  • GEOPM_NUM_DOMAIN = 10: The number of valid built-in domains.

DESCRIPTION

The interfaces described in this man page are the C language bindings for the geopm::PlatformTopo(3) C++ class. Please refer to the geopm::PlatformTopo(3) man page for a general description of the purpose, goals and use case for this interface.

  • geopm_topo_num_domain():

    Returns the number of domains available on the system of type _domaintype. If the _domaintype is valid, but there are no domains of that type on the system, the return value is zero. If the domain is not a valid domain defined by the geopm_domain_e enum then the function will return a negative error code: GEOPM_ERROR_INVALID.

  • geopm_topo_domain_idx(): Returns the index of the domain of type _domaintype that is local to the Linux logical CPU _cpuidx. The return value will be greater than or equal to zero and less than the value returned by geopm_topo_num_domain(_domaintype) for valid input parameters. A negative error code is returned if _domaintype or _cpuidx are out of range: GEOPM_ERROR_INVALID.

  • geopm_topo_num_domain_nested(): Returns the number of domains of type _interdomain that are contained within each domain of _outerdomain type. The return value is one if _innerdomain is equal to _outerdomain. A negative error code is returned if _innerdomain is not contained within _outerdomain: GEOPM_ERROR_INVALID. Any non-negative return value can be used to size the _domainnested array that is passed to geopm_topo_domain_nested() with the same values for _innerdomain and _outerdomain.

  • geopm_topo_domain_nested(): Fills the output array _domainnested with the domain indices of all of the _innerdomain types nested within the specific _outerdomain type indexed by _outeridx. The _num_domainnested defines the length of the _domainnested array must match the positive return value from geopm_topo_num_domain_nested(_innerdomain, _outerdomain). Zero is returned upon success. A negative error code is returned if _innerdomain is not within _outerdomain, or if _outeridx is not between zero and geopm_topo_num_domain(_outerdomain).

  • geopm_topo_domain_name(): Sets the _domainname string to the name associated with the _domaintype selected from the geopm_domain_e enum. At most _resultmax bytes are written to the _domainname string. Providing a string of NAME_MAX length (from limits.h) will be sufficient for storing any result. If _resultmax is too small to contain the domain name an error will occur. Zero is returned on success and a negative error code is returned if any error occurs.

  • geopm_topo_domain_type(): Returns the domain type that is associated with the provided _domainname string. This is the inverse function to geopm_topo_domain_name() and the input _domainname must match the output from geopm_topo_domain_name() for a valid domain type. If the string does not match any of the valid domain names, then GEOPM_DOMAIN_INVALID is returned.

  • geopm_topo_create_cache(): Create a cache file for the geopm::PlatformTopo(3) object if one does not exist. This cache file will be used by any calls to the other geopm_topo_*() functions documented here as well as any use of the GEOPM runtime. File permissions of the cache file are set to "-rw-rw-rw-", i.e. 666. The path for the cache file is /tmp/geopm-topo-cache. If the file exists no operation will be performed. To force the creation of a new cache file, unlink(3) the existing cache file prior to calling this function.

RETURN VALUE

If an error occurs in any call to an interface documented here, the return value of the function will be a negative integer corresponding to one of the error codes documented in geopm_error(3).

SEE ALSO

geopm(7), geopm_pio_c(3), geopm_error(3), geopm::PlatformTopo(3), geopm::PlatformIO(3), unlink(3)