Go to main content

man pages section 3: DAX Library Functions

Exit Print View

Updated: Friday, August 13, 2021
 
 

dax_translate (3DAX)

Name

dax_translate - translate each vector element to 0 or 1

Synopsis

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

#include <dax.h>

dax_result_t
dax_translate(dax_context_t *ctx, uint64_t flags,
    dax_vec_t *src, dax_vec_t *dst, dax_vec_t *bitmap,
    unsigned val_width);

Description

This function translates each element in src to 0 or 1 and writes the value to the corresponding element of the dst bit vector. It uses the value x of the ith element in src as an index into bitmap, and writes the xth element in bitmap to the ith element of the dst bit vector.

dst[i] = bitmap[src[i]];

The following rules apply during translation:

  • Width of the element in src may be any of the following:

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

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

  • src may be fixed width or run-length encoded, but cannot be zipped.

  • bitmap->elem_width must be 1 and format must be DAX_BITS.

  • bitmap->offset must be 0.

  • bitmap->data must be aligned on a 64 byte boundary.

  • bitmap->elements count must not exceed 16M.

val_width is the number of significant low-order bits of each element to use in the index value. It must be less than or equal to the width of the element.

High-order bits above val_width must be 0 in all elements. libdax checks these conditions only if the DAX_DEBUG_EXTRA debug option is set. If this condition is violated and not checked, you will get undefined results.

DAX supports bitmaps up to 32K bits natively, and up to 16M bits with reduced efficiency by making multiple passes over the src data. If the number of bitmap elements is less than the largest value in src plus 1, the results are undefined. The DAX_DEBUG_EXTRA debug option checks this condition.

The dst->offset field must be set to 0.

If you omit the DAX_ONES_INDEX flag, the width of the elements in dst must be 1 bit and the number of elements in dst must be at least the number of elements in src, where the latter number includes expansion from run-length encoding. If src is run-length encoded, this condition is only checked if the DAX_DEBUG_EXTRA debug option is set.

The data in dst must start on a 64 byte boundary. You must round up the size of the data in dst as described in the dax_vec_t(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 src->aux_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_INVERT

Inverts the result of translation. 0 becomes 1, and 1 becomes 0.

DAX_ONES_INDEX

Instead of writing a single 0 or 1 bit to dst for each element in src, write the index of the src element for which the translation is 1 (after inversion if specified). The indices start at 0. The width of the elements in dst may be 2 or 4 bytes, and correspondingly writes each index as a 2 or 4-byte big-endian word. If the index is too large for the word, writes the maximum unsigned value for the word in libdax versions 1 and 2. The number of elements in dst must be at least the number of elements that translate to 1. If this is not known, use the number of elements in src as an upper bound.

Limits the number of elements in src to 232 when you specify this flag. For the usage notes, see the dax_scan_value(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.

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 elements that translate to 1 in the dax_result_t count field (after inversion if specified) 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.

Usage

You can use the translate() function to test for set membership. The bitmap is a bit set, where element x is 1 if value x is a member of the set. The ith element in dst is 1 if the ith element in src is a member of the set.

For best performance, align the bitmap data to the value of the trans_bitmap_align_best property as defined in the dax_get_props(3DAX) man page.

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)