#include <stddef.h>
#include <stdint.h>

Include dependency graph for randomx.h:

This graph shows which files directly or indirectly include this file:

Macros
#define	RANDOMX_HASH_SIZE 32
#define	RANDOMX_DATASET_ITEM_SIZE 64
#define	RANDOMX_EXPORT

Typedefs
typedef struct randomx_dataset	randomx_dataset
typedef struct randomx_cache	randomx_cache
typedef struct randomx_vm	randomx_vm

Enumerations
enum	randomx_flags { RANDOMX_FLAG_DEFAULT = 0 , RANDOMX_FLAG_LARGE_PAGES = 1 , RANDOMX_FLAG_HARD_AES = 2 , RANDOMX_FLAG_FULL_MEM = 4 , RANDOMX_FLAG_JIT = 8 , RANDOMX_FLAG_SECURE = 16 , RANDOMX_FLAG_ARGON2_SSSE3 = 32 , RANDOMX_FLAG_ARGON2_AVX2 = 64 , RANDOMX_FLAG_ARGON2 = 96 }

Functions
RANDOMX_EXPORT randomx_flags	randomx_get_flags (void)
RANDOMX_EXPORT randomx_cache *	randomx_alloc_cache (randomx_flags flags)
RANDOMX_EXPORT void	randomx_init_cache (randomx_cache cache, const void key, size_t keySize)
RANDOMX_EXPORT void	randomx_release_cache (randomx_cache *cache)
RANDOMX_EXPORT randomx_dataset *	randomx_alloc_dataset (randomx_flags flags)
RANDOMX_EXPORT unsigned long	randomx_dataset_item_count (void)
RANDOMX_EXPORT void	randomx_init_dataset (randomx_dataset dataset, randomx_cache cache, unsigned long startItem, unsigned long itemCount)
RANDOMX_EXPORT void *	randomx_get_dataset_memory (randomx_dataset *dataset)
RANDOMX_EXPORT void	randomx_release_dataset (randomx_dataset *dataset)
RANDOMX_EXPORT randomx_vm *	randomx_create_vm (randomx_flags flags, randomx_cache cache, randomx_dataset dataset)
RANDOMX_EXPORT void	randomx_vm_set_cache (randomx_vm machine, randomx_cache cache)
RANDOMX_EXPORT void	randomx_vm_set_dataset (randomx_vm machine, randomx_dataset dataset)
RANDOMX_EXPORT void	randomx_destroy_vm (randomx_vm *machine)
RANDOMX_EXPORT void	randomx_calculate_hash (randomx_vm machine, const void input, size_t inputSize, void *output)
RANDOMX_EXPORT void	randomx_calculate_hash_first (randomx_vm machine, const void input, size_t inputSize)
RANDOMX_EXPORT void	randomx_calculate_hash_next (randomx_vm machine, const void nextInput, size_t nextInputSize, void *output)
RANDOMX_EXPORT void	randomx_calculate_hash_last (randomx_vm machine, void output)
RANDOMX_EXPORT void	randomx_calculate_commitment (const void input, size_t inputSize, const void hash_in, void *com_out)

Macro Definition Documentation

◆ RANDOMX_DATASET_ITEM_SIZE

#define RANDOMX_DATASET_ITEM_SIZE 64

◆ RANDOMX_EXPORT

#define RANDOMX_EXPORT

◆ RANDOMX_HASH_SIZE

#define RANDOMX_HASH_SIZE 32

Typedef Documentation

◆ randomx_cache

typedef struct randomx_cache randomx_cache

◆ randomx_dataset

typedef struct randomx_dataset randomx_dataset

◆ randomx_vm

typedef struct randomx_vm randomx_vm

Enumeration Type Documentation

◆ randomx_flags

enum randomx_flags

Enumerator
RANDOMX_FLAG_DEFAULT
RANDOMX_FLAG_LARGE_PAGES
RANDOMX_FLAG_HARD_AES
RANDOMX_FLAG_FULL_MEM
RANDOMX_FLAG_JIT
RANDOMX_FLAG_SECURE
RANDOMX_FLAG_ARGON2_SSSE3
RANDOMX_FLAG_ARGON2_AVX2
RANDOMX_FLAG_ARGON2

Function Documentation

◆ randomx_alloc_cache()

RANDOMX_EXPORT randomx_cache * randomx_alloc_cache ( randomx_flags flags )

Creates a randomx_cache structure and allocates memory for RandomX Cache.

Parameters

flags is any combination of these 2 flags (each flag can be set or not set): RANDOMX_FLAG_LARGE_PAGES - allocate memory in large pages RANDOMX_FLAG_JIT - create cache structure with JIT compilation support; this makes subsequent Dataset initialization faster Optionally, one of these two flags may be selected: RANDOMX_FLAG_ARGON2_SSSE3 - optimized Argon2 for CPUs with the SSSE3 instruction set makes subsequent cache initialization faster RANDOMX_FLAG_ARGON2_AVX2 - optimized Argon2 for CPUs with the AVX2 instruction set makes subsequent cache initialization faster

