archspec¶

archspec.cpu¶

The “cpu” package permits to query and compare different CPU microarchitectures.

class archspec.cpu.Microarchitecture(name, parents, vendor, features, compilers, generation=0)¶

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 (list 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.

ancestors¶: All the ancestors of this microarchitecture.

family¶: Returns the architecture family a given target belongs to

feature_aliases = <archspec.cpu.schema.LazyDictionary object>¶: Aliases for micro-architecture’s features

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.

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

to_dict(return_list_of_items=False)¶

Returns a dictionary representation of this object.

Parameters:	return_list_of_items (bool) – if True returns an ordered list of items instead of the dictionary

exception archspec.cpu.UnsupportedMicroarchitecture¶: Raised if a compiler version does not support optimization for a given micro-architecture.

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

archspec.cpu.detect.INFO_FACTORY = {'Darwin': [<function sysctl_info_dict>], 'Linux': [<function proc_cpuinfo>]}¶: Mapping from operating systems to chain of commands to obtain a dictionary of raw info on the current cpu

archspec.cpu.detect.adjust_raw_flags(info)¶: Adjust the flags detected on the system to homogenize slightly different representations.

archspec.cpu.detect.adjust_raw_vendor(info)¶: Adjust the vendor field to make it human readable

archspec.cpu.detect.compatibility_check(architecture_family)¶

Decorator to register a function as a proper compatibility check.

A compatibility check function takes the raw info dictionary as a first argument and an arbitrary target as the second argument. It returns True if the target is compatible with the info dictionary, False otherwise.

Parameters:	architecture_family (str or tuple) – architecture family for which this test can be used, e.g. x86_64 or ppc64le etc.

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)¶

Returns an unordered list of known micro-architectures that are compatible with the info dictionary passed as argument.

Parameters:	info (dict) – dictionary containing information on the host cpu

archspec.cpu.detect.host()¶: Detects the host micro-architecture and returns it.

archspec.cpu.detect.info_dict(operating_system)¶

Decorator to mark functions that are meant to return raw info on the current cpu.

Parameters:	operating_system (str or tuple) – operating system for which the marked function is a viable factory of raw info dictionaries.

archspec.cpu.detect.proc_cpuinfo()¶: Returns a raw info dictionary by parsing the first entry of /proc/cpuinfo

archspec.cpu.detect.raw_info_dictionary()¶

Returns a dictionary 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.

archspec.cpu.detect.sysctl_info_dict()¶: Returns a raw info dictionary parsing the output of sysctl.

archspec.cpu.microarchitecture¶

Types and functions to manage information on CPU microarchitectures.

class archspec.cpu.microarchitecture.Microarchitecture(name, parents, vendor, features, compilers, generation=0)¶

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 (list 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.

ancestors¶: All the ancestors of this microarchitecture.

family¶: Returns the architecture family a given target belongs to

feature_aliases = <archspec.cpu.schema.LazyDictionary object>¶: Aliases for micro-architecture’s features

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.

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

to_dict(return_list_of_items=False)¶

Returns a dictionary representation of this object.

Parameters:	return_list_of_items (bool) – if True returns an ordered list of items instead of the dictionary

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

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

data¶: Returns the lazily constructed dictionary

archspec.cpu.schema.SCHEMA = <archspec.cpu.schema.LazyDictionary object>¶: JSON schema for microarchitectures.json, loaded on first access

archspec.cpu.schema.TARGETS_JSON = <archspec.cpu.schema.LazyDictionary object>¶: In memory representation of the data in microarchitectures.json, loaded on first access