Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 260 insertions, 0 deletions

diff --git a/upstream/debian-unstable/man2/spu_run.2 b/upstream/debian-unstable/man2/spu_run.2
new file mode 100644
index 00000000..0a9d2299
--- /dev/null
+++ b/upstream/debian-unstable/man2/spu_run.2
@@ -0,0 +1,260 @@
+.\" Copyright (c) International Business Machines Corp., 2006
+.\"
+.\" SPDX-License-Identifier: GPL-2.0-or-later
+.\"
+.\" HISTORY:
+.\" 2005-09-28, created by Arnd Bergmann <arndb@de.ibm.com>
+.\" 2006-06-16, revised by Eduardo M. Fleury <efleury@br.ibm.com>
+.\" 2007-07-10, some polishing by mtk
+.\" 2007-09-28, updates for newer kernels, added example
+.\"             by Jeremy Kerr <jk@ozlabs.org>
+.\"
+.TH spu_run 2 2023-05-03 "Linux man-pages 6.05.01"
+.SH NAME
+spu_run \- execute an SPU context
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#include <sys/spu.h>" "          /* Definition of " SPU_* " constants */"
+.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
+.PP
+.BI "int syscall(SYS_spu_run, int " fd ", uint32_t *" npc \
+", uint32_t *" event );
+.fi
+.PP
+.IR Note :
+glibc provides no wrapper for
+.BR spu_run (),
+necessitating the use of
+.BR syscall (2).
+.SH DESCRIPTION
+The
+.BR spu_run ()
+system call is used on PowerPC machines that implement the
+Cell Broadband Engine Architecture in order to access Synergistic
+Processor Units (SPUs).
+The
+.I fd
+argument is a file descriptor returned by
+.BR spu_create (2)
+that refers to a specific SPU context.
+When the context gets scheduled to a physical SPU,
+it starts execution at the instruction pointer passed in
+.IR npc .
+.PP
+Execution of SPU code happens synchronously, meaning that
+.BR spu_run ()
+blocks while the SPU is still running.
+If there is a need
+to execute SPU code in parallel with other code on either the
+main CPU or other SPUs, a new thread of execution must be created
+first (e.g., using
+.BR pthread_create (3)).
+.PP
+When
+.BR spu_run ()
+returns, the current value of the SPU program counter is written to
+.IR npc ,
+so successive calls to
+.BR spu_run ()
+can use the same
+.I npc
+pointer.
+.PP
+The
+.I event
+argument provides a buffer for an extended status code.
+If the SPU
+context was created with the
+.B SPU_CREATE_EVENTS_ENABLED
+flag, then this buffer is populated by the Linux kernel before
+.BR spu_run ()
+returns.
+.PP
+The status code may be one (or more) of the following constants:
+.TP
+.B SPE_EVENT_DMA_ALIGNMENT
+A DMA alignment error occurred.
+.TP
+.B SPE_EVENT_INVALID_DMA
+An invalid MFC DMA command was attempted.
+.\" SPE_EVENT_SPE_DATA_SEGMENT is defined, but does not seem to be generated
+.\" at any point (in Linux 5.9 sources).
+.TP
+.B SPE_EVENT_SPE_DATA_STORAGE
+A DMA storage error occurred.
+.TP
+.B SPE_EVENT_SPE_ERROR
+An illegal instruction was executed.
+.PP
+NULL
+is a valid value for the
+.I event
+argument.
+In this case, the events will not be reported to the calling process.
+.SH RETURN VALUE
+On success,
+.BR spu_run ()
+returns the value of the
+.I spu_status
+register.
+On failure, it returns \-1 and sets
+.I errno
+is set to indicate the error.
+.PP
+The
+.I spu_status
+register value is a bit mask of status codes and
+optionally a 14-bit code returned from the
+.B stop-and-signal
+instruction on the SPU.
+The bit masks for the status codes
+are:
+.TP
+.B 0x02
+SPU was stopped by a
+.B stop-and-signal
+instruction.
+.TP
+.B 0x04
+SPU was stopped by a
+.B halt
+instruction.
+.TP
+.B 0x08
+SPU is waiting for a channel.
+.TP
+.B 0x10
+SPU is in single-step mode.
+.TP
+.B 0x20
+SPU has tried to execute an invalid instruction.
+.TP
+.B 0x40
+SPU has tried to access an invalid channel.
+.TP
+.B 0x3fff0000
+The bits masked with this value contain the code returned from a
+.B stop-and-signal
+instruction.
+These bits are valid only if the 0x02 bit is set.
+.PP
+If
+.BR spu_run ()
+has not returned an error, one or more bits among the lower eight
+ones are always set.
+.SH ERRORS
+.TP
+.B EBADF
+.I fd
+is not a valid file descriptor.
+.TP
+.B EFAULT
+.I npc
+is not a valid pointer, or
+.I event
+is non-NULL and an invalid pointer.
+.TP
+.B EINTR
+A signal occurred while
+.BR spu_run ()
+was in progress; see
+.BR signal (7).
+The
+.I npc
+value has been updated to the new program counter value if
+necessary.
+.TP
+.B EINVAL
+.I fd
+is not a valid file descriptor returned from
+.BR spu_create (2).
+.TP
+.B ENOMEM
+There was not enough memory available to handle a page fault
+resulting from a Memory Flow Controller (MFC) direct memory access.
+.TP
+.B ENOSYS
+The functionality is not provided by the current system, because
+either the hardware does not provide SPUs or the spufs module is not
+loaded.
+.SH STANDARDS
+Linux on PowerPC.
+.SH HISTORY
+Linux 2.6.16.
+.SH NOTES
+.BR spu_run ()
+is meant to be used from libraries that implement a more abstract
+interface to SPUs, not to be used from regular applications.
+See
+.UR http://www.bsc.es\:/projects\:/deepcomputing\:/linuxoncell/
+.UE
+for the recommended libraries.
+.SH EXAMPLES
+The following is an example of running a simple, one-instruction SPU
+program with the
+.BR spu_run ()
+system call.
+.PP
+.\" SRC BEGIN (spu_run.c)
+.EX
+#include <err.h>
+#include <fcntl.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <sys/types.h>
+#include <unistd.h>
+\&
+int main(void)
+{
+    int       context, fd, spu_status;
+    uint32_t  instruction, npc;
+\&
+    context = syscall(SYS_spu_create, "/spu/example\-context", 0, 0755);
+    if (context == \-1)
+        err(EXIT_FAILURE, "spu_create");
+\&
+    /*
+     * Write a \[aq]stop 0x1234\[aq] instruction to the SPU\[aq]s
+     * local store memory.
+     */
+    instruction = 0x00001234;
+\&
+    fd = open("/spu/example\-context/mem", O_RDWR);
+    if (fd == \-1)
+        err(EXIT_FAILURE, "open");
+    write(fd, &instruction, sizeof(instruction));
+\&
+    /*
+     * set npc to the starting instruction address of the
+     * SPU program. Since we wrote the instruction at the
+     * start of the mem file, the entry point will be 0x0.
+     */
+    npc = 0;
+\&
+    spu_status = syscall(SYS_spu_run, context, &npc, NULL);
+    if (spu_status == \-1)
+        err(EXIT_FAILURE, "open");
+\&
+    /*
+     * We should see a status code of 0x12340002:
+     *   0x00000002 (spu was stopped due to stop\-and\-signal)
+     * | 0x12340000 (the stop\-and\-signal code)
+     */
+    printf("SPU Status: %#08x\en", spu_status);
+\&
+    exit(EXIT_SUCCESS);
+}
+.EE
+.\" SRC END
+.\" .SH AUTHORS
+.\" Arnd Bergmann <arndb@de.ibm.com>, Jeremy Kerr <jk@ozlabs.org>
+.SH SEE ALSO
+.BR close (2),
+.BR spu_create (2),
+.BR capabilities (7),
+.BR spufs (7)