Debian Codegraph @

upstream/debian-trixie/man2/spu_run.2

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