2007-11-24 06:55:35 +00:00
|
|
|
.\" Copyright (c) International Business Machines Corp., 2006
|
2007-07-01 06:04:26 +00:00
|
|
|
.\"
|
2007-11-24 06:55:35 +00:00
|
|
|
.\" This program is free software; you can redistribute it and/or
|
2007-07-01 06:04:26 +00:00
|
|
|
.\" modify it under the terms of the GNU General Public License as
|
|
|
|
.\" published by the Free Software Foundation; either version 2 of
|
|
|
|
.\" the License, or (at your option) any later version.
|
|
|
|
.\"
|
|
|
|
.\" This program is distributed in the hope that it will be useful,
|
2007-11-24 06:55:35 +00:00
|
|
|
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
|
|
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
|
2007-07-01 06:04:26 +00:00
|
|
|
.\" the GNU General Public License for more details.
|
|
|
|
.\"
|
|
|
|
.\" You should have received a copy of the GNU General Public License
|
2007-11-24 06:55:35 +00:00
|
|
|
.\" along with this program; if not, write to the Free Software
|
2007-07-01 06:04:26 +00:00
|
|
|
.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston,
|
|
|
|
.\" MA 02111-1307 USA
|
|
|
|
.\"
|
|
|
|
.\" HISTORY:
|
|
|
|
.\" 2005-09-28, created by Arnd Bergmann <arndb@de.ibm.com>,
|
|
|
|
.\" Mark Nutter <mnutter@us.ibm.com> and
|
|
|
|
.\" Ulrich Weigand <Ulrich.Weigand@de.ibm.com>
|
|
|
|
.\" 2006-06-16, revised by Eduardo M. Fleury <efleury@br.ibm.com>
|
|
|
|
.\" 2007-07-10, quite a lot of polishing by mtk
|
2007-11-24 06:55:35 +00:00
|
|
|
.\" 2007-09-28, updates for newer kernels by Jeremy Kerr <jk@ozlabs.org>
|
2007-07-01 06:04:26 +00:00
|
|
|
.\"
|
2007-12-20 11:24:01 +00:00
|
|
|
.TH SPUFS 7 2007-12-20 Linux "Linux Programmer's Manual"
|
2007-07-01 06:04:26 +00:00
|
|
|
.SH NAME
|
|
|
|
spufs \- the SPU file system
|
|
|
|
.SH DESCRIPTION
|
|
|
|
The SPU file system 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
|
|
|
|
memory or message queues.
|
|
|
|
Users that have write permissions
|
2007-07-08 12:39:24 +00:00
|
|
|
on the file system can use
|
2007-07-01 06:04:26 +00:00
|
|
|
.BR spu_create (2)
|
2007-12-24 16:44:30 +00:00
|
|
|
to establish SPU contexts under the
|
|
|
|
.B spufs
|
|
|
|
root directory.
|
2007-07-01 06:04:26 +00:00
|
|
|
|
|
|
|
Every SPU context is represented by a directory containing
|
|
|
|
a predefined set of files.
|
|
|
|
These files can be
|
|
|
|
used for manipulating the state of the logical SPU.
|
2007-11-24 06:55:35 +00:00
|
|
|
Users can change permissions on the files, but can't
|
2007-07-01 06:04:26 +00:00
|
|
|
add or remove files.
|
|
|
|
.SS Mount Options
|
|
|
|
.TP
|
|
|
|
.B uid=<uid>
|
2007-11-24 06:55:35 +00:00
|
|
|
Set the user owning the mount point; the default is 0 (root).
|
2007-07-01 06:04:26 +00:00
|
|
|
.TP
|
|
|
|
.B gid=<gid>
|
2007-11-24 06:55:35 +00:00
|
|
|
Set the group owning the mount point; the default is 0 (root).
|
|
|
|
.TP
|
|
|
|
.B mode=<mode>
|
2007-12-24 16:44:30 +00:00
|
|
|
Set the mode of the top-level directory in
|
|
|
|
.BR spufs ,
|
2007-11-24 06:55:35 +00:00
|
|
|
as an octal mode string.
|
|
|
|
The default is 0775.
|
2007-07-01 06:04:26 +00:00
|
|
|
.SS Files
|
|
|
|
The files in
|
2007-12-24 16:44:30 +00:00
|
|
|
.B spufs
|
2007-07-01 06:04:26 +00:00
|
|
|
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.
|
|
|
|
This list details the supported
|
|
|
|
operations and the deviations from the standard behavior described
|
|
|
|
in the respective man pages.
|
|
|
|
|
|
|
|
All files that support the
|
|
|
|
.BR read (2)
|
|
|
|
operation also support
|
|
|
|
.BR readv (2)
|
|
|
|
and all files that support the
|
|
|
|
.BR write (2)
|
|
|
|
operation also support
|
|
|
|
.BR writev (2).
|
|
|
|
All files support the
|
|
|
|
.BR access (2)
|
|
|
|
and
|
|
|
|
.BR stat (2)
|
|
|
|
family of operations, but for the latter call,
|
2007-07-08 12:39:24 +00:00
|
|
|
the only fields of the returned
|
2007-07-01 06:04:26 +00:00
|
|
|
.I stat
|
|
|
|
structure that contain reliable information are
|
|
|
|
.IR st_mode ,
|
|
|
|
.IR st_nlink ,
|
|
|
|
.IR st_uid ,
|
|
|
|
and
|
|
|
|
.IR st_gid .
|
|
|
|
|
|
|
|
All files support the
|
|
|
|
.BR chmod (2)/ fchmod (2)
|
|
|
|
and
|
|
|
|
.BR chown (2)/ fchown (2)
|
|
|
|
operations, but will not be able to grant permissions that contradict
|
|
|
|
the possible operations (e.g., read access on the
|
|
|
|
.I wbox
|
|
|
|
file).
|
|
|
|
|
|
|
|
The current set of files is:
|
|
|
|
.TP
|
2007-11-24 06:55:35 +00:00
|
|
|
.I /capabilities
|
|
|
|
Contains a comma-delimited string representing the capabilities of this
|
|
|
|
SPU context.
|
|
|
|
Possible capabilities are:
|
|
|
|
.RS
|
|
|
|
.TP
|
|
|
|
.B sched
|
|
|
|
This context may be scheduled.
|
|
|
|
.TP
|
|
|
|
.B step
|
|
|
|
This context can be run in single-step mode, for debugging.
|
|
|
|
.PP
|
|
|
|
New capabilities flags may be added in the future.
|
|
|
|
.RE
|
|
|
|
.TP
|
|
|
|
.I /mem
|
2007-07-01 06:04:26 +00:00
|
|
|
the contents of the local storage memory of the SPU.
|
|
|
|
This can be accessed like a regular shared memory
|
|
|
|
file and contains both code and data in the address
|
|
|
|
space of the SPU.
|
|
|
|
The possible operations on an open
|
|
|
|
.I mem
|
|
|
|
file are:
|
|
|
|
.RS
|
|
|
|
.TP
|
|
|
|
.BR read "(2), " pread "(2), " write "(2), " pwrite "(2), " lseek (2)
|
2007-07-08 12:39:24 +00:00
|
|
|
These operate as usual, with the exception that
|
2007-11-24 06:55:35 +00:00
|
|
|
.BR lseek (2),
|
|
|
|
.BR write (2),
|
2007-07-08 12:39:24 +00:00
|
|
|
and
|
2007-07-01 06:04:26 +00:00
|
|
|
.BR pwrite (2)
|
|
|
|
are not supported beyond the end of the file.
|
|
|
|
The file size
|
|
|
|
is the size of the local storage of the SPU,
|
|
|
|
which is normally 256 kilobytes.
|
|
|
|
.TP
|
|
|
|
.BR mmap (2)
|
|
|
|
Mapping
|
|
|
|
.I mem
|
|
|
|
into the process address space provides access to the SPU local
|
|
|
|
storage within the process address space.
|
|
|
|
Only
|
|
|
|
.B MAP_SHARED
|
|
|
|
mappings are allowed.
|
|
|
|
.RE
|
|
|
|
.TP
|
2007-11-24 06:55:35 +00:00
|
|
|
.I /regs
|
|
|
|
Contains the saved general-purpose registers of the SPU context.
|
|
|
|
This file contains the 128-bit values of each register,
|
|
|
|
from register 0 to register 127, in order.
|
|
|
|
This allows the general-purpose registers to be
|
|
|
|
inspected for debugging.
|
|
|
|
|
|
|
|
Reading to or writing from this file requires that the context is
|
|
|
|
scheduled out, so use of this file is not recommended in normal
|
|
|
|
program operation.
|
|
|
|
|
|
|
|
The
|
|
|
|
.I regs
|
|
|
|
file is not present on contexts that have been created with the
|
|
|
|
.B SPU_CREATE_NOSCHED
|
|
|
|
flag.
|
|
|
|
.TP
|
|
|
|
.I /mbox
|
2007-07-01 06:04:26 +00:00
|
|
|
The first SPU-to-CPU communication mailbox.
|
2007-11-24 06:55:35 +00:00
|
|
|
This file is read-only and can be read in units of 4 bytes.
|
accept.2, connect.2, eventfd.2, flock.2, open.2, posix_fadvise.2, read.2, recv.2, sched_setscheduler.2, select_tut.2, send.2, signalfd.2, splice.2, timerfd_create.2, write.2, flockfile.3, mkfifo.3, mq_notify.3, mq_open.3, pthread_tryjoin_np.3, scanf.3, random.4, ddp.7, epoll.7, fifo.7, ip.7, pipe.7, socket.7, spufs.7: Global fix: s/non-blocking/nonblocking/
The tendency in English, as prescribed in style guides like
Chicago MoS, is towards removing hyphens after prefixes
like "non-" etc.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-01-16 16:43:10 +00:00
|
|
|
The file can only be used in nonblocking mode \- even
|
2007-07-01 06:04:26 +00:00
|
|
|
.BR poll (2)
|
2007-11-24 06:55:35 +00:00
|
|
|
cannot be used to block on this file.
|
2007-07-08 12:39:24 +00:00
|
|
|
The only possible operation on an open
|
2007-07-01 06:04:26 +00:00
|
|
|
.I mbox
|
|
|
|
file is:
|
|
|
|
.RS
|
|
|
|
.TP
|
|
|
|
.BR read (2)
|
|
|
|
If
|
|
|
|
.I count
|
|
|
|
is smaller than four,
|
|
|
|
.BR read (2)
|
|
|
|
returns \-1 and sets
|
|
|
|
.I errno
|
|
|
|
to
|
|
|
|
.BR EINVAL .
|
2007-11-24 06:55:35 +00:00
|
|
|
If there is no data available in the mailbox (i.e., the SPU has not
|
|
|
|
sent a mailbox message), the return value is set to \-1 and
|
2007-07-01 06:04:26 +00:00
|
|
|
.I errno
|
|
|
|
is set to
|
|
|
|
.BR EAGAIN .
|
|
|
|
When data
|
|
|
|
has been read successfully, four bytes are placed in
|
|
|
|
the data buffer and the value four is returned.
|
|
|
|
.RE
|
|
|
|
.TP
|
2007-11-24 06:55:35 +00:00
|
|
|
.I /ibox
|
2007-07-01 06:04:26 +00:00
|
|
|
The second SPU-to-CPU communication mailbox.
|
|
|
|
This file is similar to the first mailbox file, but can be read
|
2007-12-20 11:24:01 +00:00
|
|
|
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,
|
2007-07-01 06:04:26 +00:00
|
|
|
.BR poll (2)
|
2007-12-20 11:24:01 +00:00
|
|
|
and similar system calls can be used to monitor for the presence
|
|
|
|
of mailbox data.
|
|
|
|
|
2007-07-08 12:39:24 +00:00
|
|
|
The possible operations on an open
|
2007-07-01 06:04:26 +00:00
|
|
|
.I ibox
|
|
|
|
file are:
|
|
|
|
.RS
|
|
|
|
.TP
|
|
|
|
.BR read (2)
|
|
|
|
If
|
|
|
|
.I count
|
|
|
|
is smaller than four,
|
|
|
|
.BR read (2)
|
|
|
|
returns \-1 and sets
|
|
|
|
.I errno
|
|
|
|
to
|
|
|
|
.BR EINVAL .
|
|
|
|
If there is no data available in the mailbox and the file
|
|
|
|
descriptor has been opened with
|
|
|
|
.BR O_NONBLOCK ,
|
|
|
|
the return value is set to \-1 and
|
|
|
|
.I errno
|
|
|
|
is set to
|
|
|
|
.BR EAGAIN .
|
|
|
|
|
|
|
|
If there is no data available in the mailbox and the file
|
|
|
|
descriptor has been opened without
|
|
|
|
.BR O_NONBLOCK ,
|
|
|
|
the call will
|
|
|
|
block until the SPU writes to its interrupt mailbox channel.
|
|
|
|
When data has been read successfully, four bytes are placed in
|
|
|
|
the data buffer and the value four is returned.
|
|
|
|
.TP
|
|
|
|
.BR poll (2)
|
2007-07-08 12:39:24 +00:00
|
|
|
Poll on the
|
2007-07-01 06:04:26 +00:00
|
|
|
.I ibox
|
|
|
|
file returns
|
|
|
|
.I "(POLLIN | POLLRDNORM)"
|
|
|
|
whenever data is available for reading.
|
|
|
|
.RE
|
|
|
|
.TP
|
2007-11-24 06:55:35 +00:00
|
|
|
.I /wbox
|
2007-07-01 06:04:26 +00:00
|
|
|
The CPU-to-SPU communication mailbox.
|
2007-11-24 06:55:35 +00:00
|
|
|
It is write-only and can be written in units of four bytes.
|
2007-07-01 06:04:26 +00:00
|
|
|
If the mailbox is full,
|
|
|
|
.BR write (2)
|
2007-11-24 06:55:35 +00:00
|
|
|
will block, and
|
2007-07-01 06:04:26 +00:00
|
|
|
.BR poll (2)
|
2007-11-24 06:55:35 +00:00
|
|
|
can be used to block until the mailbox is available for writing again.
|
2007-07-08 12:39:24 +00:00
|
|
|
The possible operations on an open
|
2007-07-01 06:04:26 +00:00
|
|
|
.I wbox
|
|
|
|
file are:
|
|
|
|
.RS
|
|
|
|
.TP
|
|
|
|
.BR write (2)
|
|
|
|
If
|
|
|
|
.I count
|
|
|
|
is smaller than four,
|
|
|
|
.BR write (2)
|
|
|
|
returns \-1 and sets
|
|
|
|
.I errno
|
|
|
|
to
|
|
|
|
.BR EINVAL .
|
|
|
|
If there is no space available in the mailbox and the file
|
|
|
|
descriptor has been opened with
|
|
|
|
.BR O_NONBLOCK ,
|
|
|
|
the return
|
|
|
|
value is set to \-1 and
|
|
|
|
.I errno
|
|
|
|
is set to
|
|
|
|
.BR EAGAIN .
|
|
|
|
|
|
|
|
If there is no space available in the mailbox and the file
|
|
|
|
descriptor has been opened without
|
|
|
|
.BR O_NONBLOCK ,
|
2007-11-24 07:55:48 +00:00
|
|
|
the call will block until the SPU reads from its
|
2007-11-24 06:55:35 +00:00
|
|
|
PPE (PowerPC Processing Element)
|
|
|
|
mailbox channel.
|
2007-07-08 12:39:24 +00:00
|
|
|
When data has been written successfully,
|
2007-07-01 06:04:26 +00:00
|
|
|
the system call returns four as its function result.
|
|
|
|
.TP
|
|
|
|
.BR poll (2)
|
2007-07-08 12:39:24 +00:00
|
|
|
A poll on the
|
2007-07-01 06:04:26 +00:00
|
|
|
.I wbox
|
|
|
|
file returns
|
|
|
|
.I "(POLLOUT | POLLWRNORM)"
|
|
|
|
whenever space is available for writing.
|
|
|
|
.RE
|
|
|
|
.TP
|
2007-11-24 06:55:35 +00:00
|
|
|
.IR /mbox_stat ", " /ibox_stat ", " /wbox_stat
|
2007-07-01 06:04:26 +00:00
|
|
|
These are read-only files that contain the length of the current
|
2007-07-08 12:39:24 +00:00
|
|
|
queue of each mailbox, i.e., how many words can be read from
|
2007-07-01 06:04:26 +00:00
|
|
|
.IR mbox " or " ibox
|
|
|
|
or how many words can be written to
|
2007-07-08 12:39:24 +00:00
|
|
|
.I wbox
|
2007-07-01 06:04:26 +00:00
|
|
|
without blocking.
|
|
|
|
The files can be read only in four-byte units and return
|
|
|
|
a big-endian binary integer number.
|
2007-11-24 06:55:35 +00:00
|
|
|
The only possible operation on an open
|
2007-07-01 06:04:26 +00:00
|
|
|
.I *box_stat
|
2007-11-24 06:55:35 +00:00
|
|
|
file is:
|
2007-07-01 06:04:26 +00:00
|
|
|
.RS
|
|
|
|
.TP
|
|
|
|
.BR read (2)
|
|
|
|
If
|
|
|
|
.I count
|
|
|
|
is smaller than four,
|
|
|
|
.BR read (2)
|
|
|
|
returns \-1 and sets
|
|
|
|
.I errno
|
|
|
|
to
|
2007-12-05 13:47:50 +00:00
|
|
|
.BR EINVAL .
|
2007-07-01 06:04:26 +00:00
|
|
|
Otherwise, a four-byte value is placed in the data buffer.
|
|
|
|
This value is the number of elements that can be read from (for
|
2007-11-24 06:55:35 +00:00
|
|
|
.IR mbox_stat
|
2007-07-01 06:04:26 +00:00
|
|
|
and
|
|
|
|
.IR ibox_stat )
|
|
|
|
or written to (for
|
|
|
|
.IR wbox_stat )
|
2007-11-24 06:55:35 +00:00
|
|
|
the respective mailbox without blocking or returning an
|
|
|
|
.BR EAGAIN
|
2007-07-01 06:04:26 +00:00
|
|
|
error.
|
|
|
|
.RE
|
|
|
|
.TP
|
2007-11-24 06:55:35 +00:00
|
|
|
.IR /npc ", " /decr ", " /decr_status ", " /spu_tag_mask ", " \
|
|
|
|
/event_mask ", " /event_status ", " /srr0 ", " /lslr
|
|
|
|
Internal registers of the SPU.
|
|
|
|
These files contain an ASCII string
|
|
|
|
representing the hex value of the specified register.
|
|
|
|
Reads and writes on these
|
|
|
|
files (except for
|
|
|
|
.IR npc ,
|
|
|
|
see below) require that the SPU context be scheduled out,
|
|
|
|
so frequent access to
|
|
|
|
these files is not recommended for normal program operation.
|
2007-07-01 06:04:26 +00:00
|
|
|
.IP
|
|
|
|
The contents of these files are:
|
|
|
|
.RS
|
|
|
|
.TP 16
|
|
|
|
.I npc
|
2007-11-24 06:55:35 +00:00
|
|
|
Next Program Counter \- only valid when the SPU is in a stopped state.
|
2007-07-01 06:04:26 +00:00
|
|
|
.TP
|
|
|
|
.I decr
|
|
|
|
SPU Decrementer
|
|
|
|
.TP
|
|
|
|
.I decr_status
|
|
|
|
Decrementer Status
|
|
|
|
.TP
|
|
|
|
.I spu_tag_mask
|
|
|
|
MFC tag mask for SPU DMA
|
|
|
|
.TP
|
|
|
|
.I event_mask
|
|
|
|
Event mask for SPU interrupts
|
|
|
|
.TP
|
2007-11-24 06:55:35 +00:00
|
|
|
.I event_status
|
|
|
|
Number of SPU events pending (read-only)
|
|
|
|
.TP
|
2007-07-01 06:04:26 +00:00
|
|
|
.I srr0
|
|
|
|
Interrupt Return address register
|
2007-11-24 06:55:35 +00:00
|
|
|
.TP
|
|
|
|
.I lslr
|
|
|
|
Local Store Limit Register
|
2007-07-01 06:04:26 +00:00
|
|
|
.RE
|
|
|
|
.IP
|
2007-11-24 06:55:35 +00:00
|
|
|
The possible operations on these files are:
|
2007-07-01 06:04:26 +00:00
|
|
|
.RS
|
|
|
|
.TP
|
|
|
|
.BR read (2)
|
2007-11-24 06:55:35 +00:00
|
|
|
Reads the current register value.
|
|
|
|
If the register value is larger than the buffer passed to the
|
2007-07-01 06:04:26 +00:00
|
|
|
.BR read (2)
|
2007-11-24 06:55:35 +00:00
|
|
|
system call, subsequent reads will continue reading from the same
|
|
|
|
buffer, until the end of the buffer is reached.
|
|
|
|
|
2007-07-01 06:04:26 +00:00
|
|
|
When a complete string has been read, all subsequent read operations
|
2007-07-08 12:39:24 +00:00
|
|
|
will return zero bytes and a new file descriptor needs to be opened
|
2007-07-01 06:04:26 +00:00
|
|
|
to read a new value.
|
|
|
|
.TP
|
|
|
|
.BR write (2)
|
2007-07-08 12:39:24 +00:00
|
|
|
A
|
2007-07-01 06:04:26 +00:00
|
|
|
.BR write (2)
|
2007-07-08 12:39:24 +00:00
|
|
|
operation on the file sets the register to the
|
2007-07-01 06:04:26 +00:00
|
|
|
value given in the string.
|
2007-07-08 12:39:24 +00:00
|
|
|
The string is parsed from the beginning
|
2010-01-16 16:50:28 +00:00
|
|
|
until the first nonnumeric character or the end of the buffer.
|
2007-07-08 12:39:24 +00:00
|
|
|
Subsequent writes to the same file descriptor overwrite the
|
2007-07-01 06:04:26 +00:00
|
|
|
previous setting.
|
2007-11-24 06:55:35 +00:00
|
|
|
|
|
|
|
Except for the
|
|
|
|
.I npc
|
|
|
|
file, these files are not present on contexts that have been created with
|
|
|
|
the
|
|
|
|
.B SPU_CREATE_NOSCHED
|
|
|
|
flag.
|
2007-07-01 06:04:26 +00:00
|
|
|
.RE
|
|
|
|
.TP
|
2007-11-24 06:55:35 +00:00
|
|
|
.IR /fpcr
|
2007-07-08 12:39:24 +00:00
|
|
|
This file provides access to the Floating Point Status and
|
2007-11-24 06:55:35 +00:00
|
|
|
Control Register (fcpr) as a binary, four-byte file.
|
|
|
|
The operations on the
|
2007-07-01 06:04:26 +00:00
|
|
|
.I fpcr
|
|
|
|
file are:
|
|
|
|
.RS
|
|
|
|
.TP
|
|
|
|
.BR read (2)
|
|
|
|
If
|
|
|
|
.I count
|
|
|
|
is smaller than four,
|
|
|
|
.BR read (2)
|
|
|
|
returns \-1 and sets
|
|
|
|
.I errno
|
|
|
|
to
|
|
|
|
.BR EINVAL .
|
|
|
|
Otherwise, a four-byte value is placed in the data buffer;
|
|
|
|
this is the current value of the
|
|
|
|
.I fpcr
|
|
|
|
register.
|
|
|
|
.TP
|
|
|
|
.BR write (2)
|
|
|
|
If
|
|
|
|
.I count
|
|
|
|
is smaller than four,
|
|
|
|
.BR write (2)
|
|
|
|
returns \-1 and sets
|
|
|
|
.I errno
|
|
|
|
to
|
|
|
|
.BR EINVAL .
|
|
|
|
Otherwise, a four-byte value is copied from the data buffer,
|
|
|
|
updating the value of the
|
|
|
|
.I fpcr
|
|
|
|
register.
|
|
|
|
.RE
|
|
|
|
.TP
|
2007-11-24 06:55:35 +00:00
|
|
|
.IR /signal1 ", " /signal2
|
2007-07-01 06:04:26 +00:00
|
|
|
The files provide access to the two signal notification channels
|
|
|
|
of an SPU.
|
2007-11-24 06:55:35 +00:00
|
|
|
These are read-write files that operate on four-byte words.
|
2007-07-01 06:04:26 +00:00
|
|
|
Writing to one of these files triggers an interrupt on the SPU.
|
|
|
|
The value written to the signal files can
|
|
|
|
be read from the SPU through a channel read or from
|
|
|
|
host user space through the file.
|
|
|
|
After the value has been read by the SPU, it is reset to zero.
|
2007-07-08 12:39:24 +00:00
|
|
|
The possible operations on an open
|
2007-07-01 06:04:26 +00:00
|
|
|
.I signal1
|
|
|
|
or
|
|
|
|
.I signal2
|
|
|
|
file are:
|
|
|
|
.RS
|
|
|
|
.TP
|
|
|
|
.BR read (2)
|
|
|
|
If
|
|
|
|
.I count
|
|
|
|
is smaller than four,
|
|
|
|
.BR read (2)
|
|
|
|
returns \-1 and sets
|
|
|
|
.I errno
|
|
|
|
to
|
|
|
|
.BR EINVAL .
|
|
|
|
Otherwise, a four-byte value is placed in the data buffer;
|
|
|
|
this is the current value of the specified signal notification
|
|
|
|
register.
|
|
|
|
.TP
|
|
|
|
.BR write (2)
|
|
|
|
If
|
|
|
|
.I count
|
|
|
|
is smaller than four,
|
|
|
|
.BR write (2)
|
|
|
|
returns \-1 and sets
|
|
|
|
.I errno
|
|
|
|
to
|
|
|
|
.BR EINVAL .
|
|
|
|
Otherwise, a four-byte value is copied from the data buffer,
|
2007-07-08 12:39:24 +00:00
|
|
|
updating the value of the specified signal notification
|
2007-07-01 06:04:26 +00:00
|
|
|
register.
|
2007-07-08 12:39:24 +00:00
|
|
|
The signal notification register will either be replaced with
|
|
|
|
the input data or will be updated to the bitwise OR operation
|
2007-07-01 06:04:26 +00:00
|
|
|
of the old value and the input data, depending on the contents
|
|
|
|
of the
|
2007-11-24 06:55:35 +00:00
|
|
|
.IR signal1_type
|
2007-07-01 06:04:26 +00:00
|
|
|
or
|
2007-11-24 06:55:35 +00:00
|
|
|
.IR signal2_type
|
2007-07-01 06:04:26 +00:00
|
|
|
files respectively.
|
|
|
|
.RE
|
|
|
|
.TP
|
2007-11-24 06:55:35 +00:00
|
|
|
.IR /signal1_type ", " /signal2_type
|
2007-07-01 06:04:26 +00:00
|
|
|
These two files change the behavior of the
|
2007-11-24 06:55:35 +00:00
|
|
|
.IR signal1
|
2007-07-01 06:04:26 +00:00
|
|
|
and
|
2007-11-24 06:55:35 +00:00
|
|
|
.IR signal2
|
2007-07-01 06:04:26 +00:00
|
|
|
notification files.
|
2007-11-24 06:55:35 +00:00
|
|
|
They contain a numeric ASCII string which is read
|
|
|
|
as either "1" or "0".
|
2007-07-01 06:04:26 +00:00
|
|
|
In mode 0 (overwrite), the hardware replaces the contents
|
|
|
|
of the signal channel with the data that is written to it.
|
|
|
|
In mode 1 (logical OR), the hardware accumulates the bits
|
|
|
|
that are subsequently written to it.
|
2007-07-08 12:39:24 +00:00
|
|
|
The possible operations on an open
|
2007-07-01 06:04:26 +00:00
|
|
|
.I signal1_type
|
|
|
|
or
|
|
|
|
.I signal2_type
|
|
|
|
file are:
|
|
|
|
.RS
|
|
|
|
.TP
|
|
|
|
.BR read (2)
|
|
|
|
When the count supplied to the
|
|
|
|
.BR read (2)
|
2007-11-24 06:55:35 +00:00
|
|
|
call is shorter than the required length for the digit (plus a newline
|
|
|
|
character), subsequent reads from the same file descriptor will
|
|
|
|
complete the string.
|
2007-07-01 06:04:26 +00:00
|
|
|
When a complete string has been read, all subsequent read operations
|
|
|
|
will return zero bytes and a new file descriptor needs to be opened
|
|
|
|
to read the value again.
|
|
|
|
.TP
|
|
|
|
.BR write (2)
|
2007-07-08 12:39:24 +00:00
|
|
|
A
|
2007-07-01 06:04:26 +00:00
|
|
|
.BR write (2)
|
|
|
|
operation on the file sets the register to the
|
|
|
|
value given in the string.
|
|
|
|
The string is parsed from the beginning
|
2010-01-16 16:50:28 +00:00
|
|
|
until the first nonnumeric character or the end of the buffer.
|
2007-07-01 06:04:26 +00:00
|
|
|
Subsequent writes to the same file descriptor overwrite the
|
|
|
|
previous setting.
|
|
|
|
.RE
|
2007-11-24 06:55:35 +00:00
|
|
|
.TP
|
|
|
|
.IR /mbox_info ", " /ibox_info ", " /wbox_info ", " /dma_into ", " /proxydma_info
|
|
|
|
Read-only files that contain the saved state of the SPU mailboxes and
|
|
|
|
DMA queues.
|
|
|
|
This allows the SPU status to be inspected, mainly for debugging.
|
|
|
|
The
|
|
|
|
.I mbox_info
|
|
|
|
and
|
|
|
|
.I ibox_info
|
|
|
|
files each contain the four-byte mailbox message that has been written
|
|
|
|
by the SPU.
|
|
|
|
If no message has been written to these mailboxes, then
|
|
|
|
contents of these files is undefined.
|
|
|
|
The
|
|
|
|
.IR mbox_stat ,
|
|
|
|
.I ibox_stat
|
|
|
|
and
|
|
|
|
.I wbox_stat
|
|
|
|
files contain the available message count.
|
|
|
|
|
|
|
|
The
|
|
|
|
.I wbox_info
|
|
|
|
file contains an array of four-byte mailbox messages, which have been
|
|
|
|
sent to the SPU.
|
|
|
|
With current CBEA machines, the array is four items in
|
|
|
|
length, so up to 4 * 4 = 16 bytes can be read from this file.
|
|
|
|
If any mailbox queue entry is empty,
|
|
|
|
then the bytes read at the corresponding location are undefined.
|
|
|
|
|
|
|
|
The
|
|
|
|
.I dma_info
|
|
|
|
file contains the contents of the SPU MFC DMA queue, represented as the
|
|
|
|
following structure:
|
|
|
|
|
2007-12-19 06:57:44 +00:00
|
|
|
.in +4n
|
2007-11-24 06:55:35 +00:00
|
|
|
.nf
|
|
|
|
struct spu_dma_info {
|
|
|
|
uint64_t dma_info_type;
|
|
|
|
uint64_t dma_info_mask;
|
|
|
|
uint64_t dma_info_status;
|
|
|
|
uint64_t dma_info_stall_and_notify;
|
|
|
|
uint64_t dma_info_atomic_command_status;
|
|
|
|
struct mfc_cq_sr dma_info_command_data[16];
|
|
|
|
};
|
|
|
|
.fi
|
|
|
|
.in
|
|
|
|
|
|
|
|
The last member of this data structure is the actual DMA queue,
|
|
|
|
containing 16 entries.
|
|
|
|
The
|
|
|
|
.I mfc_cq_sr
|
|
|
|
structure is defined as:
|
|
|
|
|
2007-12-19 06:57:44 +00:00
|
|
|
.in +4n
|
2007-11-24 06:55:35 +00:00
|
|
|
.nf
|
|
|
|
struct mfc_cq_sr {
|
|
|
|
uint64_t mfc_cq_data0_RW;
|
|
|
|
uint64_t mfc_cq_data1_RW;
|
|
|
|
uint64_t mfc_cq_data2_RW;
|
|
|
|
uint64_t mfc_cq_data3_RW;
|
|
|
|
};
|
|
|
|
.fi
|
|
|
|
.in
|
|
|
|
|
|
|
|
The
|
|
|
|
.I proxydma_info
|
|
|
|
file contains similar information, but describes the proxy DMA queue
|
|
|
|
(i.e., DMAs initiated by entities outside the SPU) instead.
|
|
|
|
The file is in the following format:
|
|
|
|
|
2007-12-19 06:57:44 +00:00
|
|
|
.in +4n
|
2007-11-24 06:55:35 +00:00
|
|
|
.nf
|
|
|
|
struct spu_proxydma_info {
|
|
|
|
uint64_t proxydma_info_type;
|
|
|
|
uint64_t proxydma_info_mask;
|
|
|
|
uint64_t proxydma_info_status;
|
|
|
|
struct mfc_cq_sr proxydma_info_command_data[8];
|
|
|
|
};
|
|
|
|
.fi
|
|
|
|
.in
|
|
|
|
|
|
|
|
Accessing these files requires that the SPU context is scheduled out -
|
|
|
|
frequent use can be inefficient.
|
|
|
|
These files should not be used for normal program operation.
|
|
|
|
|
|
|
|
These files are not present on contexts that have been created with the
|
|
|
|
.B SPU_CREATE_NOSCHED
|
|
|
|
flag.
|
|
|
|
.TP
|
|
|
|
.IR /cntl
|
|
|
|
This file provides access to the SPU Run Control and SPU status
|
|
|
|
registers, as an ASCII string.
|
|
|
|
The following operations are supported:
|
|
|
|
.RS
|
|
|
|
.TP
|
|
|
|
.BR read (2)
|
|
|
|
Reads from the
|
|
|
|
.I cntl
|
|
|
|
file will return an ASCII string with the hex
|
|
|
|
value of the SPU Status register.
|
|
|
|
.TP
|
|
|
|
.BR write (2)
|
|
|
|
Writes to the
|
|
|
|
.I cntl
|
|
|
|
file will set the context's SPU Run Control register.
|
|
|
|
.RE
|
|
|
|
.TP
|
|
|
|
.I /mfc
|
|
|
|
Provides access to the Memory Flow Controller of the SPU.
|
|
|
|
Reading from the file returns the contents of the
|
|
|
|
SPU's MFC Tag Status register, and
|
|
|
|
writing to the file initiates a DMA from the MFC.
|
|
|
|
The following operations are supported:
|
|
|
|
.RS
|
|
|
|
.TP
|
|
|
|
.BR write (2)
|
|
|
|
Writes to this file need to be in the format of a MFC DMA command,
|
|
|
|
defined as follows:
|
|
|
|
|
2007-12-19 06:57:44 +00:00
|
|
|
.in +4n
|
2007-11-24 06:55:35 +00:00
|
|
|
.nf
|
|
|
|
struct mfc_dma_command {
|
|
|
|
int32_t pad; /* reserved */
|
|
|
|
uint32_t lsa; /* local storage address */
|
|
|
|
uint64_t ea; /* effective address */
|
|
|
|
uint16_t size; /* transfer size */
|
|
|
|
uint16_t tag; /* command tag */
|
|
|
|
uint16_t class; /* class ID */
|
|
|
|
uint16_t cmd; /* command opcode */
|
|
|
|
};
|
|
|
|
.fi
|
|
|
|
.in
|
|
|
|
|
|
|
|
Writes are required to be exactly
|
|
|
|
.I sizeof(struct mfc_dma_command)
|
|
|
|
bytes in size.
|
|
|
|
The command will be sent to the SPU's MFC proxy queue, and the
|
|
|
|
tag stored in the kernel (see below).
|
|
|
|
.TP
|
|
|
|
.BR read (2)
|
|
|
|
Reads the contents of the tag status register.
|
|
|
|
If the file is opened in blocking mode (i.e., without
|
|
|
|
.BR O_NONBLOCK ),
|
|
|
|
then the read will block until a
|
|
|
|
DMA tag (as performed by a previous write) is complete.
|
accept.2, connect.2, eventfd.2, flock.2, open.2, posix_fadvise.2, read.2, recv.2, sched_setscheduler.2, select_tut.2, send.2, signalfd.2, splice.2, timerfd_create.2, write.2, flockfile.3, mkfifo.3, mq_notify.3, mq_open.3, pthread_tryjoin_np.3, scanf.3, random.4, ddp.7, epoll.7, fifo.7, ip.7, pipe.7, socket.7, spufs.7: Global fix: s/non-blocking/nonblocking/
The tendency in English, as prescribed in style guides like
Chicago MoS, is towards removing hyphens after prefixes
like "non-" etc.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-01-16 16:43:10 +00:00
|
|
|
In nonblocking mode,
|
2007-11-24 06:55:35 +00:00
|
|
|
the MFC tag status register will be returned without waiting.
|
|
|
|
.TP
|
|
|
|
.BR poll (2)
|
|
|
|
Calling
|
|
|
|
.BR poll (2)
|
|
|
|
on the
|
|
|
|
.I mfc
|
|
|
|
file will block until a new DMA can be
|
|
|
|
started (by checking for
|
|
|
|
.BR POLLOUT )
|
|
|
|
or until a previously started DMA
|
|
|
|
(by checking for
|
|
|
|
.BR POLLIN )
|
|
|
|
has been completed.
|
|
|
|
|
|
|
|
.I /mss
|
2008-01-04 05:40:48 +00:00
|
|
|
Provides access to the MFC MultiSource Synchronization (MSS) facility.
|
2007-11-24 06:55:35 +00:00
|
|
|
By
|
|
|
|
.BR mmap (2)-ing
|
2008-01-03 07:06:07 +00:00
|
|
|
this file, processes can access the MSS area of the SPU.
|
2007-11-24 06:55:35 +00:00
|
|
|
|
|
|
|
The following operations are supported:
|
|
|
|
.TP
|
|
|
|
.BR mmap (2)
|
|
|
|
Mapping
|
|
|
|
.B mss
|
|
|
|
into the process address space gives access to the SPU MSS area
|
|
|
|
within the process address space.
|
|
|
|
Only
|
|
|
|
.B MAP_SHARED
|
|
|
|
mappings are allowed.
|
|
|
|
.RE
|
|
|
|
.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
|
2007-12-24 16:44:30 +00:00
|
|
|
writing to individual register files in
|
|
|
|
.BR spufs .
|
2007-11-24 06:55:35 +00:00
|
|
|
|
|
|
|
The following operations are supported:
|
|
|
|
.RS
|
|
|
|
.TP
|
|
|
|
.BR mmap (2)
|
|
|
|
Mapping
|
2007-12-10 15:12:05 +00:00
|
|
|
.B psmap
|
2007-11-24 06:55:35 +00:00
|
|
|
gives a process a direct map of the SPU problem state area.
|
|
|
|
Only
|
|
|
|
.B MAP_SHARED
|
|
|
|
mappings are supported.
|
|
|
|
.RE
|
|
|
|
.TP
|
|
|
|
.I /phys-id
|
|
|
|
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".
|
|
|
|
|
|
|
|
The physical SPU number is given by an ASCII hex string.
|
|
|
|
.TP
|
|
|
|
.I /object-id
|
|
|
|
Allows applications to store (or retrieve) a single 64-bit ID into the
|
|
|
|
context.
|
|
|
|
This ID is later used by profiling tools to uniquely identify
|
|
|
|
the context.
|
|
|
|
.RS
|
|
|
|
.TP
|
|
|
|
.BR write (2)
|
|
|
|
By writing an ASCII hex value into this file, applications can set the
|
|
|
|
object ID of the SPU context.
|
|
|
|
Any previous value of the object ID is overwritten.
|
|
|
|
.TP
|
|
|
|
.BR read (2)
|
|
|
|
Reading this file gives an ASCII hex string representing the object ID
|
|
|
|
for this SPU context.
|
2007-12-17 09:24:53 +00:00
|
|
|
.RE
|
2007-07-01 06:04:26 +00:00
|
|
|
.SH EXAMPLE
|
|
|
|
.TP
|
|
|
|
.IR /etc/fstab " entry"
|
|
|
|
none /spu spufs gid=spu 0 0
|
|
|
|
.\" .SH AUTHORS
|
2007-11-24 06:55:35 +00:00
|
|
|
.\" Arnd Bergmann <arndb@de.ibm.com>, Mark Nutter <mnutter@us.ibm.com>,
|
|
|
|
.\" Ulrich Weigand <Ulrich.Weigand@de.ibm.com>, Jeremy Kerr <jk@ozlabs.org>
|
2007-07-01 06:04:26 +00:00
|
|
|
.SH SEE ALSO
|
|
|
|
.BR close (2),
|
|
|
|
.BR spu_create (2),
|
2007-11-24 06:55:35 +00:00
|
|
|
.BR spu_run (2),
|
|
|
|
.BR capabilities (7),
|
|
|
|
.I The Cell Broadband Engine Architecture (CBEA) specification
|