522 lines
20 KiB
Plaintext
522 lines
20 KiB
Plaintext
SPUFS(2) Linux Programmer's Manual SPUFS(2)
|
|
|
|
|
|
|
|
NAME
|
|
spufs - the SPU file system
|
|
|
|
|
|
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 on the file system
|
|
can use spu_create(2) to establish SPU contexts in the spufs root.
|
|
|
|
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. Users can change permissions on those files, but not actu-
|
|
ally add or remove files.
|
|
|
|
|
|
MOUNT OPTIONS
|
|
uid=<uid>
|
|
set the user owning the mount point, the default is 0 (root).
|
|
|
|
gid=<gid>
|
|
set the group owning the mount point, the default is 0 (root).
|
|
|
|
|
|
FILES
|
|
The files in spufs mostly follow the standard behavior for regular sys-
|
|
tem calls like read(2) or 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 behaviour in the
|
|
respective man pages.
|
|
|
|
All files that support the read(2) operation also support readv(2) and
|
|
all files that support the write(2) operation also support writev(2).
|
|
All files support the access(2) and stat(2) family of operations, but
|
|
only the st_mode, st_nlink, st_uid and st_gid fields of struct stat
|
|
contain reliable information.
|
|
|
|
All files support the chmod(2)/fchmod(2) and chown(2)/fchown(2) opera-
|
|
tions, but will not be able to grant permissions that contradict the
|
|
possible operations, e.g. read access on the wbox file.
|
|
|
|
The current set of files is:
|
|
|
|
|
|
/mem
|
|
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 mem file are:
|
|
|
|
read(2), pread(2), write(2), pwrite(2), lseek(2)
|
|
These operate as documented, with the exception that seek(2),
|
|
write(2) and 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 normally is 256 kilobytes.
|
|
|
|
mmap(2)
|
|
Mapping mem into the process address space gives access to the
|
|
SPU local storage within the process address space. Only
|
|
MAP_SHARED mappings are allowed.
|
|
|
|
|
|
/mbox
|
|
The first SPU to CPU communication mailbox. This file is read-only and
|
|
can be read in units of 32 bits. The file can only be used in non-
|
|
blocking mode and it even poll() will not block on it. The possible
|
|
operations on an open mbox file are:
|
|
|
|
read(2)
|
|
If a count smaller than four is requested, read returns -1 and
|
|
sets errno to EINVAL. If there is no data available in the mail
|
|
box, the return value is set to -1 and errno becomes EAGAIN.
|
|
When data has been read successfully, four bytes are placed in
|
|
the data buffer and the value four is returned.
|
|
|
|
|
|
/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, and the
|
|
poll family of system calls can be used to wait for it. The possible
|
|
operations on an open ibox file are:
|
|
|
|
read(2)
|
|
If a count smaller than four is requested, read returns -1 and
|
|
sets errno to EINVAL. If there is no data available in the mail
|
|
box and the file descriptor has been opened with O_NONBLOCK, the
|
|
return value is set to -1 and errno becomes EAGAIN.
|
|
|
|
If there is no data available in the mail box and the file
|
|
descriptor has been opened without 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.
|
|
|
|
poll(2)
|
|
Poll on the ibox file returns (POLLIN | POLLRDNORM) whenever
|
|
data is available for reading.
|
|
|
|
|
|
/wbox
|
|
The CPU to SPU communation mailbox. It is write-only and can be written
|
|
in units of 32 bits. If the mailbox is full, write() will block and
|
|
poll can be used to wait for it becoming empty again. The possible
|
|
operations on an open wbox file are: write(2) If a count smaller than
|
|
four is requested, write returns -1 and sets errno to EINVAL. If there
|
|
is no space available in the mail box and the file descriptor has been
|
|
opened with O_NONBLOCK, the return value is set to -1 and errno becomes
|
|
EAGAIN.
|
|
|
|
If there is no space available in the mail box and the file descriptor
|
|
has been opened without O_NONBLOCK, the call will block until the SPU
|
|
reads from its PPE mailbox channel. When data has been read success-
|
|
fully, four bytes are placed in the data buffer and the value four is
|
|
returned.
|
|
|
|
poll(2)
|
|
Poll on the ibox file returns (POLLOUT | POLLWRNORM) whenever
|
|
space is available for writing.
|
|
|
|
|
|
/mbox_stat
|
|
/ibox_stat
|
|
/wbox_stat
|
|
Read-only files that contain the length of the current queue, i.e. how
|
|
many words can be read from mbox or ibox or how many words can be
|
|
written to wbox without blocking. The files can be read only in 4-byte
|
|
units and return a big-endian binary integer number. The possible
|
|
operations on an open *box_stat file are:
|
|
|
|
read(2)
|
|
If a count smaller than four is requested, read returns -1 and
|
|
sets errno to EINVAL. Otherwise, a four byte value is placed in
|
|
the data buffer, containing the number of elements that can be
|
|
read from (for mbox_stat and ibox_stat) or written to (for
|
|
wbox_stat) the respective mail box without blocking or resulting
|
|
in EAGAIN.
|
|
|
|
|
|
/npc
|
|
/decr
|
|
/decr_status
|
|
/spu_tag_mask
|
|
/event_mask
|
|
/srr0
|
|
Internal registers of the SPU. The representation is an ASCII string
|
|
with the numeric value of the next instruction to be executed. These
|
|
can be used in read/write mode for debugging, but normal operation of
|
|
programs should not rely on them because access to any of them except
|
|
npc requires an SPU context save and is therefore very inefficient.
|
|
|
|
The contents of these files are:
|
|
|
|
npc Next Program Counter
|
|
|
|
decr SPU Decrementer
|
|
|
|
decr_status Decrementer Status
|
|
|
|
spu_tag_mask MFC tag mask for SPU DMA
|
|
|
|
event_mask Event mask for SPU interrupts
|
|
|
|
srr0 Interrupt Return address register
|
|
|
|
|
|
The possible operations on an open npc, decr, decr_status,
|
|
spu_tag_mask, event_mask or srr0 file are:
|
|
|
|
read(2)
|
|
When the count supplied to the read call is shorter than the
|
|
required length for the pointer value plus a newline character,
|
|
subsequent reads from the same file descriptor will result in
|
|
completing the string, regardless of changes to the register by
|
|
a running SPU task. 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.
|
|
|
|
write(2)
|
|
A write operation on the file results in setting the register to
|
|
the value given in the string. The string is parsed from the
|
|
beginning to the first non-numeric character or the end of the
|
|
buffer. Subsequent writes to the same file descriptor overwrite
|
|
the previous setting.
|
|
|
|
|
|
/fpcr
|
|
This file gives access to the Floating Point Status and Control Regis-
|
|
ter as a four byte long file. The operations on the fpcr file are:
|
|
|
|
read(2)
|
|
If a count smaller than four is requested, read returns -1 and
|
|
sets errno to EINVAL. Otherwise, a four byte value is placed in
|
|
the data buffer, containing the current value of the fpcr regis-
|
|
ter.
|
|
|
|
write(2)
|
|
If a count smaller than four is requested, write returns -1 and
|
|
sets errno to EINVAL. Otherwise, a four byte value is copied
|
|
from the data buffer, updating the value of the fpcr register.
|
|
|
|
|
|
/signal1
|
|
/signal2
|
|
The two signal notification channels of an SPU. These are read-write
|
|
files that operate on a 32 bit word. 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. The possible operations on an open signal1 or sig-
|
|
nal2 file are:
|
|
|
|
read(2)
|
|
If a count smaller than four is requested, read returns -1 and
|
|
sets errno to EINVAL. Otherwise, a four byte value is placed in
|
|
the data buffer, containing the current value of the specified
|
|
signal notification register.
|
|
|
|
write(2)
|
|
If a count smaller than four is requested, write returns -1 and
|
|
sets errno to EINVAL. Otherwise, a four byte value is copied
|
|
from the data buffer, updating the value of the specified signal
|
|
notification register. The signal notification register will
|
|
either be replaced with the input data or will be updated to the
|
|
bitwise OR or the old value and the input data, depending on the
|
|
contents of the signal1_type, or signal2_type respectively,
|
|
file.
|
|
|
|
|
|
/signal1_type
|
|
/signal2_type
|
|
These two files change the behavior of the signal1 and signal2 notifi-
|
|
cation files. The contain a numerical ASCII string which is read as
|
|
either "1" or "0". 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 subse-
|
|
quently written to it. The possible operations on an open signal1_type
|
|
or signal2_type file are:
|
|
|
|
read(2)
|
|
When the count supplied to the read call is shorter than the
|
|
required length for the digit plus a newline character, subse-
|
|
quent reads from the same file descriptor will result in com-
|
|
pleting the string. 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.
|
|
|
|
write(2)
|
|
A write operation on the file results in setting the register to
|
|
the value given in the string. The string is parsed from the
|
|
beginning to the first non-numeric character or the end of the
|
|
buffer. Subsequent writes to the same file descriptor overwrite
|
|
the previous setting.
|
|
|
|
|
|
EXAMPLES
|
|
/etc/fstab entry
|
|
none /spu spufs gid=spu 0 0
|
|
|
|
|
|
AUTHORS
|
|
Arnd Bergmann <arndb@de.ibm.com>, Mark Nutter <mnutter@us.ibm.com>,
|
|
Ulrich Weigand <Ulrich.Weigand@de.ibm.com>
|
|
|
|
SEE ALSO
|
|
capabilities(7), close(2), spu_create(2), spu_run(2), spufs(7)
|
|
|
|
|
|
|
|
Linux 2005-09-28 SPUFS(2)
|
|
|
|
------------------------------------------------------------------------------
|
|
|
|
SPU_RUN(2) Linux Programmer's Manual SPU_RUN(2)
|
|
|
|
|
|
|
|
NAME
|
|
spu_run - execute an spu context
|
|
|
|
|
|
SYNOPSIS
|
|
#include <sys/spu.h>
|
|
|
|
int spu_run(int fd, unsigned int *npc, unsigned int *event);
|
|
|
|
DESCRIPTION
|
|
The spu_run system call is used on PowerPC machines that implement the
|
|
Cell Broadband Engine Architecture in order to access Synergistic Pro-
|
|
cessor Units (SPUs). It uses the fd that was returned from spu_cre-
|
|
ate(2) to address a specific SPU context. When the context gets sched-
|
|
uled to a physical SPU, it starts execution at the instruction pointer
|
|
passed in npc.
|
|
|
|
Execution of SPU code happens synchronously, meaning that spu_run does
|
|
not return while the SPU is still running. If there is a need to exe-
|
|
cute SPU code in parallel with other code on either the main CPU or
|
|
other SPUs, you need to create a new thread of execution first, e.g.
|
|
using the pthread_create(3) call.
|
|
|
|
When spu_run returns, the current value of the SPU instruction pointer
|
|
is written back to npc, so you can call spu_run again without updating
|
|
the pointers.
|
|
|
|
event can be a NULL pointer or point to an extended status code that
|
|
gets filled when spu_run returns. It can be one of the following con-
|
|
stants:
|
|
|
|
SPE_EVENT_DMA_ALIGNMENT
|
|
A DMA alignment error
|
|
|
|
SPE_EVENT_SPE_DATA_SEGMENT
|
|
A DMA segmentation error
|
|
|
|
SPE_EVENT_SPE_DATA_STORAGE
|
|
A DMA storage error
|
|
|
|
If NULL is passed as the event argument, these errors will result in a
|
|
signal delivered to the calling process.
|
|
|
|
RETURN VALUE
|
|
spu_run returns the value of the spu_status register or -1 to indicate
|
|
an error and set errno to one of the error codes listed below. The
|
|
spu_status register value contains a bit mask of status codes and
|
|
optionally a 14 bit code returned from the stop-and-signal instruction
|
|
on the SPU. The bit masks for the status codes are:
|
|
|
|
0x02 SPU was stopped by stop-and-signal.
|
|
|
|
0x04 SPU was stopped by halt.
|
|
|
|
0x08 SPU is waiting for a channel.
|
|
|
|
0x10 SPU is in single-step mode.
|
|
|
|
0x20 SPU has tried to execute an invalid instruction.
|
|
|
|
0x40 SPU has tried to access an invalid channel.
|
|
|
|
0x3fff0000
|
|
The bits masked with this value contain the code returned from
|
|
stop-and-signal.
|
|
|
|
There are always one or more of the lower eight bits set or an error
|
|
code is returned from spu_run.
|
|
|
|
ERRORS
|
|
EAGAIN or EWOULDBLOCK
|
|
fd is in non-blocking mode and spu_run would block.
|
|
|
|
EBADF fd is not a valid file descriptor.
|
|
|
|
EFAULT npc is not a valid pointer or status is neither NULL nor a valid
|
|
pointer.
|
|
|
|
EINTR A signal occurred while spu_run was in progress. The npc value
|
|
has been updated to the new program counter value if necessary.
|
|
|
|
EINVAL fd is not a file descriptor returned from spu_create(2).
|
|
|
|
ENOMEM Insufficient memory was available to handle a page fault result-
|
|
ing from an MFC direct memory access.
|
|
|
|
ENOSYS the functionality is not provided by the current system, because
|
|
either the hardware does not provide SPUs or the spufs module is
|
|
not loaded.
|
|
|
|
|
|
NOTES
|
|
spu_run is meant to be used from libraries that implement a more
|
|
abstract interface to SPUs, not to be used from regular applications.
|
|
See http://www.bsc.es/projects/deepcomputing/linuxoncell/ for the rec-
|
|
ommended libraries.
|
|
|
|
|
|
CONFORMING TO
|
|
This call is Linux specific and only implemented by the ppc64 architec-
|
|
ture. Programs using this system call are not portable.
|
|
|
|
|
|
BUGS
|
|
The code does not yet fully implement all features lined out here.
|
|
|
|
|
|
AUTHOR
|
|
Arnd Bergmann <arndb@de.ibm.com>
|
|
|
|
SEE ALSO
|
|
capabilities(7), close(2), spu_create(2), spufs(7)
|
|
|
|
|
|
|
|
Linux 2005-09-28 SPU_RUN(2)
|
|
|
|
------------------------------------------------------------------------------
|
|
|
|
SPU_CREATE(2) Linux Programmer's Manual SPU_CREATE(2)
|
|
|
|
|
|
|
|
NAME
|
|
spu_create - create a new spu context
|
|
|
|
|
|
SYNOPSIS
|
|
#include <sys/types.h>
|
|
#include <sys/spu.h>
|
|
|
|
int spu_create(const char *pathname, int flags, mode_t mode);
|
|
|
|
DESCRIPTION
|
|
The spu_create system call is used on PowerPC machines that implement
|
|
the Cell Broadband Engine Architecture in order to access Synergistic
|
|
Processor Units (SPUs). It creates a new logical context for an SPU in
|
|
pathname and returns a handle to associated with it. pathname must
|
|
point to a non-existing directory in the mount point of the SPU file
|
|
system (spufs). When spu_create is successful, a directory gets cre-
|
|
ated on pathname and it is populated with files.
|
|
|
|
The returned file handle can only be passed to spu_run(2) or closed,
|
|
other operations are not defined on it. When it is closed, all associ-
|
|
ated directory entries in spufs are removed. When the last file handle
|
|
pointing either inside of the context directory or to this file
|
|
descriptor is closed, the logical SPU context is destroyed.
|
|
|
|
The parameter flags can be zero or any bitwise or'd combination of the
|
|
following constants:
|
|
|
|
SPU_RAWIO
|
|
Allow mapping of some of the hardware registers of the SPU into
|
|
user space. This flag requires the CAP_SYS_RAWIO capability, see
|
|
capabilities(7).
|
|
|
|
The mode parameter specifies the permissions used for creating the new
|
|
directory in spufs. mode is modified with the user's umask(2) value
|
|
and then used for both the directory and the files contained in it. The
|
|
file permissions mask out some more bits of mode because they typically
|
|
support only read or write access. See stat(2) for a full list of the
|
|
possible mode values.
|
|
|
|
|
|
RETURN VALUE
|
|
spu_create returns a new file descriptor. It may return -1 to indicate
|
|
an error condition and set errno to one of the error codes listed
|
|
below.
|
|
|
|
|
|
ERRORS
|
|
EACCESS
|
|
The current user does not have write access on the spufs mount
|
|
point.
|
|
|
|
EEXIST An SPU context already exists at the given path name.
|
|
|
|
EFAULT pathname is not a valid string pointer in the current address
|
|
space.
|
|
|
|
EINVAL pathname is not a directory in the spufs mount point.
|
|
|
|
ELOOP Too many symlinks were found while resolving pathname.
|
|
|
|
EMFILE The process has reached its maximum open file limit.
|
|
|
|
ENAMETOOLONG
|
|
pathname was too long.
|
|
|
|
ENFILE The system has reached the global open file limit.
|
|
|
|
ENOENT Part of pathname could not be resolved.
|
|
|
|
ENOMEM The kernel could not allocate all resources required.
|
|
|
|
ENOSPC There are not enough SPU resources available to create a new
|
|
context or the user specific limit for the number of SPU con-
|
|
texts has been reached.
|
|
|
|
ENOSYS the functionality is not provided by the current system, because
|
|
either the hardware does not provide SPUs or the spufs module is
|
|
not loaded.
|
|
|
|
ENOTDIR
|
|
A part of pathname is not a directory.
|
|
|
|
|
|
|
|
NOTES
|
|
spu_create is meant to be used from libraries that implement a more
|
|
abstract interface to SPUs, not to be used from regular applications.
|
|
See http://www.bsc.es/projects/deepcomputing/linuxoncell/ for the rec-
|
|
ommended libraries.
|
|
|
|
|
|
FILES
|
|
pathname must point to a location beneath the mount point of spufs. By
|
|
convention, it gets mounted in /spu.
|
|
|
|
|
|
CONFORMING TO
|
|
This call is Linux specific and only implemented by the ppc64 architec-
|
|
ture. Programs using this system call are not portable.
|
|
|
|
|
|
BUGS
|
|
The code does not yet fully implement all features lined out here.
|
|
|
|
|
|
AUTHOR
|
|
Arnd Bergmann <arndb@de.ibm.com>
|
|
|
|
SEE ALSO
|
|
capabilities(7), close(2), spu_run(2), spufs(7)
|
|
|
|
|
|
|
|
Linux 2005-09-28 SPU_CREATE(2)
|