Download Source
Rdrand Library (Linux* and OS X* Version)
About
This is the Rdrand Library, a project designed to bring the rdrand instruction to customers who would traditionally not have access to it.
The new "rdrand" instruction is available at all privilege levels to any programmer. Unfortunately, however, since this technology is so new, toolchain support is limited. The goal of this library is to provide easy-to-use access to this feature through a pre-compiled static library. A second level goal is to provide a consistent, small, and very easy-to-use API to access the "rdrand" instruction for various sizes of random data. Finally, the source code and build system are provided for the entire library allowing any needed changes.
One limitation of the new rdrand instruction is that it does not guarantee to return a result to the caller--instead it may return that the hardware is not ready. As part of API simplification, this can be handled transparently by requesting a loop (default of 10 iterations, not user-configurable, but changeable in the source) to wait for the hardware to become ready, or fail.
Getting Started
For ease of use, this library is distributed with static libraries for Microsoft* Windows* and Microsoft* Visual Studio* 2010, Linux Ubuntu* 10.04, and OS X* Mountain Lion*. The library can also be built from source, and requires the Intel(r) C++ Compiler v12 on Windows, or GNU* gcc* on Linux and OS X. See the Building section for more details.
Once the static library is compiled, it is simply a matter of linking in the library with your code and including the header in the header search path to use the library. Linking the static library is beyond the scope of this documentation, but for demonstration, a simple Microsoft Visual Studio project is included, named test. Source for the test is in main.c. The test program on Linux and OS X* is built from the Makefile.
Since rdrand is a new instruction, it is only supported on 3rd generation Intel(r) Core processors and beyond. It then makes sense to determine whether or not the new instruction is supported by the CPU-- this is done by examining the 40th bit of the ecx register after calling cpuid. To ease use, the library automatically handles this, and stores the results internally and transparently to the end user of the library. This result is stored in global data, and is thread-safe, given that if one thread of execution supports rdrand, they all will.
The API was designed to be as simple and easy-to-use as possible, and consists of only these functions:int rdrand_16(uint16_t* x, int retry););
int rdrand_32(uint32_t* x, int retry);
int rdrand_64(uint64_t* x, int retry);
int rdrand_get_n_64(unsigned int n, uint64_t* x);
int rdrand_get_n_32(unsigned int n, uint32_t* x);
int rdrand_get_bytes(unsigned int n, unsigned char *buffer
Each function calls rdrand internally for a specific data-size of random data to return to the caller.
The return of these functions states the hardware was not ready (if non-retry specified), success, or that the host hardware doesn't support "rdrand" at all. Please see the define documentation for details on these defines.
Note that the data size types are exact--these are provided by a new C99 header, stdint.h. This seems to defeat the purpose of a wide-use library, so these are mocked up if C99 support isn't detected. Only Microsoft Visual Studio support is provided, but Intel(r) C++ Compiler and GCC 4.4.3 both natively support these C99 data types.
Building
Building the Rdrand Library is supported under Microsoft Visual Studio 2010 using Intel(r) C++ Compiler v12, and under Linux and OS X with the Intel(r) C++ Compiler v12 or GNU gcc.
To build the library, open the rdrand Microsoft Visual Studio solution (rdrand.sln), make sure that "Use Intel C/C++ Compiler" is enabled under the Intel(r) C++ Composer XE context menu context menu, and build the project as normal, from the build menu. Included are two projects, rdrand the actual library and test, the demonstration program.
Release Notes
The Rdrand Library is simple and as of this release is functionally complete. There are no known issues.