Section (2) spu_run
Name
spu_run — execute an SPU context
Synopsis
#include <sys/spu.h>
int
spu_run( |
int fd, |
unsigned int *npc, | |
unsigned int *event) ; |
![]() |
Note |
---|---|
There is no glibc wrapper for this system call; see NOTES. |
DESCRIPTION
The 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 fd
argument is a file descriptor returned by 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 npc
.
Execution of SPU code happens synchronously, meaning that
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 pthread_create(3)).
When spu_run
() returns, the
current value of the SPU program counter is written to
npc
, so successive
calls to spu_run
() can use the
same npc
pointer.
The event
argument
provides a buffer for an extended status code. If the SPU
context was created with the SPU_CREATE_EVENTS_ENABLED
flag, then this
buffer is populated by the Linux kernel before spu_run
() returns.
The status code may be one (or more) of the following constants:
SPE_EVENT_DMA_ALIGNMENT
-
A DMA alignment error occurred.
SPE_EVENT_INVALID_DMA
-
An invalid MFC DMA command was attempted.
SPE_EVENT_SPE_DATA_STORAGE
-
A DMA storage error occurred.
SPE_EVENT_SPE_ERROR
-
An illegal instruction was executed.
NULL is a valid value for the event
argument. In this case,
the events will not be reported to the calling process.
RETURN VALUE
On success, spu_run
()
returns the value of the spu_status
register. On
error, it returns −1 and sets errno
to one of the error codes listed
below.
The spu_status
register value is a bit mask of status codes and optionally a
14-bit code returned from the stop-and-signal
instruction on the SPU. The
bit masks for the status codes are:
- 0x02
-
SPU was stopped by a
stop-and-signal
instruction. - 0x04
-
SPU was stopped by a
halt
instruction. - 0x08
-
SPU is waiting for a channel.
- 0x10
-
SPU is in single-step mode.
- 0x20
-
SPU has tried to execute an invalid instruction.
- 0x40
-
SPU has tried to access an invalid channel.
- 0x3fff0000
-
The bits masked with this value contain the code returned from a
stop-and-signal
instruction. These bits are valid only if the 0x02 bit is set.
If spu_run
() has not
returned an error, one or more bits among the lower eight
ones are always set.
ERRORS
- EBADF
-
fd
is not a valid file descriptor. - EFAULT
-
npc
is not a valid pointer, orevent
is non-NULL and an invalid pointer. - EINTR
-
A signal occurred while
spu_run
() was in progress; see signal(7). Thenpc
value has been updated to the new program counter value if necessary. - EINVAL
-
fd
is not a valid file descriptor returned from spu_create(2). - ENOMEM
-
There was not enough memory available to handle a page fault resulting from a Memory Flow Controller (MFC) direct memory access.
- 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.
CONFORMING TO
This call is Linux-specific and implemented only by the PowerPC architecture. Programs using this system call are not portable.
NOTES
Glibc does not provide a wrapper for this system call;
call it using syscall(2). Note however,
that 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
http://www.bsc.es/projects/deepcomputing/linuxoncell/
for the recommended libraries.
EXAMPLE
The following is an example of running a simple,
one-instruction SPU program with the spu_run
() system call.
#include <stdlib.h> #include <stdint.h> #include <unistd.h> #include <stdio.h> #include <sys/types.h> #include <fcntl.h> #define handle_error(msg) do { perror(msg); exit(EXIT_FAILURE); } while (0) int main(void) { int context, fd, spu_status; uint32_t instruction, npc; context = spu_create(/spu/example−context, 0, 0755); if (context == −1) handle_error(spu_create); /* write a _zsingle_quotesz_stop 0x1234_zsingle_quotesz_ instruction to the SPU_zsingle_quotesz_s * local store memory */ instruction = 0x00001234; fd = open(/spu/example−context/mem, O_RDWR); if (fd == −1) handle_error(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 = spu_run(context, &npc, NULL); if (spu_status == −1) handle_error(open); /* we should see a status code of 0x1234002: * 0x00000002 (spu was stopped due to stop−and−signal) * | 0x12340000 (the stop−and−signal code) */ printf(SPU Status: 0x%08x , spu_status); exit(EXIT_SUCCESS); }
COLOPHON
This page is part of release 5.04 of the Linux man-pages
project. A
description of the project, information about reporting bugs,
and the latest version of this page, can be found at
https://www.kernel.org/doc/man−pages/.
Copyright (c) International Business Machines Corp., 2006 %%%LICENSE_START(GPLv2+_SW_3_PARA) This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this manual; if not, see <http://www.gnu.org/licenses/>. %%%LICENSE_END HISTORY: 2005-09-28, created by Arnd Bergmann <arndbde.ibm.com> 2006-06-16, revised by Eduardo M. Fleury <efleurybr.ibm.com> 2007-07-10, some polishing by mtk 2007-09-28, updates for newer kernels, added example by Jeremy Kerr <jkozlabs.org> |