1 .\" Copyright (c) International Business Machines Corp., 2006
3 .\" This program is free software; you can redistribute it and/or
4 .\" modify it under the terms of the GNU General Public License as
5 .\" published by the Free Software Foundation; either version 2 of
6 .\" the License, or (at your option) any later version.
8 .\" This program is distributed in the hope that it will be useful,
9 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
10 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
11 .\" the GNU General Public License for more details.
13 .\" You should have received a copy of the GNU General Public License
14 .\" along with this program; if not, write to the Free Software
15 .\" Foundation, Inc., 59 Temple Place, Suite 330, Boston,
19 .\" 2005-09-28, created by Arnd Bergmann <arndb@de.ibm.com>
20 .\" 2006-06-16, revised by Eduardo M. Fleury <efleury@br.ibm.com>
21 .\" 2007-07-10, some polishing by mtk
22 .\" 2007-09-28, updates for newer kernels, added example
23 .\" by Jeremy Kerr <jk@ozlabs.org>
25 .TH SPU_RUN 2 2007-11-25 Linux "Linux Programmer's Manual"
27 spu_run \- execute an SPU context
30 .B #include <sys/spu.h>
32 .BI "int spu_run(int " fd ", unsigned int *" npc \
33 ", unsigned int *" event ");"
38 system call is used on PowerPC machines that implement the
39 Cell Broadband Engine Architecture in order to access Synergistic
40 Processor Units (SPUs).
43 argument is a file descriptor returned by
45 that refers to a specific SPU context.
46 When the context gets scheduled to a physical SPU,
47 it starts execution at the instruction pointer passed in
50 Execution of SPU code happens synchronously, meaning that
52 blocks while the SPU is still running.
54 to execute SPU code in parallel with other code on either the
55 main CPU or other SPUs, a new thread of execution must be created
57 .BR pthread_create (3)).
61 returns, the current value of the SPU program counter is written to
63 so successive calls to
71 argument provides a buffer for an extended status code.
73 context was created with the
74 .B SPU_CREATE_EVENTS_ENABLED
75 flag, then this buffer is populated by the Linux kernel before
79 The status code may be one (or more) of the following constants:
81 .B SPE_EVENT_DMA_ALIGNMENT
82 A DMA alignment error occurred.
84 .B SPE_EVENT_INVALID_DMA
85 An invalid MFC DMA command was attempted.
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 error it returns \-1 and sets
106 to one of the error codes listed below.
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 only valid 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 only implemented by the PowerPC
191 Programs using this system call are not portable.
193 Glibc does not provide a wrapper for this system call; call it using
197 is meant to be used from libraries that implement a more abstract
198 interface to SPUs, not to be used from regular applications.
200 .I http://www.bsc.es/projects/deepcomputing/linuxoncell/
201 for the recommended libraries.
203 The following is an example of running a simple, one-instruction SPU
213 #include <sys/types.h>
216 #define handle_error(msg) \\
217 do { perror(msg); exit(EXIT_FAILURE); } while (0)
221 int context, fd, spu_status;
222 uint32_t instruction, npc;
224 context = spu_create("/spu/example\-context", 0, 0755);
226 handle_error("spu_create");
228 /* write a \(aqstop 0x1234\(aq instruction to the SPU\(aqs
231 instruction = 0x00001234;
233 fd = open("/spu/example\-context/mem", O_RDWR);
235 handle_error("open");
236 write(fd, &instruction, sizeof(instruction));
238 /* set npc to the starting instruction address of the
239 * SPU program. Since we wrote the instruction at the
240 * start of the mem file, the entry point will be 0x0
244 spu_status = spu_run(context, &npc, NULL);
245 if (spu_status == \-1)
246 handle_error("open");
248 /* we should see a status code of 0x1234002:
249 * 0x00000002 (spu was stopped due to stop\-and\-signal)
250 * | 0x12340000 (the stop\-and\-signal code)
252 printf("SPU Status: 0x%08x\\n", spu_status);
258 .\" Arnd Bergmann <arndb@de.ibm.com>, Jeremy Kerr <jk@ozlabs.org>
262 .BR capabilities (7),