CPU, what can you do?

CpuId is a package for the Julia programming language that enables you to
query the availability of specific CPU features with low run-time cost
using the assembly instruction cpuid.

Test	Status
Windows, Linux & Mac Build
Code Coverage

Status: considered a beta version for the core functionality, ready for you to try out.

Works on Julia 1.0 and later, on Linux, Mac and Windows with Intel CPUs
and AMD CPUs. Other processor types like ARM are not supported.

Motivation

Besides the obvious reason to gather information for diagnostics, the CPU
provides valuable information when aiming at increasing the efficiency of code.
Such use-cases could be to tailor the size of working sets of data according to
the available cache sizes, to detect when the code is executed in a virtual
machine (hypervisor), or to determine the size of the largest SIMD registers
available to choose the best algorithm for the current hardware.

This information is obtained by directly querying the CPU through the cpuid
assembly instruction which operates only using CPU registers, and provides
a portable way to adapt code to specific hardware.

Same information may of course be collected from various sources, from Julia
itself or from the operating system, e.g. on Linux from /proc/cpuinfo. See
below for a few alternatives. However, the cpuid instruction
is portable in the sense that it doesn’t rely on other external dependencies.

The full documentation is found in Intel’s 4670 page combined Architectures
Software Devleoper Manual.
A more practical and concise overview of the cpuid instruction is found at
sandpile.org.

Installation and Usage

CpuId is a registered Julia package; use the package manager to install:

Julia> Pkg.add("CpuId")

Or, if you’re keen to get some intermediate updates, clone from GitHub
master branch:

Julia> Pkg.clone("https://github.com/m-j-w/CpuId.jl")

See the diagnostic summary on your CPU by typing

julia> using CpuId
julia> cpuinfo()
   Cpu Property         Value
  ╾───────────────────╌───────────────────────────────────────────────────────────╼
   Brand                Intel(R) Xeon(R) CPU E3-1225 v5 @ 3.30GHz
   Vendor               :Intel
   Architecture         :Skylake
   Model                Family: 6, Model: 94, Stepping: 3, Type: 0
   Cores                4 physical cores, 4 logical cores (on executing CPU)
                        No Hyperthreading detected
   Clock Frequencies    3300 / 3700 MHz (base/max), 100 MHz bus
   Data Cache           Level 1:3 : (32, 256, 8192) kbytes
                        64 byte cache line size
   Address Size         48 bits virtual, 39 bits physical
   SIMD                 256 bit = 32 byte max. SIMD vector size
   Time Stamp Counter   TSC is accessible via `rdtsc`
                        TSC runs at constant rate (invariant from clock frequency)
   Perf. Monitoring     Performance Monitoring Counters (PMC) revision 4
                        Available hardware counters per logical core:
                        3 fixed-function counters of 48 bit width
                        8 general-purpose counters of 48 bit width
   Hypervisor           No

Or get a list of the feature flags of your CPU with

julia> cpufeaturetable()
   Cpu Feature   Description
  ╾────────────╌───────────────────────────────────────────────────────────────╼
   3DNowP        3D Now PREFETCH and PREFETCHW instructions
   ACPI          Thermal monitor and software controlled clock facilities (MSR)
   ADX           Intel ADX (Multi-Precision Add-Carry Instruction Extensions)
   AES           AES encryption instruction set
   AHF64         LAHF and SAHF in PM64
   APIC          APIC on-chip (Advanced Programmable Interrupt Controller)
   AVX           256bit Advanced Vector Extensions, AVX
   AVX2          SIMD 256bit Advanced Vector Extensions 2
   BMI1          Bit Manipulation Instruction Set 1
   BMI2          Bit Manipulation Instruction Set 2
   CLFLUSH       CLFLUSHOPT Instructions
   CLFSH         CLFLUSH instruction (SSE2)
   CMOV          Conditional move CMOV and FCMOV instructions
   CX16          CMPXCHG16B instruction
   CX8           CMPXCHG8 instruction (64bit compare and exchange)
   ...

Features

This release covers a selection of fundamental and higher level functionality:

• cpuinfo() generates the summary shown above (markdown string).
• cpubrand(), cpumodel(), cpuvendor() allow the identification of the
  CPU.
• cpuarchitecture() tries to infer the microarchitecture, currently only of
  Intel CPUs.
• cpucores() and cputhreads() to determine the number of physical and
  logical cores on the currently executing CPU, which typically share L3
  caches and main memory bandwidth. If the result of both functions is
  equal, then the CPU does not use of hyperthreading.
• address_size() and physical_address_size() return the number of bits used
  in pointers. Useful when stealing a few bits from a pointer.
• cachelinesize() gives the size in bytes of one cache line, which is
  typically 64 bytes.
• cachesize() returns a tuple with the sizes of the data caches in bytes.
• cacheinclusive() returns a tuple indicating lower cache levels being
  included in the data cache sizes reported by cachesize().
• cpu_base_frequency(), cpu_max_frequency(), cpu_bus_frequency() give -
  if supported by the CPU, the base, maximum and bus clock frequencies.
  Use has_cpu_frequencies() to check whether this property is supported.
• hypervised() returns true when the CPU indicates that a hypervisor is
  running the operating system, aka a virtual machine. In that case,
  hvvendor() may be invoked to get the, well, hypervisor vendor, and
  hvversion() returns a dictionary of additional version tags.
  hvinfo() generates a markdown summary of same dictionary.
