.\" Copyright (c) International Business Machines Corp., 2006
.\"
+.\" %%%LICENSE_START(GPLv2+_SW_3_PARA)
.\" This program is free software; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
.\" the GNU General Public License for more details.
.\"
-.\" You should have received a copy of the GNU General Public License
-.\" along with this program; if not, write to the Free Software
-.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston,
-.\" MA 02111-1307 USA
+.\" You should have received a copy of the GNU General Public
+.\" License along with this manual; if not, see
+.\" <http://www.gnu.org/licenses/>.
+.\" %%%LICENSE_END
.\"
.\" HISTORY:
.\" 2005-09-28, created by Arnd Bergmann <arndb@de.ibm.com>,
.\" 2007-07-10, quite a lot of polishing by mtk
.\" 2007-09-28, updates for newer kernels by Jeremy Kerr <jk@ozlabs.org>
.\"
-.TH SPUFS 7 2007-11-25 Linux "Linux Programmer's Manual"
+.TH SPUFS 7 2007-12-20 Linux "Linux Programmer's Manual"
.SH NAME
-spufs \- the SPU file system
+spufs \- SPU filesystem
.SH DESCRIPTION
-The SPU file system is used on PowerPC machines that implement the
+The SPU filesystem is used on PowerPC machines that implement the
Cell Broadband Engine Architecture in order to access Synergistic
Processor Units (SPUs).
-The file system provides a name space similar to POSIX shared
+The filesystem provides a name space similar to POSIX shared
memory or message queues.
Users that have write permissions
-on the file system can use
+on the filesystem can use
.BR spu_create (2)
-to establish SPU contexts under the spufs root directory.
+to establish SPU contexts under the
+.B spufs
+root directory.
Every SPU context is represented by a directory containing
a predefined set of files.
used for manipulating the state of the logical SPU.
Users can change permissions on the files, but can't
add or remove files.
-.SS Mount Options
+.SS Mount options
.TP
.B uid=<uid>
Set the user owning the mount point; the default is 0 (root).
Set the group owning the mount point; the default is 0 (root).
.TP
.B mode=<mode>
-Set the mode of the top-level directory in spufs,
+Set the mode of the top-level directory in
+.BR spufs ,
as an octal mode string.
The default is 0775.
.SS Files
The files in
-.I spufs
+.B spufs
mostly follow the standard behavior for regular system calls like
.BR read (2)
or
.BR write (2),
but often support only a subset of the operations
-supported on regular file systems.
+supported on regular filesystems.
This list details the supported
operations and the deviations from the standard behavior described
in the respective man pages.
.I /mbox
The first SPU-to-CPU communication mailbox.
This file is read-only and can be read in units of 4 bytes.
-The file can only be used in non-blocking mode \- even
+The file can be used only in nonblocking mode \- even
.BR poll (2)
cannot be used to block on this file.
The only possible operation on an open
.I /ibox
The second SPU-to-CPU communication mailbox.
This file is similar to the first mailbox file, but can be read
-in blocking I/O mode, thus
+in blocking I/O mode, thus calling
+.BR read (2)
+on an open
+.I ibox
+file will block until the SPU has written data to its interrupt mailbox
+channel (unless the file has been opened with
+.BR O_NONBLOCK ,
+see below).
+Also,
.BR poll (2)
-and similar system calls can be used to monitor this file.
+and similar system calls can be used to monitor for the presence
+of mailbox data.
+
The possible operations on an open
.I ibox
file are:
.TP
.IR /mbox_stat ", " /ibox_stat ", " /wbox_stat
These are read-only files that contain the length of the current
-queue of each mailbox, i.e., how many words can be read from
+queue of each mailbox\(emthat is, how many words can be read from
.IR mbox " or " ibox
or how many words can be written to
.I wbox
.RS
.TP 16
.I npc
-Next Program Counter \- only valid when the SPU is in a stopped state.
+Next Program Counter \- valid only when the SPU is in a stopped state.
.TP
.I decr
SPU Decrementer
operation on the file sets the register to the
value given in the string.
The string is parsed from the beginning
-until the first non-numeric character or the end of the buffer.
+until the first nonnumeric character or the end of the buffer.
Subsequent writes to the same file descriptor overwrite the
previous setting.
operation on the file sets the register to the
value given in the string.
The string is parsed from the beginning
-until the first non-numeric character or the end of the buffer.
+until the first nonnumeric character or the end of the buffer.
Subsequent writes to the same file descriptor overwrite the
previous setting.
.RE
file contains the contents of the SPU MFC DMA queue, represented as the
following structure:
-.in +0.25i
+.in +4n
.nf
struct spu_dma_info {
uint64_t dma_info_type;
.I mfc_cq_sr
structure is defined as:
-.in +0.25i
+.in +4n
.nf
struct mfc_cq_sr {
uint64_t mfc_cq_data0_RW;
(i.e., DMAs initiated by entities outside the SPU) instead.
The file is in the following format:
-.in +0.25i
+.in +4n
.nf
struct spu_proxydma_info {
uint64_t proxydma_info_type;
Writes to this file need to be in the format of a MFC DMA command,
defined as follows:
-.in +0.25i
+.in +4n
.nf
struct mfc_dma_command {
int32_t pad; /* reserved */
.BR O_NONBLOCK ),
then the read will block until a
DMA tag (as performed by a previous write) is complete.
-In non-blocking mode,
+In nonblocking mode,
the MFC tag status register will be returned without waiting.
.TP
.BR poll (2)
has been completed.
.I /mss
-Provides access to the MFC MultiSource Synchronization facility.
+Provides access to the MFC MultiSource Synchronization (MSS) facility.
By
.BR mmap (2)-ing
-this file, processes can access the MSS area of the SPE.
+this file, processes can access the MSS area of the SPU.
The following operations are supported:
.TP
.I /psmap
Provides access to the whole problem-state mapping of the SPU.
Applications can use this area to interface to the SPU, rather than
-writing to individual register files in spufs.
+writing to individual register files in
+.BR spufs .
The following operations are supported:
.RS
Read-only file containing the physical SPU number that the SPU context
is running on.
When the context is not running, this file contains the
-string "-1".
+string "\-1".
The physical SPU number is given by an ASCII hex string.
.TP
.BR read (2)
Reading this file gives an ASCII hex string representing the object ID
for this SPU context.
+.RE
.SH EXAMPLE
.TP
.IR /etc/fstab " entry"
.BR close (2),
.BR spu_create (2),
.BR spu_run (2),
-.BR capabilities (7),
+.BR capabilities (7)
+
.I The Cell Broadband Engine Architecture (CBEA) specification