Go to main content

man pages section 3: DAX Library Functions

Exit Print View

Updated: Friday, August 13, 2021
 
 

dax_vec_t (3DAX)

Name

dax_vec_t - vector of input or output elements for DAX

Description

The dax_vec_t structure represents a vector of elements. Both the input and the output vectors use the same structure.

The members of the dax_vec_t structure are:

elements

The number of elements in the vector

elem_width

The width of each element, for fixed-width elements.

format

If (format & DAX_BITS), elem_width has units of bits, else it has units of bytes. If a width may be represented as either bits or bytes, you are free to use either. For example, elem_width=2 and format=DAX_BYTES is equivalent to elem_width=16 and format=DAX_BITS.

If (format & DAX_VAR), the vector elements are variable width, and ignores the elem_width. If (format & DAX_ADD_ONE), the width of the ith element of data in bytes is 1 plus the ith element of aux_data. For example, if the ith element of aux_data has value 0, the width of the ith element of data is 1 byte. If DAX_ADD_ONE is not specified, the width of the ith element of data is the ith element of aux_data. The true value of a width must not be 0.

If (format & DAX_RLE), the vector is run-length encoded. Implicitly repeats each element of data multiple times before using it as an input to a function. If (format & DAX_ADD_ONE), the repeat count for the ith data element is 1 plus the ith element of aux_data. For example, if the ith element of aux_data has value 2, repeats the ith element of data 3 times. If DAX_ADD_ONE is not specified, the repeat count for the ith element of data is the ith element of aux_data. The true value of a repeat count must not be 0.

If (format & DAX_ZIP), the vector data is zipped, and may be unzipped by using the codec. The element width and number of elements are the width and number in the original unzipped vector. The length in bytes of the zipped data is implicit. aux_data is not zipped.

All other bits in format must be 0.

To improve readbility, you can use the DAX_BYTES and the DAX_FIXED constants to initialize the format field. Because the constants have the value as 0, the initialization is cosmetic. For example, src->format = DAX_FIXED | DAX_BYTES;

data

Pointer to a block of memory containing all the elements. Elements are bit-packed in contiguous memory locations with no padding or terminator between each element.

If the data is not zipped, the size of the block in bits must be at least:

elements * elem_width_bits + offset

where:

elem_width_bits = (format & DAX_BITS) ?
    elem_width : (8 * elem_width);

If the data is zipped, the length of the block is the length of the compressed data.

offset

The bit in the first data byte where the first data element starts, from 0 (MSB) to 7 (LSB).

If the format is zipped, offset is the bit where the first code word starts.

If the format is not zipped, and the element width is greater than 8 bytes, then the offset must be 0.

If the format is zipped, offset is the bit where the compressed data starts; it does not apply to the unzipped data stream.

aux_data

Pointer to an array of runs or widths. Elements are bit-packed in contiguous memory locations with no padding or terminator between each element.

aux_offset

The bit in the first data byte where the first aux_data element starts, from 0 (MSB) to 7 (LSB).

aux_width

The width of each element in aux_data, in units of bits. The width can be 1, 2, 4, or 8 bits. If (format & DAX_VAR) and aux_width = 8, the upper 4 bits of each element in aux_data must be 0.

codec

Decoder for zipped data.

codewords

Number of code words in zipped data.

An element can start and end on any bit within a byte, and span byte boundaries. Each element is big endian. The position of each element runs from 0 to elements - 1, inclusive. Position increases from left to right, ie from MSB to LSB within a byte, and from low address to high address across bytes. The phrase ith element refers to the element in position i.

A bit vector is a special case of dax_vec_t in which elem_width is 1 bit and format is DAX_BITS.

When you use a dax_vec_t for the output of a DAX operation, the size of data in bytes must be at least the expected size of the output in bytes rounded up to the next 64 byte boundary, plus 64 bytes. If elements represents the number of output elements, the computation of the required size in bytes is as follows:

      dst_pad = 64;
      n = dst_pad * 8;
      size = ((elements * elem_width_bits + n - 1) / n * n) / 8;

You can compute the size by using the DAX_OUTPUT_SIZE(elements,elem_width_bits) macro.

Only the variable-length and run-length encoded formats use the aux_data, aux_offset, and aux_width fields. Ignores these fields in all other formats.

Attributes

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

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Availability
system/library
Interface Stability
Committed

See Also

libdax(3LIB)