]>
Commit | Line | Data |
---|---|---|
d24596d5 | 1 | .\" Copyright (c) International Business Machines Corp., 2006 |
6f5ff36a | 2 | .\" |
f0008367 | 3 | .\" %%%LICENSE_START(GPLv2+_SW_3_PARA) |
d24596d5 | 4 | .\" This program is free software; you can redistribute it and/or |
6f5ff36a MK |
5 | .\" modify it under the terms of the GNU General Public License as |
6 | .\" published by the Free Software Foundation; either version 2 of | |
7 | .\" the License, or (at your option) any later version. | |
8 | .\" | |
9 | .\" This program is distributed in the hope that it will be useful, | |
d24596d5 MK |
10 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of |
11 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See | |
6f5ff36a MK |
12 | .\" the GNU General Public License for more details. |
13 | .\" | |
68fa4398 MK |
14 | .\" You should have received a copy of the GNU General Public |
15 | .\" License along with this manual; if not, see | |
16 | .\" <http://www.gnu.org/licenses/>. | |
8ff7380d | 17 | .\" %%%LICENSE_END |
6f5ff36a MK |
18 | .\" |
19 | .\" HISTORY: | |
20 | .\" 2005-09-28, created by Arnd Bergmann <arndb@de.ibm.com> | |
21 | .\" 2006-06-16, revised by Eduardo M. Fleury <efleury@br.ibm.com> | |
22 | .\" 2007-07-10, some polishing by mtk | |
d24596d5 | 23 | .\" 2007-09-28, updates for newer kernels by Jeremy Kerr <jk@ozlabs.org> |
6f5ff36a | 24 | .\" |
4b8c67d9 | 25 | .TH SPU_CREATE 2 2017-09-15 Linux "Linux Programmer's Manual" |
6f5ff36a MK |
26 | .SH NAME |
27 | spu_create \- create a new spu context | |
28 | .SH SYNOPSIS | |
29 | .nf | |
30 | .B #include <sys/types.h> | |
31 | .B #include <sys/spu.h> | |
dbfe9c70 | 32 | .PP |
6f5ff36a | 33 | .BI "int spu_create(const char *" pathname ", int " flags ", mode_t " mode ");" |
d24596d5 MK |
34 | .BI "int spu_create(const char *" pathname ", int " flags ", mode_t " mode "," |
35 | .BI " int " neighbor_fd ");" | |
6f5ff36a | 36 | .fi |
dbfe9c70 | 37 | .PP |
45c99e3e MK |
38 | .IR Note : |
39 | There is no glibc wrapper for this system call; see NOTES. | |
6f5ff36a MK |
40 | .SH DESCRIPTION |
41 | The | |
42 | .BR spu_create () | |
43 | system call is used on PowerPC machines that implement the | |
44 | Cell Broadband Engine Architecture in order to access Synergistic | |
45 | Processor Units (SPUs). | |
d24596d5 | 46 | It creates a new logical context for an SPU in |
6f5ff36a MK |
47 | .I pathname |
48 | and returns a file descriptor associated with it. | |
49 | .I pathname | |
f74bac5d | 50 | must refer to a nonexistent directory in the mount point of |
9ee4a2b6 | 51 | the SPU filesystem |
56ef4d29 | 52 | .RB ( spufs ). |
6f5ff36a MK |
53 | If |
54 | .BR spu_create () | |
d24596d5 | 55 | is successful, a directory is created at |
6f5ff36a MK |
56 | .I pathname |
57 | and it is populated with the files described in | |
58 | .BR spufs (7). | |
efeece04 | 59 | .PP |
d24596d5 MK |
60 | When a context is created, |
61 | the returned file descriptor can only be passed to | |
30f6523b MK |
62 | .BR spu_run (2), |
63 | used as the | |
64 | .I dirfd | |
65 | argument to the | |
66 | .B *at | |
67 | family of system calls (e.g., | |
68 | .BR openat (2)), | |
6f5ff36a | 69 | or closed; |
30f6523b | 70 | other operations are not defined. |
6f5ff36a | 71 | A logical SPU |
d24596d5 MK |
72 | context is destroyed (along with all files created within the context's |
73 | .I pathname | |
74 | directory) once the last reference to the context has gone; | |
75 | this usually occurs when the file descriptor returned by | |
76 | .BR spu_create () | |
77 | is closed. | |
efeece04 | 78 | .PP |
d24596d5 | 79 | The |
6f5ff36a | 80 | .I flags |
d24596d5 MK |
81 | argument can be zero or any bitwise OR-ed |
82 | combination of the following constants: | |
83 | .TP | |
84 | .B SPU_CREATE_EVENTS_ENABLED | |
85 | Rather than using signals for reporting DMA errors, use the | |
86 | .I event | |
87 | argument to | |
1368e847 | 88 | .BR spu_run (2). |
d24596d5 MK |
89 | .TP |
90 | .B SPU_CREATE_GANG | |
91 | Create an SPU gang instead of a context. | |
92 | (A gang is a group of SPU contexts that are | |
93 | functionally related to each other and which share common scheduling | |
5503c85e | 94 | parameters\(empriority and policy. |
d24596d5 MK |
95 | In the future, gang scheduling may be implemented causing |
96 | the group to be switched in and out as a single unit.) | |
efeece04 | 97 | .IP |
d24596d5 MK |
98 | A new directory will be created at the location specified by the |
99 | .I pathname | |
100 | argument. | |
101 | This gang may be used to hold other SPU contexts, by providing | |
102 | a pathname that is within the gang directory to further calls to | |
2777b1ca | 103 | .BR spu_create (). |
d24596d5 MK |
104 | .TP |
105 | .B SPU_CREATE_NOSCHED | |
106 | Create a context that is not affected by the SPU scheduler. | |
107 | Once the context is run, | |
108 | it will not be scheduled out until it is destroyed by | |
109 | the creating process. | |
efeece04 | 110 | .IP |
d24596d5 | 111 | Because the context cannot be removed from the SPU, some functionality |
9a7f80e2 MK |
112 | is disabled for |
113 | .BR SPU_CREATE_NOSCHED | |
114 | contexts. | |
d24596d5 | 115 | Only a subset of the files will be |
9a7f80e2 MK |
116 | available in this context directory in |
117 | .BR spufs . | |
118 | Additionally, | |
119 | .BR SPU_CREATE_NOSCHED | |
120 | contexts cannot dump a core file when crashing. | |
efeece04 | 121 | .IP |
9a7f80e2 MK |
122 | Creating |
123 | .BR SPU_CREATE_NOSCHED | |
124 | contexts requires the | |
d24596d5 | 125 | .B CAP_SYS_NICE |
6f5ff36a | 126 | capability. |
d24596d5 MK |
127 | .TP |
128 | .B SPU_CREATE_ISOLATE | |
129 | Create an isolated SPU context. | |
130 | Isolated contexts are protected from some | |
131 | PPE (PowerPC Processing Element) | |
132 | operations, | |
133 | such as access to the SPU local store and the NPC register. | |
efeece04 | 134 | .IP |
d24596d5 MK |
135 | Creating |
136 | .B SPU_CREATE_ISOLATE | |
137 | contexts also requires the | |
138 | .B SPU_CREATE_NOSCHED | |
139 | flag. | |
140 | .TP | |
141 | .B SPU_CREATE_AFFINITY_SPU | |
142 | Create a context with affinity to another SPU context. | |
143 | This affinity information is used within the SPU scheduling algorithm. | |
144 | Using this flag requires that a file descriptor referring to | |
145 | the other SPU context be passed in the | |
146 | .I neighbor_fd | |
147 | argument. | |
148 | .TP | |
149 | .B SPU_CREATE_AFFINITY_MEM | |
150 | Create a context with affinity to system memory. | |
151 | This affinity information | |
152 | is used within the SPU scheduling algorithm. | |
6f5ff36a | 153 | .PP |
d24596d5 MK |
154 | The |
155 | .I mode | |
156 | argument (minus any bits set in the process's | |
157 | .BR umask (2)) | |
158 | specifies the permissions used for creating the new directory in | |
9a7f80e2 | 159 | .BR spufs . |
d24596d5 MK |
160 | See |
161 | .BR stat (2) | |
162 | for a full list of the possible | |
6f5ff36a | 163 | .I mode |
d24596d5 | 164 | values. |
6f5ff36a MK |
165 | .SH RETURN VALUE |
166 | On success, | |
2777b1ca | 167 | .BR spu_create () |
6f5ff36a | 168 | returns a new file descriptor. |
d24596d5 | 169 | On error, \-1 is returned, and |
6f5ff36a MK |
170 | .I errno |
171 | is set to one of the error codes listed below. | |
172 | .SH ERRORS | |
173 | .TP | |
d1de5f75 | 174 | .B EACCES |
d24596d5 MK |
175 | The current user does not have write access to the |
176 | .BR spufs (7) | |
177 | mount point. | |
178 | .TP | |
6f5ff36a | 179 | .B EEXIST |
9e802a1f | 180 | An SPU context already exists at the given pathname. |
6f5ff36a MK |
181 | .TP |
182 | .B EFAULT | |
183 | .I pathname | |
d24596d5 MK |
184 | is not a valid string pointer in the |
185 | calling process's address space. | |
6f5ff36a MK |
186 | .TP |
187 | .B EINVAL | |
188 | .I pathname | |
d24596d5 MK |
189 | is not a directory in the |
190 | .BR spufs (7) | |
191 | mount point, or invalid flags have been provided. | |
6f5ff36a MK |
192 | .TP |
193 | .B ELOOP | |
d24596d5 | 194 | Too many symbolic links were found while resolving |
6f5ff36a MK |
195 | .IR pathname . |
196 | .TP | |
197 | .B EMFILE | |
26c32fab | 198 | The per-process limit on the number of open file descriptors has been reached. |
6f5ff36a MK |
199 | .TP |
200 | .B ENAMETOOLONG | |
201 | .I pathname | |
202 | is too long. | |
203 | .TP | |
204 | .B ENFILE | |
e258766b | 205 | The system-wide limit on the total number of open files has been reached. |
6f5ff36a | 206 | .TP |
d24596d5 MK |
207 | .B ENODEV |
208 | An isolated context was requested, but the hardware does not support | |
209 | SPU isolation. | |
210 | .TP | |
6f5ff36a MK |
211 | .B ENOENT |
212 | Part of | |
213 | .I pathname | |
214 | could not be resolved. | |
215 | .TP | |
216 | .B ENOMEM | |
217 | The kernel could not allocate all resources required. | |
218 | .TP | |
219 | .B ENOSPC | |
220 | There are not enough SPU resources available to create | |
d24596d5 | 221 | a new context or the user-specific limit for the number |
6f5ff36a MK |
222 | of SPU contexts has been reached. |
223 | .TP | |
224 | .B ENOSYS | |
225 | The functionality is not provided by the current system, because | |
226 | either the hardware does not provide SPUs or the spufs module is not | |
227 | loaded. | |
228 | .TP | |
229 | .B ENOTDIR | |
230 | A part of | |
231 | .I pathname | |
232 | is not a directory. | |
92f9f654 MK |
233 | .TP |
234 | .B EPERM | |
235 | The | |
236 | .I SPU_CREATE_NOSCHED | |
237 | flag has been given, but the user does not have the | |
238 | .B CAP_SYS_NICE | |
239 | capability. | |
6f5ff36a MK |
240 | .SH FILES |
241 | .I pathname | |
d24596d5 MK |
242 | must point to a location beneath the mount point of |
243 | .BR spufs . | |
6f5ff36a MK |
244 | By convention, it gets mounted in |
245 | .IR /spu . | |
246 | .SH VERSIONS | |
247 | The | |
2777b1ca | 248 | .BR spu_create () |
6f5ff36a MK |
249 | system call was added to Linux in kernel 2.6.16. |
250 | .SH CONFORMING TO | |
33a0ccb2 | 251 | This call is Linux-specific and implemented only on the PowerPC |
6f5ff36a MK |
252 | architecture. |
253 | Programs using this system call are not portable. | |
254 | .SH NOTES | |
255 | Glibc does not provide a wrapper for this system call; call it using | |
256 | .BR syscall (2). | |
257 | Note however, that | |
258 | .BR spu_create () | |
259 | is meant to be used from libraries that implement a more abstract | |
260 | interface to SPUs, not to be used from regular applications. | |
e0bf9127 | 261 | See |
608bf950 SK |
262 | .UR http://www.bsc.es\:/projects\:/deepcomputing\:/linuxoncell/ |
263 | .UE | |
6f5ff36a | 264 | for the recommended libraries. |
d24596d5 MK |
265 | .SH EXAMPLE |
266 | See | |
267 | .BR spu_run (2) | |
268 | for an example of the use of | |
269 | .BR spu_create () | |
6f5ff36a MK |
270 | .SH SEE ALSO |
271 | .BR close (2), | |
272 | .BR spu_run (2), | |
273 | .BR capabilities (7), | |
274 | .BR spufs (7) |