mirror of https://github.com/Qortal/Brooklyn
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
273 lines
12 KiB
273 lines
12 KiB
.. SPDX-License-Identifier: GPL-2.0 |
|
|
|
===== |
|
spufs |
|
===== |
|
|
|
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 <[email protected]>, Mark Nutter <[email protected]>, |
|
Ulrich Weigand <[email protected]> |
|
|
|
See Also |
|
======== |
|
capabilities(7), close(2), spu_create(2), spu_run(2), spufs(7)
|
|
|