1 .\" Copyright (c) International Business Machines Corp., 2006
3 .\" SPDX-License-Identifier: GPL-2.0-or-later
6 .\" 2005-09-28, created by Arnd Bergmann <arndb@de.ibm.com>
7 .\" 2006-06-16, revised by Eduardo M. Fleury <efleury@br.ibm.com>
8 .\" 2007-07-10, some polishing by mtk
9 .\" 2007-09-28, updates for newer kernels, added example
10 .\" by Jeremy Kerr <jk@ozlabs.org>
12 .TH SPU_RUN 2 2021-03-22 Linux "Linux Programmer's Manual"
14 spu_run \- execute an SPU context
17 .RI ( libc ", " \-lc )
20 .BR "#include <sys/spu.h>" " /* Definition of " SPU_* " constants */"
21 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
22 .B #include <unistd.h>
24 .BI "int syscall(SYS_spu_run, int " fd ", uint32_t *" npc \
25 ", uint32_t *" event );
29 glibc provides no wrapper for
31 necessitating the use of
36 system call is used on PowerPC machines that implement the
37 Cell Broadband Engine Architecture in order to access Synergistic
38 Processor Units (SPUs).
41 argument is a file descriptor returned by
43 that refers to a specific SPU context.
44 When the context gets scheduled to a physical SPU,
45 it starts execution at the instruction pointer passed in
48 Execution of SPU code happens synchronously, meaning that
50 blocks while the SPU is still running.
52 to execute SPU code in parallel with other code on either the
53 main CPU or other SPUs, a new thread of execution must be created
55 .BR pthread_create (3)).
59 returns, the current value of the SPU program counter is written to
61 so successive calls to
69 argument provides a buffer for an extended status code.
71 context was created with the
72 .B SPU_CREATE_EVENTS_ENABLED
73 flag, then this buffer is populated by the Linux kernel before
77 The status code may be one (or more) of the following constants:
79 .B SPE_EVENT_DMA_ALIGNMENT
80 A DMA alignment error occurred.
82 .B SPE_EVENT_INVALID_DMA
83 An invalid MFC DMA command was attempted.
84 .\" SPE_EVENT_SPE_DATA_SEGMENT is defined, but does not seem to be generated
85 .\" at any point (in Linux 5.9 sources).
87 .B SPE_EVENT_SPE_DATA_STORAGE
88 A DMA storage error occurred.
90 .B SPE_EVENT_SPE_ERROR
91 An illegal instruction was executed.
94 is a valid value for the
97 In this case, the events will not be reported to the calling process.
101 returns the value of the
104 On failure, it returns \-1 and sets
106 is set to indicate the error.
110 register value is a bit mask of status codes and
111 optionally a 14-bit code returned from the
113 instruction on the SPU.
114 The bit masks for the status codes
128 SPU is waiting for a channel.
131 SPU is in single-step mode.
134 SPU has tried to execute an invalid instruction.
137 SPU has tried to access an invalid channel.
140 The bits masked with this value contain the code returned from a
143 These bits are valid only if the 0x02 bit is set.
147 has not returned an error, one or more bits among the lower eight
153 is not a valid file descriptor.
157 is not a valid pointer, or
159 is non-NULL and an invalid pointer.
162 A signal occurred while
168 value has been updated to the new program counter value if
173 is not a valid file descriptor returned from
177 There was not enough memory available to handle a page fault
178 resulting from a Memory Flow Controller (MFC) direct memory access.
181 The functionality is not provided by the current system, because
182 either the hardware does not provide SPUs or the spufs module is not
187 system call was added to Linux in kernel 2.6.16.
189 This call is Linux-specific and implemented only by the PowerPC
191 Programs using this system call are not portable.
194 is meant to be used from libraries that implement a more abstract
195 interface to SPUs, not to be used from regular applications.
197 .UR http://www.bsc.es\:/projects\:/deepcomputing\:/linuxoncell/
199 for the recommended libraries.
201 The following is an example of running a simple, one-instruction SPU
206 .\" SRC BEGIN (spu_run.c)
212 #include <sys/types.h>
215 #define handle_error(msg) \e
216 do { perror(msg); exit(EXIT_FAILURE); } while (0)
220 int context, fd, spu_status;
221 uint32_t instruction, npc;
223 context = syscall(SYS_spu_create, "/spu/example\-context", 0, 0755);
225 handle_error("spu_create");
228 * Write a \(aqstop 0x1234\(aq instruction to the SPU\(aqs
229 * local store memory.
231 instruction = 0x00001234;
233 fd = open("/spu/example\-context/mem", O_RDWR);
235 handle_error("open");
236 write(fd, &instruction, sizeof(instruction));
239 * set npc to the starting instruction address of the
240 * SPU program. Since we wrote the instruction at the
241 * start of the mem file, the entry point will be 0x0.
245 spu_status = syscall(SYS_spu_run, context, &npc, NULL);
246 if (spu_status == \-1)
247 handle_error("open");
250 * We should see a status code of 0x1234002:
251 * 0x00000002 (spu was stopped due to stop\-and\-signal)
252 * | 0x12340000 (the stop\-and\-signal code)
254 printf("SPU Status: %#08x\en", spu_status);
261 .\" Arnd Bergmann <arndb@de.ibm.com>, Jeremy Kerr <jk@ozlabs.org>
265 .BR capabilities (7),