accel_compress Subroutine

Purpose

Compresses data by using hardware accelerated memory compression.

Syntax

#include <sys/types.h>

#include <sys/vminfo.h>

int accel_compress (void *uc_buf, size_t uc_len,
void *c.buf, size_t *c_lenp, int flags);

Description

Given a pointer to a buffer with data to compress, the accel_compress subroutine compresses the data into the buffer pointed to by the c_buf parameter.

The compression subroutine should be called with the c_lenp parameter initialized to the total size of the c_buf parameter. Upon successful return, the c_lenp parameter is updated with the size of the compressed data in the c_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 results, 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_len and c_lenp 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 c_buf.

The subroutine uses the 842 algorithm to compress the data. The compressed buffer includes a cyclic redundancy check (CRC) which is automatically checked by the accel_decompress() subroutine. The Active Memory Expansion (AME) and Active Memory Sharing (AMS) features must not be enabled to use this call. The subroutine supports both 32 and 64 bit applications. The subroutine can be called from either a single or multi-threaded process.

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 compression.

Parameters

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

Execution environment

The accel_compress 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_len or c_lenp 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.
ENOSYS
The hardware accelerator is not available, or AME is enabled, or AMS is enabled.
ENOMEM
Failed to allocate memory inside the subroutine.
EFBIG
The uc_len or the c_lenp 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_compress() subroutine.
ENOSPC
The c_buf parameter is too small to hold the entire compressed output.
ERANGE
The compressed data is larger than the uncompressed data.