man-pages/man2/spu_run.2

.\" This is _*_ nroff _*_ source. Emacs, gimme all those colors :)
.\"
.\" Copyright (c) International Business Machines <20>Corp., 2006
.\"
.\" This program is free software; <20>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; <20>without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. <20>See
.\" the GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program; <20>if not, write to the Free Software
.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston,
.\" MA 02111-1307 USA
.\"
.\" 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
.\"
.TH SPU_RUN 2 2007-07-10 "Linux" "Linux Programmer's Manual"
.SH NAME
spu_run \- execute an spu context
.SH SYNOPSIS
.nf
.B #include <sys/spu.h>

.BI "int spu_run(int " fd ", unsigned int *" npc \
", unsigned int *" event ");"
.fi
.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 addresses a specific SPU context.
When the context gets
scheduled to a physical SPU, it starts execution at the instruction
pointer passed in
.IR npc .

Execution of SPU code happens synchronously, meaning that
.BR spu_run ()
does not return 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, using the
.BR pthread_create (3)
call for instance.

When
.BR spu_run ()
returns, the current value of the SPU instruction pointer is written to
.IR npc ,
so one can call
.BR spu_run ()
again without having to update the pointers.

.I event
can be a NULL pointer or a pointer to an to a buffer that
.BR spu_run ()
uses to return an extended status code.
The status code may be one of the following constants:
.TP
.B SPE_EVENT_DMA_ALIGNMENT
A DMA alignment error occurred
.RB ( SIGBUS ,
.I si_code
set to
.BR BUS_ADRALN ).
.TP
.B SPE_EVENT_INVALID_DMA
MFC DMA was invalid
.RB ( SIGBUS ,
.I si_code
set to
.BR BUS_OBJERR ).
.\" .B SPE_EVENT_SPE_DATA_SEGMENT
.\" A DMA segmentation error occurred.
.TP
.B SPE_EVENT_SPE_DATA_STORAGE
A DMA storage error occurred
.RB ( SIGBUS ,
.I si_code
set to
.BR BUS_ADRERR ).
.TP
.B SPE_EVENT_SPE_ERROR
Illegal instruction error
.RB ( SIGBUS ,
.I si_code
set to
.BR BUS_ADRALN ).
.PP
If
.I event
is NULL, these errors will cause the corresponding signal listed
above to be delivered to the calling process.
.SH RETURN VALUE
On success
.BR spu_run ()
returns the value of the
.I spu_status
register.
On error it returns \-1 and sets
.I errno
to one of the error codes listed below.
The
.I 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:
.TP
.B 0x02
SPU was stopped by stop-and-signal.
In this case the 14-bit code
returned from the instruction can be retrieved with the mask
.IR 0x3fff0000 .
.TP
.B 0x04
SPU was stopped by halt.
.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.
.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
.BR EAGAIN " or " EWOULDBLOCK
.I fd
is in non-blocking mode and
.BR spu_run ()
would block.
.TP
.B EBADF
.I fd
is not a valid file descriptor.
.TP
.B EFAULT
.I npc
is not a valid pointer or
.I status
is neither NULL nor a valid pointer.
.TP
.B EINTR
A signal occurred while
.BR spu_run ()
was in progress.
The
.I npc
value has been updated to the new program counter value if
necessary.
.TP
.B EINVAL
.I fd
is not a 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 VERSIONS
The
.BR spu_run (2)
system call was added to Linux in kernel 2.6.16.
.SH CONFORMING TO
This call is Linux specific and only implemented by the ppc64
architecture.
Programs using this system call are not portable.
.SH NOTES
Glibc does not provide a wrapper for this system call; call it using
.BR syscall (2).
Note however, that
.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
.I http://www.bsc.es/projects/deepcomputing/linuxoncell/
for the recommended libraries.
.SH BUGS
The code does not yet fully implement all features outlined here.
.\" .SH AUTHOR
.\" Arnd Bergmann <arndb@de.ibm.com>
.SH SEE ALSO
.BR close (2),
.BR spu_create (2),
.BR spufs (7)