0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 =====
0004 spufs
0005 =====
0006
0007 Name
0008 ====
0009
0010 spufs - the SPU file system
0011
0012
0013 Description
0014 ===========
0015
0016 The SPU file system is used on PowerPC machines that implement the Cell
0017 Broadband Engine Architecture in order to access Synergistic Processor
0018 Units (SPUs).
0019
0020 The file system provides a name space similar to posix shared memory or
0021 message queues. Users that have write permissions on the file system
0022 can use spu_create(2) to establish SPU contexts in the spufs root.
0023
0024 Every SPU context is represented by a directory containing a predefined
0025 set of files. These files can be used for manipulating the state of the
0026 logical SPU. Users can change permissions on those files, but not actu-
0027 ally add or remove files.
0028
0029
0030 Mount Options
0031 =============
0032
0033 uid=<uid>
0034 set the user owning the mount point, the default is 0 (root).
0035
0036 gid=<gid>
0037 set the group owning the mount point, the default is 0 (root).
0038
0039
0040 Files
0041 =====
0042
0043 The files in spufs mostly follow the standard behavior for regular sys-
0044 tem calls like read(2) or write(2), but often support only a subset of
0045 the operations supported on regular file systems. This list details the
0046 supported operations and the deviations from the behaviour in the
0047 respective man pages.
0048
0049 All files that support the read(2) operation also support readv(2) and
0050 all files that support the write(2) operation also support writev(2).
0051 All files support the access(2) and stat(2) family of operations, but
0052 only the st_mode, st_nlink, st_uid and st_gid fields of struct stat
0053 contain reliable information.
0054
0055 All files support the chmod(2)/fchmod(2) and chown(2)/fchown(2) opera-
0056 tions, but will not be able to grant permissions that contradict the
0057 possible operations, e.g. read access on the wbox file.
0058
0059 The current set of files is:
0060
0061
0062 /mem
0063 the contents of the local storage memory of the SPU. This can be
0064 accessed like a regular shared memory file and contains both code and
0065 data in the address space of the SPU. The possible operations on an
0066 open mem file are:
0067
0068 read(2), pread(2), write(2), pwrite(2), lseek(2)
0069 These operate as documented, with the exception that seek(2),
0070 write(2) and pwrite(2) are not supported beyond the end of the
0071 file. The file size is the size of the local storage of the SPU,
0072 which normally is 256 kilobytes.
0073
0074 mmap(2)
0075 Mapping mem into the process address space gives access to the
0076 SPU local storage within the process address space. Only
0077 MAP_SHARED mappings are allowed.
0078
0079
0080 /mbox
0081 The first SPU to CPU communication mailbox. This file is read-only and
0082 can be read in units of 32 bits. The file can only be used in non-
0083 blocking mode and it even poll() will not block on it. The possible
0084 operations on an open mbox file are:
0085
0086 read(2)
0087 If a count smaller than four is requested, read returns -1 and
0088 sets errno to EINVAL. If there is no data available in the mail
0089 box, the return value is set to -1 and errno becomes EAGAIN.
0090 When data has been read successfully, four bytes are placed in
0091 the data buffer and the value four is returned.
0092
0093
0094 /ibox
0095 The second SPU to CPU communication mailbox. This file is similar to
0096 the first mailbox file, but can be read in blocking I/O mode, and the
0097 poll family of system calls can be used to wait for it. The possible
0098 operations on an open ibox file are:
0099
0100 read(2)
0101 If a count smaller than four is requested, read returns -1 and
0102 sets errno to EINVAL. If there is no data available in the mail
0103 box and the file descriptor has been opened with O_NONBLOCK, the
0104 return value is set to -1 and errno becomes EAGAIN.
0105
0106 If there is no data available in the mail box and the file
0107 descriptor has been opened without O_NONBLOCK, the call will
0108 block until the SPU writes to its interrupt mailbox channel.
0109 When data has been read successfully, four bytes are placed in
0110 the data buffer and the value four is returned.
0111
0112 poll(2)
0113 Poll on the ibox file returns (POLLIN | POLLRDNORM) whenever
0114 data is available for reading.
0115
0116
0117 /wbox
0118 The CPU to SPU communation mailbox. It is write-only and can be written
0119 in units of 32 bits. If the mailbox is full, write() will block and
0120 poll can be used to wait for it becoming empty again. The possible
0121 operations on an open wbox file are: write(2) If a count smaller than
0122 four is requested, write returns -1 and sets errno to EINVAL. If there
0123 is no space available in the mail box and the file descriptor has been
0124 opened with O_NONBLOCK, the return value is set to -1 and errno becomes
0125 EAGAIN.
0126
0127 If there is no space available in the mail box and the file descriptor
0128 has been opened without O_NONBLOCK, the call will block until the SPU
0129 reads from its PPE mailbox channel. When data has been read success-
0130 fully, four bytes are placed in the data buffer and the value four is
0131 returned.
0132
0133 poll(2)
0134 Poll on the ibox file returns (POLLOUT | POLLWRNORM) whenever
0135 space is available for writing.
0136
0137
0138 /mbox_stat, /ibox_stat, /wbox_stat
0139 Read-only files that contain the length of the current queue, i.e. how
0140 many words can be read from mbox or ibox or how many words can be
0141 written to wbox without blocking. The files can be read only in 4-byte
0142 units and return a big-endian binary integer number. The possible
0143 operations on an open ``*box_stat`` file are:
0144
0145 read(2)
0146 If a count smaller than four is requested, read returns -1 and
0147 sets errno to EINVAL. Otherwise, a four byte value is placed in
0148 the data buffer, containing the number of elements that can be
0149 read from (for mbox_stat and ibox_stat) or written to (for
0150 wbox_stat) the respective mail box without blocking or resulting
0151 in EAGAIN.
0152
0153
0154 /npc, /decr, /decr_status, /spu_tag_mask, /event_mask, /srr0
0155 Internal registers of the SPU. The representation is an ASCII string
0156 with the numeric value of the next instruction to be executed. These
0157 can be used in read/write mode for debugging, but normal operation of
0158 programs should not rely on them because access to any of them except
0159 npc requires an SPU context save and is therefore very inefficient.
0160
0161 The contents of these files are:
0162
0163 =================== ===================================
0164 npc Next Program Counter
0165 decr SPU Decrementer
0166 decr_status Decrementer Status
0167 spu_tag_mask MFC tag mask for SPU DMA
0168 event_mask Event mask for SPU interrupts
0169 srr0 Interrupt Return address register
0170 =================== ===================================
0171
0172
0173 The possible operations on an open npc, decr, decr_status,
0174 spu_tag_mask, event_mask or srr0 file are:
0175
0176 read(2)
0177 When the count supplied to the read call is shorter than the
0178 required length for the pointer value plus a newline character,
0179 subsequent reads from the same file descriptor will result in
0180 completing the string, regardless of changes to the register by
0181 a running SPU task. When a complete string has been read, all
0182 subsequent read operations will return zero bytes and a new file
0183 descriptor needs to be opened to read the value again.
0184
0185 write(2)
0186 A write operation on the file results in setting the register to
0187 the value given in the string. The string is parsed from the
0188 beginning to the first non-numeric character or the end of the
0189 buffer. Subsequent writes to the same file descriptor overwrite
0190 the previous setting.
0191
0192
0193 /fpcr
0194 This file gives access to the Floating Point Status and Control Regis-
0195 ter as a four byte long file. The operations on the fpcr file are:
0196
0197 read(2)
0198 If a count smaller than four is requested, read returns -1 and
0199 sets errno to EINVAL. Otherwise, a four byte value is placed in
0200 the data buffer, containing the current value of the fpcr regis-
0201 ter.
0202
0203 write(2)
0204 If a count smaller than four is requested, write returns -1 and
0205 sets errno to EINVAL. Otherwise, a four byte value is copied
0206 from the data buffer, updating the value of the fpcr register.
0207
0208
0209 /signal1, /signal2
0210 The two signal notification channels of an SPU. These are read-write
0211 files that operate on a 32 bit word. Writing to one of these files
0212 triggers an interrupt on the SPU. The value written to the signal
0213 files can be read from the SPU through a channel read or from host user
0214 space through the file. After the value has been read by the SPU, it
0215 is reset to zero. The possible operations on an open signal1 or sig-
0216 nal2 file are:
0217
0218 read(2)
0219 If a count smaller than four is requested, read returns -1 and
0220 sets errno to EINVAL. Otherwise, a four byte value is placed in
0221 the data buffer, containing the current value of the specified
0222 signal notification register.
0223
0224 write(2)
0225 If a count smaller than four is requested, write returns -1 and
0226 sets errno to EINVAL. Otherwise, a four byte value is copied
0227 from the data buffer, updating the value of the specified signal
0228 notification register. The signal notification register will
0229 either be replaced with the input data or will be updated to the
0230 bitwise OR or the old value and the input data, depending on the
0231 contents of the signal1_type, or signal2_type respectively,
0232 file.
0233
0234
0235 /signal1_type, /signal2_type
0236 These two files change the behavior of the signal1 and signal2 notifi-
0237 cation files. The contain a numerical ASCII string which is read as
0238 either "1" or "0". In mode 0 (overwrite), the hardware replaces the
0239 contents of the signal channel with the data that is written to it. in
0240 mode 1 (logical OR), the hardware accumulates the bits that are subse-
0241 quently written to it. The possible operations on an open signal1_type
0242 or signal2_type file are:
0243
0244 read(2)
0245 When the count supplied to the read call is shorter than the
0246 required length for the digit plus a newline character, subse-
0247 quent reads from the same file descriptor will result in com-
0248 pleting the string. When a complete string has been read, all
0249 subsequent read operations will return zero bytes and a new file
0250 descriptor needs to be opened to read the value again.
0251
0252 write(2)
0253 A write operation on the file results in setting the register to
0254 the value given in the string. The string is parsed from the
0255 beginning to the first non-numeric character or the end of the
0256 buffer. Subsequent writes to the same file descriptor overwrite
0257 the previous setting.
0258
0259
0260 Examples
0261 ========
0262 /etc/fstab entry
0263 none /spu spufs gid=spu 0 0
0264
0265
0266 Authors
0267 =======
0268 Arnd Bergmann <arndb@de.ibm.com>, Mark Nutter <mnutter@us.ibm.com>,
0269 Ulrich Weigand <Ulrich.Weigand@de.ibm.com>
0270
0271 See Also
0272 ========
0273 capabilities(7), close(2), spu_create(2), spu_run(2), spufs(7)
