mirror of https://github.com/mkerrisk/man-pages
217 lines
5.3 KiB
Groff
217 lines
5.3 KiB
Groff
.\" This is _*_ nroff _*_ source. Emacs, gimme all those colors :)
|
||
.\"
|
||
.\" Copyright (c) International Business Machines Corp., 2006
|
||
.\"
|
||
.\" 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 program; 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)
|