Go to main content

man pages section 3: DAX Library Functions

Exit Print View

Updated: Friday, August 13, 2021
 
 

dax_thread_init (3DAX)

Name

dax_thread_init - create a command context

Synopsis

cc [ flag... ] file... -ldax [ library...]

#include <dax.h>

dax_status_t
dax_thread_init(unsigned major, unsigned minor, uint64_t options,
    dax_init_options_t *args, dax_context_t **ctx);

Description

This function initializes the DAX for use by the calling thread and returns a DAX context in ctx. Only the thread that creates the context should use it.

The major parameter identifies the major version of the libdax API to be used, and minor identifies the minor version. Supported combinations are:

major
minor
11
21

The following are the values for the options parameter, and they can be logically OR'd together:

DAX_ALLOC

The libdax library uses the args->alloc_func() and args->free_func() functions to allocate and free memory in DAX functions that use ctx. The alloc_func() must return a pointer that is at least 8 byte aligned. The functions use the following arguments:

ptr = alloc_func(size, args->cb_data);
free_func(ptr, size, args->cb_data);
DAX_EMULATE

By default, DAX operations are done in hardware when possible, and emulated in software when hardware support is not present. DAX_EMULATE forces software emulation to be used in all cases. Software emulation can also be selected at runtime, by setting the DAX_EMULATE environment variable to 1.

Sets debug options for ctx to the value of the DAX_DEBUG_OPTIONS environment variable if it is defined, else sets options to DAX_DEBUG_ARG. The format of DAX_DEBUG_OPTIONS is a comma separated list of option names with no whitespace. Recognized names are "arg", "extra", and "all". The latter enables all options. For more information, see the dax_set_debug(3DAX) man page.

Sets log options for ctx to the value of the DAX_LOG_OPTIONS environment variable if it is defined, else sets the options to DAX_LOG_OFF. The format of DAX_LOG_OPTIONS is a comma separated list of option names with no whitespace. Recognized names are "error", "warn", "entry", "return", "perf", "verbose", and "all". The latter enables all options. For more information, see the dax_set_log(3DAX) man page.

Sends log messages to the file descriptor specified by the DAX_LOG_FD environment variable. Its format is an integer. Sends messages to syslog(3c) if DAX_LOG_OPTIONS is set but DAX_LOG_FD is not defined.

Return Values

DAX_SUCCESS

Operation completed successfully

DAX_EBADVER

Bad API version

DAX_ENOACCESS

Caller does not have permission to use DAX

DAX_ENOMEM

Memory resources are unavailable

DAX_ENODEV

No DAX device present

DAX_EINVAL

Unknown options, or DAX_ALLOC is specified and alloc_func() or free_func() is NULL.

DAX_EINTERNAL

Unknown internal error

Usage

For best performance, the alloc_func() function should return memory backed by large pages. Oracle Solaris creates large pages by default, and you can change the default page size by using the MC_HAT_ADVISE option of memcntl(2).

DAX_EMULATE is useful for developing libdax applications on platforms that do not support DAX hardware. But emulation is not recommended for production, as the emulation functions are not optimized and performance will be low.

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Availability
system/library
Interface Stability
Committed

See Also

dax_thread_fini(3DAX), dax_set_debug(3DAX), dax_set_log(3DAX), libdax(3LIB), privileges(7), memcntl(2)