'\" te .\" Copyright (c) 2015, Oracle and/or its affiliates. All rights .\" reserved. .TH adi 3C "22 Sep 2015" "SunOS 5.11" "Standard C Library Functions" .SH NAME adi, adi_clr_version, adi_get_version, adi_set_version, adi_memset, adi_get_precise, adi_set_precise \- Application Data Integrity operations .SH SYNOPSIS .LP .nf #include #include 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); .fi .SH OVERVIEW .sp .LP 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: .RS +4 .TP 1. 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. .RE .RS +4 .TP 2. On execution, the processor compares the version encoded in the pointer and referenced by a \fBload\fR or \fBstore\fR instruction, with the version assigned to the target memory. .RE .RS +4 .TP 3. If there is a mismatch, the processor generates a \fBversion mismatch exception\fR and delivers the exception to Oracle Solaris either as a \fBprecise\fR or as a \fBdisrupting trap\fR as follows: .RS +4 .TP .ie t \(bu .el o For a \fBload\fR instruction, the hardware delivers the exception as a \fBprecise trap\fR. .RE .RS +4 .TP .ie t \(bu .el o For a \fBstore\fR instruction, the hardware delivers the exception as a \fBprecise trap\fR or as a \fBdisrupting trap\fR depending on the current state of the ADI precise exception mode of the thread executing the \fBstore\fR instruction. Disrupting traps are the default for performance reasons. .RE .RE .RS +4 .TP 4. Oracle Solaris signals the exception to a process by delivering a \fBSIGSEGV\fR signal. .RS +4 .TP .ie t \(bu .el o For exceptions that generate \fBprecise traps\fR, the signal information includes the exact \fBPC\fR (program counter), mismatching \fBVA\fR (virtual address), and current version assigned to the memory. .RE .RS +4 .TP .ie t \(bu .el o For exceptions that generate \fBdisrupting traps\fR, the signal information only includes the \fBPC\fR (program counter) of the \fBstore\fR instruction. .RE .RE .sp .LP The hardware can perform ADI checking on data accesses to a given page of memory if both the following conditions are met: .RS +4 .TP .ie t \(bu .el o ADI is enabled for the thread executing a virtual-addressed \fBload\fR or \fBstore\fR to the memory. .RE .RS +4 .TP .ie t \(bu .el o ADI is enabled for the virtual address range mapped to the page. .RE .sp .LP The following conditions need to be met to enable the hardware to get (read) or set (write) the version associated with a cache line: .RS +4 .TP .ie t \(bu .el o The thread executing the get or set is ADI-enabled. .RE .RS +4 .TP .ie t \(bu .el o The target memory is ADI-enabled. .RE .RS +4 .TP .ie t \(bu .el o The target memory is mapped with protections conducive to a successful get or set. .RE .sp .LP 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 \fBmemcntl\fR(2) or \fBmmap\fR(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. .sp .LP The system call functions documented on the \fBadi\fR(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. .SH DESCRIPTION .sp .LP The following C Library functions provide the ADI API to 64-bit applications: .RS +4 .TP .ie t \(bu .el o The \fBadi_clr_version()\fR function clears (sets to \fB0\fR) all ADI version tags for the specified range of ADI-enabled memory. \fBLoad\fR and \fBstore\fR instructions that reference a memory location with a clear ADI version will not cause a mismatch exception. .RE .RS +4 .TP .ie t \(bu .el o The \fBadi_get_version()\fR function returns the ADI version for a memory address assigned to a region of ADI-enabled memory. .RE .RS +4 .TP .ie t \(bu .el o The \fBadi_set_version()\fR function sets the ADI version tags to a specified version for a specified range of ADI-enabled memory. .RE .RS +4 .TP .ie t \(bu .el o The \fBadi_memset()\fR function sets the bytes in an ADI-enabled memory range to the value of \fBc\fR (converted to an unsigned \fBchar\fR) and sets the ADI version tags of the memory range to the specified version number. Calling the \fBadi_memset()\fR function is more efficient than calling the \fBmemset()\fR and the \fBadi_set_version()\fR functions separately. .RE .RS +4 .TP .ie t \(bu .el o The \fBadi_get_precise()\fR function returns the current state of the ADI precise exception mode for the calling thread. .RE .RS +4 .TP .ie t \(bu .el o The \fBadi_set_precise()\fR function sets the current state of the ADI precise exception mode for the calling thread. The value of mode can either be \fBADI_PRECISE_ENABLE\fR or \fBADI_PRECISE_DISABLE\fR. .RE .SH RETURN VALUES .sp .LP On success, the \fBadi_clr_version()\fR function returns a non-versioned address pointer to the specified memory. Otherwise, the function returns the value \fB(caddr_t)-1\fR and sets \fBerrno\fR to indicate the error. .sp .LP On success, the \fBadi_get_version()\fR function returns the ADI version tag value for the specified address. Otherwise, the function returns the value \fB-1\fR and sets \fBerrno\fR to indicate the error. .sp .LP On success, the \fBadi_set_version()\fR and the \fBadi_memset()\fR functions return a versioned address pointer to the specified memory. Otherwise, the functions return the value \fB(caddr_t)-1\fR and set \fBerrno\fR to indicate the error. .sp .LP On success, the \fBadi_get_precise()\fR function returns the value \fBADI_PRECISE_DISABLE\fR or \fBADI_PRECISE_ENABLE\fR, to indicate the current state of ADI \fBprecise exception mode\fR. Otherwise, the function returns the value \fB-1\fR and sets \fBerrno\fR to indicate the error. .sp .LP On success, the \fBadi_set_precise()\fR function returns the value \fBADI_PRECISE_DISABLE\fR or \fBADI_PRECISE_ENABLE\fR, to indicate the previous state of ADI \fBprecise exception mode\fR. Otherwise, the function returns the value \fB-1\fR and sets \fBerrno\fR to indicate the error. .SH ERRORS .sp .LP The ADI \fBlibc\fR library calls will fail if: .sp .ne 2 .mk .na \fB\fBENOTSUP\fR\fR .ad .RS 11n .rt .RS +4 .TP .ie t \(bu .el o ADI is not supported by the platform. .RE .RS +4 .TP .ie t \(bu .el o ADI is not supported for 32-bit processes. .RE .RE .sp .ne 2 .mk .na \fB\fBEINVAL\fR\fR .ad .RS 11n .rt The version argument is greater than the \fBmaximum version\fR value returned by the \fBadi_version_max\fR(2) function. .sp The \fBprecise exception mode\fR value specified is not \fBADI_PRECISE_ENABLE\fR or \fBADI_PRECISE_DISABLE\fR. .RE .SH ATTRIBUTES .sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp .sp .TS tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) . ATTRIBUTE TYPEATTRIBUTE VALUE _ Interface StabilityVolatile _ MT-LevelMT-Safe .TE .SH SEE ALSO .sp .LP \fBattributes\fR(5), \fBstandards\fR(5), \fBadi\fR(2), \fBsiginfo.h\fR(3HEAD) .SH WARNINGS .sp .LP If you try to set or clear versions on memory that are not ADI-enabled, you may receive a \fBSIGSEGV\fR signal with an \fBsi_code\fR equal to \fBSEGV_ACCADI\fR. .sp .LP You can set or clear versions on memory more efficiently if you align the \fIaddress\fR and \fIsize\fR arguments to the ADI \fBversioning block size\fR as returned by \fBadi_blksz\fR(2). .sp .LP Do not attempt pointer arithmetic between versioned data pointers that might have different versions. .sp .LP Use only non-versioned addresses when providing user addresses to the kernel as data not intended to be used for kernel \fBcopyin()\fR/\fBcopyout()\fR or I/O. .sp .LP A thread that explicitly disables ADI by calling the \fBadi_set_enabled()\fR function must access ADI-enabled memory using normalized addresses. .sp .LP Be careful when you write to ADI-enabled memory from a thread that is not ADI-enabled. When \fBADI checking\fR is disabled, executing \fBblock store\fR and \fBblock initializing store\fR instructions might clear the version assigned to the target memory address. Library functions such as, but not limited to \fBbzero\fR(3C), \fBmemset\fR(3C), and \fBmemcpy\fR(3C) may use \fBblock initializing store\fR instructions. .sp .LP Under certain conditions, a \fBread()\fR operation that uses direct I/O enabled through the \fBdirectio\fR(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. .sp .LP 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 \fBload\fR or \fBstore\fR of the affected cacheline generates a version mismatch. If the version mismatch results in a \fBSIGSEGV\fR signal with an \fBsi_code\fR equal to \fBSEGV_ADIPERR\fR, then the \fBsi_adivers\fR value will be set to \fB-1\fR to indicate that the original version is lost. .SH NOTES .sp .LP When a versioned data pointer is provided to the kernel as a target for a \fBcopyin()\fR or \fBcopyout()\fR function or to an I/O operation such as an operation through a \fBread\fR(2) or \fBwrite\fR(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 \fBerrno\fR will be set to \fBEADI\fR. Because the \fBcopyin\fR(9F)/\fBddi_copyin\fR(9F) and \fBcopyout\fR(9F)/\fBddi_copyout\fR(9F) functions return \fB-1\fR 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 \fBerrno\fR will be set to \fBEFAULT\fR.