• simdbits() and simdbytes() return the size of the largest SIMD register
  available on the executing CPU.
• perf_revision() to query the revision number of hardware performance
  monitoring counters, along with perf_fix_counters(), perf_gen_counters(),
  perf_fix_bits(), perf_gen_bits() to determine the number and bit width
  of available fixed-function and general purpose counters per logical core.
• cpucycle() and cpucycle_id() let you directly get the CPU’s time stamp
  counter, which is increased for every CPU clock cycle. This is a method to
  perform low overhead micro-benchmarking; though, technically, this uses the
  rdtsc and rdtscp instructions rather than cpuid.
• cpufeature(::Symbol) permits asking for the availability of a specific
  feature, and cpufeaturetable() gives a complete overview of all detected
  features with a brief explanation, as shown above.

Background

The cpuid instruction is a generic way provided by the CPU vendor to obtain
basic hardware information. It provides data in form of boolean bit fields,
integer fields and strings, all packed in the returned CPU registers EAX, EBX,
ECX and EDX. Which information is returned is determined by the so called leaf,
which is defined by setting the input register EAX to a specific 32 bit integer
value before executing the instruction. The extent and kind of information
obtainable via this instruction has changed quite a lot over the past decade and
still evolves with every CPU generation. Thus, not all information is available
on every CPU model, and certainly everything is vendor dependent.

This Julia package also provides the cpucycle() function which allows getting
the current time stamp counter (TSC) by emitting a rdtsc instruction.
Similarly to cpuid, it only requires CPU registers and is usable in user-land
code and facilitates an alternative approach to micro-benchmarking.

Limitations

The behaviour on non-Intel CPUs is currently unknown; though technically a crash
of Julia could be expected, theoretically, a rather large list of CPUs support
the cpuid instruction. Tip: Just try it and report back.

There are plenty of different CPUs, and in particular the cpuid instruction
has numerous corner cases, which this package does not address, yet.

Moreover, the cpuid instruction can only provide information for the executing
physical CPU, called a package. To obtain information on all packages, and all
physical and logical cores, the executing program must be pinned sequentially to
each and every core, and gather its properties. This is how libuv, hwloc or
the operating system obtain that kind information. However, this would require
additional external or operating system dependent code which is not the scope of
this package.

Specific limitations and caveats

• The number of physical cores and logical cores reported by CpuId seems wrong!
  If you have multiple processors on your motherboard, then CpuId will
  always only give you information for the processor the current task is running
  on. For example: You have 2 processors, each with 12 physical cores and 24
  logical cores (thus with hyperthreading). While you have in total 48 logical
  cores on both processors, CpuId will only give you 24 logical and 12 physical
  cores from the one it is running on.
  Resolving this is outside the scope of this Julia module, since it requires
  additional other operating system dependent functions, pinning the current
  task to a specific CPU, or querying other BIOS related functions.

• Why aren’t all infos available that are seen e.g. in /proc/cpuinfo?
  Many of those features, flags and properties reside in the so called machine
  specific registers (MSR), which are only accessible to privileged programs
  running in the so called ring 0, such as the Linux kernel itself. Thus,
  short answer: You’re not allowed to.

• The results obtained by CpuId functions are inconsistent with my hardware!
  Try other programs whether they give the same information or differ. If they
  differ, then you found a bug. See below for some
  alternatives, in particular the Linux command line tool
  cpuid.

• When running a hypervisor (virtual machine) the presented information is wrong!
  Hypervisor vendors are free to provide the cpuid information
  by intercepting calls to that instruction. Not all vendors comply, and some
  even permit the user to change what is reported. Thus, expect some
  surprises when a hypervisor is detected.

• My hypervisor is not detected!
  Either you’re not really running a hypervisor, e.g. Bash on Windows is
  not a virtual machine, or there is a feature missing. Raise an issue on
  GitHub.

• cpucycles() invokes rdtsc; that is not cpuid!
  True. However, both are valuable when diagnosing performance issues
  and trying to perform micro benchmarks on specific hardware.

Alternatives

On Linux, most of the information may be obtained by reading from the /proc
tree, in particular /proc/cpuinfo, which eventually also invokes the cpuid
instruction. Type man 4 cpuid to get a brief description of this kernel
driver.

On many Linux distributions, there is also the command line tool cpuid, which essentially does exactly the same. On
Ubuntu, you would install it using sudo apt install cpuid, then use it to show
a summary by simply typing cpuid.

Then, of course, there are a few functions in Julia Base. These are
Base.Sys.cpu_info(), and Base.Sys.cpu_summary(), as well as the global
variable Base.Sys.CPU_THREADS. These are mostly provided by wrapping libuv.
In particular CPU_THREADS is the reason for this module: This reports the
number of logical cores, but how many physical cores do you have that you would
want to run your code on?

The Julia package Hwloc.jl provides
similar and more information primarily directed towards the topology of your
CPUs, viz. number of CPU packages, physical & logical cores and associated
caches, along with a number of features to deal with thread affinity. However,
it also pulls in additional external binary dependencies in that it relies on
hwloc, which also implies quite some
computational overhead. Whether this is an issue in the first place depends much
on your use-case.

Terms of usage

This Julia package CpuId is published as open source and licensed under the
MIT “Expat” License.

Contributions welcome!

You’re welcome to report successful usage or any issues via GitHub, and to open
pull requests to extend the current functionality.