summaryrefslogtreecommitdiffstats
path: root/man2/spu_run.2
diff options
context:
space:
mode:
Diffstat (limited to 'man2/spu_run.2')
-rw-r--r--man2/spu_run.2260
1 files changed, 0 insertions, 260 deletions
diff --git a/man2/spu_run.2 b/man2/spu_run.2
deleted file mode 100644
index 5b70753..0000000
--- a/man2/spu_run.2
+++ /dev/null
@@ -1,260 +0,0 @@
-.\" 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-10-31 "Linux man-pages 6.7"
-.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>
-.P
-.BI "int syscall(SYS_spu_run, int " fd ", uint32_t *" npc \
-", uint32_t *" event );
-.fi
-.P
-.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 .
-.P
-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)).
-.P
-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.
-.P
-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.
-.P
-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.
-.P
-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.
-.P
-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.
-.P
-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.
-.P
-.\" 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)