docs: sparc: convert to ReST

================================

Application Data Integrity (ADI)

================================

ADI block size to userspace using auxiliary vector along with other ADI

info. Following auxiliary vectors are provided by the kernel:

	============	===========================================

	AT_ADI_BLKSZ	ADI block size. This is the granularity and

			alignment, in bytes, of ADI versioning.

	AT_ADI_NBITS	Number of ADI version bits in the VA

	============	===========================================

IMPORTANT NOTES:

IMPORTANT NOTES

===============

- Version tag values of 0x0 and 0xf are reserved. These values match any

  tag in virtual address and never generate a mismatch exception.

ADI related traps

-----------------

=================

With ADI enabled, following new traps may occur:

Disrupting memory corruption

----------------------------

	When a store accesses a memory localtion that has TTE.mcd=1,

	the task is running with ADI enabled (PSTATE.mcde=1), and the ADI

	first. Hypervisor creates a sun4v error report and sends a

	resumable error (TT=0x7e) trap to the kernel. The kernel sends

	a SIGSEGV to the task that resulted in this trap with the following

	info:

	info::

		siginfo.si_signo = SIGSEGV;

		siginfo.errno = 0;

Precise memory corruption

-------------------------

	When a store accesses a memory location that has TTE.mcd=1,

	the task is running with ADI enabled (PSTATE.mcde=1), and the ADI

	MCD precise exception is enabled (MCDPERR=1), a precise

	exception is sent to the kernel with TT=0x1a. The kernel sends

	a SIGSEGV to the task that resulted in this trap with the following

	info:

	info::

		siginfo.si_signo = SIGSEGV;

		siginfo.errno = 0;

		siginfo.si_addr = addr;	/* address that caused trap */

		siginfo.si_trapno = 0;

	NOTE: ADI tag mismatch on a load always results in precise trap.

	NOTE:

		ADI tag mismatch on a load always results in precise trap.

MCD disabled

------------

	When a task has not enabled ADI and attempts to set ADI version

	on a memory address, processor sends an MCD disabled trap. This

	trap is handled by hypervisor first and the hypervisor vectors this

	trap through to the kernel as Data Access Exception trap with

	fault type set to 0xa (invalid ASI). When this occurs, the kernel

	sends the task SIGSEGV signal with following info:

	sends the task SIGSEGV signal with following info::

		siginfo.si_signo = SIGSEGV;

		siginfo.errno = 0;

-------------------------

Following sample program is meant to illustrate how to use the ADI

functionality.

functionality::

  #include <unistd.h>

  #include <stdio.h>

Steps for sending 'break' on sunhv console:

===========================================

Steps for sending 'break' on sunhv console

==========================================

On Baremetal:

   1. press   Esc + 'B'

:orphan:

==================

Sparc Architecture

==================

.. toctree::

   :maxdepth: 1

   console

   adi

   oradax/oracle-dax

=======================================

Oracle Data Analytics Accelerator (DAX)

---------------------------------------

=======================================

DAX is a coprocessor which resides on the SPARC M7 (DAX1) and M8

(DAX2) processor chips, and has direct access to the CPU's L3 caches

functionality.

The user library is open source and available at:

    https://oss.oracle.com/git/gitweb.cgi?p=libdax.git

The Hypervisor interface to the coprocessor is described in detail in

High Level Overview

-------------------

===================

A coprocessor request is described by a Command Control Block

(CCB). The CCB contains an opcode and various parameters. The opcode

Addressing Memory

-----------------

=================

The kernel does not have access to physical memory in the Sun4v

architecture, as there is an additional level of memory virtualization

The Driver API

--------------

==============

An application makes requests to the driver via the write() system

call, and gets results (if any) via read(). The completion areas are

returned and errno is set.

CCB_DEQUEUE

-----------

Tells the driver to clean up resources associated with past

requests. Since no interrupt is generated upon the completion of a

subsequently call read().

CCB_KILL

--------

Kills a CCB during execution. The CCB is guaranteed to not continue

executing once this call returns successfully. On success, read() must

be called to retrieve the result of the action.

CCB_INFO

--------

Retrieves information about a currently executing CCB. Note that some

Hypervisors might return 'notfound' when the CCB is in 'inprogress'

called to retrieve the details of the action.

Submission of an array of CCBs for execution

---------------------------------------------

A write() whose length is a multiple of the CCB size is treated as a

submit operation. The file offset is treated as the index of the

