librdtsc

A simple multi-platform library for reading TSC values on x86-64 and ARM
architectures.

Disclaimer

Most of the code in this library is adapted from the implementation of a similar
mechanism in DPDK project. Most source and header files maintain original
copyright notices on top, since I just adjusted function names and a few things
here and there. In the adaptation process, I might have broken some stuff here
and there, but the most essential functionality of the library remains.

Tested On

For now, the library has been tested on Linux on a x86-64 platform and an ARM64 one. Testing on
other ARM platforms will soon be carried out.

Configuring the library

This project uses CMake as build system. It provides a set of CMake option
toggles that must be set ON or OFF to configure the build system before
building for any platform.

The toggles are used to identify the target OS and architecture, as well as the
features of each architecture that should be enabled.

Selecting Target OS

For now, only Linux is supported, hence the following option should always be ON (default):

• LIBRDTSC_OS_LINUX

Selecting Target Architecture

The target architecture can be selected by enabling only one among the
following toggles (the others must be set to OFF):

• LIBRDTSC_ARCH_x86 (default ON) for x86-64 platforms
• LIBRDTSC_ARCH_ARM for ARM 32-bit platforms
• LIBRDTSC_ARCH_ARM64 for ARM64 platforms

Selecting Target Architecture Features

The library supports multiple mechanisms to access the TSC value on the
supported platforms. These can be enabled using the following toggles (both are
OFF by default):

• LIBRDTSC_USE_HPET to enable HPET usage on x86-64 platforms (currently not
  working)
• LIBRDTSC_USE_PMC to enable PMU usage on ARM platforms (requires some
  options enabled from privileged kernel context)

I personally suggest users to leave either of these features disabled.

Building the library

To build the library, once the set of toggles to enable/disabled has been
decided, use the following snippet from the project top level directory:

mkdir build
cd build
cmake <options> ..

where options should be the complete list of CMake options to enable/disable.

Example for Linux x86-64 (nothing is selected because this is the default
configuration):

mkdir build
cd build
cmake ..

Example for Linux ARM64:

mkdir build
cd build
cmake -DLIBRDTSC_ARCH_x86=OFF -DLIBRDTSC_ARCH_ARM64=ON ..

I understand that this is not the most user-friendly way of providing
parameters, but it was very quick for me to implement. Future revisions of the
library may change this behavior.

Installing the library

Once built, simply run make install (with the appropriate privileges) to install the library in the system.

Writing an app using librdtsc

A sample application is provided in the test directory. For simplicity,
the code is also included here.

This sample application should output a difference between NEW and OLD TSC
values that is approximately equal to the TSC HZ value. While a more accurate
implementation should probably use clock_nanosleep and similar precision, to
get familiar with the library this should be enough.

#include <librdtsc/rdtsc.h>
#include <stdio.h>
#include <unistd.h>

int main() {
    // Initialization must be performed only if rdtsc_get_tsc_hz() is used.
    // The basic rdtsc() call does not require any initialization.
    int res = rdtsc_init();
    if (res != 0) return res;

    uint64_t tsc_hz = rdtsc_get_tsc_hz();
    uint64_t tsc_old = rdtsc();
    sleep(1);
    uint64_t tsc_new = rdtsc();

    printf("TSC OLD:  %ld\n", tsc_old);
    printf("TSC NEW:  %ld\n", tsc_new);
    printf("TSC DIFF: %ld\n", tsc_new - tsc_old);
    printf("TSC HZ:   %ld\n", tsc_hz);
    printf("Elapsed time ( s): %ld\n", rdtsc_elapsed_s(tsc_old, tsc_new));
    printf("Elapsed time (ms): %ld\n", rdtsc_elapsed_ms(tsc_old, tsc_new));
    printf("Elapsed time (us): %ld\n", rdtsc_elapsed_us(tsc_old, tsc_new));
    printf("Elapsed time (ns): %ld\n", rdtsc_elapsed_ns(tsc_old, tsc_new));

    return 0;
}