Go to main content

man pages section 3: DAX Library Functions

Exit Print View

Updated: Friday, August 13, 2021
 
 

dax_dtrace (3DAX)

Name

dax_dtrace - DTrace probes for libdax

Description

The libdax library defines the following DTrace SDT probes. The provider name is dax.

dax-post

This probe is called when any of the dax_post_xxxx() functions post a request to DAX. If a function posts multiple DAX requests, this probe is called for each request.

The arguments for this probe are as follows:

arg0 is dax_context_t *

Context passed to the post function

arg1 is dax_queue_t *

Queue passed to the post function

arg2 is uint64_t

udata passed to the post function

dax-execute

This probe is called when a non-post DAX function completes.

The arguments for this probe are as follows:

arg0 is uint64_t

A filter word that contains a small amount of data describing the command. You can use it in a filter expression, without incurring the cost of a copyin. The filter word has the following format:

Bits:  63-32     31-24  23-16  15-0
Field: reserved  major  minor  cmd

cmd is the DAX command that executed, with values from dax_cmd_t. You can access this sub-field by using the DAX_DFILTER_CMD(filter) convenience macro.

major is the major version of the API used by the ctx that generated this probe. You can access this sub-field by using the DAX_DFILTER_MAJOR(filter) convenience macro.

minor is the minor version of the API used by the ctx that generated this probe. You can access this sub-field by using the DAX_DFILTER_MINOR(filter) convenience macro.

arg1 is dax_request_t *

Structure that describes the operation

arg2 is dax_result_t *

Structure that describes the result of the operation

arg3 is dax_perf_event_t *

Structure that describes the performance events that occurred during this operation

dax-poll

This probe is called when a DAX post function completes asynchronously.

The argument types and definitions are identical to the dax-execute probe.

dax_request_t Structure

This structure contains the arguments passed to the libdax function that called the probe. The description of the arguments are:

major and minor

The version of the API used by the ctx that generated this probe

ctx

DAX context passed to the libdax function that called the probe

flags

The flags argument passed to the function

udata

The udata argument passed to the post function, or NULL for a non-post function. If udata is unique per request, you can use it in the script as an index into an associative array to track information related to the request, such as a starting timestamp.

queue

The queue argument passed to the post function, or NULL for a non-post function

cmd

Indicates the type of the command that executed. The following table shows which fields are valid for each value of cmd.

cmd
Fields
DAX_CMD_SCAN_VALUE
src, dst, scan_value
DAX_CMD_SCAN_RANGE
src, dst, scan_range
DAX_CMD_TRANSLATE
src, dst, translate
DAX_CMD_SELECT
src, dst, select
DAX_CMD_EXTRACT
src, dst
DAX_CMD_COPY
copy
DAX_CMD_FILL
fill
DAX_CMD_AND
src, src2, dst
DAX_CMD_OR
src, src2, dst
DAX_CMD_XOR
src, src2, dst

dax_perf_event_t Structure

This structure contains the performance events. The description of the performance events is as follows:

page

Number of physical pages that were crossed during the execution of the function. Each crossing causes an additional command to be submitted to DAX.

You can reduce crossings by mapping buffers with larger pages. For more information, see the MC_HAT_ADVISE option of memcntl(2).

retry

Number of times command was re-submitted because of transient resource contention. This is usually 0, but may increase because of high system load.

emulate

Has the value 1 if some or all of the command failed to run on DAX and was emulated in software, else 0. Emulation of commands occurs in conditions such as transient resource contention, to guarantee completion.

nomap

Number of times this command was re-submitted because a buffer address was not translatable, else 0. This is usually 0, but may increase because of high system load.

copy

Has the value 1 if the command uses an intermediate source or destination buffer. This can occur in page crossing commands and commands that are long because of DAX alignment restrictions.

unzip

Has the value 1 if the command unzipped the src into a temporary buffer. This can occur in page crossing commands and commands that are long because of DAX alignment restrictions.

split

Number of times a long command was split at the maximum size supported by DAX and submitted as multiple hardware commands.

Splitting of a command happens because its src vector or its dst vector is too long. The max_src_len and max_dst_len values in the dax_get_props() function define the length of the src and dst vectors.

