adi, adi_clr_version, adi_get_version, adi_set_version, adi_memset, adi_get_precise, adi_set_precise - Application Data Integrity operations
#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);
Application Data Integrity (ADI), available on the M7/T7 platform series, is a hardware feature that detects invalid data accesses. The ADI feature works in the following way:
By using spare bits in the cache and in the memory hierarchy, the hardware allows the software to assign version numbers to regions of memory at the granularity of a cache line. The software sets the high bits of the virtual address pointer used to reference a data object with the same version assigned to the target memory in which the data object resides.
On execution, the processor compares the version encoded in the pointer and referenced by a load or store instruction, with the version assigned to the target memory.
If there is a mismatch, the processor generates a version mismatch exception and delivers the exception to Oracle Solaris either as a precise or as a disrupting trap as follows:
For a load instruction, the hardware delivers the exception as a precise trap.
For a store instruction, the hardware delivers the exception as a precise trap or as a disrupting trap depending on the current state of the ADI precise exception mode of the thread executing the store instruction. Disrupting traps are the default for performance reasons.
Oracle Solaris signals the exception to a process by delivering a SIGSEGV signal.
For exceptions that generate precise traps, the signal information includes the exact PC (program counter), mismatching VA (virtual address), and current version assigned to the memory.
For exceptions that generate disrupting traps, the signal information only includes the PC (program counter) of the store instruction.
The hardware can perform ADI checking on data accesses to a given page of memory if both the following conditions are met:
ADI is enabled for the thread executing a virtual-addressed load or store to the memory.
ADI is enabled for the virtual address range mapped to the page.
The following conditions need to be met to enable the hardware to get (read) or set (write) the version associated with a cache line:
The thread executing the get or set is ADI-enabled.
The target memory is ADI-enabled.
The target memory is mapped with protections conducive to a successful get or set.
By default, all threads of a 64-bit application run with ADI enabled, but ADI is not enabled on the memory assigned to the application. An application can enable ADI on memory segments that support ADI using the memcntl(2) or mmap(2) function. It is up to applications and libraries to decide which application memory to enable for ADI and the versions to assign to the memory.
The system call functions documented on the adi(2) man page, and the C Library functions, documented in the "Description" section, provide an API that allows a 64-bit application to enable the use of ADI. 32-bit applications cannot use ADI.
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.
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.
The ADI libc library calls will fail if:
ADI is not supported by the platform.
ADI is not supported for 32-bit processes.
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.
See attributes(5) for descriptions of the following attributes:
|
attributes(5), standards(5), adi(2), siginfo.h(3HEAD)
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 gurantee 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.
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.