Contents
Intel provides great and well designed site Intrinsics Guide that gives a programmer the full list of x86 intrinsics functions. I use the page often, but there are days when I'm offline and then miss ability to do quick searches.
This repository contains a python script which creates a set of Unix manual pages. It uses data from Intrinsics Guide and optionally from uops.info. The latter provides detailed parameters of CPU instructions (latency, throughput, port usage) for various Intel architectures.
The easiest way to install man pages is build a package suitable for your system. Building man pages does not require root rights, only installation of package requires administrator rights.
The MANOPTIONS variable sets extra options for script, please read the next
section or run program main.py -h.
There's also PKGBUILD for Arch prepared by @pimzero.
To create a .deb package you need dpkg-deb program installed. Then run:
# optionally set extra options for script $ export MANOPTIONS='' $ make deb
It will download XML files, create special .deb files (control, postinst,
postrm) and finally build the package man-intrinsics-<version>_all.deb.
You can install it with dpkg -i man-intrinsics-<version>_all.deb.
To create an .rpm package you need rpmbuild program installed.
Then run:
# optionally set extra options for script $ export MANOPTIONS='' $ make rpm
It will download XML files, create a .spec file and finally build the package
man-intrinsics-<version>-1.noarch.rpm.
You can install it with man-intrinsics-<version>-1.noarch.rpm.
Intrinsics Guide loads a huge XML file, just download that file and feed the
generator. uops.info provides a direct link to download their database, also
in XML format. You may use make to download these .xml files into the
current directory:
$ make download
Two files should be available: data-latest.xml (from Intrinsics Guide)
and instructions.xml (from uops.info).
Then, to create man pages, you might run either:
$ ./main.py -g data-latest.xml -o destination-dir
or:
$ ./main.py -g data-latest.xml -u instructions.xml -o destination-dir
The first invocation creates basic version of man pages (instruction name, description, etc.), the second one includes also tables with latency, throughput.
Please run the script main.py with option --help to find out more
options; two most important features are described in the following
subsections.
Intrinsics Guide lists all SIMD (and not only SIMD) instructions. However, MMX is not used anymore; likewise, KNC wasn't a very widespread technology.
It's possible to select which instructions include or exclude. The option
--isa selects ISA to generate, the option --omit-isa excludes ISA.
Both can be passed as many times as it's needed and both accept a string,
an ISA symbol, as argument
To obtain the list of meaningful ISA symbols use --dump-isa.
Examples:
$ ./main.py -g guide.xml --dump-isa List of ISAs defined in guide.xml: ..., MMX, ..., SSE, SSE2, ... # will generate man pages only for instructions from SSE and SSE2 $ ./main.py -g guide.xml --isa=SSE --isa=SSE2 -o output-dir # will generate man pages for all instructions except MMX $ ./main.py -g guide.xml --omit-isa=MMX -o output-dir
Database from uops.info provides parameters for several architectures,
some of them outdated. It's possible to select which architecture include
(with option --arch) or exclude (with option --omit-arch).
The options can be passed as many times as it's needed, both accept a string,
arch name or symbol.
The list of symbols and names is displayed by option --dump-arch.
Examples:
# will include details for architectures Haswell, Skylake and SkylakeX $ ./main.py -g guide.xml -u uops.xml -o output-dir --arch=HSW --arch=skylake --arch=SkylakeX # will exclude details for Westmere $ ./main.py -g guide.xml -o output-dir --omit-arch=Westmere
The option -l/--create-symlinks adds symbolic links to names of CPU
instructions, thanks to that it's easy to find out which intrinsics function is
mapped to given instruction. For instance man vpandn will bring the manual
page for _mm256_and_si256.
By default this option is disabled.
- https://github.com/Wunkolo/Intriman --- similar project, targeting more output formats
- https://github.com/zwegner/x86-info-term --- TUI for Intrinsics Guide and uops.info
- https://github.com/HJLebbink/asm-dude/wiki --- data extracted from the official Intel documents