Debian Codegraph @

upstream/debian-unstable/man2/spu_create.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_create 2 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 spu_create \- create a new 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_create, const char *" path ", unsigned int " flags ,
19 .BI " mode_t " mode ", int " neighbor_fd );
20 .fi
21 .P
22 .IR Note :
23 glibc provides no wrapper for
24 .BR spu_create (),
25 necessitating the use of
26 .BR syscall (2).
27 .SH DESCRIPTION
28 The
29 .BR spu_create ()
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 It creates a new logical context for an SPU in
34 .I path
35 and returns a file descriptor associated with it.
36 .I path
37 must refer to a nonexistent directory in the mount point of
38 the SPU filesystem
39 .RB ( spufs ).
40 If
41 .BR spu_create ()
42 is successful, a directory is created at
43 .I path
44 and it is populated with the files described in
45 .BR spufs (7).
46 .P
47 When a context is created,
48 the returned file descriptor can only be passed to
49 .BR spu_run (2),
50 used as the
51 .I dirfd
52 argument to the
53 .B *at
54 family of system calls (e.g.,
55 .BR openat (2)),
56 or closed;
57 other operations are not defined.
58 A logical SPU
59 context is destroyed (along with all files created within the context's
60 .I path
61 directory) once the last reference to the context has gone;
62 this usually occurs when the file descriptor returned by
63 .BR spu_create ()
64 is closed.
65 .P
66 The
67 .I mode
68 argument (minus any bits set in the process's
69 .BR umask (2))
70 specifies the permissions used for creating the new directory in
71 .BR spufs .
72 See
73 .BR stat (2)
74 for a full list of the possible
75 .I mode
76 values.
77 .P
78 The
79 .I neighbor_fd
80 is used only when the
81 .B SPU_CREATE_AFFINITY_SPU
82 flag is specified;
83 see below.
84 .P
85 The
86 .I flags
87 argument can be zero or any bitwise OR-ed
88 combination of the following constants:
89 .TP
90 .B SPU_CREATE_EVENTS_ENABLED
91 Rather than using signals for reporting DMA errors, use the
92 .I event
93 argument to
94 .BR spu_run (2).
95 .TP
96 .B SPU_CREATE_GANG
97 Create an SPU gang instead of a context.
98 (A gang is a group of SPU contexts that are
99 functionally related to each other and which share common scheduling
100 parameters\[em]priority and policy.
101 In the future, gang scheduling may be implemented causing
102 the group to be switched in and out as a single unit.)
103 .IP
104 A new directory will be created at the location specified by the
105 .I path
106 argument.
107 This gang may be used to hold other SPU contexts, by providing
108 a pathname that is within the gang directory to further calls to
109 .BR spu_create ().
110 .TP
111 .B SPU_CREATE_NOSCHED
112 Create a context that is not affected by the SPU scheduler.
113 Once the context is run,
114 it will not be scheduled out until it is destroyed by
115 the creating process.
116 .IP
117 Because the context cannot be removed from the SPU, some functionality
118 is disabled for
119 .B SPU_CREATE_NOSCHED
120 contexts.
121 Only a subset of the files will be
122 available in this context directory in
123 .BR spufs .
124 Additionally,
125 .B SPU_CREATE_NOSCHED
126 contexts cannot dump a core file when crashing.
127 .IP
128 Creating
129 .B SPU_CREATE_NOSCHED
130 contexts requires the
131 .B CAP_SYS_NICE
132 capability.
133 .TP
134 .B SPU_CREATE_ISOLATE
135 Create an isolated SPU context.
136 Isolated contexts are protected from some
137 PPE (PowerPC Processing Element)
138 operations,
139 such as access to the SPU local store and the NPC register.
140 .IP
141 Creating
142 .B SPU_CREATE_ISOLATE
143 contexts also requires the
144 .B SPU_CREATE_NOSCHED
145 flag.
146 .TP
147 .BR SPU_CREATE_AFFINITY_SPU " (since Linux 2.6.23)"
148 .\" commit 8e68e2f248332a9c3fd4f08258f488c209bd3e0c
149 Create a context with affinity to another SPU context.
150 This affinity information is used within the SPU scheduling algorithm.
151 Using this flag requires that a file descriptor referring to
152 the other SPU context be passed in the
153 .I neighbor_fd
154 argument.
155 .TP
156 .BR SPU_CREATE_AFFINITY_MEM " (since Linux 2.6.23)"
157 .\" commit 8e68e2f248332a9c3fd4f08258f488c209bd3e0c
158 Create a context with affinity to system memory.
159 This affinity information
160 is used within the SPU scheduling algorithm.
161 .SH RETURN VALUE
162 On success,
163 .BR spu_create ()
164 returns a new file descriptor.
165 On failure, \-1 is returned, and
166 .I errno
167 is set to indicate the error.
168 .SH ERRORS
169 .TP
170 .B EACCES
171 The current user does not have write access to the
172 .BR spufs (7)
173 mount point.
174 .TP
175 .B EEXIST
176 An SPU context already exists at the given pathname.
177 .TP
178 .B EFAULT
179 .I path
180 is not a valid string pointer in the
181 calling process's address space.
182 .TP
183 .B EINVAL
184 .I path
185 is not a directory in the
186 .BR spufs (7)
187 mount point, or invalid flags have been provided.
188 .TP
189 .B ELOOP
190 Too many symbolic links were found while resolving
191 .IR path .
192 .TP
193 .B EMFILE
194 The per-process limit on the number of open file descriptors has been reached.
195 .TP
196 .B ENAMETOOLONG
197 .I path
198 is too long.
199 .TP
200 .B ENFILE
201 The system-wide limit on the total number of open files has been reached.
202 .TP
203 .B ENODEV
204 An isolated context was requested, but the hardware does not support
205 SPU isolation.
206 .TP
207 .B ENOENT
208 Part of
209 .I path
210 could not be resolved.
211 .TP
212 .B ENOMEM
213 The kernel could not allocate all resources required.
214 .TP
215 .B ENOSPC
216 There are not enough SPU resources available to create
217 a new context or the user-specific limit for the number
218 of SPU contexts has been reached.
219 .TP
220 .B ENOSYS
221 The functionality is not provided by the current system, because
222 either the hardware does not provide SPUs or the spufs module is not
223 loaded.
224 .TP
225 .B ENOTDIR
226 A part of
227 .I path
228 is not a directory.
229 .TP
230 .B EPERM
231 The
232 .B SPU_CREATE_NOSCHED
233 flag has been given, but the user does not have the
234 .B CAP_SYS_NICE
235 capability.
236 .SH FILES
237 .I path
238 must point to a location beneath the mount point of
239 .BR spufs .
240 By convention, it gets mounted in
241 .IR /spu .
242 .SH STANDARDS
243 Linux on PowerPC.
244 .SH HISTORY
245 Linux 2.6.16.
246 .P
247 Prior to the addition of the
248 .B SPU_CREATE_AFFINITY_SPU
249 flag in Linux 2.6.23, the
250 .BR spu_create ()
251 system call took only three arguments (i.e., there was no
252 .I neighbor_fd
253 argument).
254 .SH NOTES
255 .BR spu_create ()
256 is meant to be used from libraries that implement a more abstract
257 interface to SPUs, not to be used from regular applications.
258 See
259 .UR http:\://www.bsc.es\:/projects\:/deepcomputing\:/linuxoncell/
260 .UE
261 for the recommended libraries.
262 .SH EXAMPLES
263 See
264 .BR spu_run (2)
265 for an example of the use of
266 .BR spu_create ()
267 .SH SEE ALSO
268 .BR close (2),
269 .BR spu_run (2),
270 .BR capabilities (7),
271 .BR spufs (7)