1 .\" Copyright (c) International Business Machines Corp., 2006
3 .\" %%%LICENSE_START(GPLv2+_SW_3_PARA)
4 .\" This program is free software; you can redistribute it and/or
5 .\" modify it under the terms of the GNU General Public License as
6 .\" published by the Free Software Foundation; either version 2 of
7 .\" the License, or (at your option) any later version.
9 .\" This program is distributed in the hope that it will be useful,
10 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
11 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
12 .\" the GNU General Public License for more details.
14 .\" You should have received a copy of the GNU General Public
15 .\" License along with this manual; if not, see
16 .\" <http://www.gnu.org/licenses/>.
20 .\" 2005-09-28, created by Arnd Bergmann <arndb@de.ibm.com>
21 .\" 2006-06-16, revised by Eduardo M. Fleury <efleury@br.ibm.com>
22 .\" 2007-07-10, some polishing by mtk
23 .\" 2007-09-28, updates for newer kernels, added example
24 .\" by Jeremy Kerr <jk@ozlabs.org>
26 .TH SPU_RUN 2 2012-08-05 Linux "Linux Programmer's Manual"
28 spu_run \- execute an SPU context
31 .B #include <sys/spu.h>
33 .BI "int spu_run(int " fd ", unsigned int *" npc \
34 ", unsigned int *" event ");"
38 There is no glibc wrapper for this system call; see NOTES.
42 system call is used on PowerPC machines that implement the
43 Cell Broadband Engine Architecture in order to access Synergistic
44 Processor Units (SPUs).
47 argument is a file descriptor returned by
49 that refers to a specific SPU context.
50 When the context gets scheduled to a physical SPU,
51 it starts execution at the instruction pointer passed in
54 Execution of SPU code happens synchronously, meaning that
56 blocks while the SPU is still running.
58 to execute SPU code in parallel with other code on either the
59 main CPU or other SPUs, a new thread of execution must be created
61 .BR pthread_create (3)).
65 returns, the current value of the SPU program counter is written to
67 so successive calls to
75 argument provides a buffer for an extended status code.
77 context was created with the
78 .B SPU_CREATE_EVENTS_ENABLED
79 flag, then this buffer is populated by the Linux kernel before
83 The status code may be one (or more) of the following constants:
85 .B SPE_EVENT_DMA_ALIGNMENT
86 A DMA alignment error occurred.
88 .B SPE_EVENT_INVALID_DMA
89 An invalid MFC DMA command was attempted.
91 .B SPE_EVENT_SPE_DATA_STORAGE
92 A DMA storage error occurred.
94 .B SPE_EVENT_SPE_ERROR
95 An illegal instruction was executed.
98 is a valid value for the
101 In this case, the events will not be reported to the calling process.
105 returns the value of the
108 On error, it returns \-1 and sets
110 to one of the error codes listed below.
114 register value is a bit mask of status codes and
115 optionally a 14-bit code returned from the
117 instruction on the SPU.
118 The bit masks for the status codes
132 SPU is waiting for a channel.
135 SPU is in single-step mode.
138 SPU has tried to execute an invalid instruction.
141 SPU has tried to access an invalid channel.
144 The bits masked with this value contain the code returned from a
147 These bits are valid only if the 0x02 bit is set.
151 has not returned an error, one or more bits among the lower eight
157 is not a valid file descriptor.
161 is not a valid pointer, or
163 is non-NULL and an invalid pointer.
166 A signal occurred while
172 value has been updated to the new program counter value if
177 is not a valid file descriptor returned from
181 There was not enough memory available to handle a page fault
182 resulting from a Memory Flow Controller (MFC) direct memory access.
185 The functionality is not provided by the current system, because
186 either the hardware does not provide SPUs or the spufs module is not
191 system call was added to Linux in kernel 2.6.16.
193 This call is Linux-specific and implemented only by the PowerPC
195 Programs using this system call are not portable.
197 Glibc does not provide a wrapper for this system call; call it using
201 is meant to be used from libraries that implement a more abstract
202 interface to SPUs, not to be used from regular applications.
204 .UR http://www.bsc.es\:/projects\:/deepcomputing\:/linuxoncell/
206 for the recommended libraries.
208 The following is an example of running a simple, one-instruction SPU
218 #include <sys/types.h>
221 #define handle_error(msg) \\
222 do { perror(msg); exit(EXIT_FAILURE); } while (0)
226 int context, fd, spu_status;
227 uint32_t instruction, npc;
229 context = spu_create("/spu/example\-context", 0, 0755);
231 handle_error("spu_create");
233 /* write a \(aqstop 0x1234\(aq instruction to the SPU\(aqs
236 instruction = 0x00001234;
238 fd = open("/spu/example\-context/mem", O_RDWR);
240 handle_error("open");
241 write(fd, &instruction, sizeof(instruction));
243 /* set npc to the starting instruction address of the
244 * SPU program. Since we wrote the instruction at the
245 * start of the mem file, the entry point will be 0x0
249 spu_status = spu_run(context, &npc, NULL);
250 if (spu_status == \-1)
251 handle_error("open");
253 /* we should see a status code of 0x1234002:
254 * 0x00000002 (spu was stopped due to stop\-and\-signal)
255 * | 0x12340000 (the stop\-and\-signal code)
257 printf("SPU Status: 0x%08x\\n", spu_status);
263 .\" Arnd Bergmann <arndb@de.ibm.com>, Jeremy Kerr <jk@ozlabs.org>
267 .BR capabilities (7),