1spufs(7)               Miscellaneous Information 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 de‐
39       scribed 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 op‐
68              erations 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 ac‐
78                     cess to the SPU local storage within the process  address
79                     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  re‐
106                     turned.
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  (un‐
112              less  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 re‐
165              turn  a big-endian binary integer number.  The only possible op‐
166              eration 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)  re‐
181              quire  that the SPU context be scheduled out, so frequent access
182              to these files is not recommended for normal program operation.
183
184              The contents of these files are:
185
186              npc             Next Program Counter - valid only when  the  SPU
187                              is in a stopped state.
188
189              decr            SPU Decrementer
190
191              decr_status     Decrementer Status
192
193              spu_tag_mask    MFC tag mask for SPU DMA
194
195              event_mask      Event mask for SPU interrupts
196
197              event_status    Number of SPU events pending (read-only)
198
199              srr0            Interrupt Return address register
200
201              lslr            Local Store Limit Register
202
203              The possible operations on these files are:
204
205              read(2)
206                     Reads  the current register value.  If the register value
207                     is larger than the buffer passed to  the  read(2)  system
208                     call,  subsequent  reads  will  continue reading from the
209                     same buffer, until the end of the buffer is reached.
210
211                     When a complete string has been read, all subsequent read
212                     operations will return zero bytes and a new file descrip‐
213                     tor needs to be opened to read a new value.
214
215              write(2)
216                     A write(2) operation on the file sets the register to the
217                     value given in the string.  The string is parsed from the
218                     beginning until the first nonnumeric character or the end
219                     of  the  buffer.   Subsequent writes to the same file de‐
220                     scriptor overwrite the previous setting.
221
222                     Except for the npc file, these files are not  present  on
223                     contexts   that  have  been  created  with  the  SPU_CRE‐
224                     ATE_NOSCHED flag.
225
226       /fpcr  This file provides access to the Floating Point Status and  Con‐
227              trol  Register  (fcpr)  as a binary, four-byte file.  The opera‐
228              tions on the fpcr file are:
229
230              read(2)
231                     If count is smaller than four,  read(2)  returns  -1  and
232                     sets  errno  to  EINVAL.  Otherwise, a four-byte value is
233                     placed in the data buffer; this is the current  value  of
234                     the fpcr register.
235
236              write(2)
237                     If  count  is  smaller than four, write(2) returns -1 and
238                     sets errno to EINVAL.  Otherwise, a  four-byte  value  is
239                     copied  from  the  data buffer, updating the value of the
240                     fpcr register.
241
242       /signal1, /signal2
243              The files provide access to the two signal notification channels
244              of an SPU.  These are read-write files that operate on four-byte
245              words.  Writing to one of these files triggers an  interrupt  on
246              the SPU.  The value written to the signal files can be read from
247              the SPU through a channel read or from host user  space  through
248              the file.  After the value has been read by the SPU, it is reset
249              to zero.  The possible operations on an open signal1 or  signal2
250              file are:
251
252              read(2)
253                     If  count  is  smaller  than four, read(2) returns -1 and
254                     sets errno to EINVAL.  Otherwise, a  four-byte  value  is
255                     placed  in  the data buffer; this is the current value of
256                     the specified signal notification register.
257
258              write(2)
259                     If count is smaller than four, write(2)  returns  -1  and
260                     sets  errno  to  EINVAL.  Otherwise, a four-byte value is
261                     copied from the data buffer, updating the  value  of  the
262                     specified signal notification register.  The signal noti‐
263                     fication register will either be replaced with the  input
264                     data  or  will  be updated to the bitwise OR operation of
265                     the old value and the input data, depending on  the  con‐
266                     tents  of  the signal1_type or signal2_type files respec‐
267                     tively.
268
269       /signal1_type, /signal2_type
270              These two files change the behavior of the signal1  and  signal2
271              notification  files.   They contain a numeric ASCII string which
272              is read as either "1" or "0".  In mode 0 (overwrite), the  hard‐
273              ware  replaces  the contents of the signal channel with the data
274              that is written to it.  In mode 1 (logical OR), the hardware ac‐
275              cumulates  the  bits  that  are subsequently written to it.  The
276              possible operations on an open signal1_type or signal2_type file
277              are:
278
279              read(2)
280                     When  the  count  supplied to the read(2) call is shorter
281                     than the required length for the digit  (plus  a  newline
282                     character),  subsequent reads from the same file descrip‐
283                     tor will complete the string.  When a complete string has
284                     been  read,  all  subsequent  read operations will return
285                     zero bytes and a new file descriptor needs to  be  opened
286                     to read the value again.
287
288              write(2)
289                     A write(2) operation on the file sets the register to the
290                     value given in the string.  The string is parsed from the
291                     beginning until the first nonnumeric character or the end
292                     of the buffer.  Subsequent writes to the  same  file  de‐
293                     scriptor overwrite the previous setting.
294
295       /mbox_info, /ibox_info, /wbox_info, /dma_into, /proxydma_info
296              Read-only  files  that  contain the saved state of the SPU mail‐
297              boxes and DMA queues.  This allows the  SPU  status  to  be  in‐
298              spected,  mainly  for  debugging.   The  mbox_info and ibox_info
299              files each contain the four-byte mailbox message that  has  been
300              written  by  the  SPU.   If no message has been written to these
301              mailboxes, then contents  of  these  files  is  undefined.   The
302              mbox_stat,  ibox_stat, and wbox_stat files contain the available
303              message count.
304
305              The wbox_info file contains an array of four-byte  mailbox  mes‐
306              sages,  which  have been sent to the SPU.  With current CBEA ma‐
307              chines, the array is four items in length, so up to 4 * 4  =  16
308              bytes can be read from this file.  If any mailbox queue entry is
309              empty, then the bytes read at the corresponding location are un‐
310              defined.
311
312              The  dma_info  file  contains  the  contents  of the SPU MFC DMA
313              queue, represented as the following structure:
314
315                  struct spu_dma_info {
316                      uint64_t         dma_info_type;
317                      uint64_t         dma_info_mask;
318                      uint64_t         dma_info_status;
319                      uint64_t         dma_info_stall_and_notify;
320                      uint64_t         dma_info_atomic_command_status;
321                      struct mfc_cq_sr dma_info_command_data[16];
322                  };
323
324              The last member of this data structure is the actual DMA  queue,
325              containing 16 entries.  The mfc_cq_sr structure is defined as:
326
327                  struct mfc_cq_sr {
328                      uint64_t mfc_cq_data0_RW;
329                      uint64_t mfc_cq_data1_RW;
330                      uint64_t mfc_cq_data2_RW;
331                      uint64_t mfc_cq_data3_RW;
332                  };
333
334              The  proxydma_info  file  contains  similar information, but de‐
335              scribes the proxy DMA queue (i.e., DMAs  initiated  by  entities
336              outside the SPU) instead.  The file is in the following format:
337
338                  struct spu_proxydma_info {
339                      uint64_t         proxydma_info_type;
340                      uint64_t         proxydma_info_mask;
341                      uint64_t         proxydma_info_status;
342                      struct mfc_cq_sr proxydma_info_command_data[8];
343                  };
344
345              Accessing these files requires that the SPU context is scheduled
346              out - frequent use can be inefficient.  These files  should  not
347              be used for normal program operation.
348
349              These  files  are not present on contexts that have been created
350              with the SPU_CREATE_NOSCHED flag.
351
352       /cntl  This file provides access to the SPU Run Control and SPU  status
353              registers,  as  an  ASCII  string.  The following operations are
354              supported:
355
356              read(2)
357                     Reads from the cntl file will return an ASCII string with
358                     the hex value of the SPU Status register.
359
360              write(2)
361                     Writes  to  the  cntl file will set the context's SPU Run
362                     Control register.
363
364       /mfc   Provides access to the Memory Flow Controller of the SPU.  Read‐
365              ing from the file returns the contents of the SPU's MFC Tag Sta‐
366              tus register, and writing to the file initiates a DMA  from  the
367              MFC.  The following operations are supported:
368
369              write(2)
370                     Writes to this file need to be in the format of a MFC DMA
371                     command, defined as follows:
372
373                         struct mfc_dma_command {
374                             int32_t  pad;    /* reserved */
375                             uint32_t lsa;    /* local storage address */
376                             uint64_t ea;     /* effective address */
377                             uint16_t size;   /* transfer size */
378                             uint16_t tag;    /* command tag */
379                             uint16_t class;  /* class ID */
380                             uint16_t cmd;    /* command opcode */
381                         };
382
383                     Writes  are  required   to   be   exactly   sizeof(struct
384                     mfc_dma_command) bytes in size.  The command will be sent
385                     to the SPU's MFC proxy queue, and the tag stored  in  the
386                     kernel (see below).
387
388              read(2)
389                     Reads  the  contents  of the tag status register.  If the
390                     file is opened in blocking  mode  (i.e.,  without  O_NON‐
391                     BLOCK), then the read will block until a DMA tag (as per‐
392                     formed by a previous write) is complete.  In  nonblocking
393                     mode,  the MFC tag status register will be returned with‐
394                     out waiting.
395
396              poll(2)
397                     Calling poll(2) on the mfc file will block  until  a  new
398                     DMA  can  be started (by checking for POLLOUT) or until a
399                     previously started DMA (by checking for POLLIN) has  been
400                     completed.
401
402                     /mss  Provides access to the MFC MultiSource Synchroniza‐
403                     tion (MSS) facility.  By mmap(2)-ing this file, processes
404                     can access the MSS area of the SPU.
405
406                     The following operations are supported:
407
408              mmap(2)
409                     Mapping  mss  into the process address space gives access
410                     to the SPU MSS area within  the  process  address  space.
411                     Only MAP_SHARED mappings are allowed.
412
413       /psmap Provides  access  to the whole problem-state mapping of the SPU.
414              Applications can use this area to interface to the  SPU,  rather
415              than writing to individual register files in spufs.
416
417              The following operations are supported:
418
419              mmap(2)
420                     Mapping  psmap  gives  a  process a direct map of the SPU
421                     problem state area.  Only MAP_SHARED  mappings  are  sup‐
422                     ported.
423
424       /phys-id
425              Read-only  file  containing the physical SPU number that the SPU
426              context is running on.  When the context is  not  running,  this
427              file contains the string "-1".
428
429              The physical SPU number is given by an ASCII hex string.
430
431       /object-id
432              Allows  applications  to  store (or retrieve) a single 64-bit ID
433              into the context.  This ID is later used by profiling  tools  to
434              uniquely identify the context.
435
436              write(2)
437                     By  writing  an  ASCII hex value into this file, applica‐
438                     tions can set the object ID of the SPU context.  Any pre‐
439                     vious value of the object ID is overwritten.
440
441              read(2)
442                     Reading  this file gives an ASCII hex string representing
443                     the object ID for this SPU context.
444

EXAMPLES

446       To automatically mount(8) the SPU filesystem when booting, at the loca‐
447       tion  /spu chosen by the user, put this line into the fstab(5) configu‐
448       ration file:
449       none /spu spufs gid=spu 0 0
450

SEE ALSO

452       close(2), spu_create(2), spu_run(2), capabilities(7)
453
454       The Cell Broadband Engine Architecture (CBEA) specification
455
456
457
458Linux man-pages 6.04              2023-02-05                          spufs(7)
Impressum