Go to main content

man pages section 3: DAX Library Functions

Exit Print View

Updated: Friday, August 13, 2021
 
 

dax_select (3DAX)

Name

dax_select - copy selected values from input to output

Synopsis

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

#include <dax.h>

dax_result_t
dax_select(dax_context_t *ctx, uint64_t flags,
    dax_vec_t *src, dax_vec_t *dst, dax_vec_t *mask);

Description

This function copies selected elements of src to contiguous elements of dst. It selects the ith element in src if the ith bit in the mask bit vector is 1.

If src is zipped, translates each code word of src by using the src codec and produces a 1 to 8 byte symbol which it appends to an intermediate unzip stream. It then partitions the unzip stream into elements at src->elem_width boundaries, and selects the ith element in src if the ith bit in the mask bit vector is 1.

The parameters of this function must meet the following conditions:

  • Width of an element in src can be any of the following:

    • 1 to 16 bits or 1 to 16 bytes in libdax version 1

    • 1 to 24 bits or 1 to 16 bytes in libdax version 2

  • src must be fixed width.

  • Width of the mask element must be 1 bit, and format must be DAX_BITS.

  • The mask->offset field specifies the bit in the first mask data byte where the bit vector starts from 0 (MSB) to 7 (LSB).

  • The number of elements in mask must be at least the number of elements in src.

  • The dst->offset field must be 0.

  • Width of an element in dst can be any of 1, 2, 4, 8, or 16 bytes.

  • Number of elements in dst must be at least the number of selected elements. If this is not known, use the number of elements in src as an upper bound.

  • dst->data must start on a 64 byte boundary. You must round up the size of the dst->data as described in the dax_vec_t(3DAX) man page.

  • If the width of a src element is larger than the width of a dst element, this function truncates the element.

  • If the width of a src element is smaller, this function pads the element. For more information, see the dax_extract(3DAX) man page.

The following address ranges must not overlap:

  • Address range of the src->data vector and the dst->data vector.

  • Address range of the mask->data vector and the dst->data vector.

The libdax library checks the overlap in the address ranges only if the DAX_DEBUG_EXTRA debug option is set. If violations of the conditions occur and are not checked, you will get undefined results.

Supported Flags

DAX_PAD_RIGHT

For more information, see the dax_extract(3DAX) man page.

DAX_CACHE_DST

Writes results to cache. If not specified, invalidates the address range for dst in the cache, and writes the result to the main memory. For more information, see the dax_scan_value(3DAX) man page.

DAX_NOWAIT

If the DAX command queue is full, returns without submitting the command, instead of waiting to submit.

Return Values

Returns the number of selected elements in the dax_result_t count field and sets the dax_result_t status field to one of the following values:

DAX_SUCCESS

Operation completed successfully

DAX_EINVAL

Invalid argument, detected by libdax.

DAX_EPARSE

Invalid argument, detected by DAX.

DAX_EDATAFMT

The true value of an aux_data element is 0, or the width of a zip symbol is less than 1 or greater than 8, detected by DAX.

DAX_EOVERFLOW

Output buffer overflow

DAX_EADI

ADI mismatch error for an input or output buffer

DAX_ETHREAD

The calling thread did not create ctx

DAX_EBUSY

DAX is busy and nowait was requested.

DAX_EINTERNAL

Unknown internal error. Caller must stop using ctx.

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_vec_t(3DAX), dax_adi(3DAX), dax_dtrace(3DAX), dax_scan_value(3DAX), dax_zip(3DAX)