Commit | Line | Data |
---|---|---|
67207b96 AB |
1 | SPUFS(2) Linux Programmer's Manual SPUFS(2) |
2 | ||
3 | ||
4 | ||
5 | NAME | |
6 | spufs - the SPU file system | |
7 | ||
8 | ||
9 | DESCRIPTION | |
10 | The SPU file system is used on PowerPC machines that implement the Cell | |
11 | Broadband Engine Architecture in order to access Synergistic Processor | |
12 | Units (SPUs). | |
13 | ||
14 | The file system provides a name space similar to posix shared memory or | |
15 | message queues. Users that have write permissions on the file system | |
16 | can use spu_create(2) to establish SPU contexts in the spufs root. | |
17 | ||
18 | Every SPU context is represented by a directory containing a predefined | |
19 | set of files. These files can be used for manipulating the state of the | |
20 | logical SPU. Users can change permissions on those files, but not actu- | |
21 | ally add or remove files. | |
22 | ||
23 | ||
24 | MOUNT OPTIONS | |
25 | uid=<uid> | |
26 | set the user owning the mount point, the default is 0 (root). | |
27 | ||
28 | gid=<gid> | |
29 | set the group owning the mount point, the default is 0 (root). | |
30 | ||
31 | ||
32 | FILES | |
33 | The files in spufs mostly follow the standard behavior for regular sys- | |
34 | tem calls like read(2) or write(2), but often support only a subset of | |
35 | the operations supported on regular file systems. This list details the | |
36 | supported operations and the deviations from the behaviour in the | |
37 | respective man pages. | |
38 | ||
39 | All files that support the read(2) operation also support readv(2) and | |
40 | all files that support the write(2) operation also support writev(2). | |
41 | All files support the access(2) and stat(2) family of operations, but | |
42 | only the st_mode, st_nlink, st_uid and st_gid fields of struct stat | |
43 | contain reliable information. | |
44 | ||
45 | All files support the chmod(2)/fchmod(2) and chown(2)/fchown(2) opera- | |
46 | tions, but will not be able to grant permissions that contradict the | |
47 | possible operations, e.g. read access on the wbox file. | |
48 | ||
49 | The current set of files is: | |
50 | ||
51 | ||
52 | /mem | |
53 | the contents of the local storage memory of the SPU. This can be | |
54 | accessed like a regular shared memory file and contains both code and | |
55 | data in the address space of the SPU. The possible operations on an | |
56 | open mem file are: | |
57 | ||
58 | read(2), pread(2), write(2), pwrite(2), lseek(2) | |
59 | These operate as documented, with the exception that seek(2), | |
60 | write(2) and pwrite(2) are not supported beyond the end of the | |
61 | file. The file size is the size of the local storage of the SPU, | |
62 | which normally is 256 kilobytes. | |
63 | ||
64 | mmap(2) | |
65 | Mapping mem into the process address space gives access to the | |
66 | SPU local storage within the process address space. Only | |
67 | MAP_SHARED mappings are allowed. | |
68 | ||
69 | ||
70 | /mbox | |
71 | The first SPU to CPU communication mailbox. This file is read-only and | |
72 | can be read in units of 32 bits. The file can only be used in non- | |
73 | blocking mode and it even poll() will not block on it. The possible | |
74 | operations on an open mbox file are: | |
75 | ||
76 | read(2) | |
77 | If a count smaller than four is requested, read returns -1 and | |
78 | sets errno to EINVAL. If there is no data available in the mail | |
79 | box, the return value is set to -1 and errno becomes EAGAIN. | |
80 | When data has been read successfully, four bytes are placed in | |
81 | the data buffer and the value four is returned. | |
82 | ||
83 | ||
84 | /ibox | |
85 | The second SPU to CPU communication mailbox. This file is similar to | |
86 | the first mailbox file, but can be read in blocking I/O mode, and the | |
87 | poll familiy of system calls can be used to wait for it. The possible | |
88 | operations on an open ibox file are: | |
89 | ||
90 | read(2) | |
91 | If a count smaller than four is requested, read returns -1 and | |
92 | sets errno to EINVAL. If there is no data available in the mail | |
93 | box and the file descriptor has been opened with O_NONBLOCK, the | |
94 | return value is set to -1 and errno becomes EAGAIN. | |
95 | ||
96 | If there is no data available in the mail box and the file | |
97 | descriptor has been opened without O_NONBLOCK, the call will | |
98 | block until the SPU writes to its interrupt mailbox channel. | |
99 | When data has been read successfully, four bytes are placed in | |
100 | the data buffer and the value four is returned. | |
101 | ||
102 | poll(2) | |
103 | Poll on the ibox file returns (POLLIN | POLLRDNORM) whenever | |
104 | data is available for reading. | |
105 | ||
106 | ||
107 | /wbox | |
108 | The CPU to SPU communation mailbox. It is write-only can can be written | |
109 | in units of 32 bits. If the mailbox is full, write() will block and | |
110 | poll can be used to wait for it becoming empty again. The possible | |
111 | operations on an open wbox file are: write(2) If a count smaller than | |
112 | four is requested, write returns -1 and sets errno to EINVAL. If there | |
113 | is no space available in the mail box and the file descriptor has been | |
114 | opened with O_NONBLOCK, the return value is set to -1 and errno becomes | |
115 | EAGAIN. | |
116 | ||
117 | If there is no space available in the mail box and the file descriptor | |
118 | has been opened without O_NONBLOCK, the call will block until the SPU | |
119 | reads from its PPE mailbox channel. When data has been read success- | |
120 | fully, four bytes are placed in the data buffer and the value four is | |
121 | returned. | |
122 | ||
123 | poll(2) | |
124 | Poll on the ibox file returns (POLLOUT | POLLWRNORM) whenever | |
125 | space is available for writing. | |
126 | ||
127 | ||
128 | /mbox_stat | |
129 | /ibox_stat | |
130 | /wbox_stat | |
131 | Read-only files that contain the length of the current queue, i.e. how | |
132 | many words can be read from mbox or ibox or how many words can be | |
133 | written to wbox without blocking. The files can be read only in 4-byte | |
134 | units and return a big-endian binary integer number. The possible | |
135 | operations on an open *box_stat file are: | |
136 | ||
137 | read(2) | |
138 | If a count smaller than four is requested, read returns -1 and | |
139 | sets errno to EINVAL. Otherwise, a four byte value is placed in | |
140 | the data buffer, containing the number of elements that can be | |
141 | read from (for mbox_stat and ibox_stat) or written to (for | |
142 | wbox_stat) the respective mail box without blocking or resulting | |
143 | in EAGAIN. | |
144 | ||
145 | ||
146 | /npc | |
147 | /decr | |
148 | /decr_status | |
149 | /spu_tag_mask | |
150 | /event_mask | |
151 | /srr0 | |
152 | Internal registers of the SPU. The representation is an ASCII string | |
153 | with the numeric value of the next instruction to be executed. These | |
154 | can be used in read/write mode for debugging, but normal operation of | |
155 | programs should not rely on them because access to any of them except | |
156 | npc requires an SPU context save and is therefore very inefficient. | |
157 | ||
158 | The contents of these files are: | |
159 | ||
160 | npc Next Program Counter | |
161 | ||
162 | decr SPU Decrementer | |
163 | ||
164 | decr_status Decrementer Status | |
165 | ||
166 | spu_tag_mask MFC tag mask for SPU DMA | |
167 | ||
168 | event_mask Event mask for SPU interrupts | |
169 | ||
170 | srr0 Interrupt Return address register | |
171 | ||
172 | ||
173 | The possible operations on an open npc, decr, decr_status, | |
174 | spu_tag_mask, event_mask or srr0 file are: | |
175 | ||
176 | read(2) | |
177 | When the count supplied to the read call is shorter than the | |
178 | required length for the pointer value plus a newline character, | |
179 | subsequent reads from the same file descriptor will result in | |
180 | completing the string, regardless of changes to the register by | |
181 | a running SPU task. When a complete string has been read, all | |
182 | subsequent read operations will return zero bytes and a new file | |
183 | descriptor needs to be opened to read the value again. | |
184 | ||
185 | write(2) | |
186 | A write operation on the file results in setting the register to | |
187 | the value given in the string. The string is parsed from the | |
188 | beginning to the first non-numeric character or the end of the | |
189 | buffer. Subsequent writes to the same file descriptor overwrite | |
190 | the previous setting. | |
191 | ||
192 | ||
193 | /fpcr | |
194 | This file gives access to the Floating Point Status and Control Regis- | |
195 | ter as a four byte long file. The operations on the fpcr file are: | |
196 | ||
197 | read(2) | |
198 | If a count smaller than four is requested, read returns -1 and | |
199 | sets errno to EINVAL. Otherwise, a four byte value is placed in | |
200 | the data buffer, containing the current value of the fpcr regis- | |
201 | ter. | |
202 | ||
203 | write(2) | |
204 | If a count smaller than four is requested, write returns -1 and | |
205 | sets errno to EINVAL. Otherwise, a four byte value is copied | |
206 | from the data buffer, updating the value of the fpcr register. | |
207 | ||
208 | ||
209 | /signal1 | |
210 | /signal2 | |
211 | The two signal notification channels of an SPU. These are read-write | |
212 | files that operate on a 32 bit word. Writing to one of these files | |
213 | triggers an interrupt on the SPU. The value writting to the signal | |
214 | files can be read from the SPU through a channel read or from host user | |
215 | space through the file. After the value has been read by the SPU, it | |
216 | is reset to zero. The possible operations on an open signal1 or sig- | |
217 | nal2 file are: | |
218 | ||
219 | read(2) | |
220 | If a count smaller than four is requested, read returns -1 and | |
221 | sets errno to EINVAL. Otherwise, a four byte value is placed in | |
222 | the data buffer, containing the current value of the specified | |
223 | signal notification register. | |
224 | ||
225 | write(2) | |
226 | If a count smaller than four is requested, write returns -1 and | |
227 | sets errno to EINVAL. Otherwise, a four byte value is copied | |
228 | from the data buffer, updating the value of the specified signal | |
229 | notification register. The signal notification register will | |
230 | either be replaced with the input data or will be updated to the | |
231 | bitwise OR or the old value and the input data, depending on the | |
232 | contents of the signal1_type, or signal2_type respectively, | |
233 | file. | |
234 | ||
235 | ||
236 | /signal1_type | |
237 | /signal2_type | |
238 | These two files change the behavior of the signal1 and signal2 notifi- | |
239 | cation files. The contain a numerical ASCII string which is read as | |
240 | either "1" or "0". In mode 0 (overwrite), the hardware replaces the | |
241 | contents of the signal channel with the data that is written to it. in | |
242 | mode 1 (logical OR), the hardware accumulates the bits that are subse- | |
243 | quently written to it. The possible operations on an open signal1_type | |
244 | or signal2_type file are: | |
245 | ||
246 | read(2) | |
247 | When the count supplied to the read call is shorter than the | |
248 | required length for the digit plus a newline character, subse- | |
249 | quent reads from the same file descriptor will result in com- | |
250 | pleting the string. When a complete string has been read, all | |
251 | subsequent read operations will return zero bytes and a new file | |
252 | descriptor needs to be opened to read the value again. | |
253 | ||
254 | write(2) | |
255 | A write operation on the file results in setting the register to | |
256 | the value given in the string. The string is parsed from the | |
257 | beginning to the first non-numeric character or the end of the | |
258 | buffer. Subsequent writes to the same file descriptor overwrite | |
259 | the previous setting. | |
260 | ||
261 | ||
262 | EXAMPLES | |
263 | /etc/fstab entry | |
264 | none /spu spufs gid=spu 0 0 | |
265 | ||
266 | ||
267 | AUTHORS | |
268 | Arnd Bergmann <arndb@de.ibm.com>, Mark Nutter <mnutter@us.ibm.com>, | |
269 | Ulrich Weigand <Ulrich.Weigand@de.ibm.com> | |
270 | ||
271 | SEE ALSO | |
272 | capabilities(7), close(2), spu_create(2), spu_run(2), spufs(7) | |
273 | ||
274 | ||
275 | ||
276 | Linux 2005-09-28 SPUFS(2) | |
277 | ||
278 | ------------------------------------------------------------------------------ | |
279 | ||
280 | SPU_RUN(2) Linux Programmer's Manual SPU_RUN(2) | |
281 | ||
282 | ||
283 | ||
284 | NAME | |
285 | spu_run - execute an spu context | |
286 | ||
287 | ||
288 | SYNOPSIS | |
289 | #include <sys/spu.h> | |
290 | ||
291 | int spu_run(int fd, unsigned int *npc, unsigned int *event); | |
292 | ||
293 | DESCRIPTION | |
294 | The spu_run system call is used on PowerPC machines that implement the | |
295 | Cell Broadband Engine Architecture in order to access Synergistic Pro- | |
296 | cessor Units (SPUs). It uses the fd that was returned from spu_cre- | |
297 | ate(2) to address a specific SPU context. When the context gets sched- | |
298 | uled to a physical SPU, it starts execution at the instruction pointer | |
299 | passed in npc. | |
300 | ||
301 | Execution of SPU code happens synchronously, meaning that spu_run does | |
302 | not return while the SPU is still running. If there is a need to exe- | |
303 | cute SPU code in parallel with other code on either the main CPU or | |
304 | other SPUs, you need to create a new thread of execution first, e.g. | |
305 | using the pthread_create(3) call. | |
306 | ||
307 | When spu_run returns, the current value of the SPU instruction pointer | |
308 | is written back to npc, so you can call spu_run again without updating | |
309 | the pointers. | |
310 | ||
311 | event can be a NULL pointer or point to an extended status code that | |
312 | gets filled when spu_run returns. It can be one of the following con- | |
313 | stants: | |
314 | ||
315 | SPE_EVENT_DMA_ALIGNMENT | |
316 | A DMA alignment error | |
317 | ||
318 | SPE_EVENT_SPE_DATA_SEGMENT | |
319 | A DMA segmentation error | |
320 | ||
321 | SPE_EVENT_SPE_DATA_STORAGE | |
322 | A DMA storage error | |
323 | ||
324 | If NULL is passed as the event argument, these errors will result in a | |
325 | signal delivered to the calling process. | |
326 | ||
327 | RETURN VALUE | |
328 | spu_run returns the value of the spu_status register or -1 to indicate | |
329 | an error and set errno to one of the error codes listed below. The | |
330 | spu_status register value contains a bit mask of status codes and | |
331 | optionally a 14 bit code returned from the stop-and-signal instruction | |
332 | on the SPU. The bit masks for the status codes are: | |
333 | ||
334 | 0x02 SPU was stopped by stop-and-signal. | |
335 | ||
336 | 0x04 SPU was stopped by halt. | |
337 | ||
338 | 0x08 SPU is waiting for a channel. | |
339 | ||
340 | 0x10 SPU is in single-step mode. | |
341 | ||
342 | 0x20 SPU has tried to execute an invalid instruction. | |
343 | ||
344 | 0x40 SPU has tried to access an invalid channel. | |
345 | ||
346 | 0x3fff0000 | |
347 | The bits masked with this value contain the code returned from | |
348 | stop-and-signal. | |
349 | ||
350 | There are always one or more of the lower eight bits set or an error | |
351 | code is returned from spu_run. | |
352 | ||
353 | ERRORS | |
354 | EAGAIN or EWOULDBLOCK | |
355 | fd is in non-blocking mode and spu_run would block. | |
356 | ||
357 | EBADF fd is not a valid file descriptor. | |
358 | ||
359 | EFAULT npc is not a valid pointer or status is neither NULL nor a valid | |
360 | pointer. | |
361 | ||
362 | EINTR A signal occured while spu_run was in progress. The npc value | |
363 | has been updated to the new program counter value if necessary. | |
364 | ||
365 | EINVAL fd is not a file descriptor returned from spu_create(2). | |
366 | ||
367 | ENOMEM Insufficient memory was available to handle a page fault result- | |
368 | ing from an MFC direct memory access. | |
369 | ||
370 | ENOSYS the functionality is not provided by the current system, because | |
371 | either the hardware does not provide SPUs or the spufs module is | |
372 | not loaded. | |
373 | ||
374 | ||
375 | NOTES | |
376 | spu_run is meant to be used from libraries that implement a more | |
377 | abstract interface to SPUs, not to be used from regular applications. | |
378 | See http://www.bsc.es/projects/deepcomputing/linuxoncell/ for the rec- | |
379 | ommended libraries. | |
380 | ||
381 | ||
382 | CONFORMING TO | |
383 | This call is Linux specific and only implemented by the ppc64 architec- | |
384 | ture. Programs using this system call are not portable. | |
385 | ||
386 | ||
387 | BUGS | |
388 | The code does not yet fully implement all features lined out here. | |
389 | ||
390 | ||
391 | AUTHOR | |
392 | Arnd Bergmann <arndb@de.ibm.com> | |
393 | ||
394 | SEE ALSO | |
395 | capabilities(7), close(2), spu_create(2), spufs(7) | |
396 | ||
397 | ||
398 | ||
399 | Linux 2005-09-28 SPU_RUN(2) | |
400 | ||
401 | ------------------------------------------------------------------------------ | |
402 | ||
403 | SPU_CREATE(2) Linux Programmer's Manual SPU_CREATE(2) | |
404 | ||
405 | ||
406 | ||
407 | NAME | |
408 | spu_create - create a new spu context | |
409 | ||
410 | ||
411 | SYNOPSIS | |
412 | #include <sys/types.h> | |
413 | #include <sys/spu.h> | |
414 | ||
415 | int spu_create(const char *pathname, int flags, mode_t mode); | |
416 | ||
417 | DESCRIPTION | |
418 | The spu_create system call is used on PowerPC machines that implement | |
419 | the Cell Broadband Engine Architecture in order to access Synergistic | |
420 | Processor Units (SPUs). It creates a new logical context for an SPU in | |
421 | pathname and returns a handle to associated with it. pathname must | |
422 | point to a non-existing directory in the mount point of the SPU file | |
423 | system (spufs). When spu_create is successful, a directory gets cre- | |
424 | ated on pathname and it is populated with files. | |
425 | ||
426 | The returned file handle can only be passed to spu_run(2) or closed, | |
427 | other operations are not defined on it. When it is closed, all associ- | |
428 | ated directory entries in spufs are removed. When the last file handle | |
429 | pointing either inside of the context directory or to this file | |
430 | descriptor is closed, the logical SPU context is destroyed. | |
431 | ||
432 | The parameter flags can be zero or any bitwise or'd combination of the | |
433 | following constants: | |
434 | ||
435 | SPU_RAWIO | |
436 | Allow mapping of some of the hardware registers of the SPU into | |
437 | user space. This flag requires the CAP_SYS_RAWIO capability, see | |
438 | capabilities(7). | |
439 | ||
440 | The mode parameter specifies the permissions used for creating the new | |
441 | directory in spufs. mode is modified with the user's umask(2) value | |
442 | and then used for both the directory and the files contained in it. The | |
443 | file permissions mask out some more bits of mode because they typically | |
444 | support only read or write access. See stat(2) for a full list of the | |
445 | possible mode values. | |
446 | ||
447 | ||
448 | RETURN VALUE | |
449 | spu_create returns a new file descriptor. It may return -1 to indicate | |
450 | an error condition and set errno to one of the error codes listed | |
451 | below. | |
452 | ||
453 | ||
454 | ERRORS | |
455 | EACCESS | |
456 | The current user does not have write access on the spufs mount | |
457 | point. | |
458 | ||
459 | EEXIST An SPU context already exists at the given path name. | |
460 | ||
461 | EFAULT pathname is not a valid string pointer in the current address | |
462 | space. | |
463 | ||
464 | EINVAL pathname is not a directory in the spufs mount point. | |
465 | ||
466 | ELOOP Too many symlinks were found while resolving pathname. | |
467 | ||
468 | EMFILE The process has reached its maximum open file limit. | |
469 | ||
470 | ENAMETOOLONG | |
471 | pathname was too long. | |
472 | ||
473 | ENFILE The system has reached the global open file limit. | |
474 | ||
475 | ENOENT Part of pathname could not be resolved. | |
476 | ||
477 | ENOMEM The kernel could not allocate all resources required. | |
478 | ||
479 | ENOSPC There are not enough SPU resources available to create a new | |
480 | context or the user specific limit for the number of SPU con- | |
481 | texts has been reached. | |
482 | ||
483 | ENOSYS the functionality is not provided by the current system, because | |
484 | either the hardware does not provide SPUs or the spufs module is | |
485 | not loaded. | |
486 | ||
487 | ENOTDIR | |
488 | A part of pathname is not a directory. | |
489 | ||
490 | ||
491 | ||
492 | NOTES | |
493 | spu_create is meant to be used from libraries that implement a more | |
494 | abstract interface to SPUs, not to be used from regular applications. | |
495 | See http://www.bsc.es/projects/deepcomputing/linuxoncell/ for the rec- | |
496 | ommended libraries. | |
497 | ||
498 | ||
499 | FILES | |
500 | pathname must point to a location beneath the mount point of spufs. By | |
501 | convention, it gets mounted in /spu. | |
502 | ||
503 | ||
504 | CONFORMING TO | |
505 | This call is Linux specific and only implemented by the ppc64 architec- | |
506 | ture. Programs using this system call are not portable. | |
507 | ||
508 | ||
509 | BUGS | |
510 | The code does not yet fully implement all features lined out here. | |
511 | ||
512 | ||
513 | AUTHOR | |
514 | Arnd Bergmann <arndb@de.ibm.com> | |
515 | ||
516 | SEE ALSO | |
517 | capabilities(7), close(2), spu_run(2), spufs(7) | |
518 | ||
519 | ||
520 | ||
521 | Linux 2005-09-28 SPU_CREATE(2) |