psteinb/compass

drop-in header-only C++ library to detect hardware capabilities at runtime and at compiletime

compass

A drop-in header-only C++ library to detect hardware capabilities at runtime and at compiletime.

How to use it?

You have 2 options:

1. you can just copy the contents of single_include (or include if you like to have multiple folders and source code files) into your project and off you go

2. you use the cmake build infrastructure to put compass in a desired folder

   • on *NIX platforms and macOS/OSX

   $ cd repo
   $ mkdir build && cd build
   $ cmake -DCMAKE_INSTALL_PREFIX=/path/where/compass/needs/to/go ..
   $ make && ctest
   $ make install #depending on the contents of CMAKE_INSTALL_PREFIX, you may use sudo
   

   • on Windows platforms (assuming that cmake is in your PATH)

   > cd repo
   > mkdir build
   > cd build
   > cmake.exe -G "Visual Studio 14 2015 Win64" ..
   > cmake.exe --build . --target ALL_BUILD --config Release
   > ctest.exe -C Release
   

(3.) tests should only be run on the hardware where cmake was called. CMakeLists.txt is trying hard to detect the hardware features at cmake invocation. They are then included in the unit test suite.

Compass API

Here is a minimal code example that tries to detect SSE4 at runtime:

#include <iostream>
#include "compass.hpp"

using namespace compass;

int main(int argc, char** argv){

    if(runtime::has(feature::sse4()))
        std::cout << "SSE4 found!!\n";
    else
        std::cout << "This is an old machine. I hope I don't break anything.\n";
        
    return 0;

}

if you want to learn more supported features, check this test file.

Help needed

This project is quite small, so here is your chance to boost open-source to the benefit of the entire C++ community.

• code review the model to extend compass for new compilers/platforms/OSes
• code review the model to extend compass for new features
• is thread-safety an issue of the current implementation ?
• contribute for adding Intel compiler on x86
• contribute for GPUs (nvcc)
• extend support for OpenPower (gcc) if you have according hardware available
• contribute for ARM (gcc/clang) if you have according hardware available

A good place to start and to see what is needed, is llvm Host.cpp file.

License

This project is licensed under the BSD 3-clause open source license. See LICENSE for details.

compass's Issues

Encapsulation of properties?

... coming from issue #3
Instead of:

auto node = compass::node();
auto devices = compass::devices();

auto value_node = compass::has(node, compass::feature::sse());
auto value_dev  = compass::has(devices[0], compass::feature::sse());
...

what about:

auto node = compass::node();
auto devices = compass::devices();

auto value_node = node.has(compass::feature::sse());
auto value_dev  = devices[0].has(compass::feature::sse());
...

prepare windows build with visual studio

Other "compass"-like libraries

There are other libraries around which try to provide a generic hardware discovering.
What is done there and what can be re-used in compass?
The ideal case would be to gather the authors and merge the work into compass.
I will try to list them in this issue...

read /proc/cpuinfo only once

in include/detail/rt/linux_os_impl.hpp, /proc/cpuinfo is opened multiple times and read in, it would be nice if this could only be done once in a thread-safe manner

add build matrix for linux/osx

once #8 is merged, as outlined

compass cache size detection not working on AMD EPYC hosts

travis CI is using AMD EPYC 7401P 24-Core Processor recently, compass cannot detect the cache hierarchy correctly there
https://travis-ci.org/psteinb/compass/jobs/417308560

Node and Device Properties

We run into the issue of a standardization process for hardware topologies and I think HSA can help us with names and layers.

What is the current state of compass. The current compass usage usually looks like this:

auto vendor = compass::runtime::vendor();
auto device_name = compass::runtime::device_name();
auto value = compass::runtime::has(compass::feature::sse());
...

The instantiation of the corresponding wrappers happens at compile-time through the detection of

• OS (linux, mac, windows)
• platform (x86, x86_64, power)
• compiler architecture (clang, intel, gcc, msvc),

mostly retrieved by macros coming from header includes and compilers.

So, the code above always refer to CPU device (keep in mind, nvcc does not compile host code). So first thing coming up here is:

How to name device layer?

There is a need for a layer for the devices within a node. C++AMP just calls them accelerator, which does not seem sufficient for our library. What about HSA, what's their convention:

HSA nomenclature

• HSA 1.1 specification:
  • system and agent information
  • device types: HSA defines CPU, GPU and DSP

1x compass instance only sees 1x node, but n devices (HSA refers to as agents).

// possible compass API
auto node = compass::node();
auto node_compiletime = compass::compiletime::node(); // for compile-time structure
auto vendor = compass::vendor(node);

• So, how about using compass::node and compass::devices to get [compile-time] properties encapsulated in structures?

How to select or iterate through devices?

// possible compass API
...
auto devices = compass::devices();
auto value_node = compass::has(node, compass::feature::sse());
auto value_dev  = compass::has(devices[0], compass::feature::sse());
auto devices_gpu = compass::devices(compass::device_type::gpu);
...

• maybe the runtime namespace can be neglected. A user should not start guessing "is this in runtime or in compiletime". However, compiletime could be a reasonable namespace to ensure compile-time features
• does compile-time feature still work when using cross-compiler?
• accessing device- or node-specific properties can be done via structures/methods, see issue #4