Debian Codegraph @

upstream/debian-unstable/man2/spu_run.2

raw
1 .\" Copyright 2006, International Business Machines Corp.
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: GPL-2.0-or-later
5 .\"
6 .TH spu_run 2 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 spu_run \- execute an SPU context
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .SH SYNOPSIS
13 .nf
14 .BR "#include <sys/spu.h>" " /* Definition of " SPU_* " constants */"
15 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
16 .B #include <unistd.h>
17 .P
18 .BI "int syscall(SYS_spu_run, int " fd ", uint32_t *" npc \
19 ", uint32_t *" event );
20 .fi
21 .P
22 .IR Note :
23 glibc provides no wrapper for
24 .BR spu_run (),
25 necessitating the use of
26 .BR syscall (2).
27 .SH DESCRIPTION
28 The
29 .BR spu_run ()
30 system call is used on PowerPC machines that implement the
31 Cell Broadband Engine Architecture in order to access Synergistic
32 Processor Units (SPUs).
33 The
34 .I fd
35 argument is a file descriptor returned by
36 .BR spu_create (2)
37 that refers to a specific SPU context.
38 When the context gets scheduled to a physical SPU,
39 it starts execution at the instruction pointer passed in
40 .IR npc .
41 .P
42 Execution of SPU code happens synchronously, meaning that
43 .BR spu_run ()
44 blocks while the SPU is still running.
45 If there is a need
46 to execute SPU code in parallel with other code on either the
47 main CPU or other SPUs, a new thread of execution must be created
48 first (e.g., using
49 .BR pthread_create (3)).
50 .P
51 When
52 .BR spu_run ()
53 returns, the current value of the SPU program counter is written to
54 .IR npc ,
55 so successive calls to
56 .BR spu_run ()
57 can use the same
58 .I npc
59 pointer.
60 .P
61 The
62 .I event
63 argument provides a buffer for an extended status code.
64 If the SPU
65 context was created with the
66 .B SPU_CREATE_EVENTS_ENABLED
67 flag, then this buffer is populated by the Linux kernel before
68 .BR spu_run ()
69 returns.
70 .P
71 The status code may be one (or more) of the following constants:
72 .TP
73 .B SPE_EVENT_DMA_ALIGNMENT
74 A DMA alignment error occurred.
75 .TP
76 .B SPE_EVENT_INVALID_DMA
77 An invalid MFC DMA command was attempted.
78 .\" SPE_EVENT_SPE_DATA_SEGMENT is defined, but does not seem to be generated
79 .\" at any point (in Linux 5.9 sources).
80 .TP
81 .B SPE_EVENT_SPE_DATA_STORAGE
82 A DMA storage error occurred.
83 .TP
84 .B SPE_EVENT_SPE_ERROR
85 An illegal instruction was executed.
86 .P
87 NULL
88 is a valid value for the
89 .I event
90 argument.
91 In this case, the events will not be reported to the calling process.
92 .SH RETURN VALUE
93 On success,
94 .BR spu_run ()
95 returns the value of the
96 .I spu_status
97 register.
98 On failure, it returns \-1 and sets
99 .I errno
100 is set to indicate the error.
101 .P
102 The
103 .I spu_status
104 register value is a bit mask of status codes and
105 optionally a 14-bit code returned from the
106 .B stop-and-signal
107 instruction on the SPU.
108 The bit masks for the status codes
109 are:
110 .TP
111 .B 0x02
112 SPU was stopped by a
113 .B stop-and-signal
114 instruction.
115 .TP
116 .B 0x04
117 SPU was stopped by a
118 .B halt
119 instruction.
120 .TP
121 .B 0x08
122 SPU is waiting for a channel.
123 .TP
124 .B 0x10
125 SPU is in single-step mode.
126 .TP
127 .B 0x20
128 SPU has tried to execute an invalid instruction.
129 .TP
130 .B 0x40
131 SPU has tried to access an invalid channel.
132 .TP
133 .B 0x3fff0000
134 The bits masked with this value contain the code returned from a
135 .B stop-and-signal
136 instruction.
137 These bits are valid only if the 0x02 bit is set.
138 .P
139 If
140 .BR spu_run ()
141 has not returned an error, one or more bits among the lower eight
142 ones are always set.
143 .SH ERRORS
144 .TP
145 .B EBADF
146 .I fd
147 is not a valid file descriptor.
148 .TP
149 .B EFAULT
150 .I npc
151 is not a valid pointer, or
152 .I event
153 is non-NULL and an invalid pointer.
154 .TP
155 .B EINTR
156 A signal occurred while
157 .BR spu_run ()
158 was in progress;
159 see
160 .BR signal (7).
161 The
162 .I npc
163 value has been updated to the new program counter value if
164 necessary.
165 .TP
166 .B EINVAL
167 .I fd
168 is not a valid file descriptor returned from
169 .BR spu_create (2).
170 .TP
171 .B ENOMEM
172 There was not enough memory available to handle a page fault
173 resulting from a Memory Flow Controller (MFC) direct memory access.
174 .TP
175 .B ENOSYS
176 The functionality is not provided by the current system, because
177 either the hardware does not provide SPUs or the spufs module is not
178 loaded.
179 .SH STANDARDS
180 Linux on PowerPC.
181 .SH HISTORY
182 Linux 2.6.16.
183 .SH NOTES
184 .BR spu_run ()
185 is meant to be used from libraries that implement a more abstract
186 interface to SPUs, not to be used from regular applications.
187 See
188 .UR http:\://www.bsc.es\:/projects\:/deepcomputing\:/linuxoncell/
189 .UE
190 for the recommended libraries.
191 .SH EXAMPLES
192 The following is an example of running a simple, one-instruction SPU
193 program with the
194 .BR spu_run ()
195 system call.
196 .P
197 .\" SRC BEGIN (spu_run.c)
198 .EX
199 #include <err.h>
200 #include <fcntl.h>
201 #include <stdint.h>
202 #include <stdio.h>
203 #include <stdlib.h>
204 #include <sys/types.h>
205 #include <unistd.h>
206 \&
207 int main(void)
208 {
209 int context, fd, spu_status;
210 uint32_t instruction, npc;
211 \&
212 context = syscall(SYS_spu_create, "/spu/example\-context", 0, 0755);
213 if (context == \-1)
214 err(EXIT_FAILURE, "spu_create");
215 \&
216 /*
217 * Write a \[aq]stop 0x1234\[aq] instruction to the SPU\[aq]s
218 * local store memory.
219 */
220 instruction = 0x00001234;
221 \&
222 fd = open("/spu/example\-context/mem", O_RDWR);
223 if (fd == \-1)
224 err(EXIT_FAILURE, "open");
225 write(fd, &instruction, sizeof(instruction));
226 \&
227 /*
228 * set npc to the starting instruction address of the
229 * SPU program. Since we wrote the instruction at the
230 * start of the mem file, the entry point will be 0x0.
231 */
232 npc = 0;
233 \&
234 spu_status = syscall(SYS_spu_run, context, &npc, NULL);
235 if (spu_status == \-1)
236 err(EXIT_FAILURE, "open");
237 \&
238 /*
239 * We should see a status code of 0x12340002:
240 * 0x00000002 (spu was stopped due to stop\-and\-signal)
241 * | 0x12340000 (the stop\-and\-signal code)
242 */
243 printf("SPU Status: %#08x\[rs]n", spu_status);
244 \&
245 exit(EXIT_SUCCESS);
246 }
247 .EE
248 .\" SRC END
249 .\" .SH AUTHORS
250 .\" Arnd Bergmann <[email protected]>, Jeremy Kerr <[email protected]>
251 .SH SEE ALSO
252 .BR close (2),
253 .BR spu_create (2),
254 .BR capabilities (7),
255 .BR spufs (7)