spu_run(2)

1spu_run(2)                    System Calls Manual                   spu_run(2)
2
3
4

NAME

6       spu_run - execute an SPU context
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <sys/spu.h>          /* Definition of SPU_* constants */
13       #include <sys/syscall.h>      /* Definition of SYS_* constants */
14       #include <unistd.h>
15
16       int syscall(SYS_spu_run, int fd, uint32_t *npc, uint32_t *event);
17
18       Note: glibc provides no wrapper for spu_run(), necessitating the use of
19       syscall(2).
20

DESCRIPTION

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

RETURN VALUE

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

ERRORS

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

STANDARDS

110       Linux on PowerPC.
111

HISTORY

113       Linux 2.6.16.
114

NOTES

116       spu_run() is meant to be used from libraries that implement a more  ab‐
117       stract  interface  to  SPUs,  not to be used from regular applications.
118       See  ⟨http://www.bsc.es/projects/deepcomputing/linuxoncell/⟩  for   the
119       recommended libraries.
120

EXAMPLES

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