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