archspec
archspec.cpu
The “cpu” package permits to query and compare different CPU microarchitectures.
- exception archspec.cpu.InvalidCompilerVersion
Raised when an invalid format is used for compiler versions in archspec.
- class archspec.cpu.Microarchitecture(name, parents, vendor, features, compilers, generation=0, cpu_part='')
Represents a specific CPU micro-architecture.
- Parameters:
name (str) – name of the micro-architecture (e.g. skylake).
parents (list) – list of parents micro-architectures, if any. Parenthood is considered by cpu features and not chronologically. As such each micro-architecture is compatible with its ancestors. For example “skylake”, which has “broadwell” as a parent, supports running binaries optimized for “broadwell”.
vendor (str) – vendor of the micro-architecture
features (set of str) – supported CPU flags. Note that the semantic of the flags in this field might vary among architectures, if at all present. For instance x86_64 processors will list all the flags supported by a given CPU while Arm processors will list instead only the flags that have been added on top of the base model for the current micro-architecture.
compilers (dict) –
compiler support to generate tuned code for this micro-architecture. This dictionary has as keys names of supported compilers, while values are list of dictionaries with fields:
- name: name of the micro-architecture according to the
compiler. This is the name passed to the
-march
option or similar. Not needed if the name is the same as that passed in as argument above.
versions: versions that support this micro-architecture.
generation (int) – generation of the micro-architecture, if relevant.
cpu_part (str) – cpu part of the architecture, if relevant.
- property ancestors
All the ancestors of this microarchitecture.
- property family
Returns the architecture family a given target belongs to
- feature_aliases = <archspec.cpu.schema.LazyDictionary object>
Aliases for micro-architecture’s features
- static from_dict(data) Microarchitecture
Construct a microarchitecture from a dictionary representation.
- property generic
Returns the best generic architecture that is compatible with self
- optimization_flags(compiler, version)
Returns a string containing the optimization flags that needs to be used to produce code optimized for this micro-architecture.
The version is expected to be a string of dot separated digits.
If there is no information on the compiler passed as argument the function returns an empty string. If it is known that the compiler version we want to use does not support this architecture the function raises an exception.
- Parameters:
compiler (str) – name of the compiler to be used
version (str) – version of the compiler to be used
- Raises:
UnsupportedMicroarchitecture – if the requested compiler does not support this micro-architecture.
ValueError – if the version doesn’t match the expected format
- to_dict()
Returns a dictionary representation of this object.
- exception archspec.cpu.UnsupportedMicroarchitecture
Raised if a compiler version does not support optimization for a given micro-architecture.
- archspec.cpu.brand_string() str | None
Returns the brand string of the host, if detected, or None.
- archspec.cpu.generic_microarchitecture(name)
Returns a generic micro-architecture with no vendor and no features.
- Parameters:
name (str) – name of the micro-architecture
- archspec.cpu.host()
Detects the host micro-architecture and returns it.
- archspec.cpu.version_components(version)
Decomposes the version passed as input in version number and suffix and returns them.
If the version number or the suffix are not present, an empty string is returned.
- Parameters:
version (str) – version to be decomposed into its components
archspec.cpu.alias
Aliases for microarchitecture features.
- class archspec.cpu.alias.FeatureAliasTest(rules)
A test that must be passed for a feature alias to succeed.
- Parameters:
rules (dict) – dictionary of rules to be met. Each key must be a valid alias predicate
- archspec.cpu.alias.alias_predicate(func)
Decorator to register a predicate that can be used to evaluate feature aliases.
- archspec.cpu.alias.any_of(list_of_features)
Returns a predicate that is True if any of the feature in the list is in the microarchitecture being tested, False otherwise.
- archspec.cpu.alias.families(list_of_families)
Returns a predicate that is True if the architecture family of the microarchitecture being tested is in the list, False otherwise.
- archspec.cpu.alias.reason(_)
This predicate returns always True and it’s there to allow writing a documentation string in the JSON file to explain why an alias is needed.
archspec.cpu.detect
Detection of CPU microarchitectures
- archspec.cpu.detect.COMPATIBILITY_CHECKS = {'aarch64': <function compatibility_check_for_aarch64>, 'ppc64': <function compatibility_check_for_power>, 'ppc64le': <function compatibility_check_for_power>, 'riscv64': <function compatibility_check_for_riscv64>, 'x86_64': <function compatibility_check_for_x86_64>}
Mapping from micro-architecture families (x86_64, ppc64le, etc.) to functions checking the compatibility of the host with a given target
- class archspec.cpu.detect.CpuidInfoCollector
Collects the information we need on the host CPU from cpuid
- brand_string() str | None
Returns the brand string, if available.
- archspec.cpu.detect.INFO_FACTORY = {'Darwin': [<function sysctl_info>], 'Linux': [<function proc_cpuinfo>], 'Windows': [<function cpuid_info>]}
Mapping from operating systems to chain of commands to obtain a dictionary of raw info on the current cpu
- archspec.cpu.detect.brand_string() str | None
Returns the brand string of the host, if detected, or None.
- archspec.cpu.detect.compatibility_check(architecture_family: str | Tuple[str, ...])
Decorator to register a function as a proper compatibility check.
A compatibility check function takes a partial Microarchitecture object as a first argument, and an arbitrary target Microarchitecture as the second argument. It returns True if the target is compatible with first argument, False otherwise.
- Parameters:
architecture_family – architecture family for which this test can be used
- archspec.cpu.detect.compatibility_check_for_aarch64(info, target)
Compatibility check for AARCH64 architectures.
- archspec.cpu.detect.compatibility_check_for_power(info, target)
Compatibility check for PPC64 and PPC64LE architectures.
- archspec.cpu.detect.compatibility_check_for_riscv64(info, target)
Compatibility check for riscv64 architectures.
- archspec.cpu.detect.compatibility_check_for_x86_64(info, target)
Compatibility check for x86_64 architectures.
- archspec.cpu.detect.compatible_microarchitectures(info: Microarchitecture) List[Microarchitecture]
Returns an unordered list of known micro-architectures that are compatible with the partial Microarchitecture passed as input.
- archspec.cpu.detect.cpuid_info()
Returns a partial Microarchitecture, obtained from running the cpuid instruction
- archspec.cpu.detect.detected_info() Microarchitecture
Returns a partial Microarchitecture with information on the CPU of the current host.
This function calls all the viable factories one after the other until there’s one that is able to produce the requested information. Falls-back to a generic microarchitecture, if none of the calls succeed.
- archspec.cpu.detect.detection(operating_system: str)
Decorator to mark functions that are meant to return partial information on the current cpu.
- Parameters:
operating_system – operating system where this function can be used.
- archspec.cpu.detect.host()
Detects the host micro-architecture and returns it.
- archspec.cpu.detect.partial_uarch(name: str = '', vendor: str = '', features: Set[str] | None = None, generation: int = 0, cpu_part: str = '') Microarchitecture
Construct a partial microarchitecture, from information gathered during system scan.
- archspec.cpu.detect.proc_cpuinfo() Microarchitecture
Returns a partial Microarchitecture, obtained from scanning
/proc/cpuinfo
- archspec.cpu.detect.sysctl_info() Microarchitecture
Returns a raw info dictionary parsing the output of sysctl.
archspec.cpu.microarchitecture
Types and functions to manage information on CPU microarchitectures.
- exception archspec.cpu.microarchitecture.ArchspecError
Base class for errors within archspec
- exception archspec.cpu.microarchitecture.InvalidCompilerVersion
Raised when an invalid format is used for compiler versions in archspec.
- class archspec.cpu.microarchitecture.Microarchitecture(name, parents, vendor, features, compilers, generation=0, cpu_part='')
Represents a specific CPU micro-architecture.
- Parameters:
name (str) – name of the micro-architecture (e.g. skylake).
parents (list) – list of parents micro-architectures, if any. Parenthood is considered by cpu features and not chronologically. As such each micro-architecture is compatible with its ancestors. For example “skylake”, which has “broadwell” as a parent, supports running binaries optimized for “broadwell”.
vendor (str) – vendor of the micro-architecture
features (set of str) – supported CPU flags. Note that the semantic of the flags in this field might vary among architectures, if at all present. For instance x86_64 processors will list all the flags supported by a given CPU while Arm processors will list instead only the flags that have been added on top of the base model for the current micro-architecture.
compilers (dict) –
compiler support to generate tuned code for this micro-architecture. This dictionary has as keys names of supported compilers, while values are list of dictionaries with fields:
- name: name of the micro-architecture according to the
compiler. This is the name passed to the
-march
option or similar. Not needed if the name is the same as that passed in as argument above.
versions: versions that support this micro-architecture.
generation (int) – generation of the micro-architecture, if relevant.
cpu_part (str) – cpu part of the architecture, if relevant.
- property ancestors
All the ancestors of this microarchitecture.
- property family
Returns the architecture family a given target belongs to
- feature_aliases = <archspec.cpu.schema.LazyDictionary object>
Aliases for micro-architecture’s features
- static from_dict(data) Microarchitecture
Construct a microarchitecture from a dictionary representation.
- property generic
Returns the best generic architecture that is compatible with self
- optimization_flags(compiler, version)
Returns a string containing the optimization flags that needs to be used to produce code optimized for this micro-architecture.
The version is expected to be a string of dot separated digits.
If there is no information on the compiler passed as argument the function returns an empty string. If it is known that the compiler version we want to use does not support this architecture the function raises an exception.
- Parameters:
compiler (str) – name of the compiler to be used
version (str) – version of the compiler to be used
- Raises:
UnsupportedMicroarchitecture – if the requested compiler does not support this micro-architecture.
ValueError – if the version doesn’t match the expected format
- to_dict()
Returns a dictionary representation of this object.
- archspec.cpu.microarchitecture.TARGETS = <archspec.cpu.schema.LazyDictionary object>
Dictionary of known micro-architectures
- exception archspec.cpu.microarchitecture.UnsupportedMicroarchitecture
Raised if a compiler version does not support optimization for a given micro-architecture.
- archspec.cpu.microarchitecture.coerce_target_names(func)
Decorator that automatically converts a known target name to a proper Microarchitecture object.
- archspec.cpu.microarchitecture.generic_microarchitecture(name)
Returns a generic micro-architecture with no vendor and no features.
- Parameters:
name (str) – name of the micro-architecture
- archspec.cpu.microarchitecture.version_components(version)
Decomposes the version passed as input in version number and suffix and returns them.
If the version number or the suffix are not present, an empty string is returned.
- Parameters:
version (str) – version to be decomposed into its components
archspec.cpu.schema
Global objects with the content of the microarchitecture JSON file and its schema
- archspec.cpu.schema.CPUID_JSON = <archspec.cpu.schema.LazyDictionary object>
Information on how to call ‘cpuid’ to get information on the HOST CPU
- archspec.cpu.schema.CPUID_JSON_SCHEMA = <archspec.cpu.schema.LazyDictionary object>
JSON schema for cpuid.json, loaded on first access
- archspec.cpu.schema.DIR_FROM_ENVIRONMENT = 'ARCHSPEC_CPU_DIR'
Environment variable that might point to a directory with a user defined JSON file
- archspec.cpu.schema.EXTENSION_DIR_FROM_ENVIRONMENT = 'ARCHSPEC_EXTENSION_CPU_DIR'
Environment variable that might point to a directory with extensions to JSON files
- class archspec.cpu.schema.LazyDictionary(factory, *args, **kwargs)
Lazy dictionary that gets constructed on first access to any object key
- Parameters:
factory (callable) – factory function to construct the dictionary
- property data
Returns the lazily constructed dictionary
- archspec.cpu.schema.TARGETS_JSON = <archspec.cpu.schema.LazyDictionary object>
In memory representation of the data in microarchitectures.json, loaded on first access
- archspec.cpu.schema.TARGETS_JSON_SCHEMA = <archspec.cpu.schema.LazyDictionary object>
JSON schema for microarchitectures.json, loaded on first access