accepted, and status_data will provide additional data in some cases.

MMAP

----

The mmap() function provides access to the completion area allocated

in the driver.  Note that the completion area is not writeable by the

Completion of a Request

-----------------------

=======================

The first byte in each completion area is the command status which is

updated by the coprocessor hardware. Software may take advantage of

Application Life Cycle of a DAX Submission

------------------------------------------

==========================================

 - open dax device

 - call mmap() to get the completion area address

Memory Constraints

------------------

==================

The DAX hardware operates only on physical addresses. Therefore, it is

not aware of virtual memory mappings and the discontiguities that may

-------------

A CCB is an array of 8 64-bit words. Several of these words provide

command opcodes, parameters, flags, etc., and the rest are addresses

for the completion area, output buffer, and various inputs:

for the completion area, output buffer, and various inputs::

   struct ccb {

       u64   control;

Example Code

------------

============

The DAX is accessible to both user and kernel code.  The kernel code

can make hypercalls directly while the user code must use wrappers

First, the proper device must be opened. For M7 it will be

/dev/oradax1 and for M8 it will be /dev/oradax2. The simplest

procedure is to attempt to open both, as only one will succeed:

procedure is to attempt to open both, as only one will succeed::

	fd = open("/dev/oradax1", O_RDWR);

	if (fd < 0)

	if (fd < 0)

	       /* No DAX found */

Next, the completion area must be mapped:

Next, the completion area must be mapped::

      completion_area = mmap(NULL, DAX_MMAP_LEN, PROT_READ, MAP_SHARED, fd, 0);

For details of all the parameters and bits used in this CCB, please

refer to section 36.2.1.3 of the DAX Hypervisor API document, which

describes the Scan command in detail.

describes the Scan command in detail::

	ccb->control =       /* Table 36.1, CCB Header Format */

		  (2L << 48)     /* command = Scan Value */

The CCB submission is a write() or pwrite() system call to the

driver. If the call fails, then a read() must be used to retrieve the

status:

status::

	if (pwrite(fd, ccb, 64, 0) != 64) {

		struct ccb_exec_result status;

After a successful submission of the CCB, the completion area may be

polled to determine when the DAX is finished. Detailed information on

the contents of the completion area can be found in section 36.2.2 of

the DAX HV API document.

the DAX HV API document::

	while (1) {

		/* Monitored Load */

A completion area status of 1 indicates successful completion of the

CCB and validity of the output bitmap, which may be used immediately.

All other non-zero values indicate error conditions which are

described in section 36.2.2.

described in section 36.2.2::

	if (completion_area[0] != 1) {	/* section 36.2.2, 1 = command ran and succeeded */

		/* completion_area[0] contains the completion status */

After the completion area has been processed, the driver must be

notified that it can release any resources associated with the

request. This is done via the dequeue operation:

request. This is done via the dequeue operation::

	struct dax_command cmd;

	cmd.command = CCB_DEQUEUE;

Finally, normal program cleanup should be done, i.e., unmapping

completion area, closing the dax device, freeing memory etc.

[Kernel example]

Kernel example

--------------

The only difference in using the DAX in kernel code is the treatment

of the completion area. Unlike user applications which mmap the

completion area allocated by the driver, kernel code must allocate its

own memory to use for the completion area, and this address and its

type must be given in the CCB:

type must be given in the CCB::

	ccb->control |=      /* Table 36.1, CCB Header Format */

	        (3L << 32);     /* completion area address type = primary virtual */

	ccb->completion = (unsigned long) completion_area;   /* Completion area address */

The dax submit hypercall is made directly. The flags used in the

ccb_submit call are documented in the DAX HV API in section 36.3.1.

ccb_submit call are documented in the DAX HV API in section 36.3.1/

::

  #include <asm/hypervisor.h>

	}

After the submission, the completion area polling code is identical to

that in user land:

that in user land::

	while (1) {

		/* Monitored Load */

The output bitmap is ready for consumption immediately after the

completion status indicates success.

Excer[t from UltraSPARC Virtual Machine Specification

=====================================================

 .. include:: dax-hv-api.txt

    :literal:

 * the recommended way for applications to use the coprocessor, and

 * the driver interface is not intended for general use.

 *

 * See Documentation/sparc/oradax/oracle-dax.txt for more details.

 * See Documentation/sparc/oradax/oracle-dax.rst for more details.

 */

#include <linux/uaccess.h>