diff options
Diffstat (limited to 'man/man2/spu_run.2')
| -rw-r--r-- | man/man2/spu_run.2 | 260 |
1 files changed, 260 insertions, 0 deletions
diff --git a/man/man2/spu_run.2 b/man/man2/spu_run.2 new file mode 100644 index 000000000..d96592726 --- /dev/null +++ b/man/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 (date) "Linux man-pages (unreleased)" +.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) |