1SPU_RUN(2) Linux Programmer's Manual SPU_RUN(2)
2
6 spu_run - execute an SPU context
7
9 #include <sys/spu.h>
10 int spu_run(int fd, unsigned int *npc, unsigned int *event);
12
14 The spu_run() system call is used on PowerPC machines that implement
15 the Cell Broadband Engine Architecture in order to access Synergistic
16 Processor Units (SPUs). The fd argument is a file descriptor returned
17 by spu_create(2) that refers to a specific SPU context. When the con‐
18 text gets scheduled to a physical SPU, it starts execution at the
19 instruction pointer passed in npc.
20 Execution of SPU code happens synchronously, meaning that spu_run()
22 blocks while the SPU is still running. If there is a need to execute
23 SPU code in parallel with other code on either the main CPU or other
24 SPUs, a new thread of execution must be created first (e.g., using
25 pthread_create(3)).
26 When spu_run() returns, the current value of the SPU program counter is
28 written to npc, so successive calls to spu_run() can use the same npc
29 pointer.
30 The event argument provides a buffer for an extended status code. If
32 the SPU context was created with the SPU_CREATE_EVENTS_ENABLED flag,
33 then this buffer is populated by the Linux kernel before spu_run()
34 returns.
35 The status code may be one (or more) of the following constants:
37 SPE_EVENT_DMA_ALIGNMENT
39 A DMA alignment error occurred.
40 SPE_EVENT_INVALID_DMA
42 An invalid MFC DMA command was attempted.
43 SPE_EVENT_SPE_DATA_STORAGE
45 A DMA storage error occurred.
46 SPE_EVENT_SPE_ERROR
48 An illegal instruction was executed.
49 NULL is a valid value for the event argument. In this case, the events
51 will not be reported to the calling process.
52
54 On success, spu_run() returns the value of the spu_status register. On
55 error it returns -1 and sets errno to one of the error codes listed
56 below.
57 The spu_status register value is a bit mask of status codes and option‐
59 ally a 14-bit code returned from the stop-and-signal instruction on the
60 SPU. The bit masks for the status codes are:
61 0x02 SPU was stopped by a stop-and-signal instruction.
63 0x04 SPU was stopped by a halt instruction.
65 0x08 SPU is waiting for a channel.
67 0x10 SPU is in single-step mode.
69 0x20 SPU has tried to execute an invalid instruction.
71 0x40 SPU has tried to access an invalid channel.
73 0x3fff0000
75 The bits masked with this value contain the code returned from a
76 stop-and-signal instruction. These bits are only valid if the
77 0x02 bit is set.
78 If spu_run() has not returned an error, one or more bits among the
80 lower eight ones are always set.
81
83 EBADF fd is not a valid file descriptor.
84 EFAULT npc is not a valid pointer, or event is non-NULL and an invalid
86 pointer.
87 EINTR A signal occurred while spu_run() was in progress; see sig‐
89 nal(7). The npc value has been updated to the new program
90 counter value if necessary.
91 EINVAL fd is not a valid file descriptor returned from spu_create(2).
93 ENOMEM There was not enough memory available to handle a page fault
95 resulting from a Memory Flow Controller (MFC) direct memory
96 access.
97 ENOSYS The functionality is not provided by the current system, because
99 either the hardware does not provide SPUs or the spufs module is
100 not loaded.
101
103 The spu_run() system call was added to Linux in kernel 2.6.16.
104
106 This call is Linux-specific and only implemented by the PowerPC archi‐
107 tecture. Programs using this system call are not portable.
108
110 Glibc does not provide a wrapper for this system call; call it using
111 syscall(2). Note however, that spu_run() is meant to be used from
112 libraries that implement a more abstract interface to SPUs, not to be
113 used from regular applications. See http://www.bsc.es/projects/deep‐
114 computing/linuxoncell/ for the recommended libraries.
115
117 The following is an example of running a simple, one-instruction SPU
118 program with the spu_run() system call.
119 #include <stdlib.h>
121 #include <stdint.h>
122 #include <unistd.h>
123 #include <stdio.h>
124 #include <sys/types.h>
125 #include <fcntl.h>
126 #define handle_error(msg) \
128 do { perror(msg); exit(EXIT_FAILURE); } while (0)
129 int main(void)
131 {
132 int context, fd, spu_status;
133 uint32_t instruction, npc;
134 context = spu_create("/spu/example-context", 0, 0755);
136 if (context == -1)
137 handle_error("spu_create");
138 /* write a 'stop 0x1234' instruction to the SPU's
140 * local store memory
141 */
142 instruction = 0x00001234;
143 fd = open("/spu/example-context/mem", O_RDWR);
145 if (fd == -1)
146 handle_error("open");
147 write(fd, &instruction, sizeof(instruction));
148 /* set npc to the starting instruction address of the
150 * SPU program. Since we wrote the instruction at the
151 * start of the mem file, the entry point will be 0x0
152 */
153 npc = 0;
154 spu_status = spu_run(context, &npc, NULL);
156 if (spu_status == -1)
157 handle_error("open");
158 /* we should see a status code of 0x1234002:
160 * 0x00000002 (spu was stopped due to stop-and-signal)
161 * | 0x12340000 (the stop-and-signal code)
162 */
163 printf("SPU Status: 0x%08x\n", spu_status);
164 exit(EXIT_SUCCESS);
166 }
167
169 close(2), spu_create(2), capabilities(7), spufs(7)
170
172 This page is part of release 3.25 of the Linux man-pages project. A
173 description of the project, and information about reporting bugs, can
174 be found at http://www.kernel.org/doc/man-pages/.
175Linux 2007-11-25 SPU_RUN(2)