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