Go to main content

man pages section 3: DAX Library Functions

Exit Print View

Updated: Friday, August 13, 2021
 
 

dax_zip (3DAX)

Name

dax_zip - compress data and create codec

Synopsis

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

#include <dax.h>

dax_result_t
dax_zip(dax_context_t *ctx, uint64_t options, dax_vec_t *src, void *buf,
    size_t *buflen, dax_zip_t **codec);

Description

This function zips data in src and writes the code word stream to buf. The buflen parameter specifies the size of buf in bytes. It returns an encoder or decoder in codec, which you can pass to libdax functions that unzip data. The codec should be destroyed when no longer needed by using the dax_zip_free function. It returns the number of bytes written to buf in buflen.

Supported Flags

DAX_ZIP_HIGH

Derive a codec that yields a higher compression ratio for src. This requires more memory and CPU time.

Return Values

Returns the number of code words written to buf 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_ENOMEM

Memory resources unavailable

DAX_EOVERFLOW

Output buffer overflow. Returns the required buffer size in buflen and modifies buf.

DAX_ETHREAD

The calling thread did not create ctx

DAX_EZIP

Cannot compress the data in src. The size of the compressed data plus the size of the codec exceeds the size of the src data. buf may be modified.

Usage

After calling the dax_zip() function, you can create a dax_vec_t with data pointing to buf, and pass it to the DAX functions that unzip data.

Examples

Example 1 
#include <stdio.h>
#include <stdlib.h>
#include <strings.h>
#include <dax.h>

#define ELEM_BITS(vec) \
    ((vec->format & DAX_BITS) ? \
    vec->elem_width : (8 * vec->elem_width))

#define VEC_LEN(vec) \
    ((vec->elements * ELEM_BITS(vec) + vec->offset + 7) / 8)

void compress(dax_context_t *ctx, dax_vec_t *src)
{
        dax_result_t res;
        dax_zip_t *codec;
        size_t len = VEC_LEN(src);
        void *buf = memalign(64, len);

        res = dax_zip(ctx, DAX_ZIP_HIGH, src, buf, &len, &codec);
        if (res.status == DAX_EOVERFLOW) {
                printf("data is not compressible.\n");
                return;
        }
        src->data = realloc(buf, len);
        src->format |= DAX_ZIP;
        src->codec = codec;
        src->codewords = res.count;
}

void decompress(dax_context_t *ctx, dax_vec_t *src)
{
        dax_result_t res;
        size_t dstlen = DAX_OUTPUT_SIZE(VEC_LEN(src), 8);
        void *dstbuf = memalign(64, dstlen);
        dax_vec_t dst = {dstlen, dstbuf, DAX_BYTES, 1};

        res = dax_extract(ctx, 0, src, &dst);
        free(src->data);
        (void) dax_zip_free(ctx, src->codec);
        src->data = dstbuf;
        src->format &= ~DAX_ZIP;
        src->codec = NULL;
}      

Attributes

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

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Availability
system/library
Interface Stability
Committed

See Also

dax_encode(3DAX), dax_extract(3DAX), dax_zip_free(3DAX), libdax(3LIB)

Notes

The DAX hardware does not compress the data. Compression is implemented in software.

The zipped format of this function is not the same format supported by the zip(1) command.

The zipped buf is a contiguous stream of fixed-width code words with no padding between each. The codec provides the width of the code word which can be 1 to 10 bits wide, and each code word is big endian. The code word order increases from left to right (from MSB to LSB) within each byte and from low address to high address across bytes. Each code word represents a symbol of 1 to 8 bytes in length. The symbols are defined in codec.