Returns: Pointer to an allocated randomx_cache structure. Returns NULL if: (1) memory allocation fails (2) the RANDOMX_FLAG_JIT is set and JIT compilation is not supported on the current platform (3) an invalid or unsupported RANDOMX_FLAG_ARGON2 value is set

◆ randomx_alloc_dataset()

RANDOMX_EXPORT randomx_dataset * randomx_alloc_dataset ( randomx_flags flags )

Creates a randomx_dataset structure and allocates memory for RandomX Dataset.

Parameters

flags is the initialization flags. Only one flag is supported (can be set or not set): RANDOMX_FLAG_LARGE_PAGES - allocate memory in large pages

Returns: Pointer to an allocated randomx_dataset structure. NULL is returned if memory allocation fails.

◆ randomx_calculate_commitment()

RANDOMX_EXPORT void randomx_calculate_commitment	(	const void *	input,
		size_t	inputSize,
		const void *	hash_in,
		void *	com_out )

Calculate a RandomX commitment from a RandomX hash and its input.

Parameters

input	is a pointer to memory that was hashed. Must not be NULL.
inputSize	is the number of bytes in the input.
hash_in	is the output from randomx_calculate_hash* (RANDOMX_HASH_SIZE bytes).
com_out	is a pointer to memory where the commitment will be stored. Must not be NULL and at least RANDOMX_HASH_SIZE bytes must be available for writing.

◆ randomx_calculate_hash()

RANDOMX_EXPORT void randomx_calculate_hash	(	randomx_vm *	machine,
		const void *	input,
		size_t	inputSize,
		void *	output )

Calculates a RandomX hash value.

Parameters

machine	is a pointer to a randomx_vm structure. Must not be NULL.
input	is a pointer to memory to be hashed. Must not be NULL.
inputSize	is the number of bytes to be hashed.
output	is a pointer to memory where the hash will be stored. Must not be NULL and at least RANDOMX_HASH_SIZE bytes must be available for writing.

◆ randomx_calculate_hash_first()

RANDOMX_EXPORT void randomx_calculate_hash_first	(	randomx_vm *	machine,
		const void *	input,
		size_t	inputSize )

Set of functions used to calculate multiple RandomX hashes more efficiently. randomx_calculate_hash_first will begin a hash calculation. randomx_calculate_hash_next will output the hash value of the previous input and begin the calculation of the next hash. randomx_calculate_hash_last will output the hash value of the previous input.

WARNING: These functions may alter the floating point rounding mode of the calling thread.

Parameters

machine	is a pointer to a randomx_vm structure. Must not be NULL.
input	is a pointer to memory to be hashed. Must not be NULL.
inputSize	is the number of bytes to be hashed.
nextInput	is a pointer to memory to be hashed for the next hash. Must not be NULL.
nextInputSize	is the number of bytes to be hashed for the next hash.
output	is a pointer to memory where the hash will be stored. Must not be NULL and at least RANDOMX_HASH_SIZE bytes must be available for writing.

◆ randomx_calculate_hash_last()

RANDOMX_EXPORT void randomx_calculate_hash_last	(	randomx_vm *	machine,
		void *	output )

◆ randomx_calculate_hash_next()

RANDOMX_EXPORT void randomx_calculate_hash_next	(	randomx_vm *	machine,
		const void *	nextInput,
		size_t	nextInputSize,
		void *	output )

◆ randomx_create_vm()

RANDOMX_EXPORT randomx_vm * randomx_create_vm	(	randomx_flags	flags,
		randomx_cache *	cache,
		randomx_dataset *	dataset )

Creates and initializes a RandomX virtual machine.

Parameters

flags	is any combination of these 5 flags (each flag can be set or not set): RANDOMX_FLAG_LARGE_PAGES - allocate scratchpad memory in large pages RANDOMX_FLAG_HARD_AES - virtual machine will use hardware accelerated AES RANDOMX_FLAG_FULL_MEM - virtual machine will use the full dataset RANDOMX_FLAG_JIT - virtual machine will use a JIT compiler RANDOMX_FLAG_SECURE - when combined with RANDOMX_FLAG_JIT, the JIT pages are never writable and executable at the same time (W^X policy) The numeric values of the first 4 flags are ordered so that a higher value will provide faster hash calculation and a lower numeric value will provide higher portability. Using RANDOMX_FLAG_DEFAULT (all flags not set) works on all platforms, but is the slowest.
cache	is a pointer to an initialized randomx_cache structure. Can be NULL if RANDOMX_FLAG_FULL_MEM is set.
dataset	is a pointer to a randomx_dataset structure. Can be NULL if RANDOMX_FLAG_FULL_MEM is not set.

Returns: Pointer to an initialized randomx_vm structure. Returns NULL if: (1) Scratchpad memory allocation fails. (2) The requested initialization flags are not supported on the current platform. (3) cache parameter is NULL and RANDOMX_FLAG_FULL_MEM is not set (4) dataset parameter is NULL and RANDOMX_FLAG_FULL_MEM is set

◆ randomx_dataset_item_count()