Splitting of a command does not affect its functionality, but sometimes reduces its efficiency when compared to explicitly passing multiple shorter vectors. If the copy or unzip event is non-zero, you can improve the performance by passing shorter vectors.

cycles

Number of cycles DAX spent executing the command, excluding queueing delay and command fetching time.

frequency

DAX frequency, in MHz.

Examples

The following example shows how to run the dax.d D script that displays various events for each DAX command listed in the script.

The dax.d D script is as follows.

#include <dax.h>

#pragma D option quiet

#define PRINT_COMMAND(i)                                     \
     printf("%10s %7d %9d %9d %5d %5d %5d %5d %5d %5d %3d\n",\
         Cmd[i], Count[i], Elements[i], Events[i].cycles,    \
         Events[i].page, Events[i].split, Events[i].unzip,   \
         Events[i].copy, Events[i].retry, Events[i].nomap,   \
         Events[i].emulate)

#define END_COMMAND(cmd)             \
     dtrace:::END                    \
     / Count[cmd] != 0 /             \
     {                               \
             PRINT_COMMAND(cmd);     \
     }

dax_perf_event_t Events[10];
long Elements[10];
long Count[10];

dtrace:::BEGIN
{
     Cmd[DAX_CMD_SCAN_VALUE] = "scan_value";
     Cmd[DAX_CMD_SCAN_RANGE] = "scan_range";
     Cmd[DAX_CMD_TRANSLATE] = "translate";
     Cmd[DAX_CMD_SELECT] = "select";
     Cmd[DAX_CMD_EXTRACT] = "extract";
     Cmd[DAX_CMD_COPY] = "copy";
     Cmd[DAX_CMD_FILL] = "fill";
     Cmd[DAX_CMD_AND] = "and";
     Cmd[DAX_CMD_OR] = "or";
     Cmd[DAX_CMD_XOR] = "xor";
}

dax$target:::dax-execute,
dax$target:::dax-poll
{
     cmd = DAX_DFILTER_CMD(arg0);
     req = (dax_request_t *) copyin(arg1, sizeof(dax_request_t));
     res = (dax_result_t *) copyin(arg2, sizeof(dax_result_t));
     ev = (dax_perf_event_t *) copyin(arg3, sizeof(dax_perf_event_t));
     Count[cmd]++;
     elements = (cmd == DAX_CMD_COPY ? req->arg.copy.count :
         (cmd == DAX_CMD_FILL ? req->arg.fill.count :
          req->src.elements));
     Elements[cmd] += elements;
     Events[cmd].frequency = ev->frequency;
     Events[cmd].cycles += ev->cycles;
     Events[cmd].page += ev->page;
     Events[cmd].emulate += ev->emulate;
     Events[cmd].nomap += ev->nomap;
     Events[cmd].copy += ev->copy;
     Events[cmd].retry += ev->retry;
     Events[cmd].split += ev->split;
     Events[cmd].unzip += ev->unzip;
}

dtrace:::END
{
     printf("%10s %7s %9s %9s %5s %5s %5s %5s %5s %5s %3s\n",
         "command", "count", "elems", "cycles", "cross", "split",
         "unzip", "copy", "retry", "nomap", "em");
}

END_COMMAND(DAX_CMD_SCAN_VALUE)
END_COMMAND(DAX_CMD_SCAN_RANGE)
END_COMMAND(DAX_CMD_TRANSLATE)
END_COMMAND(DAX_CMD_SELECT)
END_COMMAND(DAX_CMD_EXTRACT)
END_COMMAND(DAX_CMD_COPY)
END_COMMAND(DAX_CMD_FILL)
END_COMMAND(DAX_CMD_AND)
END_COMMAND(DAX_CMD_OR)
END_COMMAND(DAX_CMD_XOR)

To run the dax.d D script, use the following commands:

# DAX_DEBUG_OPTIONS=perf; export DAX_DEBUG_OPTIONS
# dtrace -Cs dax.d -I$inc -c a.out

Attributes

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

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Availability
system/library
Interface Stability
Committed

See Also

libdax(3LIB), dax_get_props(3DAX)