Skip to content

Commit

Permalink
docs: sparc: convert to ReST
Browse files Browse the repository at this point in the history 
Rename the sparc documentation files to ReST, add an
index for them and adjust in order to produce a nice html
output via the Sphinx build system.

There is an except from a document under oradax dir.
It doesn't seem to make much sense to convert this one
to ReST, so let's add it as an included document.

At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: David S. Miller <davem@davemloft.net>
  • Loading branch information
Mauro Carvalho Chehab authored and David S. Miller committed May 9, 2019
1 parent dac2152 commit 5d5db1c
Show file tree
Hide file tree
Showing 5 changed files with 151 additions and 114 deletions.
188 changes: 98 additions & 90 deletions Documentation/sparc/adi.txt → Documentation/sparc/adi.rst
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
================================
Application Data Integrity (ADI)
================================

Expand Down Expand Up @@ -44,12 +45,15 @@ provided by the hypervisor to the kernel. Kernel returns the value of
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.
Expand Down Expand Up @@ -86,11 +90,12 @@ IMPORTANT NOTES:


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
Expand All @@ -100,7 +105,7 @@ Disrupting memory corruption
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;
Expand All @@ -110,6 +115,7 @@ Disrupting memory corruption


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
Expand All @@ -118,25 +124,27 @@ Precise memory corruption
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_code = SEGV_ADIPERR;
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;
Expand All @@ -149,35 +157,35 @@ Sample program to use ADI
-------------------------

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

#include <unistd.h>
#include <stdio.h>
#include <stdlib.h>
#include <elf.h>
#include <sys/ipc.h>
#include <sys/shm.h>
#include <sys/mman.h>
#include <asm/asi.h>

#ifndef AT_ADI_BLKSZ
#define AT_ADI_BLKSZ 48
#endif
#ifndef AT_ADI_NBITS
#define AT_ADI_NBITS 49
#endif

#ifndef PROT_ADI
#define PROT_ADI 0x10
#endif

#define BUFFER_SIZE 32*1024*1024UL

