spu_run(2)

1SPU_RUN(2)                 Linux Programmer's Manual                SPU_RUN(2)
2
3
4

NAME

6       spu_run - execute an spu context
7
8

SYNOPSIS

10       #include <sys/spu.h>
11
12       int spu_run(int fd, unsigned int *npc, unsigned int *event);
13

DESCRIPTION

15       The  spu_run system call is used on PowerPC machines that implement the
16       Cell Broadband Engine Architecture in order to access Synergistic  Pro‐
17       cessor  Units  (SPUs).  It  uses the fd that was returned from spu_cre‐
18       ate(2) to address a specific SPU context. When the context gets  sched‐
19       uled  to a physical SPU, it starts execution at the instruction pointer
20       passed in npc.
21
22       Execution of SPU code happens synchronously, meaning that spu_run  does
23       not  return  while the SPU is still running. If there is a need to exe‐
24       cute SPU code in parallel with other code on either  the  main  CPU  or
25       other  SPUs,  you  need to create a new thread of execution first, e.g.
26       using the pthread_create(3) call.
27
28       When spu_run returns, the current value of the SPU instruction  pointer
29       is  written back to npc, so you can call spu_run again without updating
30       the pointers.
31
32       event can be a NULL pointer or point to an extended  status  code  that
33       gets  filled  when spu_run returns. It can be one of the following con‐
34       stants:
35
36       SPE_EVENT_DMA_ALIGNMENT
37              A DMA alignment error
38
39       SPE_EVENT_SPE_DATA_SEGMENT
40              A DMA segmentation error
41
42       SPE_EVENT_SPE_DATA_STORAGE
43              A DMA storage error
44
45       If NULL is passed as the event argument, these errors will result in  a
46       signal delivered to the calling process.
47

RETURN VALUE

49       spu_run  returns the value of the spu_status register or -1 to indicate
50       an error and set errno to one of the error  codes  listed  below.   The
51       spu_status  register  value  contains  a  bit  mask of status codes and
52       optionally a 14 bit code returned from the stop-and-signal  instruction
53       on the SPU. The bit masks for the status codes are:
54
55       0x02   SPU was stopped by stop-and-signal.
56
57       0x04   SPU was stopped by halt.
58
59       0x08   SPU is waiting for a channel.
60
61       0x10   SPU is in single-step mode.
62
63       0x20   SPU has tried to execute an invalid instruction.
64
65       0x40   SPU has tried to access an invalid channel.
66
67       0x3fff0000
68              The  bits  masked with this value contain the code returned from
69              stop-and-signal.
70
71       There are always one or more of the lower eight bits set  or  an  error
72       code is returned from spu_run.
73

ERRORS

75       EAGAIN or EWOULDBLOCK
76              fd is in non-blocking mode and spu_run would block.
77
78       EBADF  fd is not a valid file descriptor.
79
80       EFAULT npc is not a valid pointer or status is neither NULL nor a valid
81              pointer.
82
83       EINTR  A signal occured while spu_run was in progress.  The  npc  value
84              has been updated to the new program counter value if necessary.
85
86       EINVAL fd is not a file descriptor returned from spu_create(2).
87
88       ENOMEM Insufficient memory was available to handle a page fault result‐
89              ing from an MFC direct memory access.
90
91       ENOSYS the functionality is not provided by the current system, because
92              either the hardware does not provide SPUs or the spufs module is
93              not loaded.
94

NOTES

96       spu_run is meant to be  used  from  libraries  that  implement  a  more
97       abstract  interface  to SPUs, not to be used from regular applications.
98       See http://www.bsc.es/projects/deepcomputing/linuxoncell/ for the  rec‐
99       ommended libraries.
100
101

CONFORMING TO

103       This call is Linux specific and only implemented by the ppc64 architec‐
104       ture. Programs using this system call are not portable.
105
106

BUGS

108       The code does not yet fully implement all features lined out here.
109
110

AUTHOR

112       Arnd Bergmann <arndb@de.ibm.com>
113