Debian Codegraph @

upstream/debian-unstable/man7/spufs.7

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 spufs 7 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 spufs \- SPU filesystem
9 .SH DESCRIPTION
10 The SPU filesystem is used on PowerPC machines that implement the
11 Cell Broadband Engine Architecture in order to access Synergistic
12 Processor Units (SPUs).
13 .P
14 The filesystem provides a name space similar to POSIX shared
15 memory or message queues.
16 Users that have write permissions
17 on the filesystem can use
18 .BR spu_create (2)
19 to establish SPU contexts under the
20 .B spufs
21 root directory.
22 .P
23 Every SPU context is represented by a directory containing
24 a predefined set of files.
25 These files can be
26 used for manipulating the state of the logical SPU.
27 Users can change permissions on the files, but can't
28 add or remove files.
29 .SS Mount options
30 .TP
31 .B uid=<uid>
32 Set the user owning the mount point; the default is 0 (root).
33 .TP
34 .B gid=<gid>
35 Set the group owning the mount point; the default is 0 (root).
36 .TP
37 .B mode=<mode>
38 Set the mode of the top-level directory in
39 .BR spufs ,
40 as an octal mode string.
41 The default is 0775.
42 .SS Files
43 The files in
44 .B spufs
45 mostly follow the standard behavior for regular system calls like
46 .BR read (2)
47 or
48 .BR write (2),
49 but often support only a subset of the operations
50 supported on regular filesystems.
51 This list details the supported
52 operations and the deviations from the standard behavior described
53 in the respective man pages.
54 .P
55 All files that support the
56 .BR read (2)
57 operation also support
58 .BR readv (2)
59 and all files that support the
60 .BR write (2)
61 operation also support
62 .BR writev (2).
63 All files support the
64 .BR access (2)
65 and
66 .BR stat (2)
67 family of operations, but for the latter call,
68 the only fields of the returned
69 .I stat
70 structure that contain reliable information are
71 .IR st_mode ,
72 .IR st_nlink ,
73 .IR st_uid ,
74 and
75 .IR st_gid .
76 .P
77 All files support the
78 .BR chmod (2)/\c
79 .BR fchmod (2)
80 and
81 .BR chown (2)/\c
82 .BR fchown (2)
83 operations, but will not be able to grant permissions that contradict
84 the possible operations (e.g., read access on the
85 .I wbox
86 file).
87 .P
88 The current set of files is:
89 .TP
90 .I /capabilities
91 Contains a comma-delimited string representing the capabilities of this
92 SPU context.
93 Possible capabilities are:
94 .RS
95 .TP
96 .B sched
97 This context may be scheduled.
98 .TP
99 .B step
100 This context can be run in single-step mode, for debugging.
101 .P
102 New capabilities flags may be added in the future.
103 .RE
104 .TP
105 .I /mem
106 the contents of the local storage memory of the SPU.
107 This can be accessed like a regular shared memory
108 file and contains both code and data in the address
109 space of the SPU.
110 The possible operations on an open
111 .I mem
112 file are:
113 .RS
114 .TP
115 .BR read (2)
116 .TQ
117 .BR pread (2)
118 .TQ
119 .BR write (2)
120 .TQ
121 .BR pwrite (2)
122 .TQ
123 .BR lseek (2)
124 These operate as usual, with the exception that
125 .BR lseek (2),
126 .BR write (2),
127 and
128 .BR pwrite (2)
129 are not supported beyond the end of the file.
130 The file size
131 is the size of the local storage of the SPU,
132 which is normally 256 kilobytes.
133 .TP
134 .BR mmap (2)
135 Mapping
136 .I mem
137 into the process address space provides access to the SPU local
138 storage within the process address space.
139 Only
140 .B MAP_SHARED
141 mappings are allowed.
142 .RE
143 .TP
144 .I /regs
145 Contains the saved general-purpose registers of the SPU context.
146 This file contains the 128-bit values of each register,
147 from register 0 to register 127, in order.
148 This allows the general-purpose registers to be
149 inspected for debugging.
150 .IP
151 Reading to or writing from this file requires that the context is
152 scheduled out, so use of this file is not recommended in normal
153 program operation.
154 .IP
155 The
156 .I regs
157 file is not present on contexts that have been created with the
158 .B SPU_CREATE_NOSCHED
159 flag.
160 .TP
161 .I /mbox
162 The first SPU-to-CPU communication mailbox.
163 This file is read-only and can be read in units of 4 bytes.
164 The file can be used only in nonblocking mode \- even
165 .BR poll (2)
166 cannot be used to block on this file.
167 The only possible operation on an open
168 .I mbox
169 file is:
170 .RS
171 .TP
172 .BR read (2)
173 If
174 .I count
175 is smaller than four,
176 .BR read (2)
177 returns \-1 and sets
178 .I errno
179 to
180 .BR EINVAL .
181 If there is no data available in the mailbox (i.e., the SPU has not
182 sent a mailbox message), the return value is set to \-1 and
183 .I errno
184 is set to
185 .BR EAGAIN .
186 When data
187 has been read successfully, four bytes are placed in
188 the data buffer and the value four is returned.
189 .RE
190 .TP
191 .I /ibox
192 The second SPU-to-CPU communication mailbox.
193 This file is similar to the first mailbox file, but can be read
194 in blocking I/O mode, thus calling
195 .BR read (2)
196 on an open
197 .I ibox
198 file will block until the SPU has written data to its interrupt mailbox
199 channel (unless the file has been opened with
200 .BR O_NONBLOCK ,
201 see below).
202 Also,
203 .BR poll (2)
204 and similar system calls can be used to monitor for the presence
205 of mailbox data.
206 .IP
207 The possible operations on an open
208 .I ibox
209 file are:
210 .RS
211 .TP
212 .BR read (2)
213 If
214 .I count
215 is smaller than four,
216 .BR read (2)
217 returns \-1 and sets
218 .I errno
219 to
220 .BR EINVAL .
221 If there is no data available in the mailbox and the file
222 descriptor has been opened with
223 .BR O_NONBLOCK ,
224 the return value is set to \-1 and
225 .I errno
226 is set to
227 .BR EAGAIN .
228 .IP
229 If there is no data available in the mailbox and the file
230 descriptor has been opened without
231 .BR O_NONBLOCK ,
232 the call will
233 block until the SPU writes to its interrupt mailbox channel.
234 When data has been read successfully, four bytes are placed in
235 the data buffer and the value four is returned.
236 .TP
237 .BR poll (2)
238 Poll on the
239 .I ibox
240 file returns
241 .I "(POLLIN | POLLRDNORM)"
242 whenever data is available for reading.
243 .RE
244 .TP
245 .I /wbox
246 The CPU-to-SPU communication mailbox.
247 It is write-only and can be written in units of four bytes.
248 If the mailbox is full,
249 .BR write (2)
250 will block, and
251 .BR poll (2)
252 can be used to block until the mailbox is available for writing again.
253 The possible operations on an open
254 .I wbox
255 file are:
256 .RS
257 .TP
258 .BR write (2)
259 If
260 .I count
261 is smaller than four,
262 .BR write (2)
263 returns \-1 and sets
264 .I errno
265 to
266 .BR EINVAL .
267 If there is no space available in the mailbox and the file
268 descriptor has been opened with
269 .BR O_NONBLOCK ,
270 the return
271 value is set to \-1 and
272 .I errno
273 is set to
274 .BR EAGAIN .
275 .IP
276 If there is no space available in the mailbox and the file
277 descriptor has been opened without
278 .BR O_NONBLOCK ,
279 the call will block until the SPU reads from its
280 PPE (PowerPC Processing Element)
281 mailbox channel.
282 When data has been written successfully,
283 the system call returns four as its function result.
284 .TP
285 .BR poll (2)
286 A poll on the
287 .I wbox
288 file returns
289 .I "(POLLOUT | POLLWRNORM)"
290 whenever space is available for writing.
291 .RE
292 .TP
293 .I /mbox_stat
294 .TQ
295 .I /ibox_stat
296 .TQ
297 .I /wbox_stat
298 These are read-only files that contain the length of the current
299 queue of each mailbox\[em]that is, how many words can be read from
300 .IR mbox " or " ibox
301 or how many words can be written to
302 .I wbox
303 without blocking.
304 The files can be read only in four-byte units and return
305 a big-endian binary integer number.
306 The only possible operation on an open
307 .I *box_stat
308 file is:
309 .RS
310 .TP
311 .BR read (2)
312 If
313 .I count
314 is smaller than four,
315 .BR read (2)
316 returns \-1 and sets
317 .I errno
318 to
319 .BR EINVAL .
320 Otherwise, a four-byte value is placed in the data buffer.
321 This value is the number of elements that can be read from (for
322 .I mbox_stat
323 and
324 .IR ibox_stat )
325 or written to (for
326 .IR wbox_stat )
327 the respective mailbox without blocking or returning an
328 .B EAGAIN
329 error.
330 .RE
331 .TP
332 .I /npc
333 .TQ
334 .I /decr
335 .TQ
336 .I /decr_status
337 .TQ
338 .I /spu_tag_mask
339 .TQ
340 .I /event_mask
341 .TQ
342 .I /event_status
343 .TQ
344 .I /srr0
345 .TQ
346 .I /lslr
347 Internal registers of the SPU.
348 These files contain an ASCII string
349 representing the hex value of the specified register.
350 Reads and writes on these
351 files (except for
352 .IR npc ,
353 see below) require that the SPU context be scheduled out,
354 so frequent access to
355 these files is not recommended for normal program operation.
356 .IP
357 The contents of these files are:
358 .RS
359 .TP 16
360 .I npc
361 Next Program Counter \- valid only when the SPU is in a stopped state.
362 .TP
363 .I decr
364 SPU Decrementer
365 .TP
366 .I decr_status
367 Decrementer Status
368 .TP
369 .I spu_tag_mask
370 MFC tag mask for SPU DMA
371 .TP
372 .I event_mask
373 Event mask for SPU interrupts
374 .TP
375 .I event_status
376 Number of SPU events pending (read-only)
377 .TP
378 .I srr0
379 Interrupt Return address register
380 .TP
381 .I lslr
382 Local Store Limit Register
383 .RE
384 .IP
385 The possible operations on these files are:
386 .RS
387 .TP
388 .BR read (2)
389 Reads the current register value.
390 If the register value is larger than the buffer passed to the
391 .BR read (2)
392 system call, subsequent reads will continue reading from the same
393 buffer, until the end of the buffer is reached.
394 .IP
395 When a complete string has been read, all subsequent read operations
396 will return zero bytes and a new file descriptor needs to be opened
397 to read a new value.
398 .TP
399 .BR write (2)
400 A
401 .BR write (2)
402 operation on the file sets the register to the
403 value given in the string.
404 The string is parsed from the beginning
405 until the first nonnumeric character or the end of the buffer.
406 Subsequent writes to the same file descriptor overwrite the
407 previous setting.
408 .IP
409 Except for the
410 .I npc
411 file, these files are not present on contexts that have been created with
412 the
413 .B SPU_CREATE_NOSCHED
414 flag.
415 .RE
416 .TP
417 .I /fpcr
418 This file provides access to the Floating Point Status and
419 Control Register (fcpr) as a binary, four-byte file.
420 The operations on the
421 .I fpcr
422 file are:
423 .RS
424 .TP
425 .BR read (2)
426 If
427 .I count
428 is smaller than four,
429 .BR read (2)
430 returns \-1 and sets
431 .I errno
432 to
433 .BR EINVAL .
434 Otherwise, a four-byte value is placed in the data buffer;
435 this is the current value of the
436 .I fpcr
437 register.
438 .TP
439 .BR write (2)
440 If
441 .I count
442 is smaller than four,
443 .BR write (2)
444 returns \-1 and sets
445 .I errno
446 to
447 .BR EINVAL .
448 Otherwise, a four-byte value is copied from the data buffer,
449 updating the value of the
450 .I fpcr
451 register.
452 .RE
453 .TP
454 .I /signal1
455 .TQ
456 .I /signal2
457 The files provide access to the two signal notification channels
458 of an SPU.
459 These are read-write files that operate on four-byte words.
460 Writing to one of these files triggers an interrupt on the SPU.
461 The value written to the signal files can
462 be read from the SPU through a channel read or from
463 host user space through the file.
464 After the value has been read by the SPU, it is reset to zero.
465 The possible operations on an open
466 .I signal1
467 or
468 .I signal2
469 file are:
470 .RS
471 .TP
472 .BR read (2)
473 If
474 .I count
475 is smaller than four,
476 .BR read (2)
477 returns \-1 and sets
478 .I errno
479 to
480 .BR EINVAL .
481 Otherwise, a four-byte value is placed in the data buffer;
482 this is the current value of the specified signal notification
483 register.
484 .TP
485 .BR write (2)
486 If
487 .I count
488 is smaller than four,
489 .BR write (2)
490 returns \-1 and sets
491 .I errno
492 to
493 .BR EINVAL .
494 Otherwise, a four-byte value is copied from the data buffer,
495 updating the value of the specified signal notification
496 register.
497 The signal notification register will either be replaced with
498 the input data or will be updated to the bitwise OR operation
499 of the old value and the input data, depending on the contents
500 of the
501 .I signal1_type
502 or
503 .I signal2_type
504 files respectively.
505 .RE
506 .TP
507 .I /signal1_type
508 .TQ
509 .I /signal2_type
510 These two files change the behavior of the
511 .I signal1
512 and
513 .I signal2
514 notification files.
515 They contain a numeric ASCII string which is read
516 as either "1" or "0".
517 In mode 0 (overwrite), the hardware replaces the contents
518 of the signal channel with the data that is written to it.
519 In mode 1 (logical OR), the hardware accumulates the bits
520 that are subsequently written to it.
521 The possible operations on an open
522 .I signal1_type
523 or
524 .I signal2_type
525 file are:
526 .RS
527 .TP
528 .BR read (2)
529 When the count supplied to the
530 .BR read (2)
531 call is shorter than the required length for the digit (plus a newline
532 character), subsequent reads from the same file descriptor will
533 complete the string.
534 When a complete string has been read, all subsequent read operations
535 will return zero bytes and a new file descriptor needs to be opened
536 to read the value again.
537 .TP
538 .BR write (2)
539 A
540 .BR write (2)
541 operation on the file sets the register to the
542 value given in the string.
543 The string is parsed from the beginning
544 until the first nonnumeric character or the end of the buffer.
545 Subsequent writes to the same file descriptor overwrite the
546 previous setting.
547 .RE
548 .TP
549 .I /mbox_info
550 .TQ
551 .I /ibox_info
552 .TQ
553 .I /wbox_info
554 .TQ
555 .I /dma_into
556 .TQ
557 .I /proxydma_info
558 Read-only files that contain the saved state of the SPU mailboxes and
559 DMA queues.
560 This allows the SPU status to be inspected, mainly for debugging.
561 The
562 .I mbox_info
563 and
564 .I ibox_info
565 files each contain the four-byte mailbox message that has been written
566 by the SPU.
567 If no message has been written to these mailboxes, then
568 contents of these files is undefined.
569 The
570 .IR mbox_stat ,
571 .IR ibox_stat ,
572 and
573 .I wbox_stat
574 files contain the available message count.
575 .IP
576 The
577 .I wbox_info
578 file contains an array of four-byte mailbox messages, which have been
579 sent to the SPU.
580 With current CBEA machines, the array is four items in
581 length, so up to 4 * 4 = 16 bytes can be read from this file.
582 If any mailbox queue entry is empty,
583 then the bytes read at the corresponding location are undefined.
584 .IP
585 The
586 .I dma_info
587 file contains the contents of the SPU MFC DMA queue, represented as the
588 following structure:
589 .IP
590 .in +4n
591 .EX
592 struct spu_dma_info {
593 uint64_t dma_info_type;
594 uint64_t dma_info_mask;
595 uint64_t dma_info_status;
596 uint64_t dma_info_stall_and_notify;
597 uint64_t dma_info_atomic_command_status;
598 struct mfc_cq_sr dma_info_command_data[16];
599 };
600 .EE
601 .in
602 .IP
603 The last member of this data structure is the actual DMA queue,
604 containing 16 entries.
605 The
606 .I mfc_cq_sr
607 structure is defined as:
608 .IP
609 .in +4n
610 .EX
611 struct mfc_cq_sr {
612 uint64_t mfc_cq_data0_RW;
613 uint64_t mfc_cq_data1_RW;
614 uint64_t mfc_cq_data2_RW;
615 uint64_t mfc_cq_data3_RW;
616 };
617 .EE
618 .in
619 .IP
620 The
621 .I proxydma_info
622 file contains similar information, but describes the proxy DMA queue
623 (i.e., DMAs initiated by entities outside the SPU) instead.
624 The file is in the following format:
625 .IP
626 .in +4n
627 .EX
628 struct spu_proxydma_info {
629 uint64_t proxydma_info_type;
630 uint64_t proxydma_info_mask;
631 uint64_t proxydma_info_status;
632 struct mfc_cq_sr proxydma_info_command_data[8];
633 };
634 .EE
635 .in
636 .IP
637 Accessing these files requires that the SPU context is scheduled out -
638 frequent use can be inefficient.
639 These files should not be used for normal program operation.
640 .IP
641 These files are not present on contexts that have been created with the
642 .B SPU_CREATE_NOSCHED
643 flag.
644 .TP
645 .I /cntl
646 This file provides access to the SPU Run Control and SPU status
647 registers, as an ASCII string.
648 The following operations are supported:
649 .RS
650 .TP
651 .BR read (2)
652 Reads from the
653 .I cntl
654 file will return an ASCII string with the hex
655 value of the SPU Status register.
656 .TP
657 .BR write (2)
658 Writes to the
659 .I cntl
660 file will set the context's SPU Run Control register.
661 .RE
662 .TP
663 .I /mfc
664 Provides access to the Memory Flow Controller of the SPU.
665 Reading from the file returns the contents of the
666 SPU's MFC Tag Status register, and
667 writing to the file initiates a DMA from the MFC.
668 The following operations are supported:
669 .RS
670 .TP
671 .BR write (2)
672 Writes to this file need to be in the format of a MFC DMA command,
673 defined as follows:
674 .IP
675 .in +4n
676 .EX
677 struct mfc_dma_command {
678 int32_t pad; /* reserved */
679 uint32_t lsa; /* local storage address */
680 uint64_t ea; /* effective address */
681 uint16_t size; /* transfer size */
682 uint16_t tag; /* command tag */
683 uint16_t class; /* class ID */
684 uint16_t cmd; /* command opcode */
685 };
686 .EE
687 .in
688 .IP
689 Writes are required to be exactly
690 .I sizeof(struct mfc_dma_command)
691 bytes in size.
692 The command will be sent to the SPU's MFC proxy queue, and the
693 tag stored in the kernel (see below).
694 .TP
695 .BR read (2)
696 Reads the contents of the tag status register.
697 If the file is opened in blocking mode (i.e., without
698 .BR O_NONBLOCK ),
699 then the read will block until a
700 DMA tag (as performed by a previous write) is complete.
701 In nonblocking mode,
702 the MFC tag status register will be returned without waiting.
703 .TP
704 .BR poll (2)
705 Calling
706 .BR poll (2)
707 on the
708 .I mfc
709 file will block until a new DMA can be
710 started (by checking for
711 .BR POLLOUT )
712 or until a previously started DMA
713 (by checking for
714 .BR POLLIN )
715 has been completed.
716 .IP
717 .I /mss
718 Provides access to the MFC MultiSource Synchronization (MSS) facility.
719 By
720 .BR mmap (2)-ing
721 this file, processes can access the MSS area of the SPU.
722 .IP
723 The following operations are supported:
724 .TP
725 .BR mmap (2)
726 Mapping
727 .B mss
728 into the process address space gives access to the SPU MSS area
729 within the process address space.
730 Only
731 .B MAP_SHARED
732 mappings are allowed.
733 .RE
734 .TP
735 .I /psmap
736 Provides access to the whole problem-state mapping of the SPU.
737 Applications can use this area to interface to the SPU, rather than
738 writing to individual register files in
739 .BR spufs .
740 .IP
741 The following operations are supported:
742 .RS
743 .TP
744 .BR mmap (2)
745 Mapping
746 .B psmap
747 gives a process a direct map of the SPU problem state area.
748 Only
749 .B MAP_SHARED
750 mappings are supported.
751 .RE
752 .TP
753 .I /phys\-id
754 Read-only file containing the physical SPU number that the SPU context
755 is running on.
756 When the context is not running, this file contains the
757 string "\-1".
758 .IP
759 The physical SPU number is given by an ASCII hex string.
760 .TP
761 .I /object\-id
762 Allows applications to store (or retrieve) a single 64-bit ID into the
763 context.
764 This ID is later used by profiling tools to uniquely identify
765 the context.
766 .RS
767 .TP
768 .BR write (2)
769 By writing an ASCII hex value into this file, applications can set the
770 object ID of the SPU context.
771 Any previous value of the object ID is overwritten.
772 .TP
773 .BR read (2)
774 Reading this file gives an ASCII hex string representing the object ID
775 for this SPU context.
776 .RE
777 .SH EXAMPLES
778 To automatically
779 .BR mount (8)
780 the SPU filesystem when booting, at the location
781 .I /spu
782 chosen by the user, put this line into the
783 .BR fstab (5)
784 configuration file:
785 .EX
786 none /spu spufs gid=spu 0 0
787 .EE
788 .\" .SH AUTHORS
789 .\" Arnd Bergmann <[email protected]>, Mark Nutter <[email protected]>,
790 .\" Ulrich Weigand <[email protected]>, Jeremy Kerr <[email protected]>
791 .SH SEE ALSO
792 .BR close (2),
793 .BR spu_create (2),
794 .BR spu_run (2),
795 .BR capabilities (7)
796 .P
797 .I The Cell Broadband Engine Architecture (CBEA) specification