main(int argc, char* argv[], char* envp[])
{
unsigned long i, mcde, adi_blksz, adi_nbits;
char *shmaddr, *tmp_addr, *end, *veraddr, *clraddr;
int shmid, version;
functionality::

#include <unistd.h>
#include <stdio.h>
#include <stdlib.h>
#include <elf.h>
#include <sys/ipc.h>
#include <sys/shm.h>
#include <sys/mman.h>
#include <asm/asi.h>

#ifndef AT_ADI_BLKSZ
#define AT_ADI_BLKSZ 48
#endif
#ifndef AT_ADI_NBITS
#define AT_ADI_NBITS 49
#endif

#ifndef PROT_ADI
#define PROT_ADI 0x10
#endif

#define BUFFER_SIZE 32*1024*1024UL

main(int argc, char* argv[], char* envp[])
{
unsigned long i, mcde, adi_blksz, adi_nbits;
char *shmaddr, *tmp_addr, *end, *veraddr, *clraddr;
int shmid, version;
Elf64_auxv_t *auxv;

adi_blksz = 0;
Expand All @@ -202,77 +210,77 @@ main(int argc, char* argv[], char* envp[])
printf("\tBlock size = %ld\n", adi_blksz);
printf("\tNumber of bits = %ld\n", adi_nbits);

if ((shmid = shmget(2, BUFFER_SIZE,
IPC_CREAT | SHM_R | SHM_W)) < 0) {
perror("shmget failed");
exit(1);
}
if ((shmid = shmget(2, BUFFER_SIZE,
IPC_CREAT | SHM_R | SHM_W)) < 0) {
perror("shmget failed");
exit(1);
}

shmaddr = shmat(shmid, NULL, 0);
if (shmaddr == (char *)-1) {
perror("shm attach failed");
shmctl(shmid, IPC_RMID, NULL);
exit(1);
}
shmaddr = shmat(shmid, NULL, 0);
if (shmaddr == (char *)-1) {
perror("shm attach failed");
shmctl(shmid, IPC_RMID, NULL);
exit(1);
}

if (mprotect(shmaddr, BUFFER_SIZE, PROT_READ|PROT_WRITE|PROT_ADI)) {
perror("mprotect failed");
goto err_out;
}

/* Set the ADI version tag on the shm segment
*/
version = 10;
tmp_addr = shmaddr;
end = shmaddr + BUFFER_SIZE;
while (tmp_addr < end) {
asm volatile(
"stxa %1, [%0]0x90\n\t"
:
: "r" (tmp_addr), "r" (version));
tmp_addr += adi_blksz;
}
/* Set the ADI version tag on the shm segment
*/
version = 10;
tmp_addr = shmaddr;
end = shmaddr + BUFFER_SIZE;
while (tmp_addr < end) {
asm volatile(
"stxa %1, [%0]0x90\n\t"
:
: "r" (tmp_addr), "r" (version));
tmp_addr += adi_blksz;
}
asm volatile("membar #Sync\n\t");

/* Create a versioned address from the normal address by placing
/* Create a versioned address from the normal address by placing
* version tag in the upper adi_nbits bits
*/
tmp_addr = (void *) ((unsigned long)shmaddr << adi_nbits);
tmp_addr = (void *) ((unsigned long)tmp_addr >> adi_nbits);
veraddr = (void *) (((unsigned long)version << (64-adi_nbits))
| (unsigned long)tmp_addr);

printf("Starting the writes:\n");
for (i = 0; i < BUFFER_SIZE; i++) {
veraddr[i] = (char)(i);
if (!(i % (1024 * 1024)))
printf(".");
}
printf("\n");

printf("Verifying data...");
*/
tmp_addr = (void *) ((unsigned long)shmaddr << adi_nbits);
tmp_addr = (void *) ((unsigned long)tmp_addr >> adi_nbits);
veraddr = (void *) (((unsigned long)version << (64-adi_nbits))
| (unsigned long)tmp_addr);

printf("Starting the writes:\n");
for (i = 0; i < BUFFER_SIZE; i++) {
veraddr[i] = (char)(i);
if (!(i % (1024 * 1024)))
printf(".");
}
printf("\n");

printf("Verifying data...");
fflush(stdout);
for (i = 0; i < BUFFER_SIZE; i++)
if (veraddr[i] != (char)i)
printf("\nIndex %lu mismatched\n", i);
printf("Done.\n");
for (i = 0; i < BUFFER_SIZE; i++)
if (veraddr[i] != (char)i)
printf("\nIndex %lu mismatched\n", i);
printf("Done.\n");

/* Disable ADI and clean up
*/
/* Disable ADI and clean up
*/
if (mprotect(shmaddr, BUFFER_SIZE, PROT_READ|PROT_WRITE)) {
perror("mprotect failed");
goto err_out;
}

if (shmdt((const void *)shmaddr) != 0)
perror("Detach failure");
shmctl(shmid, IPC_RMID, NULL);
if (shmdt((const void *)shmaddr) != 0)
perror("Detach failure");
shmctl(shmid, IPC_RMID, NULL);

exit(0);
exit(0);

err_out:
if (shmdt((const void *)shmaddr) != 0)
perror("Detach failure");
shmctl(shmid, IPC_RMID, NULL);
exit(1);
}
err_out:
if (shmdt((const void *)shmaddr) != 0)
perror("Detach failure");
shmctl(shmid, IPC_RMID, NULL);
exit(1);
}
4 changes: 2 additions & 2 deletions Documentation/sparc/console.txt → Documentation/sparc/console.rst
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
Steps for sending 'break' on sunhv console:
===========================================
Steps for sending 'break' on sunhv console
==========================================

On Baremetal:
1. press Esc + 'B'
Expand Down
13 changes: 13 additions & 0 deletions Documentation/sparc/index.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
:orphan:

==================
Sparc Architecture
==================

.. toctree::
:maxdepth: 1

console
adi

oradax/oracle-dax
Loading

0 comments on commit 5d5db1c

Please sign in to comment.