nx_get_exclusive_access() subroutine

Edit online

Purpose

Reserves a specific number of quality of service (QoS) credits for exclusive use.

Syntax

#include <sys/nx.h>
int nx_get_excl_access(nx_accel_type_t accel_type,
                       uint32_t        flags,
                       int             number_of_credits,
                       nx_unit_id_t    unit_id);
Note: Currently, NX_GZIP_TYPE is the only accelerator type that is supported. You must specify NX_GZIP_TYPE in the accel_type parameter.

Description

A privileged application can use this subroutine to reserve a specific number of QoS credits for exclusive use. The credits can be requested from a specific accelerator unit that can be identified by its unit ID. The unit_id value is in the configuration data of each accelerator unit section that is returned by the nx_config_query subroutine.

A special value, NX_ANY_UNIT, can be used instead of the unit_id value if the application has no preference as to where the credits are allocated. Another special value, NX_ALL_CREDITS, can be used to request all the accelerator credits that are allocated to the specified accelerator unit. The special value, NX_ALL_CREDITS, can also be used along with NX_ANY_UNIT value to request all the accelerator credits that are allocated to the logical partition.

A privileged application that uses the zlib interface uses this subroutine to directly reserve a number of GZIP accelerator credits. The subsequent data compression and decompression requests use this pool of reserved QoS credits.

While checking, if this subroutine determines that the calling application has either root or PV_KER_NXFR privileges, the subroutine returns -1 and otherwise, returns EPERM. When this subroutine is run successfully, the subroutine returns a positive value that indicates the number of allocated credits.

If a specific number of credits are requested and sufficient QoS credits are not available to satisfy the request, the request fails, and no credits are allocated. If the NX_ALL_CREDITS value is requested, the subroutine returns the number of QoS credits that are allocated. If the QoS credits are not available, it returns an error. Requesting 0 credits is also flagged as an error.

The reserved credits are released through the nx_rel_exclusive_access subroutine or released automatically when the application exits.

Return values

>0
Indicates success. The value indicates the number of credits that are allocated for exclusive access.
0
This subroutine does not return this value.
-1
An error is detected. The errno variable is set to indicate the type of error:
  • ENOTSUP: Logical partition cannot access a nest accelerator.
  • EPERM: Calling application does not have the correct privilege level.
  • EINVAL: Invalid flags, invalid number of credits, or invalid unit ID.
  • ENOMEM: Memory allocation failed.
  • ENOSPC: Insufficient QoS credits to satisfy the request or credits are not reserved.