accel_decompress Subroutine

Purpose

Decompresses data by using hardware accelerated memory decompression or a slower software decompression if a hardware accelerator is not available.

Syntax

#include <sys/types.h>

#include <sys/vminfo.h>

int accel_decompress (void *c_buf, size_t c_len,
void *uc buf, size_t *uc_lenp, int flags);

Description

Given a pointer to a buffer with data to decompress (the c_buf parameter), the accel_decompress subroutine returns the decompressed data in the buffer pointed to by the uc_buf parameter.

The compression subroutine should be called with the uc_lenp parameter initialized to the total size of the uc_buf parameter. Upon successful return, the uc_lenp parameter is updated with the size of the compressed data in the uc_buf parameter. The following restrictions apply to this subroutine.
  • There is no overlapping of the uc_buf parameter and the c_buf parameter. An overlap results in an error.
  • The uc_buf and c_buf parameters must be aligned at least on a 128 byte boundary. For the best result, both uc_buf and c_buf parameters must be aligned on a 4096 byte boundary.

  • The c_len and *uc_lenp parameters are limited to a maximum of 1044480 bytes per subroutine call when buffers are aligned on a 4096 byte boundary. For buffers that are not aligned on a 4096 byte boundary, but are aligned on a 128 byte boundary, the c_len and *uc_lenp parameters are limited to 1040384 bytes per subroutine call plus any alignment offset from a 4096 byte boundary.

  • The uc_lenp and c_len parameters must be a multiple of 8 bytes.
  • The mapping of file segments with the shmat() function and the mmap() function are not allowed. However, the mapping of non-file segments with the shmat() function and the mmap() function are allowed (for example, MMAP_ANONYMOUS).
  • The caller is responsible for supplying a large enough uc_buf.

The subroutine uses the 842 algorithm to decompress the data. The compressed buffer includes a cyclic redundancy check (CRC) that is added by the accel_compress() subroutine, which is verified against the uncompressed data. If an hardware accelerator is not available in the system that is used for decompression, the call uses the software decompression method. The subroutine supports both 32 bit and 64 bit applications.

Hardware accelerators are a finite resource on any system and you must be careful to not overwhelm the accelerators. If you have a large pool of threads all competing for a few of the available accelerators, you can end up with worse performance than with pure software decompression.

Parameters

Item Description
c_buf Pointer to input buffer with data to decompress.
c_len Length of compressed data in the c_buf parameter.
uc_buf Pointer to out buffer written with decompressed data.
uc_lenp Pointer to in/out parameter. On entry, the uc_lenp parameter is the total available size in the uc_buf parameter and on exit, the uc_lenp parameter is the number of bytes written to the uc_buf parameter.
flags Reserved for future use. This parameter must be set to zero.

Execution environment

The accel_decompress subroutine can be called from the process environment only.

Return Values

Item Description
0 Success
1 Error. On failure, the errno global variable is set as follows:
EFAULT
Error accessing memory pointed to by the c_lenp parameter or access error on the source or target buffer.
EINVAL
Error due to one of the following conditions:
  • The uc_buf and c_buf parameters have wrong alignment.
  • The uc_buf and c_buf parameter overlap.
  • The uc_lenp or c_len parameter is not a multiple of 8.
  • The uc_buf, c_buf, or c_lenp parameter is NULL.
  • Failed to create a list of the uc_buf or c_buf parameter pages to pass on to the accelerator hardware.
  • The uc_buf or c_buf parameters are in a file.
  • The flags parameter is a nonzero value.
ENOMEM
Failed to allocate memory inside the subroutine.
EFBIG
The uc_lenp or the c_len parameter exceed 1,044,480 bytes.
EIO
The firmware call failed or the accelerator hardware returned a failure of unknown type. This might include errors caused by incorrect input arguments to the accel_decompress() subroutine.
ECORRUPT
The compressed data is invalid or doesn't match embedded CRC.
ENOSPC
The output buffer is too small to hold all decompressed data.