Go to main content

man pages section 3: Basic Library Functions

Exit Print View

Updated: Wednesday, July 27, 2022
 
 

adi(3C)

Name

adi, adi_clr_version, adi_get_version, adi_set_version, adi_memset, adi_get_precise, adi_set_precise - Application Data Integrity operations

Synopsis

#include <sys/types.h>
#include <adi.h>

caddr_t adi_clr_version(caddr_t addr, size_t size);

int adi_get_version(caddr_t addr);

caddr_t adi_set_version(caddr_t addr, size_t size, int version);

caddr_t adi_memset(caddr_t addr, int c, size_t size, int version);

int adi_get_precise(void);

int adi_set_precise(int mode);

Overview

Application Data Integrity (ADI) is a SPARC hardware feature that detects invalid memory accesses in 64-bit software. See the adi(7) man page for additional information on the ADI feature.

Description

The following C Library functions provide the ADI API to 64-bit applications:

  • The adi_clr_version() function clears (sets to 0) all ADI version tags for the specified range of ADI-enabled memory. Load and store instructions that reference a memory location with a clear ADI version will not cause a mismatch exception.

  • The adi_get_version() function returns the ADI version for a memory address assigned to a region of ADI-enabled memory.

  • The adi_set_version() function sets the ADI version tags to a specified version for a specified range of ADI-enabled memory.

  • The adi_memset() function sets the bytes in an ADI-enabled memory range to the value of c (converted to an unsigned char) and sets the ADI version tags of the memory range to the specified version number. Calling the adi_memset() function is more efficient than calling the memset() and the adi_set_version() functions separately.

  • The adi_get_precise() function returns the current state of the ADI precise exception mode for the calling thread.

  • The adi_set_precise() function sets the current state of the ADI precise exception mode for the calling thread. The value of mode can either be ADI_PRECISE_ENABLE or ADI_PRECISE_DISABLE.

Return Values

On success, the adi_clr_version() function returns a non-versioned address pointer to the specified memory. Otherwise, the function returns the value (caddr_t)-1 and sets errno to indicate the error.

On success, the adi_get_version() function returns the ADI version tag value for the specified address. Otherwise, the function returns the value -1 and sets errno to indicate the error.

On success, the adi_set_version() and the adi_memset() functions return a versioned address pointer to the specified memory. Otherwise, the functions return the value (caddr_t)-1 and set errno to indicate the error.

On success, the adi_get_precise() function returns the value ADI_PRECISE_DISABLE or ADI_PRECISE_ENABLE, to indicate the current state of ADI precise exception mode. Otherwise, the function returns the value -1 and sets errno to indicate the error.

On success, the adi_set_precise() function returns the value ADI_PRECISE_DISABLE or ADI_PRECISE_ENABLE, to indicate the previous state of ADI precise exception mode. Otherwise, the function returns the value -1 and sets errno to indicate the error.

Errors

The ADI libc library calls will fail if:

ENOTSUP
  • ADI is not supported by the platform.

  • ADI is not supported for 32-bit processes.

EINVAL

The version argument is greater than the maximum version value returned by the adi_version_max(2) function.

The precise exception mode value specified is not ADI_PRECISE_ENABLE or ADI_PRECISE_DISABLE.

Attributes

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

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Volatile
MT-Level
MT-Safe

See Also

adi(2), siginfo.h(3HEAD), attributes(7), standards(7)

Warnings

If you try to set or clear versions on memory that are not ADI-enabled, you may receive a SIGSEGV signal with an si_code equal to SEGV_ACCADI.

You can set or clear versions on memory more efficiently if you align the address and size arguments to the ADI versioning block size as returned by adi_blksz(2).

Do not attempt pointer arithmetic between versioned data pointers that might have different versions.

Use only non-versioned addresses when providing user addresses to the kernel as data not intended to be used for kernel copyin()/copyout() or I/O.

A thread that explicitly disables ADI by calling the adi_set_enabled() function must access ADI-enabled memory using normalized addresses.

Be careful when you write to ADI-enabled memory from a thread that is not ADI-enabled. When ADI checking is disabled, executing block store and block initializing store instructions might clear the version assigned to the target memory address. Library functions such as, but not limited to bzero(3C), memset(3C), and memcpy(3C) may use block initializing store instructions.

Under certain conditions, a read() operation that uses direct I/O enabled through the directio(3C) function might reset the versions in the buffer to zero. In such cases, the application software should check the version at the beginning of the buffer, and if the version is zero, the software should restore the version of the entire buffer.

On some processors, the way version bits are implemented does not guarantee the preservation of the version bits when certain processor-specific RAS (reliability, availability, and serviceability) features are invoked. If the version bits are corrupted, a subsequent load or store of the affected cacheline generates a version mismatch. If the version mismatch results in a SIGSEGV signal with an si_code equal to SEGV_ADIPERR, then the si_adivers value will be set to -1 to indicate that the original version is lost.

Notes

When a versioned data pointer is provided to the kernel as a target for a copyin() or copyout() function or to an I/O operation such as an operation through a read(2) or write(2) function, the kernel will assume that the version applies to the whole buffer. If there is an ADI mismatch exception while the kernel is executing the operation, the operation will fail gracefully and where possible errno will be set to EADI. Because the copyin(9F)/ddi_copyin(9F) and copyout(9F)/ddi_copyout(9F) functions return -1 on all kinds of failure, system calls that fail due to an ADI mismatch exception during calls to these functions cannot differentiate the failure from the other ways in which these functions can fail. In such cases errno will be set to EFAULT.