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