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

NAME

6       spu_run - execute an SPU context
7

SYNOPSIS

9       #include <sys/spu.h>
10
11       int spu_run(int fd, unsigned int *npc, unsigned int *event);
12
13       Note: There is no glibc wrapper for this system call; see NOTES.
14

DESCRIPTION

16       The  spu_run()  system  call is used on PowerPC machines that implement
17       the Cell Broadband Engine Architecture in order to  access  Synergistic
18       Processor  Units (SPUs).  The fd argument is a file descriptor returned
19       by spu_create(2) that refers to a specific SPU context.  When the  con‐
20       text  gets  scheduled  to  a  physical  SPU, it starts execution at the
21       instruction pointer passed in npc.
22
23       Execution of SPU code happens  synchronously,  meaning  that  spu_run()
24       blocks  while  the SPU is still running.  If there is a need to execute
25       SPU code in parallel with other code on either the main  CPU  or  other
26       SPUs,  a  new  thread  of  execution must be created first (e.g., using
27       pthread_create(3)).
28
29       When spu_run() returns, the current value of the SPU program counter is
30       written  to  npc, so successive calls to spu_run() can use the same npc
31       pointer.
32
33       The event argument provides a buffer for an extended status  code.   If
34       the  SPU  context  was created with the SPU_CREATE_EVENTS_ENABLED flag,
35       then this buffer is populated by  the  Linux  kernel  before  spu_run()
36       returns.
37
38       The status code may be one (or more) of the following constants:
39
40       SPE_EVENT_DMA_ALIGNMENT
41              A DMA alignment error occurred.
42
43       SPE_EVENT_INVALID_DMA
44              An invalid MFC DMA command was attempted.
45
46       SPE_EVENT_SPE_DATA_STORAGE
47              A DMA storage error occurred.
48
49       SPE_EVENT_SPE_ERROR
50              An illegal instruction was executed.
51
52       NULL is a valid value for the event argument.  In this case, the events
53       will not be reported to the calling process.
54

RETURN VALUE

56       On success, spu_run() returns the value of the spu_status register.  On
57       error,  it  returns  -1 and sets errno to one of the error codes listed
58       below.
59
60       The spu_status register value is a bit mask of status codes and option‐
61       ally a 14-bit code returned from the stop-and-signal instruction on the
62       SPU.  The bit masks for the status codes are:
63
64       0x02   SPU was stopped by a stop-and-signal instruction.
65
66       0x04   SPU was stopped by a halt instruction.
67
68       0x08   SPU is waiting for a channel.
69
70       0x10   SPU is in single-step mode.
71
72       0x20   SPU has tried to execute an invalid instruction.
73
74       0x40   SPU has tried to access an invalid channel.
75
76       0x3fff0000
77              The bits masked with this value contain the code returned from a
78              stop-and-signal  instruction.   These bits are valid only if the
79              0x02 bit is set.
80
81       If spu_run() has not returned an error, one  or  more  bits  among  the
82       lower eight ones are always set.
83

ERRORS

85       EBADF  fd is not a valid file descriptor.
86
87       EFAULT npc  is not a valid pointer, or event is non-NULL and an invalid
88              pointer.
89
90       EINTR  A signal occurred while spu_run()  was  in  progress;  see  sig‐
91              nal(7).   The  npc  value  has  been  updated to the new program
92              counter value if necessary.
93
94       EINVAL fd is not a valid file descriptor returned from spu_create(2).
95
96       ENOMEM There was not enough memory available to  handle  a  page  fault
97              resulting  from  a  Memory  Flow  Controller (MFC) direct memory
98              access.
99
100       ENOSYS The functionality is not provided by the current system, because
101              either the hardware does not provide SPUs or the spufs module is
102              not loaded.
103

VERSIONS

105       The spu_run() system call was added to Linux in kernel 2.6.16.
106

CONFORMING TO

108       This call is Linux-specific and implemented only by the PowerPC  archi‐
109       tecture.  Programs using this system call are not portable.
110

NOTES

112       Glibc  does  not  provide a wrapper for this system call; call it using
113       syscall(2).  Note however, that spu_run() is  meant  to  be  used  from
114       libraries  that  implement a more abstract interface to SPUs, not to be
115       used  from  regular  applications.    See   ⟨http://www.bsc.es/projects
116       /deepcomputing/linuxoncell/⟩ for the recommended libraries.
117

EXAMPLE

119       The  following  is  an example of running a simple, one-instruction SPU
120       program with the spu_run() system call.
121
122       #include <stdlib.h>
123       #include <stdint.h>
124       #include <unistd.h>
125       #include <stdio.h>
126       #include <sys/types.h>
127       #include <fcntl.h>
128
129       #define handle_error(msg) \
130           do { perror(msg); exit(EXIT_FAILURE); } while (0)
131
132       int main(void)
133       {
134           int context, fd, spu_status;
135           uint32_t instruction, npc;
136
137           context = spu_create("/spu/example-context", 0, 0755);
138           if (context == -1)
139               handle_error("spu_create");
140
141           /* write a 'stop 0x1234' instruction to the SPU's
142            * local store memory
143            */
144           instruction = 0x00001234;
145
146           fd = open("/spu/example-context/mem", O_RDWR);
147           if (fd == -1)
148               handle_error("open");
149           write(fd, &instruction, sizeof(instruction));
150
151           /* set npc to the starting instruction address of the
152            * SPU program. Since we wrote the instruction at the
153            * start of the mem file, the entry point will be 0x0
154            */
155           npc = 0;
156
157           spu_status = spu_run(context, &npc, NULL);
158           if (spu_status == -1)
159               handle_error("open");
160
161           /* we should see a status code of 0x1234002:
162            *   0x00000002 (spu was stopped due to stop-and-signal)
163            * | 0x12340000 (the stop-and-signal code)
164            */
165           printf("SPU Status: 0x%08x\n", spu_status);
166
167           exit(EXIT_SUCCESS);
168       }
169

SEE ALSO

171       close(2), spu_create(2), capabilities(7), spufs(7)
172

COLOPHON

174       This page is part of release 4.16 of the Linux  man-pages  project.   A
175       description  of  the project, information about reporting bugs, and the
176       latest    version    of    this    page,    can     be     found     at
177       https://www.kernel.org/doc/man-pages/.
178
179
180
181Linux                             2017-09-15                        SPU_RUN(2)
Impressum