1spu_run(2) System Calls Manual spu_run(2)
2
6 spu_run - execute an SPU context
7
9 Standard C library (libc, -lc)
10
12 #include <sys/spu.h> /* Definition of SPU_* constants */
13 #include <sys/syscall.h> /* Definition of SYS_* constants */
14 #include <unistd.h>
15 int syscall(SYS_spu_run, int fd, uint32_t *npc, uint32_t *event);
17 Note: glibc provides no wrapper for spu_run(), necessitating the use of
19 syscall(2).
20
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 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 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 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 The status code may be one (or more) of the following constants:
45 SPE_EVENT_DMA_ALIGNMENT
47 A DMA alignment error occurred.
48 SPE_EVENT_INVALID_DMA
50 An invalid MFC DMA command was attempted.
51 SPE_EVENT_SPE_DATA_STORAGE
53 A DMA storage error occurred.
54 SPE_EVENT_SPE_ERROR
56 An illegal instruction was executed.
57 NULL is a valid value for the event argument. In this case, the events
59 will not be reported to the calling process.
60
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 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 0x02 SPU was stopped by a stop-and-signal instruction.
70 0x04 SPU was stopped by a halt instruction.
72 0x08 SPU is waiting for a channel.
74 0x10 SPU is in single-step mode.
76 0x20 SPU has tried to execute an invalid instruction.
78 0x40 SPU has tried to access an invalid channel.
80 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 If spu_run() has not returned an error, one or more bits among the
87 lower eight ones are always set.
88
90 EBADF fd is not a valid file descriptor.
91 EFAULT npc is not a valid pointer, or event is non-NULL and an invalid
93 pointer.
94 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 EINVAL fd is not a valid file descriptor returned from spu_create(2).
100 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 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
110 Linux on PowerPC.
111
113 Linux 2.6.16.
114
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
122 The following is an example of running a simple, one-instruction SPU
123 program with the spu_run() system call.
124 #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 int main(void)
134 {
135 int context, fd, spu_status;
136 uint32_t instruction, npc;
137 context = syscall(SYS_spu_create, "/spu/example-context", 0, 0755);
139 if (context == -1)
140 err(EXIT_FAILURE, "spu_create");
141 /*
143 * Write a 'stop 0x1234' instruction to the SPU's
144 * local store memory.
145 */
146 instruction = 0x00001234;
147 fd = open("/spu/example-context/mem", O_RDWR);
149 if (fd == -1)
150 err(EXIT_FAILURE, "open");
151 write(fd, &instruction, sizeof(instruction));
152 /*
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 spu_status = syscall(SYS_spu_run, context, &npc, NULL);
161 if (spu_status == -1)
162 err(EXIT_FAILURE, "open");
163 /*
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 exit(EXIT_SUCCESS);
172 }
173
175 close(2), spu_create(2), capabilities(7), spufs(7)
176Linux man-pages 6.05 2023-05-03 spu_run(2)