139 lines
4.1 KiB
ReStructuredText
139 lines
4.1 KiB
ReStructuredText
.. SPDX-License-Identifier: GPL-2.0
|
|
|
|
=======
|
|
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);
|
|
|
|
Description
|
|
===========
|
|
The spu_run system call is used on PowerPC machines that implement the
|
|
Cell Broadband Engine Architecture in order to access Synergistic Pro-
|
|
cessor Units (SPUs). It uses the fd that was returned from spu_cre-
|
|
ate(2) to address a specific SPU context. When the context gets sched-
|
|
uled to a physical SPU, it starts execution at the instruction pointer
|
|
passed in npc.
|
|
|
|
Execution of SPU code happens synchronously, meaning that spu_run does
|
|
not return while the SPU is still running. If there is a need to exe-
|
|
cute SPU code in parallel with other code on either the main CPU or
|
|
other SPUs, you need to create a new thread of execution first, e.g.
|
|
using the pthread_create(3) call.
|
|
|
|
When spu_run returns, the current value of the SPU instruction pointer
|
|
is written back to npc, so you can call spu_run again without updating
|
|
the pointers.
|
|
|
|
event can be a NULL pointer or point to an extended status code that
|
|
gets filled when spu_run returns. It can be one of the following con-
|
|
stants:
|
|
|
|
SPE_EVENT_DMA_ALIGNMENT
|
|
A DMA alignment error
|
|
|
|
SPE_EVENT_SPE_DATA_SEGMENT
|
|
A DMA segmentation error
|
|
|
|
SPE_EVENT_SPE_DATA_STORAGE
|
|
A DMA storage error
|
|
|
|
If NULL is passed as the event argument, these errors will result in a
|
|
signal delivered to the calling process.
|
|
|
|
Return Value
|
|
============
|
|
spu_run returns the value of the spu_status register or -1 to indicate
|
|
an error and set errno to one of the error codes listed below. The
|
|
spu_status register value contains 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 stop-and-signal.
|
|
|
|
0x04
|
|
SPU was stopped by halt.
|
|
|
|
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
|
|
stop-and-signal.
|
|
|
|
There are always one or more of the lower eight bits set or an error
|
|
code is returned from spu_run.
|
|
|
|
Errors
|
|
======
|
|
EAGAIN or EWOULDBLOCK
|
|
fd is in non-blocking mode and spu_run would block.
|
|
|
|
EBADF fd is not a valid file descriptor.
|
|
|
|
EFAULT npc is not a valid pointer or status is neither NULL nor a valid
|
|
pointer.
|
|
|
|
EINTR A signal occurred while spu_run was in progress. The npc value
|
|
has been updated to the new program counter value if necessary.
|
|
|
|
EINVAL fd is not a file descriptor returned from spu_create(2).
|
|
|
|
ENOMEM Insufficient memory was available to handle a page fault result-
|
|
ing from an 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.
|
|
|
|
|
|
Notes
|
|
=====
|
|
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 rec-
|
|
ommended libraries.
|
|
|
|
|
|
Conforming to
|
|
=============
|
|
This call is Linux specific and only implemented by the ppc64 architec-
|
|
ture. Programs using this system call are not portable.
|
|
|
|
|
|
Bugs
|
|
====
|
|
The code does not yet fully implement all features lined out here.
|
|
|
|
|
|
Author
|
|
======
|
|
Arnd Bergmann <arndb@de.ibm.com>
|
|
|
|
See Also
|
|
========
|
|
capabilities(7), close(2), spu_create(2), spufs(7)
|