RANDOMX_EXPORT unsigned long randomx_dataset_item_count ( void )

Gets the number of items contained in the dataset.

Returns: the number of items contained in the dataset.

◆ randomx_destroy_vm()

RANDOMX_EXPORT void randomx_destroy_vm ( randomx_vm * machine )

Releases all memory occupied by the randomx_vm structure.

Parameters

machine is a pointer to a previously created randomx_vm structure.

◆ randomx_get_dataset_memory()

RANDOMX_EXPORT void * randomx_get_dataset_memory ( randomx_dataset * dataset )

Returns a pointer to the internal memory buffer of the dataset structure. The size of the internal memory buffer is randomx_dataset_item_count() * RANDOMX_DATASET_ITEM_SIZE.

Parameters

dataset is a pointer to a previously allocated randomx_dataset structure. Must not be NULL.

Returns: Pointer to the internal memory buffer of the dataset structure.

◆ randomx_get_flags()

RANDOMX_EXPORT randomx_flags randomx_get_flags ( void )

Returns: The recommended flags to be used on the current machine. Does not include: RANDOMX_FLAG_LARGE_PAGES RANDOMX_FLAG_FULL_MEM RANDOMX_FLAG_SECURE These flags must be added manually if desired. On OpenBSD RANDOMX_FLAG_SECURE is enabled by default in JIT mode as W^X is enforced by the OS.

◆ randomx_init_cache()

RANDOMX_EXPORT void randomx_init_cache	(	randomx_cache *	cache,
		const void *	key,
		size_t	keySize )

Initializes the cache memory and SuperscalarHash using the provided key value. Does nothing if called again with the same key value.

Parameters

cache	is a pointer to a previously allocated randomx_cache structure. Must not be NULL.
key	is a pointer to memory which contains the key value. Must not be NULL.
keySize	is the number of bytes of the key.

◆ randomx_init_dataset()

RANDOMX_EXPORT void randomx_init_dataset	(	randomx_dataset *	dataset,
		randomx_cache *	cache,
		unsigned long	startItem,
		unsigned long	itemCount )

Initializes dataset items.

Note: In order to use the Dataset, all items from 0 to (randomx_dataset_item_count() - 1) must be initialized. This may be done by several calls to this function using non-overlapping item sequences.

Parameters

dataset	is a pointer to a previously allocated randomx_dataset structure. Must not be NULL.
cache	is a pointer to a previously allocated and initialized randomx_cache structure. Must not be NULL.
startItem	is the item number where intialization should start.
itemCount	is the number of items that should be initialized.

◆ randomx_release_cache()

RANDOMX_EXPORT void randomx_release_cache ( randomx_cache * cache )

Releases all memory occupied by the randomx_cache structure.

Parameters

cache is a pointer to a previously allocated randomx_cache structure.

◆ randomx_release_dataset()

RANDOMX_EXPORT void randomx_release_dataset ( randomx_dataset * dataset )

Releases all memory occupied by the randomx_dataset structure.

Parameters

dataset is a pointer to a previously allocated randomx_dataset structure.

◆ randomx_vm_set_cache()

RANDOMX_EXPORT void randomx_vm_set_cache	(	randomx_vm *	machine,
		randomx_cache *	cache )

Reinitializes a virtual machine with a new Cache. This function should be called anytime the Cache is reinitialized with a new key. Does nothing if called with a Cache containing the same key value as already set.

Parameters

machine	is a pointer to a randomx_vm structure that was initialized without RANDOMX_FLAG_FULL_MEM. Must not be NULL.
cache	is a pointer to an initialized randomx_cache structure. Must not be NULL.

◆ randomx_vm_set_dataset()

RANDOMX_EXPORT void randomx_vm_set_dataset	(	randomx_vm *	machine,
		randomx_dataset *	dataset )

Reinitializes a virtual machine with a new Dataset.

Parameters

machine	is a pointer to a randomx_vm structure that was initialized with RANDOMX_FLAG_FULL_MEM. Must not be NULL.
dataset	is a pointer to an initialized randomx_dataset structure. Must not be NULL.

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

◆ RANDOMX_DATASET_ITEM_SIZE

◆ RANDOMX_EXPORT

◆ RANDOMX_HASH_SIZE

Typedef Documentation

◆ randomx_cache

◆ randomx_dataset

◆ randomx_vm

Enumeration Type Documentation

◆ randomx_flags

Function Documentation

◆ randomx_alloc_cache()

◆ randomx_alloc_dataset()

◆ randomx_calculate_commitment()

◆ randomx_calculate_hash()

◆ randomx_calculate_hash_first()

◆ randomx_calculate_hash_last()

◆ randomx_calculate_hash_next()

◆ randomx_create_vm()

◆ randomx_dataset_item_count()

◆ randomx_destroy_vm()

◆ randomx_get_dataset_memory()

◆ randomx_get_flags()

◆ randomx_init_cache()

◆ randomx_init_dataset()

◆ randomx_release_cache()

◆ randomx_release_dataset()

◆ randomx_vm_set_cache()

◆ randomx_vm_set_dataset()