1SPUFS(7)                   Linux Programmer's Manual                  SPUFS(7)
2
3
4

NAME

6       spufs - SPU filesystem
7

DESCRIPTION

9       The  SPU filesystem is used on PowerPC machines that implement the Cell
10       Broadband Engine Architecture in order to access Synergistic  Processor
11       Units (SPUs).
12
13       The  filesystem provides a name space similar to POSIX shared memory or
14       message queues.  Users that have write permissions  on  the  filesystem
15       can  use  spu_create(2)  to establish SPU contexts under the spufs root
16       directory.
17
18       Every SPU context is represented by a directory containing a predefined
19       set  of  files.   These files can be used for manipulating the state of
20       the logical SPU.  Users can change permissions on the files, but  can't
21       add or remove files.
22
23   Mount options
24       uid=<uid>
25              Set the user owning the mount point; the default is 0 (root).
26
27       gid=<gid>
28              Set the group owning the mount point; the default is 0 (root).
29
30       mode=<mode>
31              Set  the  mode  of the top-level directory in spufs, as an octal
32              mode string.  The default is 0775.
33
34   Files
35       The files in spufs mostly follow the standard behavior for regular sys‐
36       tem  calls like read(2) or write(2), but often support only a subset of
37       the operations supported on regular filesystems.  This list details the
38       supported  operations  and  the  deviations  from the standard behavior
39       described in the respective man pages.
40
41       All files that support the read(2) operation also support readv(2)  and
42       all  files  that support the write(2) operation also support writev(2).
43       All files support the access(2) and stat(2) family of  operations,  but
44       for  the  latter  call,  the only fields of the returned stat structure
45       that contain reliable information are st_mode,  st_nlink,  st_uid,  and
46       st_gid.
47
48       All  files support the chmod(2)/fchmod(2) and chown(2)/fchown(2) opera‐
49       tions, but will not be able to grant permissions  that  contradict  the
50       possible operations (e.g., read access on the wbox file).
51
52       The current set of files is:
53
54       /capabilities
55              Contains  a comma-delimited string representing the capabilities
56              of this SPU context.  Possible capabilities are:
57
58              sched  This context may be scheduled.
59
60              step   This context can be run in single-step mode,  for  debug‐
61                     ging.
62
63              New capabilities flags may be added in the future.
64
65       /mem   the  contents  of the local storage memory of the SPU.  This can
66              be accessed like a regular shared memory file and contains  both
67              code  and  data  in  the address space of the SPU.  The possible
68              operations on an open mem file are:
69
70              read(2), pread(2), write(2), pwrite(2), lseek(2)
71                     These operate as usual, with the exception that lseek(2),
72                     write(2),  and pwrite(2) are not supported beyond the end
73                     of the file.  The file size is  the  size  of  the  local
74                     storage of the SPU, which is normally 256 kilobytes.
75
76              mmap(2)
77                     Mapping  mem  into  the  process  address  space provides
78                     access to  the  SPU  local  storage  within  the  process
79                     address space.  Only MAP_SHARED mappings are allowed.
80
81       /regs  Contains the saved general-purpose registers of the SPU context.
82              This file contains the 128-bit values  of  each  register,  from
83              register  0 to register 127, in order.  This allows the general-
84              purpose registers to be inspected for debugging.
85
86              Reading to or writing from this file requires that  the  context
87              is scheduled out, so use of this file is not recommended in nor‐
88              mal program operation.
89
90              The regs file is not present on contexts that have been  created
91              with the SPU_CREATE_NOSCHED flag.
92
93       /mbox  The  first SPU-to-CPU communication mailbox.  This file is read-
94              only and can be read in units of 4 bytes.  The file can be  used
95              only  in nonblocking mode - even poll(2) cannot be used to block
96              on this file.  The only possible operation on an open mbox  file
97              is:
98
99              read(2)
100                     If  count  is  smaller  than four, read(2) returns -1 and
101                     sets errno to EINVAL.  If there is no data  available  in
102                     the  mailbox  (i.e.,  the SPU has not sent a mailbox mes‐
103                     sage), the return value is set to -1 and errno is set  to
104                     EAGAIN.  When data has been read successfully, four bytes
105                     are placed in the data  buffer  and  the  value  four  is
106                     returned.
107
108       /ibox  The second SPU-to-CPU communication mailbox.  This file is simi‐
109              lar to the first mailbox file, but can be read in  blocking  I/O
110              mode, thus calling read(2) on an open ibox file will block until
111              the SPU has  written  data  to  its  interrupt  mailbox  channel
112              (unless  the  file  has been opened with O_NONBLOCK, see below).
113              Also, poll(2) and similar system calls can be  used  to  monitor
114              for the presence of mailbox data.
115
116              The possible operations on an open ibox file are:
117
118              read(2)
119                     If  count  is  smaller  than four, read(2) returns -1 and
120                     sets errno to EINVAL.  If there is no data  available  in
121                     the  mailbox and the file descriptor has been opened with
122                     O_NONBLOCK, the return value is set to -1  and  errno  is
123                     set to EAGAIN.
124
125                     If there is no data available in the mailbox and the file
126                     descriptor has been opened without O_NONBLOCK,  the  call
127                     will  block until the SPU writes to its interrupt mailbox
128                     channel.  When data  has  been  read  successfully,  four
129                     bytes are placed in the data buffer and the value four is
130                     returned.
131
132              poll(2)
133                     Poll on the ibox file returns (POLLIN | POLLRDNORM) when‐
134                     ever data is available for reading.
135
136       /wbox  The  CPU-to-SPU communication mailbox.  It is write-only and can
137              be written in units of four bytes.   If  the  mailbox  is  full,
138              write(2)  will block, and poll(2) can be used to block until the
139              mailbox is available for writing again.  The possible operations
140              on an open wbox file are:
141
142              write(2)
143                     If  count  is  smaller than four, write(2) returns -1 and
144                     sets errno to EINVAL.  If there is no space available  in
145                     the  mailbox and the file descriptor has been opened with
146                     O_NONBLOCK, the return value is set to -1  and  errno  is
147                     set to EAGAIN.
148
149                     If  there  is  no  space available in the mailbox and the
150                     file descriptor has been opened without  O_NONBLOCK,  the
151                     call will block until the SPU reads from its PPE (PowerPC
152                     Processing Element) mailbox channel.  When data has  been
153                     written successfully, the system call returns four as its
154                     function result.
155
156              poll(2)
157                     A poll on the wbox file returns  (POLLOUT  |  POLLWRNORM)
158                     whenever space is available for writing.
159
160       /mbox_stat, /ibox_stat, /wbox_stat
161              These are read-only files that contain the length of the current
162              queue of each mailbox—that is, how many words can be  read  from
163              mbox  or  ibox  or how many words can be written to wbox without
164              blocking.  The files can be read only  in  four-byte  units  and
165              return  a  big-endian  binary integer number.  The only possible
166              operation on an open *box_stat file is:
167
168              read(2)
169                     If count is smaller than four,  read(2)  returns  -1  and
170                     sets  errno  to  EINVAL.  Otherwise, a four-byte value is
171                     placed in the data buffer.  This value is the  number  of
172                     elements  that  can  be  read  from  (for  mbox_stat  and
173                     ibox_stat) or written to (for wbox_stat)  the  respective
174                     mailbox without blocking or returning an EAGAIN error.
175
176       /npc,  /decr,  /decr_status, /spu_tag_mask, /event_mask, /event_status,
177       /srr0, /lslr
178              Internal registers of the SPU.  These  files  contain  an  ASCII
179              string  representing  the  hex  value of the specified register.
180              Reads and writes on these files  (except  for  npc,  see  below)
181              require  that  the  SPU  context  be  scheduled out, so frequent
182              access to these files is  not  recommended  for  normal  program
183              operation.
184
185              The contents of these files are:
186
187              npc             Next  Program  Counter - valid only when the SPU
188                              is in a stopped state.
189
190              decr            SPU Decrementer
191
192              decr_status     Decrementer Status
193
194              spu_tag_mask    MFC tag mask for SPU DMA
195
196              event_mask      Event mask for SPU interrupts
197
198              event_status    Number of SPU events pending (read-only)
199
200              srr0            Interrupt Return address register
201
202              lslr            Local Store Limit Register
203
204              The possible operations on these files are:
205
206              read(2)
207                     Reads the current register value.  If the register  value
208                     is  larger  than  the buffer passed to the read(2) system
209                     call, subsequent reads will  continue  reading  from  the
210                     same buffer, until the end of the buffer is reached.
211
212                     When a complete string has been read, all subsequent read
213                     operations will return zero bytes and a new file descrip‐
214                     tor needs to be opened to read a new value.
215
216              write(2)
217                     A write(2) operation on the file sets the register to the
218                     value given in the string.  The string is parsed from the
219                     beginning until the first nonnumeric character or the end
220                     of the  buffer.   Subsequent  writes  to  the  same  file
221                     descriptor overwrite the previous setting.
222
223                     Except  for  the npc file, these files are not present on
224                     contexts  that  have  been  created  with  the   SPU_CRE‐
225                     ATE_NOSCHED flag.
226
227       /fpcr  This  file provides access to the Floating Point Status and Con‐
228              trol Register (fcpr) as a binary, four-byte  file.   The  opera‐
229              tions on the fpcr file are:
230
231              read(2)
232                     If  count  is  smaller  than four, read(2) returns -1 and
233                     sets errno to EINVAL.  Otherwise, a  four-byte  value  is
234                     placed  in  the data buffer; this is the current value of
235                     the fpcr register.
236
237              write(2)
238                     If count is smaller than four, write(2)  returns  -1  and
239                     sets  errno  to  EINVAL.  Otherwise, a four-byte value is
240                     copied from the data buffer, updating the  value  of  the
241                     fpcr register.
242
243       /signal1, /signal2
244              The files provide access to the two signal notification channels
245              of an SPU.  These are read-write files that operate on four-byte
246              words.   Writing  to one of these files triggers an interrupt on
247              the SPU.  The value written to the signal files can be read from
248              the  SPU  through a channel read or from host user space through
249              the file.  After the value has been read by the SPU, it is reset
250              to  zero.  The possible operations on an open signal1 or signal2
251              file are:
252
253              read(2)
254                     If count is smaller than four,  read(2)  returns  -1  and
255                     sets  errno  to  EINVAL.  Otherwise, a four-byte value is
256                     placed in the data buffer; this is the current  value  of
257                     the specified signal notification register.
258
259              write(2)
260                     If  count  is  smaller than four, write(2) returns -1 and
261                     sets errno to EINVAL.  Otherwise, a  four-byte  value  is
262                     copied  from  the  data buffer, updating the value of the
263                     specified signal notification register.  The signal noti‐
264                     fication  register will either be replaced with the input
265                     data or will be updated to the bitwise  OR  operation  of
266                     the  old  value and the input data, depending on the con‐
267                     tents of the signal1_type or signal2_type  files  respec‐
268                     tively.
269
270       /signal1_type, /signal2_type
271              These  two  files change the behavior of the signal1 and signal2
272              notification files.  They contain a numeric ASCII  string  which
273              is  read as either "1" or "0".  In mode 0 (overwrite), the hard‐
274              ware replaces the contents of the signal channel with  the  data
275              that  is  written  to  it.  In mode 1 (logical OR), the hardware
276              accumulates the bits that are subsequently written to  it.   The
277              possible operations on an open signal1_type or signal2_type file
278              are:
279
280              read(2)
281                     When the count supplied to the read(2)  call  is  shorter
282                     than  the  required  length for the digit (plus a newline
283                     character), subsequent reads from the same file  descrip‐
284                     tor will complete the string.  When a complete string has
285                     been read, all subsequent  read  operations  will  return
286                     zero  bytes  and a new file descriptor needs to be opened
287                     to read the value again.
288
289              write(2)
290                     A write(2) operation on the file sets the register to the
291                     value given in the string.  The string is parsed from the
292                     beginning until the first nonnumeric character or the end
293                     of  the  buffer.   Subsequent  writes  to  the  same file
294                     descriptor overwrite the previous setting.
295
296       /mbox_info, /ibox_info, /wbox_info, /dma_into, /proxydma_info
297              Read-only files that contain the saved state of  the  SPU  mail‐
298              boxes  and  DMA  queues.   This  allows  the  SPU  status  to be
299              inspected, mainly for debugging.  The  mbox_info  and  ibox_info
300              files  each  contain the four-byte mailbox message that has been
301              written by the SPU.  If no message has  been  written  to  these
302              mailboxes,  then  contents  of  these  files  is undefined.  The
303              mbox_stat, ibox_stat and wbox_stat files contain  the  available
304              message count.
305
306              The  wbox_info  file contains an array of four-byte mailbox mes‐
307              sages, which have been sent  to  the  SPU.   With  current  CBEA
308              machines, the array is four items in length, so up to 4 * 4 = 16
309              bytes can be read from this file.  If any mailbox queue entry is
310              empty,  then  the  bytes  read at the corresponding location are
311              undefined.
312
313              The dma_info file contains the  contents  of  the  SPU  MFC  DMA
314              queue, represented as the following structure:
315
316                  struct spu_dma_info {
317                      uint64_t         dma_info_type;
318                      uint64_t         dma_info_mask;
319                      uint64_t         dma_info_status;
320                      uint64_t         dma_info_stall_and_notify;
321                      uint64_t         dma_info_atomic_command_status;
322                      struct mfc_cq_sr dma_info_command_data[16];
323                  };
324
325              The  last member of this data structure is the actual DMA queue,
326              containing 16 entries.  The mfc_cq_sr structure is defined as:
327
328                  struct mfc_cq_sr {
329                      uint64_t mfc_cq_data0_RW;
330                      uint64_t mfc_cq_data1_RW;
331                      uint64_t mfc_cq_data2_RW;
332                      uint64_t mfc_cq_data3_RW;
333                  };
334
335              The  proxydma_info  file  contains  similar   information,   but
336              describes  the proxy DMA queue (i.e., DMAs initiated by entities
337              outside the SPU) instead.  The file is in the following format:
338
339                  struct spu_proxydma_info {
340                      uint64_t         proxydma_info_type;
341                      uint64_t         proxydma_info_mask;
342                      uint64_t         proxydma_info_status;
343                      struct mfc_cq_sr proxydma_info_command_data[8];
344                  };
345
346              Accessing these files requires that the SPU context is scheduled
347              out  -  frequent use can be inefficient.  These files should not
348              be used for normal program operation.
349
350              These files are not present on contexts that have  been  created
351              with the SPU_CREATE_NOSCHED flag.
352
353       /cntl  This  file provides access to the SPU Run Control and SPU status
354              registers, as an ASCII string.   The  following  operations  are
355              supported:
356
357              read(2)
358                     Reads from the cntl file will return an ASCII string with
359                     the hex value of the SPU Status register.
360
361              write(2)
362                     Writes to the cntl file will set the  context's  SPU  Run
363                     Control register.
364
365       /mfc   Provides access to the Memory Flow Controller of the SPU.  Read‐
366              ing from the file returns the contents of the SPU's MFC Tag Sta‐
367              tus  register,  and writing to the file initiates a DMA from the
368              MFC.  The following operations are supported:
369
370              write(2)
371                     Writes to this file need to be in the format of a MFC DMA
372                     command, defined as follows:
373
374                         struct mfc_dma_command {
375                             int32_t  pad;    /* reserved */
376                             uint32_t lsa;    /* local storage address */
377                             uint64_t ea;     /* effective address */
378                             uint16_t size;   /* transfer size */
379                             uint16_t tag;    /* command tag */
380                             uint16_t class;  /* class ID */
381                             uint16_t cmd;    /* command opcode */
382                         };
383
384                     Writes   are   required   to   be  exactly  sizeof(struct
385                     mfc_dma_command) bytes in size.  The command will be sent
386                     to  the  SPU's MFC proxy queue, and the tag stored in the
387                     kernel (see below).
388
389              read(2)
390                     Reads the contents of the tag status  register.   If  the
391                     file  is  opened  in  blocking mode (i.e., without O_NON‐
392                     BLOCK), then the read will block until a DMA tag (as per‐
393                     formed  by a previous write) is complete.  In nonblocking
394                     mode, the MFC tag status register will be returned  with‐
395                     out waiting.
396
397              poll(2)
398                     Calling  poll(2)  on  the mfc file will block until a new
399                     DMA can be started (by checking for POLLOUT) or  until  a
400                     previously  started DMA (by checking for POLLIN) has been
401                     completed.
402
403                     /mss Provides access to the MFC MultiSource  Synchroniza‐
404                     tion (MSS) facility.  By mmap(2)-ing this file, processes
405                     can access the MSS area of the SPU.
406
407                     The following operations are supported:
408
409              mmap(2)
410                     Mapping mss into the process address space  gives  access
411                     to  the  SPU  MSS  area within the process address space.
412                     Only MAP_SHARED mappings are allowed.
413
414       /psmap Provides access to the whole problem-state mapping of  the  SPU.
415              Applications  can  use this area to interface to the SPU, rather
416              than writing to individual register files in spufs.
417
418              The following operations are supported:
419
420              mmap(2)
421                     Mapping psmap gives a process a direct  map  of  the  SPU
422                     problem  state  area.   Only MAP_SHARED mappings are sup‐
423                     ported.
424
425       /phys-id
426              Read-only file containing the physical SPU number that  the  SPU
427              context  is  running  on.  When the context is not running, this
428              file contains the string "-1".
429
430              The physical SPU number is given by an ASCII hex string.
431
432       /object-id
433              Allows applications to store (or retrieve) a  single  64-bit  ID
434              into  the  context.  This ID is later used by profiling tools to
435              uniquely identify the context.
436
437              write(2)
438                     By writing an ASCII hex value into  this  file,  applica‐
439                     tions can set the object ID of the SPU context.  Any pre‐
440                     vious value of the object ID is overwritten.
441
442              read(2)
443                     Reading this file gives an ASCII hex string  representing
444                     the object ID for this SPU context.
445

EXAMPLE

447       /etc/fstab  entry
448              none      /spu      spufs     gid=spu   0    0
449

SEE ALSO

451       close(2), spu_create(2), spu_run(2), capabilities(7)
452
453       The Cell Broadband Engine Architecture (CBEA) specification
454

COLOPHON

456       This  page  is  part of release 4.15 of the Linux man-pages project.  A
457       description of the project, information about reporting bugs,  and  the
458       latest     version     of     this    page,    can    be    found    at
459       https://www.kernel.org/doc/man-pages/.
460
461
462
463Linux                             2017-09-15                          SPUFS(7)
Impressum