User Manual for the Rdrand Library (Windows* Version)

ID 658435
Updated 8/8/2012
Version Latest
Public

author-image

By

Download Source

librdrand-windows-r1.zip(130.75 KB) 

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 and the Linux Ubuntu* 10.04. The library can also be built from source, and requires the Intel® C++ Compiler v12. 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, as well as a simple project with Makefile for Linux. Source for the test is in main.c, and the test project on Linux can uses the top-level Makefile (with target 32_test or test). The rdrand.sln solution includes the test project.

Since rdrand is a new instruction, it is only supported on the Intel® microarchitecture codenamed Ivy Bridge 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 three 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);


Each function calls rdrand internally for a specific data-size of random data to return to the caller. Additionally, each function takes a second int parameter, retry, that states whether or not (if true or false) the function call should attempt a determined number of retries (default of 10) should the hardware not be ready. The return of this function 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® 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* and under Linux using Intel® C++ Compiler v12. The reason behind this is that library was written using compiler intrinsics only available in the Intel® C++ Compiler v12.

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® 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.

On Linux a Makefile is include to demonstrate the commands useful in building the static library but also using the host CC (tested against GCC 4.4.3) to link against the generated library to produce an executable. Targets 32 and 64 build the static library for 32 and 64-bits respectively. Also available is a clean target and 32_test and test, which build the demonstration program, again for 32 and 64-bits respectively.
 

Release Notes

The Rdrand Library is simple and as of this release is functionally complete. There are no known issues.